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