# 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.

If none is specified at construction-time and no ["secret\_file"](#secret_file) exists, a new
key pair is generated via [zmq\_curve\_keypair(3)](http://man.he.net/man3/zmq_curve_keypair) and ["secret\_key"](#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"](#secret_file) exists, a new
key pair is generated via [zmq\_curve\_keypair(3)](http://man.he.net/man3/zmq_curve_keypair) and ["public\_key"](#public_key) is set
appropriately.

### public\_key\_z85

The ["public\_key"](#public_key), as a `Z85`-encoded ASCII string (see [Convert::Z85](https://metacpan.org/pod/Convert::Z85)).

### secret\_key\_z85

The ["secret\_key"](#secret_key), as a `Z85`-encoded ASCII string (see [Convert::Z85](https://metacpan.org/pod/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](https://metacpan.org/pod/List::Objects::WithUtils::Hash).

If the object is constructed from an existing ["public\_file"](#public_file) /
["secret\_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"](#public_file) and ["secret\_file"](#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)](http://man.he.net/man3/zmq_curve_keypair); 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](https://metacpan.org/pod/Text::ZPL)

[Convert::Z85](https://metacpan.org/pod/Convert::Z85)

[POEx::ZMQ](https://metacpan.org/pod/POEx::ZMQ)

[ZMQ::FFI](https://metacpan.org/pod/ZMQ::FFI)

# AUTHOR

Jon Portnoy <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.