view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    Required options:

    "KeyId => $fingerprint_or_id"
        Signing key fingerprint or short ID (e.g.
        '35ADBC3AF8355E845139D8965F3C0261CDB2E752').

    Optional options:

    "Digest => $algorithm"
        Hash algorithm. Default: "SHA256".

        Valid values: "SHA256", "SHA384", "SHA512", "SHA1".

    "GpgBin => $path"
        Full path to the "gpg" executable.

    "Passphrase => $string_or_coderef"
        Passphrase to unlock the secret key. May be a plain string or a
        "CODE" reference called with no arguments at signing time. When
        omitted, GnuPG's agent handles passphrase prompting.

  gpg_sign_encrypt( %opts )
    Signs then encrypts this message. Returns a new Mail::Make object whose
    entity is an RFC 3156 "multipart/encrypted" message containing a signed
    and encrypted OpenPGP payload.

    Accepts all options from both "gpg_sign" and "gpg_encrypt".

    Note: "KeyId" and "Recipients" are both required.

    Typical usage:

        # Sign only
        my $signed = $mail->gpg_sign(
            KeyId      => '35ADBC3AF8355E845139D8965F3C0261CDB2E752',
            Passphrase => 'my-passphrase',   # or: sub { MyKeyring::get('gpg') }
        ) || die( $mail->error );
        $signed->smtpsend( Host => 'smtp.example.com' );

        # Encrypt only
        my $encrypted = $mail->gpg_encrypt(
            Recipients => [ 'alice@example.com' ],
        ) || die( $mail->error );

        # Sign then encrypt
        my $protected = $mail->gpg_sign_encrypt(
            KeyId      => '35ADBC3AF8355E845139D8965F3C0261CDB2E752',
            Passphrase => sub { MyKeyring::get_passphrase() },
            Recipients => [ 'alice@example.com', 'bob@example.com' ],
        ) || die( $mail->error );

S/MIME METHODS
    These methods delegate to Mail::Make::SMIME, which requires Crypt::SMIME
    (an XS module wrapping OpenSSL "libcrypto"). All certificates and keys
    must be supplied in PEM format, either as file paths or as PEM strings.

  Memory usage
    All three methods load the complete serialised message into memory
    before performing any cryptographic operation. This is a fundamental
    constraint imposed by two factors: the Crypt::SMIME API accepts only
    Perl strings (no filehandle or streaming interface), and the underlying
    protocols themselves require the entire content to be available before
    the result can be emitted, thus signing requires a complete hash before
    the signature can be appended, and PKCS#7 encryption requires the total
    payload length to be declared in the ASN.1 DER header before any
    ciphertext is written.

    For typical email messages this is not a concern. If you anticipate very
    large attachments, consider Mail::Make::GPG instead, which delegates to
    the "gpg" command-line tool via IPC::Run and can handle arbitrary
    message sizes through temporary files. A future "v0.2.0" of
    Mail::Make::SMIME may add a similar "openssl smime" backend.

    See "MEMORY USAGE AND LIMITATIONS" in Mail::Make::SMIME for a full
    discussion.

  smime_encrypt( %opts )
        $encrypted = $mail->smime_encrypt(
            RecipientCert => $smime_rec_cert,
        );

    Encrypts this message for one or more recipients and returns a new
    "Mail::Make" object whose entity is an RFC 5751 "application/pkcs7-mime;
    smime-type=enveloped-data" message.

    Takes an hash or hash reference of options.

    Required options:

    "RecipientCert => $pem_string_or_path"
        Recipient certificate in PEM format (for encryption). May also be an
        array reference of PEM strings or file paths for multi-recipient
        encryption.

    Optional options:

    "CACert => $pem_string_or_path"
        CA certificate to include for chain verification.

  smime_sign( %opts )
        my $signed = $mail->smime_sign(
            Cert   => $smime_cert,
            Key    => $smime_key,
            CACert => $smime_ca, # optional
        );

    Signs this message with a detached S/MIME signature and returns a new
    "Mail::Make" object whose entity is an RFC 5751 "multipart/signed"
    message.

    The signature is always detached, which allows non-S/MIME-aware clients
    to read the message body.

    Required options:

    "Cert => $pem_string_or_path"
        Signer certificate in PEM format.

    "Key => $pem_string_or_path"
        Private key in PEM format.