From baf32a19859abdf01565dbed90518f06b37949d2 Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Mon, 26 Dec 2016 14:23:32 +0100 Subject: [PATCH 1/2] Problem: no documentation for zmq_curve_public Solution: add manpage --- doc/Makefile.am | 2 +- doc/zmq.txt | 3 ++ doc/zmq_curve_public.txt | 62 ++++++++++++++++++++++++++++++++++++++++ doc/zmq_setsockopt.txt | 6 ++-- doc/zmq_z85_decode.txt | 1 + doc/zmq_z85_encode.txt | 1 + 6 files changed, 72 insertions(+), 3 deletions(-) create mode 100644 doc/zmq_curve_public.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index ac155d69..a4f13ec6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -14,7 +14,7 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.3 \ zmq_errno.3 zmq_strerror.3 zmq_version.3 \ zmq_sendmsg.3 zmq_recvmsg.3 \ zmq_proxy.3 zmq_proxy_steerable.3 \ - zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3 \ + zmq_z85_encode.3 zmq_z85_decode.3 zmq_curve_keypair.3 zmq_curve_public.3 \ zmq_has.3 \ zmq_atomic_counter_new.3 zmq_atomic_counter_set.3 \ zmq_atomic_counter_inc.3 zmq_atomic_counter_dec.3 \ diff --git a/doc/zmq.txt b/doc/zmq.txt index 2bf78227..5ef075d6 100644 --- a/doc/zmq.txt +++ b/doc/zmq.txt @@ -199,6 +199,9 @@ Elliptic curve authentication and encryption:: Generate a CURVE keypair in armored text format:: linkzmq:zmq_curve_keypair[3] +Derive a CURVE public key from a secret key: + linkzmq:zmq_curve_public[3] + Converting keys to/from armoured text strings:: linkzmq:zmq_z85_decode[3] linkzmq:zmq_z85_encode[3] diff --git a/doc/zmq_curve_public.txt b/doc/zmq_curve_public.txt new file mode 100644 index 00000000..fd8adf16 --- /dev/null +++ b/doc/zmq_curve_public.txt @@ -0,0 +1,62 @@ +zmq_curve_public(3) +=================== + + +NAME +---- +zmq_curve_public - derive the public key from a private key + + +SYNOPSIS +-------- +*int zmq_curve_public (char *z85_public_key, char *z85_secret_key);* + + +DESCRIPTION +----------- +The _zmq_curve_public()_ function shall derive the public key from a +private key. The caller provides two buffers, each at least 41 octets +large. In z85_secret_key the caller shall provide the private key, and +the function will store the public key in z85_public_key. The keys are +encoded using linkzmq:zmq_z85_encode[3]. + + +RETURN VALUE +------------ +The _zmq_curve_public()_ 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 +------- +.Deriving the public key from a CURVE private key +---- +char public_key [41]; +char secret_key [41]; +int rc = zmq_curve_keypair (public_key, secret_key); +assert (rc == 0); +char derived_public[41]; +rc = zmq_curve_public (derived_public, secret_key); +assert (rc == 0); +assert (!strcmp (derived_public, public_key)); +---- + + +SEE ALSO +-------- +linkzmq:zmq_z85_decode[3] +linkzmq:zmq_z85_encode[3] +linkzmq:zmq_curve_keypair[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 . diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 72f9c25d..763a6221 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -132,7 +132,8 @@ sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary bytes, or as a 40-character string encoded in the Z85 encoding format and terminated in a null byte. The public key must always be used with the matching secret key. To generate a public/secret key pair, use -linkzmq:zmq_curve_keypair[3]. +linkzmq:zmq_curve_keypair[3]. To derive the public key from a secret key, +use linkzmq:zmq_curve_public[3]. NOTE: an option value size of 40 is supported for backwards compatibility, though is deprecated. @@ -150,7 +151,8 @@ Sets the socket's long term secret key. You must set this on both CURVE client and server sockets, see linkzmq:zmq_curve[7]. You can provide the key as 32 binary bytes, or as a 40-character string encoded in the Z85 encoding format and terminated in a null byte. To generate a public/secret -key pair, use linkzmq:zmq_curve_keypair[3]. +key pair, use linkzmq:zmq_curve_keypair[3]. To derive the public key from +a secret key, use linkzmq:zmq_curve_public[3]. NOTE: an option value size of 40 is supported for backwards compatibility, though is deprecated. diff --git a/doc/zmq_z85_decode.txt b/doc/zmq_z85_decode.txt index 778da726..2649547f 100644 --- a/doc/zmq_z85_decode.txt +++ b/doc/zmq_z85_decode.txt @@ -41,6 +41,7 @@ SEE ALSO -------- linkzmq:zmq_z85_decode[3] linkzmq:zmq_curve_keypair[3] +linkzmq:zmq_curve_public[3] linkzmq:zmq_curve[7] diff --git a/doc/zmq_z85_encode.txt b/doc/zmq_z85_encode.txt index d8deaa6a..f578f4d2 100644 --- a/doc/zmq_z85_encode.txt +++ b/doc/zmq_z85_encode.txt @@ -48,6 +48,7 @@ SEE ALSO -------- linkzmq:zmq_z85_decode[3] linkzmq:zmq_curve_keypair[3] +linkzmq:zmq_curve_public[3] linkzmq:zmq_curve[7] From 3dc016cab306421ce69692a944d19fc5a7c329eb Mon Sep 17 00:00:00 2001 From: Luca Boccassi Date: Mon, 26 Dec 2016 14:49:45 +0100 Subject: [PATCH 2/2] Problem: no documentation for ZMQ_SOCKS_PROXY Solution: add paragraphs to zmq_get/setsockopt man pages --- doc/zmq_getsockopt.txt | 13 +++++++++++++ doc/zmq_setsockopt.txt | 15 +++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/doc/zmq_getsockopt.txt b/doc/zmq_getsockopt.txt index 63380a04..4cbbd86b 100644 --- a/doc/zmq_getsockopt.txt +++ b/doc/zmq_getsockopt.txt @@ -653,6 +653,19 @@ Default value:: -1 (infinite) Applicable socket types:: all +ZMQ_SOCKS_PROXY: Retrieve SOCKS5 proxy address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The 'ZMQ_SOCKS_PROXY' option shall retrieve the SOCKS5 proxy address in string +format. The returned value shall be a NULL-terminated string and MAY be empty. +The returned size SHALL include the terminating null byte. + +[horizontal] +Option value type:: NULL-terminated character string +Option value unit:: N/A +Default value:: null string +Applicable socket types:: all, when using TCP transports + + ZMQ_TCP_KEEPALIVE: Override SO_KEEPALIVE socket option ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Override 'SO_KEEPALIVE' socket option(where supported by OS). diff --git a/doc/zmq_setsockopt.txt b/doc/zmq_setsockopt.txt index 763a6221..1e43b532 100644 --- a/doc/zmq_setsockopt.txt +++ b/doc/zmq_setsockopt.txt @@ -791,6 +791,21 @@ Default value:: -1 (infinite) Applicable socket types:: all +ZMQ_SOCKS_PROXY: Set SOCKS5 proxy address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Sets the SOCKS5 proxy address that shall be used by the socket for the TCP +connection(s). Does not support SOCKS5 authentication. If the endpoints are +domain names instead of addresses they shall not be resolved and they shall +be forwarded unchanged to the SOCKS proxy service in the client connection +request message (address type 0x03 domain name). + +[horizontal] +Option value type:: character string +Option value unit:: N/A +Default value:: not set +Applicable socket types:: all, when using TCP transport + + ZMQ_STREAM_NOTIFY: send connect and disconnect notifications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Enables connect and disconnect notifications on a STREAM socket, when set