Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ZAUTH_V2(3)			  CZMQ Manual			   ZAUTH_V2(3)

NAME
       zauth_v2	- authentication for ZeroMQ servers (deprecated)

SYNOPSIS
       #ifndef CURVE_ALLOW_ANY
       #   define CURVE_ALLOW_ANY "*"
       #endif

       //  Constructor
       //  Install authentication for the specified context. Returns a new zauth
       //  object that you can use to configure	authentication.	Note that until	you
       //  add policies, all incoming NULL connections are allowed (classic ZeroMQ
       //  behaviour), and all PLAIN and CURVE connections are denied. If there	was
       //  an error during initialization, returns NULL.
       CZMQ_EXPORT zauth_t *
	   zauth_new (zctx_t *ctx);

       //  Destructor
       CZMQ_EXPORT void
	   zauth_destroy (zauth_t **self_p);

       //  Allow (whitelist) a single IP address. For NULL, all	clients	from this
       //  address will	be accepted. For PLAIN and CURVE, they will be allowed to
       //  continue with authentication. You can call this method multiple times
       //  to whitelist	multiple IP addresses. If you whitelist	a single address,
       //  any non-whitelisted addresses are treated as	blacklisted.
       CZMQ_EXPORT void
	   zauth_allow (zauth_t	*self, const char *address);

       //  Deny	(blacklist) a single IP	address. 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.
       CZMQ_EXPORT void
	   zauth_deny (zauth_t *self, const char *address);

       //  Configure PLAIN authentication for a	given domain. PLAIN authentication
       //  uses	a plain-text password file. To cover all domains, use "*". You can
       //  modify the password file at any time; it is reloaded	automatically.
       CZMQ_EXPORT void
	   zauth_configure_plain (zauth_t *self, const char *domain, const char	*filename);

       //  Configure CURVE authentication for a	given domain. CURVE authentication
       //  uses	a directory that holds all public client certificates, i.e. their
       //  public keys.	The certificates must be in zcert_save () format. To cover
       //  all domains,	use "*". 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 location.
       CZMQ_EXPORT void
	   zauth_configure_curve (zauth_t *self, const char *domain, const char	*location);

       //  Configure GSSAPI authentication for a given domain. GSSAPI authentication
       //  uses	an underlying mechanism	(usually Kerberos) to establish	a secure
       //  context and perform mutual authentication. To cover all domains, use	"*".
       CZMQ_EXPORT void
	   zauth_configure_gssapi (zauth_t *self, char *domain);

       //  Enable verbose tracing of commands and activity
       CZMQ_EXPORT void
	   zauth_set_verbose (zauth_t *self, bool verbose);

       //  Selftest
       CZMQ_EXPORT void
	   zauth_v2_test (bool verbose);

DESCRIPTION
       A zauth object takes over authentication	for all	incoming connections
       in its context.

       This class is deprecated	in CZMQ	v3; it works together with zctx,
       zsocket,	and other deprecated V2	classes. New applications should use
       the V3 zauth interface, based on	zactor,	together with the zsock	class
       for sockets.

