view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

Signs this message and returns a new [Mail::Make](https://metacpan.org/pod/Mail%3A%3AMake) object whose entity is an RFC 3156 `multipart/signed; protocol="application/pgp-signature"` message with a detached, ASCII-armoured signature.

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](https://metacpan.org/pod/Mail%3A%3AMake) object whose entity is an RFC 3156 `multipart/encrypted` message containing a signed and encrypted OpenPGP payload.

Accepts all options from both ["gpg\_sign"](#gpg_sign) and ["gpg\_encrypt"](#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](https://metacpan.org/pod/Mail%3A%3AMake%3A%3ASMIME), which requires [Crypt::SMIME](https://metacpan.org/pod/Crypt%3A%3ASMIME) (an XS module wrapping OpenSSL `libcrypto`). All certificates and keys must be...

## 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](https://metacpan.org/pod/Crypt%3A%3ASMIME) API accepts only ...

For typical email messages this is not a concern. If you anticipate very large attachments, consider [Mail::Make::GPG](https://metacpan.org/pod/Mail%3A%3AMake%3A%3AGPG) instead, which delegates to the `gpg` command-line tool via [IPC::Run](https://me...

See ["MEMORY USAGE AND LIMITATIONS" in Mail::Make::SMIME](https://metacpan.org/pod/Mail%3A%3AMake%3A%3ASMIME#MEMORY-USAGE-AND-LIMITATIONS) 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.

Optional options:

- `KeyPassword => $string_or_coderef`

    Passphrase for an encrypted private key, or a CODE ref that returns one.

- `CACert => $pem_string_or_path`

    CA certificate to include in the signature for chain verification.

## smime\_sign\_encrypt( %opts )