From fd4d125d8e3dbbb74261a6c006cb9306b0be9f14 Mon Sep 17 00:00:00 2001 From: Pieter Hintjens Date: Mon, 30 Sep 2013 15:14:02 +0200 Subject: [PATCH] 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 | 2 +- doc/zmq.txt | 9 ++++++ doc/zmq_curve_keypair.txt | 56 +++++++++++++++++++++++++++++++++++ doc/zmq_z85_decode.txt | 2 +- doc/zmq_z85_encode.txt | 1 + include/zmq_utils.h | 24 ++++++++------- tests/test_security_curve.cpp | 24 ++++++++++----- 7 files changed, 98 insertions(+), 20 deletions(-) create mode 100644 doc/zmq_curve_keypair.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index 91bc6452..3805749c 100644 --- a/doc/Makefile.am +++ b/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 diff --git a/doc/zmq.txt b/doc/zmq.txt index e7110f48..c699fedd 100644 --- a/doc/zmq.txt +++ b/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 -------------- diff --git a/doc/zmq_curve_keypair.txt b/doc/zmq_curve_keypair.txt new file mode 100644 index 00000000..aa714a52 --- /dev/null +++ b/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 . diff --git a/doc/zmq_z85_decode.txt b/doc/zmq_z85_decode.txt index 708434dd..72e97037 100644 --- a/doc/zmq_z85_decode.txt +++ b/doc/zmq_z85_decode.txt @@ -31,7 +31,6 @@ EXAMPLE ------- .Decoding a CURVE key ---- -#include 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] diff --git a/doc/zmq_z85_encode.txt b/doc/zmq_z85_encode.txt index e9ca5553..add0431b 100644 --- a/doc/zmq_z85_encode.txt +++ b/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] diff --git a/include/zmq_utils.h b/include/zmq_utils.h index 90ae8f88..9b14aa72 100644 --- a/include/zmq_utils.h +++ b/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 diff --git a/tests/test_security_curve.cpp b/tests/test_security_curve.cpp index dd4f9bc3..788fb2c1 100644 --- a/tests/test_security_curve.cpp +++ b/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