rbczmq 1.7.1 → 1.7.2

data/ext/zeromq/doc/Makefile.am

@@ -1,16 +1,18 @@
 MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \
-    zmq_ctx_new.3 zmq_ctx_destroy.3 zmq_ctx_get.3 zmq_ctx_set.3 \
+    zmq_ctx_new.3 zmq_ctx_term.3 zmq_ctx_destroy.3 zmq_ctx_get.3 zmq_ctx_set.3 \
     zmq_msg_init.3 zmq_msg_init_data.3 zmq_msg_init_size.3 \
     zmq_msg_move.3 zmq_msg_copy.3 zmq_msg_size.3 zmq_msg_data.3 zmq_msg_close.3 \
     zmq_msg_send.3 zmq_msg_recv.3 \
-    zmq_send.3 zmq_recv.3 \
+    zmq_send.3 zmq_recv.3 zmq_send_const.3 \
     zmq_msg_get.3 zmq_msg_set.3 zmq_msg_more.3 \
     zmq_getsockopt.3 zmq_setsockopt.3 \
     zmq_socket.3 zmq_socket_monitor.3 zmq_poll.3 \
     zmq_errno.3 zmq_strerror.3 zmq_version.3 zmq_proxy.3 \
-    zmq_sendmsg.3 zmq_recvmsg.3 zmq_init.3 zmq_term.3
+    zmq_sendmsg.3 zmq_recvmsg.3 zmq_init.3 zmq_term.3 \
+    zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3
 
-MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7
+MAN7 = zmq.7 zmq_tcp.7 zmq_pgm.7 zmq_epgm.7 zmq_inproc.7 zmq_ipc.7 \
+    zmq_null.7 zmq_plain.7 zmq_curve.7
 
 MAN_DOC = $(MAN1) $(MAN3) $(MAN7)
 

data/ext/zeromq/doc/zmq.txt

@@ -42,7 +42,7 @@ Work with context properties::
     linkzmq:zmq_ctx_get[3]
 
 Destroy a 0MQ context::
-    linkzmq:zmq_ctx_destroy[3]
+    linkzmq:zmq_ctx_term[3]
 
 Monitor a 0MQ context::
     linkzmq:zmq_ctx_set_monitor[3]
@@ -140,6 +140,7 @@ Sending and receiving messages::
     linkzmq:zmq_msg_recv[3]
     linkzmq:zmq_send[3]
     linkzmq:zmq_recv[3]
+    linkzmq:zmq_send_const[3]
 
 .Input/output multiplexing
 0MQ provides a mechanism for applications to multiplex input/output events over
@@ -177,6 +178,32 @@ two sockets, opaquely. A proxy may optionally capture all traffic to a third
 socket. To start a proxy in an application thread, use linkzmq:zmq_proxy[3].
 
 
+Security
+~~~~~~~~
+A 0MQ socket can select a security mechanism. Both peers must use the same
+security mechanism.
+
+The following security mechanisms are provided for IPC and TCP connections:
+
+Null security::
+    linkzmq:zmq_null[7]
+
+Plain-text authentication using username and password::
+    linkzmq:zmq_plain[7]
+
+Elliptic curve authentication and encryption::
+    linkzmq:zmq_curve[7]
+
+Generate a CURVE keypair in armored text format:
+    linkzmq:zmq_curve_keypair[3]
+
+Convert an armored key into a 32-byte binary key:
+    linkzmq:zmq_z85_decode[3]
+
+Convert a 32-byte binary CURVE key to an armored text string:
+    linkzmq:zmq_z85_encode[3]
+
+
 ERROR HANDLING
 --------------
 The 0MQ library functions handle errors using the standard conventions found on
@@ -215,8 +242,8 @@ members of the 0MQ community and pointers can be found on the 0MQ website.
 
 AUTHORS
 -------
-This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com>,
-Martin Lucina <martin@lucina.net>, and Pieter Hintjens <ph@imatix.com>.
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.
 
 
 RESOURCES

data/ext/zeromq/doc/zmq_bind.txt

@@ -98,5 +98,5 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
-Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_close.txt

