# 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