1ZCERT(3) CZMQ Manual ZCERT(3)
2
6 zcert - Class for work with CURVE security certificates
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 and initialize a new certificate in memory
14 CZMQ_EXPORT zcert_t *
15 zcert_new (void);
16 // Accepts public/secret key pair from caller
18 CZMQ_EXPORT zcert_t *
19 zcert_new_from (const byte *public_key, const byte *secret_key);
20 // Load certificate from file
22 CZMQ_EXPORT zcert_t *
23 zcert_load (const char *filename);
24 // Destroy a certificate in memory
26 CZMQ_EXPORT void
27 zcert_destroy (zcert_t **self_p);
28 // Return public part of key pair as 32-byte binary string
30 CZMQ_EXPORT const byte *
31 zcert_public_key (zcert_t *self);
32 // Return secret part of key pair as 32-byte binary string
34 CZMQ_EXPORT const byte *
35 zcert_secret_key (zcert_t *self);
36 // Return public part of key pair as Z85 armored string
38 CZMQ_EXPORT const char *
39 zcert_public_txt (zcert_t *self);
40 // Return secret part of key pair as Z85 armored string
42 CZMQ_EXPORT const char *
43 zcert_secret_txt (zcert_t *self);
44 // Set certificate metadata from formatted string.
46 CZMQ_EXPORT void
47 zcert_set_meta (zcert_t *self, const char *name, const char *format, ...) CHECK_PRINTF (3);
48 // Get metadata value from certificate; if the metadata value doesn't
50 // exist, returns NULL.
51 CZMQ_EXPORT const char *
52 zcert_meta (zcert_t *self, const char *name);
53 // Get list of metadata fields from certificate. Caller is responsible for
55 // destroying list. Caller should not modify the values of list items.
56 CZMQ_EXPORT zlist_t *
57 zcert_meta_keys (zcert_t *self);
58 // Save full certificate (public + secret) to file for persistent storage
60 // This creates one public file and one secret file (filename + "_secret").
61 CZMQ_EXPORT int
62 zcert_save (zcert_t *self, const char *filename);
63 // Save public certificate only to file for persistent storage
65 CZMQ_EXPORT int
66 zcert_save_public (zcert_t *self, const char *filename);
67 // Save secret certificate only to file for persistent storage
69 CZMQ_EXPORT int
70 zcert_save_secret (zcert_t *self, const char *filename);
71 // Apply certificate to socket, i.e. use for CURVE security on socket.
73 // If certificate was loaded from public file, the secret key will be
74 // undefined, and this certificate will not work successfully.
75 CZMQ_EXPORT void
76 zcert_apply (zcert_t *self, void *socket);
77 // Return copy of certificate; if certificate is NULL or we exhausted
79 // heap memory, returns NULL.
80 // Caller owns return value and must destroy it when done.
81 CZMQ_EXPORT zcert_t *
82 zcert_dup (zcert_t *self);
83 // Return true if two certificates have the same keys
85 CZMQ_EXPORT bool
86 zcert_eq (zcert_t *self, zcert_t *compare);
87 // Print certificate contents to stdout
89 CZMQ_EXPORT void
90 zcert_print (zcert_t *self);
91 // Self test of this class
93 CZMQ_EXPORT void
94 zcert_test (bool verbose);
95 #ifdef CZMQ_BUILD_DRAFT_API
97 // *** Draft method, for development use, may change without warning ***
98 // Accepts public/secret key text pair from caller
99 CZMQ_EXPORT zcert_t *
100 zcert_new_from_txt (const char *public_txt, const char *secret_txt);
101 // *** Draft method, for development use, may change without warning ***
103 // Unset certificate metadata.
104 CZMQ_EXPORT void
105 zcert_unset_meta (zcert_t *self, const char *name);
106 #endif // CZMQ_BUILD_DRAFT_API
108 Please add '@interface' section in './../src/zcert.c'.
109
111 The zcert class provides a way to create and work with security
112 certificates for the ZMQ CURVE mechanism. A certificate contains a
113 public + secret key pair, plus metadata. It can be used as a temporary
114 object in memory, or persisted to disk. On disk, a certificate is
115 stored as two files. One is public and contains only the public key.
116 The second is secret and contains both keys. The two have the same
117 filename, with the secret file adding "_secret". To exchange
118 certificates, send the public file via some secure route. Certificates
119 are not signed but are text files that can be verified by eye.
120 Certificates are stored in the ZPL (ZMQ RFC 4) format. They have two
122 sections, "metadata" and "curve". The first contains a list of name =
123 value pairs, one per line. Values may be enclosed in quotes. The curve
124 section has a public-key = keyvalue and, for secret certificates, a
125 secret-key = keyvalue line. The keyvalue is a Z85-encoded CURVE key.
126
128 From zcert_test method.
129 const char *SELFTEST_DIR_RW = "src/selftest-rw";
131 const char *testbasedir = ".test_zcert";
133 const char *testfile = "mycert.txt";
134 char *basedirpath = NULL; // subdir in a test, under SELFTEST_DIR_RW
135 char *filepath = NULL; // pathname to testfile in a test, in dirpath
136 char *filepath_s = NULL; // pathname to testfile+secret in a test, in dirpath
137 basedirpath = zsys_sprintf ("%s/%s", SELFTEST_DIR_RW, testbasedir);
139 assert (basedirpath);
140 filepath = zsys_sprintf ("%s/%s", basedirpath, testfile);
141 assert (filepath);
142 filepath_s = zsys_sprintf ("%s_secret", filepath);
143 assert (filepath_s);
144 // Make sure old aborted tests do not hinder us
146 zdir_t *dir = zdir_new (basedirpath, NULL);
147 if (dir) {
148 zdir_remove (dir, true);
149 zdir_destroy (&dir);
150 }
151 zsys_file_delete (filepath);
152 zsys_dir_delete (basedirpath);
153 // Create temporary directory for test files
155 zsys_dir_create (basedirpath);
156 // Create a simple certificate with metadata
158 zcert_t *cert = zcert_new ();
159 assert (cert);
160 zcert_set_meta (cert, "email", "ph@imatix.com");
161 zcert_set_meta (cert, "name", "Pieter Hintjens");
162 zcert_set_meta (cert, "organization", "iMatix Corporation");
163 zcert_set_meta (cert, "version", "%d", 1);
164 zcert_set_meta (cert, "delete_me", "now");
165 zcert_unset_meta (cert, "delete_me");
166 assert (streq (zcert_meta (cert, "email"), "ph@imatix.com"));
167 zlist_t *keys = zcert_meta_keys (cert);
168 assert (zlist_size (keys) == 4);
169 zlist_destroy (&keys);
170 // Check the dup and eq methods
172 zcert_t *shadow = zcert_dup (cert);
173 assert (zcert_eq (cert, shadow));
174 zcert_destroy (&shadow);
175 // Check we can save and load certificate
177 zcert_save (cert, filepath);
178 assert (zsys_file_exists (filepath));
179 assert (zsys_file_exists (filepath_s));
180 // Load certificate, will in fact load secret one
182 shadow = zcert_load (filepath);
183 assert (shadow);
184 assert (zcert_eq (cert, shadow));
185 zcert_destroy (&shadow);
186 // Delete secret certificate, load public one
188 int rc = zsys_file_delete (filepath_s);
189 assert (rc == 0);
190 shadow = zcert_load (filepath);
191 // 32-byte null key encodes as 40 '0' characters
193 assert (streq (zcert_secret_txt (shadow), FORTY_ZEROES));
194 #ifdef CZMQ_BUILD_DRAFT_API
196 // test zcert_from_txt
197 zcert_t *cert2 = zcert_new_from_txt(cert->public_txt, cert->secret_txt);
198 assert (cert2);
199 assert (zcert_eq (cert, cert2));
200 zcert_destroy(&cert2);
201 #endif
202 zcert_destroy (&shadow);
204 zcert_destroy (&cert);
205 // Delete all test files
207 dir = zdir_new (basedirpath, NULL);
208 assert (dir);
209 zdir_remove (dir, true);
210 zdir_destroy (&dir);
211 zstr_free (&basedirpath);
213 zstr_free (&filepath);
214 zstr_free (&filepath_s);
215 #if defined (__WINDOWS__)
217 zsys_shutdown();
218 #endif
219
222 The czmq manual was written by the authors in the AUTHORS file.
223
225 Main web site:
226 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
228
230 Copyright (c) the Contributors as noted in the AUTHORS file. This file
231 is part of CZMQ, the high-level C binding for 0MQ:
232 http://czmq.zeromq.org. This Source Code Form is subject to the terms
233 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
234 distributed with this file, You can obtain one at
235 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
236 distribution.
237
239 1. zeromq-dev@lists.zeromq.org
240 mailto:zeromq-dev@lists.zeromq.org
241CZMQ 4.2.1 07/19/2023 ZCERT(3)