1ZCERTSTORE(3)                     CZMQ Manual                    ZCERTSTORE(3)
2
3
4

NAME

6       zcertstore - Class for work with CURVE security certificate stores
7

SYNOPSIS

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
22       //  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
27       //  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
32       //  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
38       //  Print list of certificates in store to logging facility
39       CZMQ_EXPORT void
40           zcertstore_print (zcertstore_t *self);
41
42       //  Self test of this class
43       CZMQ_EXPORT void
44           zcertstore_test (bool verbose);
45
46       #ifdef CZMQ_BUILD_DRAFT_API
47       // Loaders retrieve certificates from an arbitrary source.
48       typedef void (zcertstore_loader) (
49           zcertstore_t *self);
50
51       // Destructor for loader state.
52       typedef void (zcertstore_destructor) (
53           void **self_p);
54
55       //  *** 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
60       //  *** 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
66       //  *** 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
75       //  *** 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
80       #endif // CZMQ_BUILD_DRAFT_API
81       Please add '@interface' section in './../src/zcertstore.c'.
82

DESCRIPTION

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
93       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

EXAMPLE

106       From zcertstore_test method.
107
108           const char *SELFTEST_DIR_RW = "src/selftest-rw";
109
110           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
115           basedirpath = zsys_sprintf ("%s/%s", SELFTEST_DIR_RW, testbasedir);
116           assert (basedirpath);
117           filepath = zsys_sprintf ("%s/%s", basedirpath, testfile);
118           assert (filepath);
119
120           // 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
129           //  Create temporary directory for test files
130           zsys_dir_create (basedirpath);
131
132           //  Load certificate store from disk; it will be empty
133           zcertstore_t *certstore = zcertstore_new (basedirpath);
134           assert (certstore);
135
136           //  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
145           //  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
150           #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
165           //  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
176           freen (client_key);
177
178           if (verbose)
179               zcertstore_print (certstore);
180           zcertstore_destroy (&certstore);
181
182           //  Delete all test files
183           dir = zdir_new (basedirpath, NULL);
184           assert (dir);
185           zdir_remove (dir, true);
186           zdir_destroy (&dir);
187
188           zstr_free (&basedirpath);
189           zstr_free (&filepath);
190
191           #if defined (__WINDOWS__)
192           zsys_shutdown();
193           #endif
194
195

AUTHORS

197       The czmq manual was written by the authors in the AUTHORS file.
198

RESOURCES

200       Main web site:
201
202       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

NOTES

214        1. zeromq-dev@lists.zeromq.org
215           mailto:zeromq-dev@lists.zeromq.org
216
217
218
219CZMQ 4.2.1                        10/31/2019                     ZCERTSTORE(3)
Impressum