@@ -48,5 +48,5 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Martin Sustrik <sustrik@250bpm.com> and
-Martin Lucina <mato@kotelna.sk>.
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_connect.txt

@@ -41,11 +41,13 @@ matter. The first exception is when using the inproc:// transport: you must
 call _zmq_bind()_ before calling _zmq_connect()_. The second exception are
 _ZMQ_PAIR_ sockets, which do not automatically reconnect to endpoints.
 
-NOTE: following a _zmq_connect()_, the socket enters its normal 'ready' state.
-By contrast, following a _zmq_bind()_ alone, the socket enters a 'mute' state
-in which the socket blocks or drops messages according to the socket type, as
-defined in linkzmq:zmq_socket[3].
-
+NOTE: following a _zmq_connect()_, for socket types except for ZMQ_ROUTER,
+the socket enters its normal 'ready' state. By contrast, following a
+_zmq_bind()_ alone, the socket enters a 'mute' state in which the socket
+blocks or drops messages according to the socket type, as defined in
+linkzmq:zmq_socket[3]. A ZMQ_ROUTER socket enters its normal 'ready' state
+for a specific peer only when handshaking is complete for that peer, which
+may take an arbitrary time.
 
 RETURN VALUE
 ------------
@@ -94,5 +96,5 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>,
-Martin Sustrik <sustrik@250bpm.com> and Martin Lucina <mato@kotelna.sk>.
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_ctx_destroy.txt

@@ -4,7 +4,7 @@ zmq_ctx_destroy(3)
 
 NAME
 ----
-zmq_ctx_destroy - destroy a 0MQ context
+zmq_ctx_destroy - terminate a 0MQ context
 
 
 SYNOPSIS
@@ -36,7 +36,7 @@ Context termination is performed in the following steps:
 For further details regarding socket linger behavior refer to the _ZMQ_LINGER_
 option in linkzmq:zmq_setsockopt[3].
 
-This function replaces the deprecated function linkzmq:zmq_term[3].
+This function is deprecated by linkzmq:zmq_ctx_term[3].
 
 
 RETURN VALUE
@@ -63,4 +63,5 @@ linkzmq:zmq_setsockopt[3]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_ctx_get.txt

@@ -26,11 +26,15 @@ ZMQ_IO_THREADS: Get number of I/O threads
 The 'ZMQ_IO_THREADS' argument returns the size of the 0MQ thread pool
 for this context.
 
-ZMQ_MAX_SOCKETS: Set maximum number of sockets
+ZMQ_MAX_SOCKETS: Get maximum number of sockets
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'ZMQ_MAX_SOCKETS' argument returns the maximum number of sockets
 allowed for this context.
 
+ZMQ_IPV6: Set IPv6 option
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_IPV6' argument returns the IPv6 option for the context.
+
 
 RETURN VALUE
 ------------
@@ -50,7 +54,7 @@ EXAMPLE
 .Setting a limit on the number of sockets
 ----
 void *context = zmq_ctx_new ();
-zmq_ctx_get (context, ZMQ_MAX_SOCKETS, 256);
+zmq_ctx_set (context, ZMQ_MAX_SOCKETS, 256);
 int max_sockets = zmq_ctx_get (context, ZMQ_MAX_SOCKETS);
 assert (max_sockets == 256);
 ----
@@ -64,4 +68,5 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_ctx_new.txt

@@ -41,9 +41,10 @@ SEE ALSO
 linkzmq:zmq[7]
 linkzmq:zmq_ctx_set[3]
 linkzmq:zmq_ctx_get[3]
-linkzmq:zmq_ctx_destroy[3]
+linkzmq:zmq_ctx_term[3]
 
 
 AUTHORS
 -------
-This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_ctx_set.txt

@@ -40,6 +40,17 @@ on the context.
 [horizontal]
 Default value:: 1024
 
+ZMQ_IPV6: Set IPv6 option
+~~~~~~~~~~~~~~~~~~~~~~~~~
+The 'ZMQ_IPV6' argument sets the IPv6 value for all sockets created in
+the context from this point onwards. A value of `1` means IPv6 is
+enabled, while `0` means the socket will use only IPv4. When IPv6 is
+enabled, a socket will connect to, or accept connections from, both
+IPv4 and IPv6 hosts.
+
+[horizontal]
+Default value:: 0
+
 
 RETURN VALUE
 ------------
