Crypt::OpenPGP::Certificate(3)

NAME
Crypt::OpenPGP::Certificate - PGP Key certificate

SYNOPSIS
    use Crypt::OpenPGP::Certificate;

    my $dsa_secret_key = Crypt::OpenPGP::Key::Secret->new( 'DSA' );
    my $cert = Crypt::OpenPGP::Certificate->new(
        Key => $dsa_secret_key,
        Version => 4,
        Passphrase => 'foobar',
    );
    my $serialized = $cert->save;

    # Unlock the locked certificate (using the passphrase from above)
    $cert->unlock( 'foobar' );

DESCRIPTION
Crypt::OpenPGP::Certificate encapsulates a PGP key certificate for any underlying public-key algorithm, for public and secret keys, and for master keys and subkeys. All of these scenarios are handled by the same Certificate class.

A Crypt::OpenPGP::Certificate object wraps around a Crypt::OpenPGP::Key object; the latter implements all public-key algorithm-specific functionality, while the certificate layer manages some meta-data about the key, as well as the mechanisms for locking and unlocking a secret key (using a passphrase).

USAGE

  Crypt::OpenPGP::Certificate->new( %arg )
Constructs a new PGP key certificate object and returns that object. If no arguments are provided in %arg, the certificate is empty; this is used in parse, for example, to construct an empty object, then fill it with the data in the buffer.

%arg can contain:

•   Key

    The public/secret key object, an object of type Crypt::OpenPGP::Key.

    This argument is required (for a non-empty certificate).

•   Version

    The certificate packet version, as defined in the OpenPGP RFC. The two valid values are 3 and 4.

    This argument is optional; if not provided the default is to produce version 4 certificates. You may wish to override this for compatibility with older versions of PGP.

•   Subkey

    A boolean flag: if true, indicates that this certificate is a subkey, not a master key.

    This argument is optional; the default value is 0.

•   Validity

    The number of days that this certificate is valid. This argument only applies when creating a version 3 certificate; version 4 certificates hold this information in a signature.

    This argument is optional; the default value is 0, which means that the certificate never expires.

•   Passphrase

    If you are creating a certificate for a secret key--indicated by whether or not the Key (above) is a secret key--you will need to lock it (that is, encrypt the secret part of the key). The string provided in Passphrase is used as the passphrase to lock the key.

    This argument is required if the certificate holds a secret key.

•   Cipher

    Specifies the symmetric cipher to use when locking (encrypting) the secret part of a secret key. Valid values are any supported symmetric cipher names, which can be found in Crypt::OpenPGP::Cipher.

    This argument is optional; if not specified, "DES3" is used.

  $cert->save
Serializes the Crypt::OpenPGP::Certificate object $cert into a string of octets, suitable for saving in a keyring file.

  Crypt::OpenPGP::Certificate->parse($buffer)
Given $buffer, a Crypt::OpenPGP::Buffer object holding (or with offset point to) a certificate packet, returns a new object of type Crypt::OpenPGP::Certificate, initialized with the data from the buffer.

  $cert->lock($passphrase)
Locks the secret key data by encrypting that data with $passphrase.

Returns true on success, "undef" on failure; in the case of failure call errstr to get the error message.

  $cert->unlock($passphrase)
Uses the passphrase $passphrase to unlock (decrypt) the secret part of the key.

Returns true on success, "undef" on failure; in the case of failure call errstr to get the error message.

  $cert->fingerprint
Returns the key fingerprint as an octet string.

  $cert->fingerprint_hex
Returns the key fingerprint as a hex string.

  $cert->fingerprint_words
Returns the key fingerprint as a list of English words, where each word represents one octet from the fingerprint. See Crypt::OpenPGP::Words for more details about the encoding.

  $cert->key_id
Returns the key ID.

  $cert->key_id_hex
Returns the key ID as a hex string.

  $cert->key
Returns the algorithm-specific portion of the certificate, the public or secret key object (an object of type Crypt::OpenPGP::Key).

  $cert->public_cert
Returns a public version of the certificate, with a public key. If the certificate was already public, the same certificate is returned; if it was a secret certificate, a new Crypt::OpenPGP::Certificate object is created, and the secret key is made into a public version of the key.

  $cert->version
Returns the version of the certificate (3 or 4).

  $cert->timestamp
Returns the creation date and time (in epoch time).

  $cert->validity
Returns the number of days that the certificate is valid for version 3 keys.

  $cert->is_secret
Returns true if the certificate holds a secret key, false otherwise.

  $cert->is_protected
Returns true if the certificate is locked, false otherwise.

  $cert->is_subkey
Returns true if the certificate is a subkey, false otherwise.

  $cert->can_encrypt
Returns true if the public key algorithm for the certificate $cert can perform encryption/decryption, false otherwise.

  $cert->can_sign
Returns true if the public key algorithm for the certificate $cert can perform signing/verification, false otherwise.

AUTHOR & COPYRIGHTS
Please see the Crypt::OpenPGP manpage for author, copyright, and license information.