1ZCERTSTORE(3) CZMQ Manual ZCERTSTORE(3)
2
6 zcertstore - Class for 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 // *** Draft method, for development use, may change without warning ***
67 // Return a list of all the certificates in the store.
68 // The caller takes ownership of the zlistx_t object and is responsible
69 // for destroying it. The caller does not take ownership of the zcert_t
70 // objects.
71 // Caller owns return value and must destroy it when done.
72 CZMQ_EXPORT zlistx_t *
73 zcertstore_certs (zcertstore_t *self);
74 #endif // CZMQ_BUILD_DRAFT_API
76 Please add '@interface' section in './../src/zcertstore.c'.
77
79 To authenticate new clients using the ZeroMQ CURVE security mechanism,
80 we have to check that the client’s public key matches a key we know and
81 accept. There are numerous ways to store accepted client public keys.
82 The mechanism CZMQ implements is "certificates" (plain text files) held
83 in a "certificate store" (a disk directory). This class works with such
84 certificate stores, and lets you easily load them from disk, and check
85 if a given client public key is known or not. The zcert class does the
86 work of managing a single certificate.
87 The certificate store can be memory-only, in which case you can load it
89 yourself by inserting certificate objects one by one, or it can be
90 loaded from disk, in which case you can add, modify, or remove
91 certificates on disk at any time, and the store will detect such
92 changes and refresh itself automatically. In most applications you
93 won’t use this class directly but through the zauth class, which
94 provides a high-level API for authentication (and manages certificate
95 stores for you). To actually create certificates on disk, use the zcert
96 class in code, or the tools/zmakecert.c command line tool, or any text
97 editor. The format of a certificate file is defined in the zcert man
98 page.
99
101 From zcertstore_test method.
102 const char *SELFTEST_DIR_RW = "src/selftest-rw";
104 const char *testbasedir = ".test_zcertstore";
106 const char *testfile = "mycert.txt";
107 char *basedirpath = NULL; // subdir in a test, under SELFTEST_DIR_RW
108 char *filepath = NULL; // pathname to testfile in a test, in dirpath
109 basedirpath = zsys_sprintf ("%s/%s", SELFTEST_DIR_RW, testbasedir);
111 assert (basedirpath);
112 filepath = zsys_sprintf ("%s/%s", basedirpath, testfile);
113 assert (filepath);
114 // Make sure old aborted tests do not hinder us
116 zdir_t *dir = zdir_new (basedirpath, NULL);
117 if (dir) {
118 zdir_remove (dir, true);
119 zdir_destroy (&dir);
120 }
121 zsys_file_delete (filepath);
122 zsys_dir_delete (basedirpath);
123 // Create temporary directory for test files
125 zsys_dir_create (basedirpath);
126 // Load certificate store from disk; it will be empty
128 zcertstore_t *certstore = zcertstore_new (basedirpath);
129 assert (certstore);
130 // Create a single new certificate and save to disk
132 zcert_t *cert = zcert_new ();
133 assert (cert);
134 char *client_key = strdup (zcert_public_txt (cert));
135 assert (client_key);
136 zcert_set_meta (cert, "name", "John Doe");
137 zcert_save (cert, filepath);
138 zcert_destroy (&cert);
139 // Check that certificate store refreshes as expected
141 cert = zcertstore_lookup (certstore, client_key);
142 assert (cert);
143 assert (streq (zcert_meta (cert, "name"), "John Doe"));
144 #ifdef CZMQ_BUILD_DRAFT_API
146 // DRAFT-API: Security
147 // Iterate through certs
148 zlistx_t *certs = zcertstore_certs(certstore);
149 cert = (zcert_t *) zlistx_first(certs);
150 int cert_count = 0;
151 while (cert) {
152 assert (streq (zcert_meta (cert, "name"), "John Doe"));
153 cert = (zcert_t *) zlistx_next(certs);
154 cert_count++;
155 }
156 assert(cert_count==1);
157 zlistx_destroy(&certs);
158 #endif
159 // Test custom loader
161 test_loader_state *state = (test_loader_state *) zmalloc (sizeof (test_loader_state));
162 state->index = 0;
163 zcertstore_set_loader (certstore, s_test_loader, s_test_destructor, (void *)state);
164 #if (ZMQ_VERSION_MAJOR >= 4)
165 cert = zcertstore_lookup (certstore, client_key);
166 assert (cert == NULL);
167 cert = zcertstore_lookup (certstore, "abcdefghijklmnopqrstuvwxyzabcdefghijklmn");
168 assert (cert);
169 #endif
170 freen (client_key);
172 if (verbose)
174 zcertstore_print (certstore);
175 zcertstore_destroy (&certstore);
176 // Delete all test files
178 dir = zdir_new (basedirpath, NULL);
179 assert (dir);
180 zdir_remove (dir, true);
181 zdir_destroy (&dir);
182 zstr_free (&basedirpath);
184 zstr_free (&filepath);
185 #if defined (__WINDOWS__)
187 zsys_shutdown();
188 #endif
189
192 The czmq manual was written by the authors in the AUTHORS file.
193
195 Main web site:
196 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
198
200 Copyright (c) the Contributors as noted in the AUTHORS file. This file
201 is part of CZMQ, the high-level C binding for 0MQ:
202 http://czmq.zeromq.org. This Source Code Form is subject to the terms
203 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
204 distributed with this file, You can obtain one at
205 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
206 distribution.
207
209 1. zeromq-dev@lists.zeromq.org
210 mailto:zeromq-dev@lists.zeromq.org
211CZMQ 4.2.0 01/28/2020 ZCERTSTORE(3)