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);
----