Module: auth#

Utilities for ZAP authentication.

To run authentication in a background thread, see zmq.auth.thread. For integration with the tornado eventloop, see zmq.auth.ioloop. For integration with the asyncio event loop, see zmq.auth.asyncio.

Authentication examples are provided in the pyzmq codebase, under /examples/security/.

New in version 14.1.


class zmq.auth.Authenticator(context: Optional[zmq.sugar.context.Context] = None, encoding: str = 'utf-8', log: Optional[Any] = None)#

Implementation of ZAP authentication for zmq connections.

This authenticator class does not register with an event loop. As a result, you will need to manually call handle_zap_message:

auth = zmq.Authenticator()
while True:

Alternatively, you can register auth.zap_socket with a poller.

Since many users will want to run ZAP in a way that does not block the main thread, other authentication classes (such as zmq.auth.thread) are provided.


  • libzmq provides four levels of security: default NULL (which the Authenticator does not see), and authenticated NULL, PLAIN, CURVE, and GSSAPI, which the Authenticator can see.

  • until you add policies, all incoming NULL connections are allowed. (classic ZeroMQ behavior), and all PLAIN and CURVE connections are denied.

  • GSSAPI requires no configuration.

allow(*addresses: str) None#

Allow (whitelist) IP address(es).

Connections from addresses not in the whitelist will be rejected.

  • For NULL, all clients from this address will be accepted.

  • For real auth setups, they will be allowed to continue with authentication.

whitelist is mutually exclusive with blacklist.

allow_any: bool#
blacklist: Set[str]#
certs: Dict[str, Dict[bytes, Any]]#
configure_curve(domain: str = '*', location: Union[str, os.PathLike] = '.') None#

Configure CURVE authentication for a given domain.

CURVE authentication uses a directory that holds all public client certificates, i.e. their public keys.

To cover all domains, use “*”.

You can add and remove certificates in that directory at any time. configure_curve must be called every time certificates are added or removed, in order to update the Authenticator’s state

To allow all client keys without checking, specify CURVE_ALLOW_ANY for the location.

configure_curve_callback(domain: str = '*', credentials_provider: Optional[Any] = None) None#

Configure CURVE authentication for a given domain.

CURVE authentication using a callback function validating the client public key according to a custom mechanism, e.g. checking the key against records in a db. credentials_provider is an object of a class which implements a callback method accepting two parameters (domain and key), e.g.:

class CredentialsProvider(object):

    def __init__(self):
        ...e.g. db connection

    def callback(self, domain, key):
        valid = ...lookup key and/or domain in db
        if valid:
  'Authorizing: {0}, {1}'.format(domain, key))
            return True
            logging.warning('NOT Authorizing: {0}, {1}'.format(domain, key))
            return False

To cover all domains, use “*”.

To allow all client keys without checking, specify CURVE_ALLOW_ANY for the location.

configure_gssapi(domain: str = '*', location: Optional[str] = None) None#

Configure GSSAPI authentication

Currently this is a no-op because there is nothing to configure with GSSAPI.

configure_plain(domain: str = '*', passwords: Optional[Dict[str, str]] = None) None#

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.

context: zmq.sugar.context.Context#
credentials_providers: Dict[str, Any]#
curve_user_id(client_public_key: bytes) str#

Return the User-Id corresponding to a CURVE client’s public key

Default implementation uses the z85-encoding of the public key.

Override to define a custom mapping of public key : user-id

This is only called on successful authentication.


client_public_key (bytes) – The client public key used for the given message


user_id – The user ID as text

Return type


deny(*addresses: str) None#

Deny (blacklist) IP address(es).

Addresses not in the blacklist will be allowed to continue with authentication.

Blacklist is mutually exclusive with whitelist.

encoding: str#
handle_zap_message(msg: List[bytes])#

Perform ZAP authentication

log: Any#
passwords: Dict[str, Dict[str, str]]#
start() None#

Create and bind the ZAP socket

stop() None#

Close the ZAP socket

whitelist: Set[str]#
zap_socket: zmq.sugar.socket.Socket#


zmq.auth.create_certificates(key_dir: Union[str, os.PathLike], name: str, metadata: Optional[Dict[str, str]] = None) Tuple[str, str]#

Create zmq certificates.

Returns the file paths to the public and secret certificate files.

zmq.auth.load_certificate(filename: Union[str, os.PathLike]) Tuple[bytes, Optional[bytes]]#

Load public and secret key from a zmq certificate.

Returns (public_key, secret_key)

If the certificate file only contains the public key, secret_key will be None.

If there is no public key found in the file, ValueError will be raised.

zmq.auth.load_certificates(directory: Union[str, os.PathLike] = '.') Dict[bytes, bool]#

Load public keys from all certificates in a directory