view release on metacpan or  search on metacpan

lib/Mail/Make.pm  view on Meta::CPAN

Signing key fingerprint or short ID (e.g. C<'35ADBC3AF8355E845139D8965F3C0261CDB2E752'>).

=back

Optional options:

=over 4

=item C<< Digest => $algorithm >>

Hash algorithm. Default: C<SHA256>.

Valid values: C<SHA256>, C<SHA384>, C<SHA512>, C<SHA1>.

=item C<< GpgBin => $path >>

Full path to the C<gpg> executable.

=item C<< Passphrase => $string_or_coderef >>

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

=back

=head2 gpg_sign_encrypt( %opts )

Signs then encrypts this message. Returns a new L<Mail::Make> object whose entity is an RFC 3156 C<multipart/encrypted> message containing a signed and encrypted OpenPGP payload.

Accepts all options from both L</gpg_sign> and L</gpg_encrypt>.

B<Note:> C<KeyId> and C<Recipients> are both required.

B<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 );

=head1 S/MIME METHODS

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

=head2 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 L<Crypt::SMIME> API accepts only Perl strings (no filehandle or streaming i...

For typical email messages this is not a concern. If you anticipate very large attachments, consider L<Mail::Make::GPG> instead, which delegates to the C<gpg> command-line tool via L<IPC::Run> and can handle arbitrary message sizes through temporary ...

See L<Mail::Make::SMIME/"MEMORY USAGE AND LIMITATIONS"> for a full discussion.

=head2 smime_encrypt( %opts )

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

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

Takes an hash or hash reference of options.

Required options:

=over 4

=item C<< 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.

=back

Optional options:

=over 4

=item C<< CACert => $pem_string_or_path >>

CA certificate to include for chain verification.

=back

=head2 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 C<Mail::Make> object whose entity is an RFC 5751 C<multipart/signed> message.

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

Required options:

=over 4

=item C<< Cert => $pem_string_or_path >>

Signer certificate in PEM format.

=item C<< Key => $pem_string_or_path >>

Private key in PEM format.

=back