Finished authentication support in CZMQ (first draft)

* Does not yet support multiple domains * Adds zcertstore class for managing certificate stores
zeromq · Sep 19, 2013 · 4911de3 · 4911de3
1 parent e1a9211
commit 4911de3
Show file tree

Hide file tree

Showing 39 changed files with 2,422 additions and 1,134 deletions.
diff --git a/README.md b/README.md
diff --git a/README.txt b/README.txt
@@ -18,6 +18,8 @@ CZMQ has these goals:
 * To wrap the 0MQ core API in semantics that are natural and lead to shorter, more readable applications.
 * To hide the differences between versions of 0MQ, particularly 2.x and 3.x.
 * To provide a space for development of more sophisticated API semantics.
+* To wrap the 0MQ security features with high-level tools and APIs.
+* To become the basis for other language bindings built on top of CZMQ.
 
 CZMQ grew out of concepts developed in [ØMQ - The Guide](http://zguide.zeromq.org).
 
@@ -49,24 +51,14 @@ CZMQ grew out of concepts developed in [ØMQ - The Guide](http://zguide.zeromq.o
 
 [/diagram]
 
-### Highlights
-
-* Single API hides differences between 0MQ/2.x, and 0MQ/3.x.
-* Work with messages as strings, individual frames, or multipart messages.
-* Automatic closure of any open sockets at context termination.
-* Automatic LINGER configuration of all sockets for context termination.
-* Portable API for creating child threads and 0MQ pipes to talk to them.
-* Simple reactor with one-off and repeated timers, and socket readers.
-* System clock functions for sleeping and calculating timers.
-* Easy API to get/set all socket options.
-* Portable to Linux, UNIX, OS X, Windows (porting is not yet complete).
-* Includes generic hash and list containers.
-* Full self tests on all classes.
-
 ### Ownership and License
 
 CZMQ's contributors are listed in the AUTHORS file. It is held by the ZeroMQ organization at github.com. The authors of CZMQ grant you use of this software under the terms of the GNU Lesser General Public License (LGPL). For details see the files `COPYING` and `COPYING.LESSER` in this directory.
 
+### Commercial Support
+
+CZMQ is actively developed and maintained by iMatix Corporation, who provide support to commercial users that need it. Contact Pieter Hintjens vai ph@imatix.com for more information. Note that CZMQ is licensed exclusively under the same LGPLv3 + static link exception as libzmq. This lets you use CZMQ freely in any application, with the requirement that you publish patches to the code.
+
 ### Contributing
 
 CZMQ uses the [C4.1 (Collective Code Construction Contract)](http://rfc.zeromq.org/spec:22) process for contributions.
@@ -105,59 +97,95 @@ Include `czmq.h` in your application and link with libczmq. Here is a typical gc
 
 ### API Summary
 
-#### zctx - working with 0MQ contexts
+#### zauth - authentication for ZeroMQ security mechanisms
 
-.pull src/zctx.c@header,left
+.pull src/zauth.c@header,left
 
 This is the class interface:
 
-.pull include/zctx.h@interface,code
+.pull include/zauth.h@interface,code
 
-.pull src/zctx.c@discuss,left
+.pull src/zauth.c@discuss,left
 
-#### zsocket - working with 0MQ sockets
+#### zbeacon - LAN service announcement and discovery
 
-.pull src/zsocket.c@header,left
+.pull src/zbeacon.c@header,left
 
 This is the class interface:
 
-.pull include/zsocket.h@interface,code
+.pull include/zbeacon.h@interface,code
 
-.pull src/zsocket.c@discuss,left
+.pull src/zbeacon.c@discuss,left
 
-#### zsockopt - working with 0MQ socket options
+#### zcert - work with CURVE security certificates
 
-.pull src/zsockopt.c@header,left
+.pull src/zcert.c@header,left
 
 This is the class interface:
 
-.pull include/zsockopt.h@interface,code
+.pull include/zcert.h@interface,code
 
-.pull src/zsockopt.c@discuss,left
+.pull src/zcert.c@discuss,left
 
-#### zstr - sending and receiving strings
+#### zcertstore - work with CURVE security certificate stores
 
-.pull src/zstr.c@header,left
+.pull src/zcertstore.c@header,left
 
-[diagram]
+This is the class interface:
 
-           Memory                       Wire
-           +-------------+---+          +---+-------------+
-    Send   | S t r i n g | 0 |  ---->   | 6 | S t r i n g |
-           +-------------+---+          +---+-------------+
+.pull include/zcertstore.h@interface,code
 
-           Wire                         Heap
-           +---+-------------+          +-------------+---+
-    Recv   | 6 | S t r i n g |  ---->   | S t r i n g | 0 |
-           +---+-------------+          +-------------+---+
+.pull src/zcertstore.c@discuss,left
 
-[/diagram]
+#### zchunk - work with memory chunks
+
+.pull src/zchunk.c@header,left
 
 This is the class interface:
 
-.pull include/zstr.h@interface,code
+.pull include/zchunk.h@interface,code
 
-.pull src/zstr.c@discuss,left
+.pull src/zchunk.c@discuss,left
+
+#### zclock - millisecond clocks and delays
+
+.pull src/zclock.c@header,left
+
+This is the class interface:
+
+.pull include/zclock.h@interface,code
+
+.pull src/zclock.c@discuss,left
+
+#### zconfig - work with config files written in rfc.zeromq.org/spec:4/ZPL.
+
+.pull src/zconfig.c@header,left
+
+This is the class interface:
+
+.pull include/zconfig.h@interface,code
+
+.pull src/zconfig.c@discuss,left
+
+#### zctx - working with 0MQ contexts
+
+.pull src/zctx.c@header,left
+
+This is the class interface:
+
+.pull include/zctx.h@interface,code
+
+.pull src/zctx.c@discuss,left
+
+#### zdir - work with file-system directories
+
+.pull src/zdir.c@header,left
+
+This is the class interface:
+
+.pull include/zdir.h@interface,code
+
+.pull src/zdir.c@discuss,left
 
 #### zfile - work with files
 
@@ -179,15 +207,25 @@ This is the class interface:
 
 .pull src/zframe.c@discuss,left
 
-#### zmsg - working with multipart messages
+#### zhash - generic hash table container
 
-.pull src/zmsg.c@header,left
+.pull src/zhash.c@header,left
 
 This is the class interface:
 
-.pull include/zmsg.h@interface,code
+.pull include/zhash.h@interface,code
 
-.pull src/zmsg.c@discuss,left
+.pull src/zhash.c@discuss,left
+
+#### zlist - generic list container
+
+.pull src/zlist.c@header,left
+
+This is the class interface:
+
+.pull include/zlist.h@interface,code
+
+.pull src/zlist.c@discuss,left
 
 #### zloop - event-driven reactor
 
@@ -199,55 +237,109 @@ This is the class interface:
 
 .pull src/zloop.c@discuss,left
 
-#### zthread - working with system threads
+#### zmsg - working with multipart messages
 
-.pull src/zthread.c@header,left
+.pull src/zmsg.c@header,left
 
 This is the class interface:
 
-.pull include/zthread.h@interface,code
+.pull include/zmsg.h@interface,code
 
-.pull src/zthread.c@discuss,left
+.pull src/zmsg.c@discuss,left
 
-#### zhash - expandable hash table container
+#### zmutex - wrap lightweight mutexes
 
-.pull src/zhash.c@header,left
+.pull src/zmutex.c@header,left
 
 This is the class interface:
 
-.pull include/zhash.h@interface,code
+.pull include/zmutex.h@interface,code
 
-.pull src/zhash.c@discuss,left
+.pull src/zmutex.c@discuss,left
 
-#### zlist - singly-linked list container
+#### zpoller - trivial socket poller class
 
-.pull src/zlist.c@header,left
+.pull src/zpoller.c@header,left
 
 This is the class interface:
 
-.pull include/zlist.h@interface,code
+.pull include/zpoller.h@interface,code
 
-.pull src/zlist.c@discuss,left
+.pull src/zpoller.c@discuss,left
 
-#### zclock - millisecond clocks and delays
+#### zsocket - working with 0MQ sockets
 
-.pull src/zclock.c@header,left
+.pull src/zsocket.c@header,left
 
 This is the class interface:
 
-.pull include/zclock.h@interface,code
+.pull include/zsocket.h@interface,code
 
-.pull src/zclock.c@discuss,left
+.pull src/zsocket.c@discuss,left
 
-#### zmutex - wrap lightweight mutexes
+#### zsockopt - working with 0MQ socket options
 
-.pull src/zmutex.c@header,left
+.pull src/zsockopt.c@header,left
 
 This is the class interface:
 
-.pull include/zmutex.h@interface,code
+.pull include/zsockopt.h@interface,code
 
-.pull src/zmutex.c@discuss,left
+.pull src/zsockopt.c@discuss,left
+
+#### zstr - sending and receiving strings
+
+.pull src/zstr.c@header,left
+
+[diagram]
+
+           Memory                       Wire
+           +-------------+---+          +---+-------------+
+    Send   | S t r i n g | 0 |  ---->   | 6 | S t r i n g |
+           +-------------+---+          +---+-------------+
+
+           Wire                         Heap
+           +---+-------------+          +-------------+---+
+    Recv   | 6 | S t r i n g |  ---->   | S t r i n g | 0 |
+           +---+-------------+          +-------------+---+
+
+[/diagram]
+
+This is the class interface:
+
+.pull include/zstr.h@interface,code
+
+.pull src/zstr.c@discuss,left
+
+#### zsys - system-level methods
+
+.pull src/zsys.c@header,left
+
+This is the class interface:
+
+.pull include/zsys.h@interface,code
+
+.pull src/zsys.c@discuss,left
+
+#### zthread - working with system threads
+
+.pull src/zthread.c@header,left
+
+This is the class interface:
+
+.pull include/zthread.h@interface,code
+
+.pull src/zthread.c@discuss,left
+
+#### ztree - generic red-black tree container
+
+.pull src/ztree.c@header,left
+
+This is the class interface:
+
+.pull include/ztree.h@interface,code
+
+.pull src/ztree.c@discuss,left
 
 ## Under the Hood
 
@@ -260,6 +352,7 @@ If you define a new CZMQ class `myclass` you need to:
 * Add the myclass header and test call to `src/czmq_selftest.c`.
 * Add a reference documentation to 'doc/zmyclass.txt'.
 * Add myclass to 'src/Makefile.am` and `doc/Makefile.am`.
+* Add a section to README.txt.
 
 ### Documentation
 

diff --git a/addons/makecert.c b/addons/makecert.c
@@ -35,7 +35,7 @@
 //  Get and store one header in certificate
 
 static int
-s_get_header (zcert_t *cert, char *prompt, char *name)
+s_get_meta (zcert_t *cert, char *prompt, char *name)
 {
     printf ("%s ", prompt);
     char value [256];
@@ -45,7 +45,7 @@ s_get_header (zcert_t *cert, char *prompt, char *name)
     if (strlen (value) && value [strlen (value) - 1] == '\n')
         value [strlen (value) - 1] = 0;
     if (*value)
-        zcert_set_header (cert, name, value);
+        zcert_set_meta (cert, name, value);
     return 0;
 }
 
@@ -54,14 +54,14 @@ int main (void)
     puts ("Creating new CURVE certificate");
 
     zcert_t *cert = zcert_new ();
-    if (s_get_header (cert, "Enter your full name:", "name")
-    ||  s_get_header (cert, "Enter your email address:", "email")
-    ||  s_get_header (cert, "Enter your organization:", "organization"))
+    if (s_get_meta (cert, "Enter your full name:", "name")
+    ||  s_get_meta (cert, "Enter your email address:", "email")
+    ||  s_get_meta (cert, "Enter your organization:", "organization"))
         return -1;
 
     char *timestr = zclock_timestr ();
-    zcert_set_header (cert, "created-by", "CZMQ makecert");
-    zcert_set_header (cert, "date-created", timestr);
+    zcert_set_meta (cert, "created-by", "CZMQ makecert");
+    zcert_set_meta (cert, "date-created", timestr);
     free (timestr);
     zcert_dump (cert);
     zcert_save (cert, "mycert.txt");

diff --git a/doc/Makefile.am b/doc/Makefile.am
@@ -3,6 +3,7 @@ MAN3 = \
     zauth.3 \
     zbeacon.3 \
     zcert.3 \
+    zcertstore.3 \
     zchunk.3 \
     zclock.3 \
     zconfig.3 \

diff --git a/doc/mkmans b/doc/mkmans
@@ -0,0 +1,17 @@
+#! /bin/bash
+#
+#   mkmans - rebuild man pages
+#
+#   Author: Pieter Hintjens <ph@imatix.com>
+#   License: public domain
+#
+#   syntax: mkmans
+#
+
+make --quiet
+rm -f *.xml    #   Makefile does not detect version differences for XML
+for FILE in z*.txt; do 
+    ./mkman $FILE
+    make `basename $FILE .txt`.xml
+done
+