1ZCERTSTORE(3) CZMQ Manual ZCERTSTORE(3)
2
6 zcertstore - work with CURVE security certificate stores
7
9 // This is a stable class, and may not change except for emergencies. It
10 // is provided in stable builds.
11 // This class has draft methods, which may change over time. They are not
12 // in stable releases, by default. Use --enable-drafts to enable.
13 // Create a new certificate store from a disk directory, loading and
14 // indexing all certificates in that location. The directory itself may be
15 // absent, and created later, or modified at any time. The certificate store
16 // is automatically refreshed on any zcertstore_lookup() call. If the
17 // location is specified as NULL, creates a pure-memory store, which you
18 // can work with by inserting certificates at runtime.
19 CZMQ_EXPORT zcertstore_t *
20 zcertstore_new (const char *location);
21 // Destroy a certificate store object in memory. Does not affect anything
23 // stored on disk.
24 CZMQ_EXPORT void
25 zcertstore_destroy (zcertstore_t **self_p);
26 // Look up certificate by public key, returns zcert_t object if found,
28 // else returns NULL. The public key is provided in Z85 text format.
29 CZMQ_EXPORT zcert_t *
30 zcertstore_lookup (zcertstore_t *self, const char *public_key);
31 // Insert certificate into certificate store in memory. Note that this
33 // does not save the certificate to disk. To do that, use zcert_save()
34 // directly on the certificate. Takes ownership of zcert_t object.
35 CZMQ_EXPORT void
36 zcertstore_insert (zcertstore_t *self, zcert_t **cert_p);
37 // Print list of certificates in store to logging facility
39 CZMQ_EXPORT void
40 zcertstore_print (zcertstore_t *self);
41 // Self test of this class
43 CZMQ_EXPORT void
44 zcertstore_test (bool verbose);
45 #ifdef CZMQ_BUILD_DRAFT_API
47 // Loaders retrieve certificates from an arbitrary source.
48 typedef void (zcertstore_loader) (
49 zcertstore_t *self);
50 // Destructor for loader state.
52 typedef void (zcertstore_destructor) (
53 void **self_p);
54 // *** Draft method, for development use, may change without warning ***
56 // Override the default disk loader with a custom loader fn.
57 CZMQ_EXPORT void
58 zcertstore_set_loader (zcertstore_t *self, zcertstore_loader loader, zcertstore_destructor destructor, void *state);
59 // *** Draft method, for development use, may change without warning ***
61 // Empty certificate hashtable. This wrapper exists to be friendly to bindings,
62 // which don't usually have access to struct internals.
63 CZMQ_EXPORT void
64 zcertstore_empty (zcertstore_t *self);
65 #endif // CZMQ_BUILD_DRAFT_API
67 Please add '@interface' section in './../src/zcertstore.c'.
68
70 To authenticate new clients using the ZeroMQ CURVE security mechanism,
71 we have to check that the client’s public key matches a key we know and
72 accept. There are numerous ways to store accepted client public keys.
73 The mechanism CZMQ implements is "certificates" (plain text files) held
74 in a "certificate store" (a disk directory). This class works with such
75 certificate stores, and lets you easily load them from disk, and check
76 if a given client public key is known or not. The zcert class does the
77 work of managing a single certificate.
78 The certificate store can be memory-only, in which case you can load it
80 yourself by inserting certificate objects one by one, or it can be
81 loaded from disk, in which case you can add, modify, or remove
82 certificates on disk at any time, and the store will detect such
83 changes and refresh itself automatically. In most applications you
84 won’t use this class directly but through the zauth class, which
85 provides a high-level API for authentication (and manages certificate
86 stores for you). To actually create certificates on disk, use the zcert
87 class in code, or the tools/zmakecert.c command line tool, or any text
88 editor. The format of a certificate file is defined in the zcert man
89 page.
90
92 From zcertstore_test method.
93 // Create temporary directory for test files
95 # define TESTDIR ".test_zcertstore"
96 zsys_dir_create (TESTDIR);
97 // Load certificate store from disk; it will be empty
99 zcertstore_t *certstore = zcertstore_new (TESTDIR);
100 assert (certstore);
101 // Create a single new certificate and save to disk
103 zcert_t *cert = zcert_new ();
104 assert (cert);
105 char *client_key = strdup (zcert_public_txt (cert));
106 assert (client_key);
107 zcert_set_meta (cert, "name", "John Doe");
108 zcert_save (cert, TESTDIR "/mycert.txt");
109 zcert_destroy (&cert);
110 // Check that certificate store refreshes as expected
112 cert = zcertstore_lookup (certstore, client_key);
113 assert (cert);
114 assert (streq (zcert_meta (cert, "name"), "John Doe"));
115 // Test custom loader
117 test_loader_state *state = (test_loader_state *) zmalloc (sizeof (test_loader_state));
118 state->index = 0;
119 zcertstore_set_loader (certstore, s_test_loader, s_test_destructor, (void *)state);
120 #if (ZMQ_VERSION_MAJOR >= 4)
121 cert = zcertstore_lookup (certstore, client_key);
122 assert (cert == NULL);
123 cert = zcertstore_lookup (certstore, "abcdefghijklmnopqrstuvwxyzabcdefghijklmn");
124 assert (cert);
125 #endif
126 free (client_key);
128 if (verbose)
130 zcertstore_print (certstore);
131 zcertstore_destroy (&certstore);
132 // Delete all test files
134 zdir_t *dir = zdir_new (TESTDIR, NULL);
135 assert (dir);
136 zdir_remove (dir, true);
137 zdir_destroy (&dir);
138
141 The czmq manual was written by the authors in the AUTHORS file.
142
144 Main web site:
145 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
147
149 Copyright (c) the Contributors as noted in the AUTHORS file. This file
150 is part of CZMQ, the high-level C binding for 0MQ:
151 http://czmq.zeromq.org. This Source Code Form is subject to the terms
152 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
153 distributed with this file, You can obtain one at
154 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
155 distribution.
156
158 1. zeromq-dev@lists.zeromq.org
159 mailto:zeromq-dev@lists.zeromq.org
160CZMQ 4.0.2 12/31/2016 ZCERTSTORE(3)