@@ -72,4 +83,5 @@ linkzmq:zmq[7]
 
 AUTHORS
 -------
-This 0MQ manual page was written by Pieter Hintjens <ph@imatix.com>
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_ctx_shutdown.txt

@@ -0,0 +1,52 @@
+zmq_ctx_shutdown(3)
+==================
+
+
+NAME
+----
+zmq_ctx_shutdown - shutdown a 0MQ context
+
+
+SYNOPSIS
+--------
+*int zmq_ctx_shutdown (void '*context');*
+
+
+DESCRIPTION
+-----------
+The _zmq_ctx_shutdown()_ function shall shutdown the 0MQ context 'context'.
+
+Context shutdown will cause any blocking operations currently in progress on 
+sockets open within 'context' to return immediately with an error code of ETERM.
+With the exception of _zmq_close()_, any further operations on sockets open within
+'context' shall fail with an error code of ETERM.
+
+This function is optional, client code is still required to call the linkzmq:zmq_ctx_term[3]
+function to free all resources allocated by zeromq.
+
+
+RETURN VALUE
+------------
+The _zmq_ctx_shutdown()_ function shall return zero if successful. Otherwise
+it shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EFAULT*::
+The provided 'context' was invalid.
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+linkzmq:zmq_init[3]
+linkzmq:zmq_ctx_term[3]
+linkzmq:zmq_close[3]
+linkzmq:zmq_setsockopt[3]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_ctx_term.txt

@@ -0,0 +1,67 @@
+zmq_ctx_term(3)
+===============
+
+
+NAME
+----
+zmq_ctx_term - destroy a 0MQ context
+
+
+SYNOPSIS
+--------
+*int zmq_ctx_term (void '*context');*
+
+
+DESCRIPTION
+-----------
+The _zmq_ctx_term()_ function shall destroy the 0MQ context 'context'.
+
+Context termination is performed in the following steps:
+
+1. Any blocking operations currently in progress on sockets open within
+   'context' shall return immediately with an error code of ETERM.  With the
+   exception of _zmq_close()_, any further operations on sockets open within
+   'context' shall fail with an error code of ETERM.
+
+2. After interrupting all blocking calls, _zmq_ctx_term()_ shall _block_ until the
+   following conditions are satisfied:
+
+   * All sockets open within 'context' have been closed with _zmq_close()_.
+
+   * For each socket within 'context', all messages sent by the application
+     with _zmq_send()_ have either been physically transferred to a network
+     peer, or the socket's linger period set with the _ZMQ_LINGER_ socket
+     option has expired.
+
+For further details regarding socket linger behavior refer to the _ZMQ_LINGER_
+option in linkzmq:zmq_setsockopt[3].
+
+This function replaces the deprecated function linkzmq:zmq_term[3].
+
+
+RETURN VALUE
+------------
+The _zmq_ctx_term()_ function shall return zero if successful. Otherwise
+it shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*EFAULT*::
+The provided 'context' was invalid.
+*EINTR*::
+Termination was interrupted by a signal. It can be restarted if needed.
+
+
+SEE ALSO
+--------
+linkzmq:zmq[7]
+linkzmq:zmq_init[3]
+linkzmq:zmq_close[3]
+linkzmq:zmq_setsockopt[3]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_curve.txt

