view release on metacpan or  search on metacpan

README.mkdn  view on Meta::CPAN

# 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)](http://man.he.net/man3/zmq_curve_keypair) from [libzmq](http://www.zeromq.org) to generate CURVE
keys.

## ZCerts

ZCert files are `ZPL` format (see [Text::ZPL](https://metacpan.org/pod/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](https://metacpan.org/pod/Convert::Z85)) CURVE
keys.

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

Also see: [http://czmq.zeromq.org/manual:zcert](http://czmq.zeromq.org/manual:zcert)

## ATTRIBUTES

### public\_file

The path to the public ZCert.

Coerced to a [Path::Tiny](https://metacpan.org/pod/Path::Tiny).

Predicate: `has_public_file`

### secret\_file

The path to the secret ZCert; defaults to appending '\_secret' to
["public\_file"](#public_file).

Coerced to a [Path::Tiny](https://metacpan.org/pod/Path::Tiny).

Predicate: `has_secret_file`

### adjust\_permissions

If boolean true, `chmod` will be used to attempt to set the ["secret\_file"](#secret_file)'s
permissions to `0600` after writing.

### ignore\_existing

If boolean true, any existing ["public\_file"](#public_file) / ["secret\_file"](#secret_file) will not be
read; calling a ["commit"](#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.