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

NAME

6       zcert - Class for work with CURVE security certificates
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 and initialize a new certificate in memory
14       CZMQ_EXPORT zcert_t *
15           zcert_new (void);
16
17       //  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
21       //  Load certificate from file
22       CZMQ_EXPORT zcert_t *
23           zcert_load (const char *filename);
24
25       //  Destroy a certificate in memory
26       CZMQ_EXPORT void
27           zcert_destroy (zcert_t **self_p);
28
29       //  Return public part of key pair as 32-byte binary string
30       CZMQ_EXPORT const byte *
31           zcert_public_key (zcert_t *self);
32
33       //  Return secret part of key pair as 32-byte binary string
34       CZMQ_EXPORT const byte *
35           zcert_secret_key (zcert_t *self);
36
37       //  Return public part of key pair as Z85 armored string
38       CZMQ_EXPORT const char *
39           zcert_public_txt (zcert_t *self);
40
41       //  Return secret part of key pair as Z85 armored string
42       CZMQ_EXPORT const char *
43           zcert_secret_txt (zcert_t *self);
44
45       //  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
49       //  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
54       //  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
59       //  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
64       //  Save public certificate only to file for persistent storage
65       CZMQ_EXPORT int
66           zcert_save_public (zcert_t *self, const char *filename);
67
68       //  Save secret certificate only to file for persistent storage
69       CZMQ_EXPORT int
70           zcert_save_secret (zcert_t *self, const char *filename);
71
72       //  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
78       //  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
84       //  Return true if two certificates have the same keys
85       CZMQ_EXPORT bool
86           zcert_eq (zcert_t *self, zcert_t *compare);
87
88       //  Print certificate contents to stdout
89       CZMQ_EXPORT void
90           zcert_print (zcert_t *self);
91
92       //  Self test of this class
93       CZMQ_EXPORT void
94           zcert_test (bool verbose);
95
96       #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
102       //  *** 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
107       #endif // CZMQ_BUILD_DRAFT_API
108       Please add '@interface' section in './../src/zcert.c'.
109

DESCRIPTION

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

EXAMPLE

128       From zcert_test method.
129
130           const char *SELFTEST_DIR_RW = "src/selftest-rw";
131
132           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
138           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
145           // 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
154           //  Create temporary directory for test files
155           zsys_dir_create (basedirpath);
156
157           //  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
171           //  Check the dup and eq methods
172           zcert_t *shadow = zcert_dup (cert);
173           assert (zcert_eq (cert, shadow));
174           zcert_destroy (&shadow);
175
176           //  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
181           //  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
187           //  Delete secret certificate, load public one
188           int rc = zsys_file_delete (filepath_s);
189           assert (rc == 0);
190           shadow = zcert_load (filepath);
191
192           //  32-byte null key encodes as 40 '0' characters
193           assert (streq (zcert_secret_txt (shadow), FORTY_ZEROES));
194
195           #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
203           zcert_destroy (&shadow);
204           zcert_destroy (&cert);
205
206           //  Delete all test files
207           dir = zdir_new (basedirpath, NULL);
208           assert (dir);
209           zdir_remove (dir, true);
210           zdir_destroy (&dir);
211
212           zstr_free (&basedirpath);
213           zstr_free (&filepath);
214           zstr_free (&filepath_s);
215
216           #if defined (__WINDOWS__)
217           zsys_shutdown();
218           #endif
219
220

AUTHORS

222       The czmq manual was written by the authors in the AUTHORS file.
223

RESOURCES

225       Main web site:
226
227       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

NOTES

239        1. zeromq-dev@lists.zeromq.org
240           mailto:zeromq-dev@lists.zeromq.org
241
242
243
244CZMQ 4.2.1                        07/20/2022                          ZCERT(3)
Impressum