@@ -0,0 +1,92 @@
+zmq_curve(7)
+============
+
+
+NAME
+----
+zmq_curve - secure authentication and confidentiality
+
+
+SYNOPSIS
+--------
+The CURVE mechanism defines a mechanism for secure authentication and 
+confidentiality for communications between a client and a server. CURVE 
+is intended for use on public networks. The CURVE mechanism is defined 
+by this document: <http://rfc.zeromq.org/spec:25>.
+
+
+CLIENT AND SERVER ROLES
+-----------------------
+A socket using CURVE can be either client or server, at any moment, but 
+not both. The role is independent of bind/connect direction.
+
+A socket can change roles at any point by setting new options. The role
+affects all zmq_connect and zmq_bind calls that follow it.
+
+To become a CURVE server, the application sets the ZMQ_CURVE_SERVER option
+on the socket, and then sets the ZMQ_CURVE_SECRETKEY option to provide the
+socket with its long-term secret key. The application does not provide the
+socket with its long-term public key, which is used only by clients.
+
+To become a CURVE client, the application sets the ZMQ_CURVE_SERVERKEY 
+option with the long-term public key of the server it intends to connect
+to, or accept connections from, next. The application then sets the 
+ZMQ_CURVE_PUBLICKEY and ZMQ_CURVE_SECRETKEY options with its client 
+long-term key pair.
+
+If the server does authentication it will be based on the client's long
+term public key.
+
+KEY ENCODING
+------------
+The standard representation for keys in source code is either 32 bytes of
+base 256 (binary) data, or 40 characters of base 85 data encoded using the
+Z85 algorithm defined by http://rfc.zeromq.org/spec:32.
+
+The Z85 algorithm is designed to produce printable key strings for use in
+configuration files, the command line, and code. There is a reference
+implementation in C at https://github.com/zeromq/rfc/tree/master/src.
+
+    
+TEST KEY VALUES
+---------------
+For test cases, the client shall use this long-term key pair (specified
+as hexadecimal and in Z85):
+
+----
+public: 
+    BB88471D65E2659B30C55A5321CEBB5AAB2B70A398645C26DCA2B2FCB43FC518
+    Yne@$w-vo<fVvi]a<NY6T1ed:M$fCG*[IaLV{hID
+
+secret: 
+    7BB864B489AFA3671FBE69101F94B38972F24816DFB01B51656B3FEC8DFD0888
+    D:)Q[IlAW!ahhC2ac:9*A}h:p?([4%wOTJ%JR%cs
+----
+
+And the server shall use this long-term key pair (specified as hexadecimal 
+and in Z85):
+
+----
+public: 
+    54FCBA24E93249969316FB617C872BB0C1D1FF14800427C594CBFACF1BC2D652
+    rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7
+
+secret: 
+    8E0BDD697628B91D8F245587EE95C5B04D48963F79259877B49CD9063AEAD3B7
+    JTKVSB%%)wK0E.X)V>+}o?pNmC{O&4W4b!Ni{Lh6
+----
+
+SEE ALSO
+--------
+linkzmq:zmq_z85_encode[3]
+linkzmq:zmq_z85_decode[3]
+linkzmq:zmq_setsockopt[3]
+linkzmq:zmq_null[7]
+linkzmq:zmq_plain[7]
+linkzmq:zmq[7]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.

data/ext/zeromq/doc/zmq_curve_keypair.txt

@@ -0,0 +1,56 @@
+zmq_curve_keypair(3)
+====================
+
+
+NAME
+----
+zmq_curve_keypair - generate a new CURVE keypair
+
+
+SYNOPSIS
+--------
+*int zmq_curve_keypair (char *z85_public_key, char *z85_secret_key);*
+
+
+DESCRIPTION
+-----------
+The _zmq_curve_keypair()_ function shall return a newly generated random
+keypair consisting of a public key and a secret key. The caller provides
+two buffers, each at least 41 octets large, in which this method will
+store the keys. The keys are encoded using linkzmq:zmq_z85_encode[3].
+
+
+RETURN VALUE
+------------
+The _zmq_curve_keypair()_ function shall return 0 if successful, else it
+shall return `-1` and set 'errno' to one of the values defined below.
+
+
+ERRORS
+------
+*ENOTSUP*::
+The libzmq library was not built with cryptographic support (libsodium).
+
+
+EXAMPLE
+-------
+.Generating a new CURVE keypair
+----
+char public_key [41];
+char secret_key [41];
+int rc = crypto_box_keypair (public_key, secret_key);
+assert (rc == 0);
+----
+
+
+SEE ALSO
+--------
+linkzmq:zmq_z85_decode[3]
+linkzmq:zmq_z85_encode[3]
+linkzmq:zmq_curve[7]
+
+
+AUTHORS
+-------
+This page was written by the 0MQ community. To make a change please
+read the 0MQ Contribution Policy at <http://www.zeromq.org/docs:contributing>.