1SMIME(3)              User Contributed Perl Documentation             SMIME(3)
2
3
4

NAME

6       Crypt::SMIME - S/MIME message signing, verification, encryption and
7       decryption
8

SYNOPSIS

10         use Crypt::SMIME;
11
12         my $plain = <<'EOF';
13         From: alice@example.org
14         To: bob@example.com
15         Subject: Crypt::SMIME test
16
17         This is a test mail. Please ignore...
18         EOF
19
20         my $smime = Crypt::SMIME->new();
21         $smime->setPrivateKey($privkey, $crt);
22         # $smime->setPublicKey([$icacert]); # if need be.
23
24         my $signed = $smime->sign($plain);
25         print $signed;
26

DESCRIPTION

28       This module provides a class for handling S/MIME messages. It can sign,
29       verify, encrypt and decrypt messages. It requires libcrypto
30       (<http://www.openssl.org>).
31

EXPORTS

33       No symbols are exported by default. The following symbols can
34       optionally be exported:
35
36       "NO_CHECK_CERTIFICATE"
37           See "check()".
38
39       "FORMAT_SMIME"
40       "FORMAT_ASN1"
41       "FORMAT_PEM"
42           See "extractCertificates()".
43
44       ":constants"
45           Export all of the above.
46

METHODS

48       new()
49             my $smime = Crypt::SMIME->new();
50
51           The constructor takes no arguments.
52
53       setPrivateKey()
54             $smime->setPrivateKey($key, $crt);
55             $smime->setPrivateKey($key, $crt, $password);
56
57           Store a private key and its X.509 certificate into the instance.
58           The private key will be used for signing and decryption. Note that
59           this method takes a PEM string, not a name of a file which contains
60           a key or a certificate.
61
62           The private key and certificate must be encoded in PEM format. The
63           method dies if it fails to load the key.
64
65       setPrivateKeyPkcs12()
66             $smime->setPrivateKeyPkcs12($key, $pkcs12);
67             $smime->setPrivateKeyPkcs12($key, $pkcs12, $password);
68
69           Load a private key and its X.509 certificate from PKCS#12 into the
70           instance.  The private key will be used for signing and decryption.
71           The method dies if it fails to load PKCS12.
72
73       setPublicKey()
74             $smime->setPublicKey($crt);
75             $smime->setPublicKey([$crt1, $crt2, ...]);
76
77           Store one or more X.509 certificates into the instance. The public
78           keys will be used for signing, verification and encryption.
79
80           The certificates must be encoded in PEM format. The method dies if
81           it fails to load the certificates.
82
83       setPublicKeyStore()
84             $smime->setPublicKeyStore($path, ...);
85
86           Set the paths of file or directory containing trusted certificates.
87           The certificate stores will be used for verification.
88
89           The method dies if it fails to load the certificate stores.
90
91       sign()
92             $signed_mime = $smime->sign($raw_mime);
93
94           Sign a MIME message and return an S/MIME message. The signature is
95           always detached.
96
97           Any headers except "Content-*", "MIME-*" and "Subject" will be
98           moved to the top-level of the MIME message. "Subject" header will
99           be copied to both of the plain text part and the top-level for mail
100           clients which can't properly handle S/MIME messages.
101
102           The resulting message will be tainted if any of the original MIME
103           message, the private key or its certificate is tainted.
104
105       signonly()
106             $sign = $smime->signonly($prepared_mime);
107
108           Generate a signature from a MIME message. The resulting signature
109           is encoded in Base64. The MIME message to be passed to this method
110           should be preprocessed beforehand by the prepareSmimeMessage()
111           method. You would rarely need to call this method directly.
112
113           The resulting signature will be tainted if any of the original MIME
114           message, the private key or its certificate is tainted.
115
116       prepareSmimeMessage()
117             ($prepared_mime, $outer_header)
118                 = $smime->prepareSmimeMessage($source_mime);
119
120           Preprocess a MIME message to be signed. $prepared_mime will be a
121           string containing the processed MIME message, and $outer_header
122           will be a string that is a list of headers to be moved to the top-
123           level of MIME message. You would rarely need to call this method
124           directly.
125
126           The entity body of $source_mime will be directly copied to
127           $prepared_mime. Any headers of $source_mime except "Content-*",
128           "MIME-*" and "Subject" will be copied to $prepared_mime, and those
129           excluded headers will be copied to $outer_header. Note that the
130           "Subject" header will be copied to both side exceptionally.
131
132       check()
133             use Crypt::SMIME qw(:constants);
134
135             $source_mime = $smime->check($signed_mime);
136             $source_mime = $smime->check($signed_mime, $flags);
137
138           Verify a signature of S/MIME message and return a MIME message. The
139           method dies if it fails to verify it.
140
141           When the option "Crypt::SMIME::NO_CHECK_CERTIFICATE" is given as
142           $flags, the signer's certificate chain is not verified. The default
143           value for $flags is 0, which performs all the verifications.
144
145           The resulting message will be tainted if the original S/MIME
146           message, the $flags, verification time ("setAtTime()") or at least
147           one of the provided public keys are tainted.
148
149       encrypt()
150             $encrypted_mime = $smime->encrypt($raw_mime);
151
152           Encrypt a MIME message and return a S/MIME message.
153
154           Any headers except "Content-*", "MIME-*" and "Subject" will be
155           moved to the top-level of the MIME message. "Subject" header will
156           be copied to both of the plain text part and the top-level for mail
157           clients which can't properly handle S/MIME messages.
158
159           The resulting message will be tainted if the original MIME message
160           or at least one public key is tainted.
161
162       decrypt()
163             $decrypted_mime = $smime->decrypt($encrypted_mime);
164
165           Decrypt an S/MIME and return a MIME message. This method dies if it
166           fails to decrypt it.
167
168           The resulting message will be tainted if any of the original S/MIME
169           message, the private key or its certificate is tainted.
170
171       isSigned()
172             $is_signed = $smime->isSigned($mime);
173
174           Return true if the given string is a signed S/MIME message. Note
175           that if the message was encrypted after signing, this method
176           returns false because in that case the signature is hidden in the
177           encrypted message.
178
179       isEncrypted()
180             $is_encrypted = $smime->isEncrypted($mime);
181
182           Return true if the given string is an encrypted S/MIME message.
183           Note that if the message was signed with non-detached signature
184           after encryption, this method returns false because in that case
185           the encrypted message is hidden in the signature.
186
187       setAtTime()
188             $yesterday = time - (60*60*24);
189             $smime->setAtTime($yesterday);
190
191           Set the time to use for verification. Default is to use the current
192           time.  Must be an unix epoch timestamp.
193

FUNCTIONS

195       extractCertificates()
196             use Crypt::SMIME qw(:constants);
197
198             @certs = @{Crypt::SMIME::extractCertificates($data)};
199             @certs = @{Crypt::SMIME::extractCertificates($data, FORMAT_SMIME)};
200
201           Get all X.509 certificates (and CRLs, if any) included in S/MIME
202           message or PKCS#7 object $data. Optional $type parameter may
203           specify type of data: "Crypt::SMIME::FORMAT_SMIME" (default) for
204           S/MIME message; "Crypt::SMIME::FORMAT_ASN1" for binary format;
205           "Crypt::SMIME::FORMAT_PEM" for PEM format.
206
207       getSigners()
208             @certs = @{Crypt::SMIME::getSigners($data)};
209             @certs = @{Crypt::SMIME::getSigners($data, $type)};
210
211           Get X.509 certificates of signers included in S/MIME message or
212           PKCS#7 object.  Optional $type parameter may specify type of data.
213
214           Note that any public keys returned by this function are not
215           verified.  check() should be executed to ensure public keys are
216           valid.
217

AUTHOR

219       Copyright 2006-2014 YMIRLINK Inc. All Rights Reserved.
220
221       This library is free software; you can redistribute it and/or modify it
222       under the same terms as Perl itself
223
224       Bug reports and comments to: tl@tripletail.jp
225
226
227
228perl v5.36.0                      2023-01-20                          SMIME(3)