You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
309 lines
11 KiB
309 lines
11 KiB
'\" t
|
|
.\" Title: zauth
|
|
.\" Author: [see the "AUTHORS" section]
|
|
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
|
|
.\" Date: 12/31/2016
|
|
.\" Manual: CZMQ Manual
|
|
.\" Source: CZMQ 4.0.2
|
|
.\" Language: English
|
|
.\"
|
|
.TH "ZAUTH" "3" "12/31/2016" "CZMQ 4\&.0\&.2" "CZMQ Manual"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
zauth \- authentication for ZeroMQ security mechanisms
|
|
.SH "SYNOPSIS"
|
|
.sp
|
|
.nf
|
|
#define CURVE_ALLOW_ANY "*"
|
|
|
|
// CZMQ v3 API (for use with zsock, not zsocket, which is deprecated)\&.
|
|
//
|
|
// Create new zauth actor instance\&. This installs authentication on all
|
|
// zsock sockets\&. Until you add policies, all incoming NULL connections are
|
|
// allowed (classic ZeroMQ behaviour), and all PLAIN and CURVE connections
|
|
// are denied:
|
|
//
|
|
// zactor_t *auth = zactor_new (zauth, NULL);
|
|
//
|
|
// Destroy zauth instance\&. This removes authentication and allows all
|
|
// connections to pass, without authentication:
|
|
//
|
|
// zactor_destroy (&auth);
|
|
//
|
|
// Note that all zauth commands are synchronous, so your application always
|
|
// waits for a signal from the actor after each command\&.
|
|
//
|
|
// Enable verbose logging of commands and activity\&. Verbose logging can help
|
|
// debug non\-trivial authentication policies:
|
|
//
|
|
// zstr_send (auth, "VERBOSE");
|
|
// zsock_wait (auth);
|
|
//
|
|
// Allow (whitelist) a list of IP addresses\&. For NULL, all clients from
|
|
// these addresses will be accepted\&. For PLAIN and CURVE, they will be
|
|
// allowed to continue with authentication\&. You can call this method
|
|
// multiple times to whitelist more IP addresses\&. If you whitelist one
|
|
// or more addresses, any non\-whitelisted addresses are treated as
|
|
// blacklisted:
|
|
//
|
|
// zstr_sendx (auth, "ALLOW", "127\&.0\&.0\&.1", "127\&.0\&.0\&.2", NULL);
|
|
// zsock_wait (auth);
|
|
//
|
|
// Deny (blacklist) a list of IP addresses\&. For all security mechanisms,
|
|
// this rejects the connection without any further authentication\&. Use
|
|
// either a whitelist, or a blacklist, not not both\&. If you define both
|
|
// a whitelist and a blacklist, only the whitelist takes effect:
|
|
//
|
|
// zstr_sendx (auth, "DENY", "192\&.168\&.0\&.1", "192\&.168\&.0\&.2", NULL);
|
|
// zsock_wait (auth);
|
|
//
|
|
// Configure PLAIN authentication using a plain\-text password file\&. You can
|
|
// modify the password file at any time; zauth will reload it automatically
|
|
// if modified externally:
|
|
//
|
|
// zstr_sendx (auth, "PLAIN", filename, NULL);
|
|
// zsock_wait (auth);
|
|
//
|
|
// Configure CURVE authentication, using a directory that holds all public
|
|
// client certificates, i\&.e\&. their public keys\&. The certificates must be in
|
|
// zcert_save format\&. You can add and remove certificates in that directory
|
|
// at any time\&. To allow all client keys without checking, specify
|
|
// CURVE_ALLOW_ANY for the directory name:
|
|
//
|
|
// zstr_sendx (auth, "CURVE", directory, NULL);
|
|
// zsock_wait (auth);
|
|
//
|
|
// Configure GSSAPI authentication, using an underlying mechanism (usually
|
|
// Kerberos) to establish a secure context and perform mutual authentication:
|
|
//
|
|
// zstr_sendx (auth, "GSSAPI", NULL);
|
|
// zsock_wait (auth);
|
|
//
|
|
// This is the zauth constructor as a zactor_fn:
|
|
CZMQ_EXPORT void
|
|
zauth (zsock_t *pipe, void *certstore);
|
|
|
|
// Selftest
|
|
CZMQ_EXPORT void
|
|
zauth_test (bool verbose);
|
|
Please add \*(Aq@interface\*(Aq section in \*(Aq\&./\&.\&./src/zauth\&.c\*(Aq\&.
|
|
.fi
|
|
.SH "DESCRIPTION"
|
|
.sp
|
|
A zauth actor takes over authentication for all incoming connections in its context\&. You can whitelist or blacklist peers based on IP address, and define policies for securing PLAIN, CURVE, and GSSAPI connections\&.
|
|
.sp
|
|
This class replaces zauth_v2, and is meant for applications that use the CZMQ v3 API (meaning, zsock)\&.
|
|
.SH "EXAMPLE"
|
|
.PP
|
|
\fBFrom zauth_test method\fR.
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
// Create temporary directory for test files
|
|
# define TESTDIR "\&.test_zauth"
|
|
zsys_dir_create (TESTDIR);
|
|
|
|
// Check there\*(Aqs no authentication
|
|
zsock_t *server = zsock_new (ZMQ_PULL);
|
|
assert (server);
|
|
zsock_t *client = zsock_new (ZMQ_PUSH);
|
|
assert (client);
|
|
bool success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
|
|
// Install the authenticator
|
|
zactor_t *auth = zactor_new (zauth, NULL);
|
|
assert (auth);
|
|
if (verbose) {
|
|
zstr_sendx (auth, "VERBOSE", NULL);
|
|
zsock_wait (auth);
|
|
}
|
|
// Check there\*(Aqs no authentication on a default NULL server
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
|
|
// When we set a domain on the server, we switch on authentication
|
|
// for NULL sockets, but with no policies, the client connection
|
|
// will be allowed\&.
|
|
zsock_set_zap_domain (server, "global");
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
|
|
// Blacklist 127\&.0\&.0\&.1, connection should fail
|
|
zsock_set_zap_domain (server, "global");
|
|
zstr_sendx (auth, "DENY", "127\&.0\&.0\&.1", NULL);
|
|
zsock_wait (auth);
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (!success);
|
|
|
|
// Whitelist our address, which overrides the blacklist
|
|
zsock_set_zap_domain (server, "global");
|
|
zstr_sendx (auth, "ALLOW", "127\&.0\&.0\&.1", NULL);
|
|
zsock_wait (auth);
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
|
|
// Try PLAIN authentication
|
|
zsock_set_plain_server (server, 1);
|
|
zsock_set_plain_username (client, "admin");
|
|
zsock_set_plain_password (client, "Password");
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (!success);
|
|
|
|
FILE *password = fopen (TESTDIR "/password\-file", "w");
|
|
assert (password);
|
|
fprintf (password, "admin=Password\en");
|
|
fclose (password);
|
|
zsock_set_plain_server (server, 1);
|
|
zsock_set_plain_username (client, "admin");
|
|
zsock_set_plain_password (client, "Password");
|
|
zstr_sendx (auth, "PLAIN", TESTDIR "/password\-file", NULL);
|
|
zsock_wait (auth);
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
|
|
zsock_set_plain_server (server, 1);
|
|
zsock_set_plain_username (client, "admin");
|
|
zsock_set_plain_password (client, "Bogus");
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (!success);
|
|
|
|
if (zsys_has_curve ()) {
|
|
// Try CURVE authentication
|
|
// We\*(Aqll create two new certificates and save the client public
|
|
// certificate on disk; in a real case we\*(Aqd transfer this securely
|
|
// from the client machine to the server machine\&.
|
|
zcert_t *server_cert = zcert_new ();
|
|
assert (server_cert);
|
|
zcert_t *client_cert = zcert_new ();
|
|
assert (client_cert);
|
|
const char *server_key = zcert_public_txt (server_cert);
|
|
|
|
// Test without setting\-up any authentication
|
|
zcert_apply (server_cert, server);
|
|
zcert_apply (client_cert, client);
|
|
zsock_set_curve_server (server, 1);
|
|
zsock_set_curve_serverkey (client, server_key);
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (!success);
|
|
|
|
// Test CURVE_ALLOW_ANY
|
|
zcert_apply (server_cert, server);
|
|
zcert_apply (client_cert, client);
|
|
zsock_set_curve_server (server, 1);
|
|
zsock_set_curve_serverkey (client, server_key);
|
|
zstr_sendx (auth, "CURVE", CURVE_ALLOW_ANY, NULL);
|
|
zsock_wait (auth);
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
|
|
// Test full client authentication using certificates
|
|
zcert_set_meta (client_cert, "Hello", "%s", "World!");
|
|
zcert_apply (server_cert, server);
|
|
zcert_apply (client_cert, client);
|
|
zsock_set_curve_server (server, 1);
|
|
zsock_set_curve_serverkey (client, server_key);
|
|
zcert_save_public (client_cert, TESTDIR "/mycert\&.txt");
|
|
zstr_sendx (auth, "CURVE", TESTDIR, NULL);
|
|
zsock_wait (auth);
|
|
success = s_can_connect (&server, &client, false);
|
|
assert (success);
|
|
|
|
#if (ZMQ_VERSION >= ZMQ_MAKE_VERSION (4, 1, 0))
|
|
// Test send/recv certificate metadata
|
|
zframe_t *frame = zframe_recv (server);
|
|
assert (frame != NULL);
|
|
const char *meta = zframe_meta (frame, "Hello");
|
|
assert (meta != NULL);
|
|
assert (streq (meta, "World!"));
|
|
zframe_destroy (&frame);
|
|
s_renew_sockets(&server, &client);
|
|
#endif
|
|
|
|
zcert_destroy (&server_cert);
|
|
zcert_destroy (&client_cert);
|
|
|
|
// Test custom zcertstore
|
|
zcertstore_t *certstore = zcertstore_new (NULL);
|
|
zcertstore_set_loader (certstore, s_test_loader, NULL, NULL);
|
|
zactor_destroy(&auth);
|
|
auth = zactor_new (zauth, certstore);
|
|
assert (auth);
|
|
if (verbose) {
|
|
zstr_sendx (auth, "VERBOSE", NULL);
|
|
zsock_wait (auth);
|
|
}
|
|
|
|
byte public_key [32] = { 105, 76, 150, 58, 214, 191, 218, 65, 50, 172,
|
|
131, 188, 247, 211, 136, 170, 227, 26, 57, 170,
|
|
185, 63, 246, 225, 177, 230, 12, 8, 134, 136,
|
|
105, 106 };
|
|
byte secret_key [32] = { 245, 217, 172, 73, 106, 28, 195, 17, 218, 132,
|
|
135, 209, 99, 240, 98, 232, 7, 137, 244, 100,
|
|
242, 23, 29, 114, 70, 223, 83, 1, 113, 207,
|
|
132, 149 };
|
|
zcert_t *shared_cert = zcert_new_from (public_key, secret_key);
|
|
assert (shared_cert);
|
|
zcert_apply (shared_cert, server);
|
|
zcert_apply (shared_cert, client);
|
|
zsock_set_curve_server (server, 1);
|
|
zsock_set_curve_serverkey (client, "x?T*N/1Y{8goubv{Ts}#&#f}TXJ//DVe#D2HkoLU");
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
zcert_destroy (&shared_cert);
|
|
}
|
|
// Remove the authenticator and check a normal connection works
|
|
zactor_destroy (&auth);
|
|
success = s_can_connect (&server, &client, true);
|
|
assert (success);
|
|
|
|
zsock_destroy (&client);
|
|
zsock_destroy (&server);
|
|
|
|
// Delete all test files
|
|
zdir_t *dir = zdir_new (TESTDIR, NULL);
|
|
assert (dir);
|
|
zdir_remove (dir, true);
|
|
zdir_destroy (&dir);
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.SH "AUTHORS"
|
|
.sp
|
|
The czmq manual was written by the authors in the AUTHORS file\&.
|
|
.SH "RESOURCES"
|
|
.sp
|
|
Main web site: \m[blue]\fB\%\fR\m[]
|
|
.sp
|
|
Report bugs to the email <\m[blue]\fBzeromq\-dev@lists\&.zeromq\&.org\fR\m[]\&\s-2\u[1]\d\s+2>
|
|
.SH "COPYRIGHT"
|
|
.sp
|
|
Copyright (c) the Contributors as noted in the AUTHORS file\&. This file is part of CZMQ, the high\-level C binding for 0MQ: http://czmq\&.zeromq\&.org\&. This Source Code Form is subject to the terms of the Mozilla Public License, v\&. 2\&.0\&. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla\&.org/MPL/2\&.0/\&. LICENSE included with the czmq distribution\&.
|
|
.SH "NOTES"
|
|
.IP " 1." 4
|
|
zeromq-dev@lists.zeromq.org
|
|
.RS 4
|
|
\%mailto:zeromq-dev@lists.zeromq.org
|
|
.RE
|
|
|