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