.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SMIME 3pm"
.TH SMIME 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Crypt::SMIME \- S/MIME message signing, verification, encryption and decryption
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Crypt::SMIME;
\&
\&  my $plain = <<\*(AqEOF\*(Aq;
\&  From: alice@example.org
\&  To: bob@example.com
\&  Subject: Crypt::SMIME test
\&
\&  This is a test mail. Please ignore...
\&  EOF
\&
\&  my $smime = Crypt::SMIME\->new();
\&  $smime\->setPrivateKey($privkey, $crt);
\&  # $smime\->setPublicKey([$icacert]); # if need be.
\&
\&  my $signed = $smime\->sign($plain);
\&  print $signed;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides a class for handling S/MIME messages. It can sign, verify,
encrypt and decrypt messages. It requires libcrypto (<http://www.openssl.org>).
.SH "EXPORTS"
.IX Header "EXPORTS"
No symbols are exported by default. The following symbols can
optionally be exported:
.ie n .IP """NO_CHECK_CERTIFICATE""" 4
.el .IP "\f(CWNO_CHECK_CERTIFICATE\fR" 4
.IX Item "NO_CHECK_CERTIFICATE"
See \*(L"\fBcheck()\fR\*(R".
.ie n .IP """FORMAT_SMIME""" 4
.el .IP "\f(CWFORMAT_SMIME\fR" 4
.IX Item "FORMAT_SMIME"
.PD 0
.ie n .IP """FORMAT_ASN1""" 4
.el .IP "\f(CWFORMAT_ASN1\fR" 4
.IX Item "FORMAT_ASN1"
.ie n .IP """FORMAT_PEM""" 4
.el .IP "\f(CWFORMAT_PEM\fR" 4
.IX Item "FORMAT_PEM"
.PD
See \*(L"\fBextractCertificates()\fR\*(R".
.ie n .IP """:constants""" 4
.el .IP "\f(CW:constants\fR" 4
.IX Item ":constants"
Export all of the above.
.SH "METHODS"
.IX Header "METHODS"
.IP "\fBnew()\fR" 4
.IX Item "new()"
.Vb 1
\&  my $smime = Crypt::SMIME\->new();
.Ve
.Sp
The constructor takes no arguments.
.IP "\fBsetPrivateKey()\fR" 4
.IX Item "setPrivateKey()"
.Vb 2
\&  $smime\->setPrivateKey($key, $crt);
\&  $smime\->setPrivateKey($key, $crt, $password);
.Ve
.Sp
Store a private key and its X.509 certificate into the instance. The private key
will be used for signing and decryption. Note that this method takes a \s-1PEM\s0
string, not a name of a file which contains a key or a certificate.
.Sp
The private key and certificate must be encoded in \s-1PEM\s0 format. The method dies
if it fails to load the key.
.IP "\fBsetPrivateKeyPkcs12()\fR" 4
.IX Item "setPrivateKeyPkcs12()"
.Vb 2
\&  $smime\->setPrivateKeyPkcs12($key, $pkcs12);
\&  $smime\->setPrivateKeyPkcs12($key, $pkcs12, $password);
.Ve
.Sp
Load a private key and its X.509 certificate from PKCS#12 into the instance.
The private key will be used for signing and decryption. The method dies if
it fails to load \s-1PKCS12.\s0
.IP "\fBsetPublicKey()\fR" 4
.IX Item "setPublicKey()"
.Vb 2
\&  $smime\->setPublicKey($crt);
\&  $smime\->setPublicKey([$crt1, $crt2, ...]);
.Ve
.Sp
Store one or more X.509 certificates into the instance. The public keys will be
used for signing, verification and encryption.
.Sp
The certificates must be encoded in \s-1PEM\s0 format. The method dies if it fails to
load the certificates.
.IP "\fBsetPublicKeyStore()\fR" 4
.IX Item "setPublicKeyStore()"
.Vb 1
\&  $smime\->setPublicKeyStore($path, ...);
.Ve
.Sp
Set the paths of file or directory containing trusted certificates.
The certificate stores will be used for verification.
.Sp
The method dies if it fails to load the certificate stores.
.IP "\fBsign()\fR" 4
.IX Item "sign()"
.Vb 1
\&  $signed_mime = $smime\->sign($raw_mime);
.Ve
.Sp
Sign a \s-1MIME\s0 message and return an S/MIME message. The signature is always
detached.
.Sp
Any headers except \f(CW\*(C`Content\-*\*(C'\fR, \f(CW\*(C`MIME\-*\*(C'\fR and \f(CW\*(C`Subject\*(C'\fR will be moved to the
top-level of the \s-1MIME\s0 message. \f(CW\*(C`Subject\*(C'\fR header will be copied to both of the
plain text part and the top-level for mail clients which can't properly handle
S/MIME messages.
.Sp
The resulting message will be tainted if any of the original \s-1MIME\s0
message, the private key or its certificate is tainted.
.IP "\fBsignonly()\fR" 4
.IX Item "signonly()"
.Vb 1
\&  $sign = $smime\->signonly($prepared_mime);
.Ve
.Sp
Generate a signature from a \s-1MIME\s0 message. The resulting signature is encoded in
Base64. The \s-1MIME\s0 message to be passed to this method should be preprocessed
beforehand by the \fBprepareSmimeMessage()\fR method. You would rarely need to call
this method directly.
.Sp
The resulting signature will be tainted if any of the original \s-1MIME\s0
message, the private key or its certificate is tainted.
.IP "\fBprepareSmimeMessage()\fR" 4
.IX Item "prepareSmimeMessage()"
.Vb 2
\&  ($prepared_mime, $outer_header)
\&      = $smime\->prepareSmimeMessage($source_mime);
.Ve
.Sp
Preprocess a \s-1MIME\s0 message to be signed. \f(CW$prepared_mime\fR will be a string
containing the processed \s-1MIME\s0 message, and \f(CW$outer_header\fR will be a string
that is a list of headers to be moved to the top-level of \s-1MIME\s0 message. You
would rarely need to call this method directly.
.Sp
The entity body of \f(CW$source_mime\fR will be directly copied to
\&\f(CW$prepared_mime\fR. Any headers of \f(CW$source_mime\fR except \f(CW\*(C`Content\-*\*(C'\fR, \f(CW\*(C`MIME\-*\*(C'\fR
and \f(CW\*(C`Subject\*(C'\fR will be copied to \f(CW$prepared_mime\fR, and those excluded headers
will be copied to \f(CW$outer_header\fR. Note that the \f(CW\*(C`Subject\*(C'\fR header will be
copied to both side exceptionally.
.IP "\fBcheck()\fR" 4
.IX Item "check()"
.Vb 1
\&  use Crypt::SMIME qw(:constants);
\&
\&  $source_mime = $smime\->check($signed_mime);
\&  $source_mime = $smime\->check($signed_mime, $flags);
.Ve
.Sp
Verify a signature of S/MIME message and return a \s-1MIME\s0 message. The method dies
if it fails to verify it.
.Sp
When the option \f(CW\*(C`Crypt::SMIME::NO_CHECK_CERTIFICATE\*(C'\fR is given as
\&\f(CW$flags\fR, the signer's certificate chain is not verified. The default
value for \f(CW$flags\fR is \f(CW0\fR, which performs all the verifications.
.Sp
The resulting message will be tainted if the original S/MIME message,
the \f(CW$flags\fR, verification time (\*(L"\fBsetAtTime()\fR\*(R") or at least one
of the provided public keys are tainted.
.IP "\fBencrypt()\fR" 4
.IX Item "encrypt()"
.Vb 1
\&  $encrypted_mime = $smime\->encrypt($raw_mime);
.Ve
.Sp
Encrypt a \s-1MIME\s0 message and return a S/MIME message.
.Sp
Any headers except \f(CW\*(C`Content\-*\*(C'\fR, \f(CW\*(C`MIME\-*\*(C'\fR and \f(CW\*(C`Subject\*(C'\fR will be moved to the
top-level of the \s-1MIME\s0 message. \f(CW\*(C`Subject\*(C'\fR header will be copied to both of the
plain text part and the top-level for mail clients which can't properly handle
S/MIME messages.
.Sp
The resulting message will be tainted if the original \s-1MIME\s0 message or
at least one public key is tainted.
.IP "\fBdecrypt()\fR" 4
.IX Item "decrypt()"
.Vb 1
\&  $decrypted_mime = $smime\->decrypt($encrypted_mime);
.Ve
.Sp
Decrypt an S/MIME and return a \s-1MIME\s0 message. This method dies if it fails to
decrypt it.
.Sp
The resulting message will be tainted if any of the original S/MIME
message, the private key or its certificate is tainted.
.IP "\fBisSigned()\fR" 4
.IX Item "isSigned()"
.Vb 1
\&  $is_signed = $smime\->isSigned($mime);
.Ve
.Sp
Return true if the given string is a signed S/MIME message. Note that if the
message was encrypted after signing, this method returns false because in that
case the signature is hidden in the encrypted message.
.IP "\fBisEncrypted()\fR" 4
.IX Item "isEncrypted()"
.Vb 1
\&  $is_encrypted = $smime\->isEncrypted($mime);
.Ve
.Sp
Return true if the given string is an encrypted S/MIME message. Note that if the
message was signed with non-detached signature after encryption, this method
returns false because in that case the encrypted message is hidden in the
signature.
.IP "\fBsetAtTime()\fR" 4
.IX Item "setAtTime()"
.Vb 2
\&  $yesterday = time \- (60*60*24);
\&  $smime\->setAtTime($yesterday);
.Ve
.Sp
Set the time to use for verification. Default is to use the current time.
Must be an unix epoch timestamp.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.IP "\fBextractCertificates()\fR" 4
.IX Item "extractCertificates()"
.Vb 1
\&  use Crypt::SMIME qw(:constants);
\&
\&  @certs = @{Crypt::SMIME::extractCertificates($data)};
\&  @certs = @{Crypt::SMIME::extractCertificates($data, FORMAT_SMIME)};
.Ve
.Sp
Get all X.509 certificates (and CRLs, if any) included in S/MIME
message or PKCS#7 object \f(CW$data\fR. Optional \f(CW$type\fR parameter may
specify type of data:
\&\f(CW\*(C`Crypt::SMIME::FORMAT_SMIME\*(C'\fR (default) for S/MIME message;
\&\f(CW\*(C`Crypt::SMIME::FORMAT_ASN1\*(C'\fR for binary format;
\&\f(CW\*(C`Crypt::SMIME::FORMAT_PEM\*(C'\fR for \s-1PEM\s0 format.
.IP "\fBgetSigners()\fR" 4
.IX Item "getSigners()"
.Vb 2
\&  @certs = @{Crypt::SMIME::getSigners($data)};
\&  @certs = @{Crypt::SMIME::getSigners($data, $type)};
.Ve
.Sp
Get X.509 certificates of signers included in S/MIME message or PKCS#7 object.
Optional \f(CW$type\fR parameter may specify type of data.
.Sp
Note that any public keys returned by this function are not verified.
\&\fBcheck()\fR should be executed to ensure public keys are valid.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright 2006\-2014 \s-1YMIRLINK\s0 Inc. All Rights Reserved.
.PP
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself
.PP
Bug reports and comments to: tl@tripletail.jp