EXAMPLE
       From zauth_v2_test method.

	   //  Create temporary	directory for test files
	   #   define TESTDIR ".test_zauth"
	   zsys_dir_create (TESTDIR);

	   //  Install the authenticator
	   zctx_t *ctx = zctx_new ();
	   assert (ctx);
	   zauth_t *auth = zauth_new (ctx);
	   assert (auth);
	   zauth_set_verbose (auth, verbose);

	   //  A default NULL connection should	always success,	and not
	   //  go through our authentication infrastructure at all.
	   void	*server	= zsocket_new (ctx, ZMQ_PUSH);
	   assert (server);
	   void	*client	= zsocket_new (ctx, ZMQ_PULL);
	   assert (client);
	   bool	success	= s_can_connect	(ctx, &server, &client);
	   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.
	   zsocket_set_zap_domain (server, "global");
	   success = s_can_connect (ctx, &server, &client);
	   assert (success);

	   //  Blacklist 127.0.0.1, connection should fail
	   zsocket_set_zap_domain (server, "global");
	   zauth_deny (auth, "127.0.0.1");
	   success = s_can_connect (ctx, &server, &client);
	   assert (!success);

	   //  Whitelist our address, which overrides the blacklist
	   zsocket_set_zap_domain (server, "global");
	   zauth_allow (auth, "127.0.0.1");
	   success = s_can_connect (ctx, &server, &client);
	   assert (success);

	   //  Try PLAIN authentication
	   zsocket_set_plain_server (server, 1);
	   zsocket_set_plain_username (client, "admin");
	   zsocket_set_plain_password (client, "Password");
	   success = s_can_connect (ctx, &server, &client);
	   assert (!success);

	   FILE	*password = fopen (TESTDIR "/password-file", "w");
	   assert (password);
	   fprintf (password, "admin=Password\n");
	   fclose (password);
	   zsocket_set_plain_server (server, 1);
	   zsocket_set_plain_username (client, "admin");
	   zsocket_set_plain_password (client, "Password");
	   zauth_configure_plain (auth,	"*", TESTDIR "/password-file");
	   success = s_can_connect (ctx, &server, &client);
	   assert (success);

	   zsocket_set_plain_server (server, 1);
	   zsocket_set_plain_username (client, "admin");
	   zsocket_set_plain_password (client, "Bogus");
	   success = s_can_connect (ctx, &server, &client);
	   assert (!success);

	   if (zsys_has_curve ()) {
	       //  Try CURVE authentication
	       //  We'll create	two new	certificates and save the client public
	       //  certificate on disk;	in a real case we'd 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);
	       char *server_key	= zcert_public_txt (server_cert);

	       //  Test	without	setting-up any authentication
	       zcert_apply (server_cert, server);
	       zcert_apply (client_cert, client);
	       zsocket_set_curve_server	(server, 1);
	       zsocket_set_curve_serverkey (client, server_key);
	       success = s_can_connect (ctx, &server, &client);
	       assert (!success);

	       //  Test	CURVE_ALLOW_ANY
	       zcert_apply (server_cert, server);
	       zcert_apply (client_cert, client);
	       zsocket_set_curve_server	(server, 1);
	       zsocket_set_curve_serverkey (client, server_key);
	       zauth_configure_curve (auth, "*", CURVE_ALLOW_ANY);
	       success = s_can_connect (ctx, &server, &client);
	       assert (success);

	       //  Test	full client authentication using certificates
	       zcert_apply (server_cert, server);
	       zcert_apply (client_cert, client);
	       zsocket_set_curve_server	(server, 1);
	       zsocket_set_curve_serverkey (client, server_key);
	       zcert_save_public (client_cert, TESTDIR "/mycert.txt");
	       zauth_configure_curve (auth, "*", TESTDIR);
	       success = s_can_connect (ctx, &server, &client);
	       assert (success);

	       zcert_destroy (&server_cert);
	       zcert_destroy (&client_cert);
	   }
	   //  Remove the authenticator	and check a normal connection works
	   zauth_destroy (&auth);
	   success = s_can_connect (ctx, &server, &client);
	   assert (success);

	   zctx_destroy	(&ctx);

	   //  Delete all test files
	   zdir_t *dir = zdir_new (TESTDIR, NULL);
	   assert (dir);
	   zdir_remove (dir, true);
	   zdir_destroy	(&dir);

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

RESOURCES
       Main web	site:

       Report bugs to the email	<zeromq-dev@lists.zeromq.org[1]>

COPYRIGHT
       Copyright (c) 1991-2012 iMatix Corporation -- http://www.imatix.com
       Copyright other 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.

NOTES
	1. zeromq-dev@lists.zeromq.org
	   mailto:zeromq-dev@lists.zeromq.org

CZMQ 3.0.1			  06/01/2015			   ZAUTH_V2(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | AUTHORS | RESOURCES | COPYRIGHT | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=zauth_v2&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help