Packaging for zmq_curve_keypair function

* Added new man page for this
* Added test case, in tests/test_security_curve.cpp
* Noted in zmq_utils.h that these methods are documented

doc/Makefile.am

@@ -9,7 +9,7 @@ MAN3 = zmq_bind.3 zmq_unbind.3 zmq_connect.3 zmq_disconnect.3 zmq_close.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_z85_encode.3 zmq_z85_decode.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 \
     zmq_null.7 zmq_plain.7 zmq_curve.7

doc/zmq.txt

@@ -194,6 +194,15 @@ Plain-text authentication using username and password::
 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
 --------------

doc/zmq_curve_keypair.txt

+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>.

doc/zmq_z85_decode.txt

@@ -31,7 +31,6 @@ EXAMPLE
 -------
 .Decoding a CURVE key
 ----
-#include <sodium.h>
 char decoded [] = "rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7";
 uint8_t public_key [32];
 zmq_z85_decode (public_key, decoded);
@@ -41,6 +40,7 @@ zmq_z85_decode (public_key, decoded);
 SEE ALSO
 --------
 linkzmq:zmq_z85_decode[3]
+linkzmq:zmq_curve_keypair[3]
 linkzmq:zmq_curve[7]
 
 

doc/zmq_z85_encode.txt

@@ -47,6 +47,7 @@ puts (encoded);
 SEE ALSO
 --------
 linkzmq:zmq_z85_decode[3]
+linkzmq:zmq_curve_keypair[3]
 linkzmq:zmq_curve[7]
 
 

include/zmq_utils.h

@@ -61,8 +61,22 @@ extern "C" {
 #   endif
 #endif
 
+/* These functions are documented by man pages                                */
+
+/* Encode data with Z85 encoding. Returns encoded data                        */
+ZMQ_EXPORT char *zmq_z85_encode (char *dest, uint8_t *data, size_t size);
+
+/* Decode data with Z85 encoding. Returns decoded data                        */
+ZMQ_EXPORT uint8_t *zmq_z85_decode (uint8_t *dest, char *string);
+
+/* Generate z85-encoded public and private keypair with libsodium.            */
+/* Returns 0 on success.                                                      */
+ZMQ_EXPORT int zmq_curve_keypair (char *z85_public_key, char *z85_secret_key);
+
 typedef void (zmq_thread_fn) (void*);
 
+/*  These functions are not documented by man pages                           */
+
 /*  Helper functions are used by perf tests so that they don't have to care   */
 /*  about minutiae of time-related functions on different OS platforms.       */
 
@@ -82,16 +96,6 @@ ZMQ_EXPORT void *zmq_threadstart (zmq_thread_fn* func, void* arg);
 /* Wait for thread to complete then free up resources.                        */
 ZMQ_EXPORT void zmq_threadclose (void* thread);
 
-/* Encode data with Z85 encoding. Returns encoded data                        */
-ZMQ_EXPORT char *zmq_z85_encode (char *dest, uint8_t *data, size_t size);
-
-/* Decode data with Z85 encoding. Returns decoded data                        */
-ZMQ_EXPORT uint8_t *zmq_z85_decode (uint8_t *dest, char *string);
-
-/* Generate z85-encoded public and private keypair with libsodium.            */
-/* Returns 0 on success.                                                      */
-ZMQ_EXPORT int zmq_curve_keypair (char* z85_public_key, char *z85_secret_key);
-
 #undef ZMQ_EXPORT
 
 #ifdef __cplusplus

tests/test_security_curve.cpp

@@ -19,11 +19,11 @@
 
 #include "testutil.hpp"
 
-//  Test keys from the zmq_curve man page
-static char client_public [] = "Yne@$w-vo<fVvi]a<NY6T1ed:M$fCG*[IaLV{hID";
-static char client_secret [] = "D:)Q[IlAW!ahhC2ac:9*A}h:p?([4%wOTJ%JR%cs";
-static char server_public [] = "rq:rM>}U?@Lns47E1%kR.o@n%FcmmsL/@{H8]yf7";
-static char server_secret [] = "JTKVSB%%)wK0E.X)V>+}o?pNmC{O&4W4b!Ni{Lh6";
+//  We'll generate random test keys at startup
+static char client_public [41];
+static char client_secret [41];
+static char server_public [41];
+static char server_secret [41];
 
 //  --------------------------------------------------------------------------
 //  Encode a binary frame as a string; destination string MUST be at least
@@ -86,6 +86,13 @@ int main (void)
     printf ("libsodium not installed, skipping CURVE test\n");
     return 0;
 #endif
+
+    //  Generate new keypairs for this test
+    int rc = zmq_curve_keypair (client_public, client_secret);
+    assert (rc == 0);
+    rc = zmq_curve_keypair (server_public, server_secret);
+    assert (rc == 0);
+
     setup_test_environment ();
     void *ctx = zmq_ctx_new ();
     assert (ctx);
@@ -95,7 +102,7 @@ int main (void)
     //  where child thread does not start up fast enough.
     void *handler = zmq_socket (ctx, ZMQ_REP);
     assert (handler);
-    int rc = zmq_bind (handler, "inproc://zeromq.zap.01");
+    rc = zmq_bind (handler, "inproc://zeromq.zap.01");
     assert (rc == 0);
     void *zap_thread = zmq_threadstart (&zap_handler, handler);
 
@@ -175,8 +182,9 @@ int main (void)
 
     //  Check CURVE security with bogus client credentials
     //  This must be caught by the ZAP handler
-    char bogus_public [] = "8)<]6{NT{}=MZBsH)i%l0k}y*^i#80n-Yf{I8Z+P";
-    char bogus_secret [] = "[m9E0TW2Mf?Ke3K>fuBGCrkBpc6aJbj4jv4451Nx";
+    char bogus_public [41];
+    char bogus_secret [41];
+    zmq_curve_keypair (bogus_public, bogus_secret);
 
     client = zmq_socket (ctx, ZMQ_DEALER);
     assert (client);