NAME

Crypt::ZCert - Manage ZeroMQ 4+ ZCert CURVE keys and certificates

SYNOPSIS

  use Crypt::ZCert;

  my $zcert = Crypt::ZCert->new(
    public_file => "/foo/mycert",
    # Optionally specify a secret file;
    # defaults to "${public_file}_secret":
    secret_file => "/foo/sekrit",
  );

  # Loaded from existing 'secret_file' if present,
  # generated via libzmq's zmq_curve_keypair(3) if not:
  my $pubkey = $zcert->public_key;
  my $seckey = $zcert->secret_key;

  # ... or as the original Z85:
  my $pub_z85 = $zcert->public_key_z85;
  my $sec_z85 = $zcert->secret_key_z85;

  # Alter metadata:
  $zcert->metadata->set(foo => 'bar');

  # Commit certificate to disk
  # (as '/foo/mycert', '/foo/mycert_secret' pair)
  # Without '->new(adjust_permissions => 0)', _secret becomes chmod 0600:
  $zcert->commit;

  # Retrieve a public/secret ZCert file pair (as ZPL) without writing:
  my $certdata = $zcert->export_zcert;
  my $pubdata  = $certdata->public;
  my $secdata  = $certdata->secret;

  # Retrieve a newly-generated key pair (no certificate):
  my $keypair = Crypt::ZCert->new->generate_keypair;
  my $pub_z85 = $keypair->public;
  my $sec_z85 = $keypair->secret;

DESCRIPTION

A module for managing ZeroMQ "ZCert" certificates and calling zmq_curve_keypair(3) from libzmq to generate CURVE keys.

ZCerts

ZCert files are ZPL format (see Text::ZPL) with two subsections, curve and metadata. The curve section specifies public-key and secret-key names whose values are Z85-encoded (see Convert::Z85) CURVE keys.

On disk, the certificate is stored as two files; a "public_file" (containing only the public key) and a "secret_file" (containing both keys).

Also see: http://czmq.zeromq.org/manual:zcert

ATTRIBUTES

public_file

The path to the public ZCert.

Coerced to a Path::Tiny.

Predicate: has_public_file

secret_file

The path to the secret ZCert; defaults to appending '_secret' to "public_file".

Coerced to a Path::Tiny.

Predicate: has_secret_file

adjust_permissions

If boolean true, chmod will be used to attempt to set the "secret_file"'s permissions to 0600 after writing.

ignore_existing

If boolean true, any existing "public_file" / "secret_file" will not be read; calling a "commit" will cause a forcible key regeneration and rewrite of the existing certificate files.

(Obviously, this should be used with caution.)

public_key

The public key, as a binary string.

If none is specified at construction-time and no "secret_file" exists, a new key pair is generated via zmq_curve_keypair(3) and "secret_key" is set appropriately.

secret_key

The secret key, as a binary string.

If none is specified at construction-time and no "secret_file" exists, a new key pair is generated via zmq_curve_keypair(3) and "public_key" is set appropriately.

public_key_z85

The "public_key", as a Z85-encoded ASCII string (see Convert::Z85).

secret_key_z85

The "secret_key", as a Z85-encoded ASCII string (see Convert::Z85).

metadata

  # Get value:
  my $foo = $zcert->metadata->get('foo');

  # Iterate over metadata:
  my $iter = $zcert->metadata->iter;
  while ( my ($key, $val) = $iter->() ) {
    print "$key -> $val\n";
  }

  # Update metadata & write to disk:
  $zcert->metadata->set(foo => 'bar');
  $zcert->commit;

The certificate metadata, as a List::Objects::WithUtils::Hash.

If the object is constructed from an existing "public_file" / "secret_file", metadata key/value pairs in the loaded file will override key/value pairs that were previously set in a passed metadata hash.

zmq_soname

The libzmq dynamic library name; by default, the newest available library is chosen.

METHODS

commit

Write "public_file" and "secret_file" to disk.

export_zcert

Generate and return the current ZCert; the certificate is represented as a struct-like object with two accessors, public and secret, containing ZPL-encoded ASCII text:

  my $certdata = $zcert->export_zcert;
  my $public_zpl = $certdata->public;
  my $secret_zpl = $certdata->secret;

generate_keypair

Generate and return a new key pair via zmq_curve_keypair(3); if called as an instance method, the current ZCert object remains unchanged.

The returned key pair is a struct-like object with two accessors, public and secret:

  my $keypair = $zcert->generate_keypair;
  my $pub_z85 = $keypair->public;
  my $sec_z85 = $keypair->secret;

Can be called as either a class or instance method.

SEE ALSO

Text::ZPL

Convert::Z85

POEx::ZMQ

ZMQ::FFI

AUTHOR

Jon Portnoy <avenj@cobaltirc.org>