zcertstore(3)
=============

NAME
----
zcertstore - work with CURVE security certificate stores

SYNOPSIS
--------
----

//  Create a new certificate store from a disk directory, loading and 
//  indexing all certificates in that location. The directory itself may be
//  absent, and created later, or modified at any time. The certificate store 
//  is automatically refreshed on any zcertstore_lookup() call. If the 
//  location is specified as NULL, creates a pure-memory store, which you 
//  can work with by inserting certificates at runtime. The location is
//  treated as a printf format.
CZMQ_EXPORT zcertstore_t *
    zcertstore_new (char *location, ...);

//  Destroy a certificate store object in memory. Does not affect anything
//  stored on disk.
CZMQ_EXPORT void
    zcertstore_destroy (zcertstore_t **self_p);

//  Look up certificate by public key, returns zcert_t object if found, 
//  else returns NULL. The public key is provided in Z85 text format.
CZMQ_EXPORT zcert_t *
    zcertstore_lookup (zcertstore_t *self, char *public_key);

//  Insert certificate into certificate store in memory. Note that this 
//  does not save the certificate to disk. To do that, use zcert_save()
//  directly on the certificate. Takes ownership of zcert_t object.
CZMQ_EXPORT void
    zcertstore_insert (zcertstore_t *self, zcert_t **cert_p);

//  Print out list of certificates in store to stdout, for debugging
//  purposes.
CZMQ_EXPORT void
    zcertstore_dump (zcertstore_t *self);

//  Self test of this class
CZMQ_EXPORT int
    zcertstore_test (bool verbose);
----

DESCRIPTION
-----------

To authenticate new clients using the ZeroMQ CURVE security mechanism,
we have to check that the client's public key matches a key we know and
accept. There are numerous ways to store accepted client public keys. 
The mechanism CZMQ implements is "certificates" (plain text files) held 
in a "certificate store" (a disk directory). This class works with such
certificate stores, and lets you easily load them from disk, and check
if a given client public key is known or not. The zcert class does the
work of managing a single certificate.

The certificate store can be memory-only, in which case you can load it
yourself by inserting certificate objects one by one, or it can be loaded
from disk, in which case you can add, modify, or remove certificates on
disk at any time, and the store will detect such changes and refresh 
itself automatically. In most applications you won't use this class
directly but through the zauth class, which provides a high-level API for
authentication (and manages certificate stores for you). To actually
create certificates on disk, use the zcert class in code, or the 
tools/makecert.c command line tool, or any text editor. The format of a
certificate file is defined in the zcert man page.

EXAMPLE
-------
.From zcertstore_test method
----
    //  Create temporary directory for test files
#   define TESTDIR ".test_zcertstore"
    zsys_dir_create (TESTDIR);
    
    //  Load certificate store from disk; it will be empty
    zcertstore_t *certstore = zcertstore_new ("%s", TESTDIR);
    
    //  Create a single new certificate and save to disk
    zcert_t *cert = zcert_new ();
    char *client_key = strdup (zcert_public_txt (cert));
    zcert_set_meta (cert, "name", "John Doe");
    zcert_save (cert, TESTDIR "/mycert.txt");
    zcert_destroy (&cert);
    
    //  Check that certificate store refreshes as expected
    cert = zcertstore_lookup (certstore, client_key);
    assert (cert);
    assert (streq (zcert_meta (cert, "name"), "John Doe"));
    free (client_key);
    if (verbose)
        zcertstore_dump (certstore);
        
    zcertstore_destroy (&certstore);
    
    //  Delete all test files
    zdir_t *dir = zdir_new (TESTDIR, NULL);
    zdir_remove (dir, true);
    zdir_destroy (&dir);
----

SEE ALSO
--------
linkczmq:czmq[7]