1ZAUTH(3) CZMQ Manual ZAUTH(3)
2
6 zauth - authentication for ZeroMQ security mechanisms
7
9 #define CURVE_ALLOW_ANY "*"
10 // CZMQ v3 API (for use with zsock, not zsocket, which is deprecated).
12 //
13 // Create new zauth actor instance. This installs authentication on all
14 // zsock sockets. Until you add policies, all incoming NULL connections are
15 // allowed (classic ZeroMQ behaviour), and all PLAIN and CURVE connections
16 // are denied:
17 //
18 // zactor_t *auth = zactor_new (zauth, NULL);
19 //
20 // Destroy zauth instance. This removes authentication and allows all
21 // connections to pass, without authentication:
22 //
23 // zactor_destroy (&auth);
24 //
25 // Note that all zauth commands are synchronous, so your application always
26 // waits for a signal from the actor after each command.
27 //
28 // Enable verbose logging of commands and activity. Verbose logging can help
29 // debug non-trivial authentication policies:
30 //
31 // zstr_send (auth, "VERBOSE");
32 // zsock_wait (auth);
33 //
34 // Allow (whitelist) a list of IP addresses. For NULL, all clients from
35 // these addresses will be accepted. For PLAIN and CURVE, they will be
36 // allowed to continue with authentication. You can call this method
37 // multiple times to whitelist more IP addresses. If you whitelist one
38 // or more addresses, any non-whitelisted addresses are treated as
39 // blacklisted:
40 //
41 // zstr_sendx (auth, "ALLOW", "127.0.0.1", "127.0.0.2", NULL);
42 // zsock_wait (auth);
43 //
44 // Deny (blacklist) a list of IP addresses. For all security mechanisms,
45 // this rejects the connection without any further authentication. Use
46 // either a whitelist, or a blacklist, not not both. If you define both
47 // a whitelist and a blacklist, only the whitelist takes effect:
48 //
49 // zstr_sendx (auth, "DENY", "192.168.0.1", "192.168.0.2", NULL);
50 // zsock_wait (auth);
51 //
52 // Configure PLAIN authentication using a plain-text password file. You can
53 // modify the password file at any time; zauth will reload it automatically
54 // if modified externally:
55 //
56 // zstr_sendx (auth, "PLAIN", filename, NULL);
57 // zsock_wait (auth);
58 //
59 // Configure CURVE authentication, using a directory that holds all public
60 // client certificates, i.e. their public keys. The certificates must be in
61 // zcert_save format. You can add and remove certificates in that directory
62 // at any time. To allow all client keys without checking, specify
63 // CURVE_ALLOW_ANY for the directory name:
64 //
65 // zstr_sendx (auth, "CURVE", directory, NULL);
66 // zsock_wait (auth);
67 //
68 // Configure GSSAPI authentication, using an underlying mechanism (usually
69 // Kerberos) to establish a secure context and perform mutual authentication:
70 //
71 // zstr_sendx (auth, "GSSAPI", NULL);
72 // zsock_wait (auth);
73 //
74 // This is the zauth constructor as a zactor_fn:
75 CZMQ_EXPORT void
76 zauth (zsock_t *pipe, void *certstore);
77 // Selftest
79 CZMQ_EXPORT void
80 zauth_test (bool verbose);
81 Please add '@interface' section in './../src/zauth.c'.
82
84 A zauth actor takes over authentication for all incoming connections in
85 its context. You can whitelist or blacklist peers based on IP address,
86 and define policies for securing PLAIN, CURVE, and GSSAPI connections.
87 This class replaces zauth_v2, and is meant for applications that use
89 the CZMQ v3 API (meaning, zsock).
90
92 From zauth_test method.
93 // Create temporary directory for test files
95 # define TESTDIR ".test_zauth"
96 zsys_dir_create (TESTDIR);
97 // Check there's no authentication
99 zsock_t *server = zsock_new (ZMQ_PULL);
100 assert (server);
101 zsock_t *client = zsock_new (ZMQ_PUSH);
102 assert (client);
103 bool success = s_can_connect (&server, &client, true);
104 assert (success);
105 // Install the authenticator
107 zactor_t *auth = zactor_new (zauth, NULL);
108 assert (auth);
109 if (verbose) {
110 zstr_sendx (auth, "VERBOSE", NULL);
111 zsock_wait (auth);
112 }
113 // Check there's no authentication on a default NULL server
114 success = s_can_connect (&server, &client, true);
115 assert (success);
116 // When we set a domain on the server, we switch on authentication
118 // for NULL sockets, but with no policies, the client connection
119 // will be allowed.
120 zsock_set_zap_domain (server, "global");
121 success = s_can_connect (&server, &client, true);
122 assert (success);
123 // Blacklist 127.0.0.1, connection should fail
125 zsock_set_zap_domain (server, "global");
126 zstr_sendx (auth, "DENY", "127.0.0.1", NULL);
127 zsock_wait (auth);
128 success = s_can_connect (&server, &client, true);
129 assert (!success);
130 // Whitelist our address, which overrides the blacklist
132 zsock_set_zap_domain (server, "global");
133 zstr_sendx (auth, "ALLOW", "127.0.0.1", NULL);
134 zsock_wait (auth);
135 success = s_can_connect (&server, &client, true);
136 assert (success);
137 // Try PLAIN authentication
139 zsock_set_plain_server (server, 1);
140 zsock_set_plain_username (client, "admin");
141 zsock_set_plain_password (client, "Password");
142 success = s_can_connect (&server, &client, true);
143 assert (!success);
144 FILE *password = fopen (TESTDIR "/password-file", "w");
146 assert (password);
147 fprintf (password, "admin=Password\n");
148 fclose (password);
149 zsock_set_plain_server (server, 1);
150 zsock_set_plain_username (client, "admin");
151 zsock_set_plain_password (client, "Password");
152 zstr_sendx (auth, "PLAIN", TESTDIR "/password-file", NULL);
153 zsock_wait (auth);
154 success = s_can_connect (&server, &client, true);
155 assert (success);
156 zsock_set_plain_server (server, 1);
158 zsock_set_plain_username (client, "admin");
159 zsock_set_plain_password (client, "Bogus");
160 success = s_can_connect (&server, &client, true);
161 assert (!success);
162 if (zsys_has_curve ()) {
164 // Try CURVE authentication
165 // We'll create two new certificates and save the client public
166 // certificate on disk; in a real case we'd transfer this securely
167 // from the client machine to the server machine.
168 zcert_t *server_cert = zcert_new ();
169 assert (server_cert);
170 zcert_t *client_cert = zcert_new ();
171 assert (client_cert);
172 const char *server_key = zcert_public_txt (server_cert);
173 // Test without setting-up any authentication
175 zcert_apply (server_cert, server);
176 zcert_apply (client_cert, client);
177 zsock_set_curve_server (server, 1);
178 zsock_set_curve_serverkey (client, server_key);
179 success = s_can_connect (&server, &client, true);
180 assert (!success);
181 // Test CURVE_ALLOW_ANY
183 zcert_apply (server_cert, server);
184 zcert_apply (client_cert, client);
185 zsock_set_curve_server (server, 1);
186 zsock_set_curve_serverkey (client, server_key);
187 zstr_sendx (auth, "CURVE", CURVE_ALLOW_ANY, NULL);
188 zsock_wait (auth);
189 success = s_can_connect (&server, &client, true);
190 assert (success);
191 // Test full client authentication using certificates
193 zcert_set_meta (client_cert, "Hello", "%s", "World!");
194 zcert_apply (server_cert, server);
195 zcert_apply (client_cert, client);
196 zsock_set_curve_server (server, 1);
197 zsock_set_curve_serverkey (client, server_key);
198 zcert_save_public (client_cert, TESTDIR "/mycert.txt");
199 zstr_sendx (auth, "CURVE", TESTDIR, NULL);
200 zsock_wait (auth);
201 success = s_can_connect (&server, &client, false);
202 assert (success);
203 #if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (4, 1, 0))
205 // Test send/recv certificate metadata
206 zframe_t *frame = zframe_recv (server);
207 assert (frame != NULL);
208 const char *meta = zframe_meta (frame, "Hello");
209 assert (meta != NULL);
210 assert (streq (meta, "World!"));
211 zframe_destroy (&frame);
212 s_renew_sockets(&server, &client);
213 #endif
214 zcert_destroy (&server_cert);
216 zcert_destroy (&client_cert);
217 // Test custom zcertstore
219 zcertstore_t *certstore = zcertstore_new (NULL);
220 zcertstore_set_loader (certstore, s_test_loader, NULL, NULL);
221 zactor_destroy(&auth);
222 auth = zactor_new (zauth, certstore);
223 assert (auth);
224 if (verbose) {
225 zstr_sendx (auth, "VERBOSE", NULL);
226 zsock_wait (auth);
227 }
228 byte public_key [32] = { 105, 76, 150, 58, 214, 191, 218, 65, 50, 172,
230 131, 188, 247, 211, 136, 170, 227, 26, 57, 170,
231 185, 63, 246, 225, 177, 230, 12, 8, 134, 136,
232 105, 106 };
233 byte secret_key [32] = { 245, 217, 172, 73, 106, 28, 195, 17, 218, 132,
234 135, 209, 99, 240, 98, 232, 7, 137, 244, 100,
235 242, 23, 29, 114, 70, 223, 83, 1, 113, 207,
236 132, 149 };
237 zcert_t *shared_cert = zcert_new_from (public_key, secret_key);
238 assert (shared_cert);
239 zcert_apply (shared_cert, server);
240 zcert_apply (shared_cert, client);
241 zsock_set_curve_server (server, 1);
242 zsock_set_curve_serverkey (client, "x?T*N/1Y{8goubv{Ts}#&#f}TXJ//DVe#D2HkoLU");
243 success = s_can_connect (&server, &client, true);
244 assert (success);
245 zcert_destroy (&shared_cert);
246 }
247 // Remove the authenticator and check a normal connection works
248 zactor_destroy (&auth);
249 success = s_can_connect (&server, &client, true);
250 assert (success);
251 zsock_destroy (&client);
253 zsock_destroy (&server);
254 // Delete all test files
256 zdir_t *dir = zdir_new (TESTDIR, NULL);
257 assert (dir);
258 zdir_remove (dir, true);
259 zdir_destroy (&dir);
260
263 The czmq manual was written by the authors in the AUTHORS file.
264
266 Main web site:
267 Report bugs to the email <zeromq-dev@lists.zeromq.org[1]>
269
271 Copyright (c) the Contributors as noted in the AUTHORS file. This file
272 is part of CZMQ, the high-level C binding for 0MQ:
273 http://czmq.zeromq.org. This Source Code Form is subject to the terms
274 of the Mozilla Public License, v. 2.0. If a copy of the MPL was not
275 distributed with this file, You can obtain one at
276 http://mozilla.org/MPL/2.0/. LICENSE included with the czmq
277 distribution.
278
280 1. zeromq-dev@lists.zeromq.org
281 mailto:zeromq-dev@lists.zeromq.org
282CZMQ 4.0.2 12/31/2016 ZAUTH(3)