1 2=encoding utf-8 3 4=head1 NAME 5 6Crypt::SMIME - S/MIME message signing, verification, encryption and decryption 7J<< ja; Crypt::SMIME::JA - S/MIMEの署名、検証、暗号化、復号 >> 8 9=head1 SYNOPSIS 10 11 use Crypt::SMIME; 12 13 my $plain = <<'EOF'; 14 From: alice@example.org 15 To: bob@example.com 16 Subject: Crypt::SMIME test 17 18 This is a test mail. Please ignore... 19 EOF 20 21 my $smime = Crypt::SMIME->new(); 22 $smime->setPrivateKey($privkey, $crt); 23 # $smime->setPublicKey([$icacert]); # if need be. 24 25 my $signed = $smime->sign($plain); 26 print $signed; 27 28=head1 DESCRIPTION 29 30This module provides a class for handling S/MIME messages. It can sign, verify, 31encrypt and decrypt messages. It requires libcrypto (L<http://www.openssl.org>). 32J<< ja; 33S/MIMEの署名、検証、暗号化、復号を行うクラス。 34libcrypto (L<http://www.openssl.org>) が必要。 35>> 36 37=head1 EXPORTS 38 39No symbols are exported by default. The following symbols can 40optionally be exported: 41J<< ja; 42既定でエクスポートされるシンボルは無いが、次のシンボルはエクスポート可能である。 43>> 44 45=over 46 47=item C<NO_CHECK_CERTIFICATE> 48 49See L</"check()">. 50J<< ja; 51L</"check()"> を参照。 52>> 53 54=item C<FORMAT_SMIME> 55 56=item C<FORMAT_ASN1> 57 58=item C<FORMAT_PEM> 59 60See L</"extractCertificates()">. 61J<< ja; 62L</"extractCertificates()"> を参照。 63>> 64 65=item C<:constants> 66 67Export all of the above. 68J<< ja; 69上記のもの全てをエクスポートする。 70>> 71 72=back 73 74=head1 METHODS 75 76=over 4 77 78=item new() 79 80 my $smime = Crypt::SMIME->new(); 81 82The constructor takes no arguments. 83J<< ja; 84引数無し 85>> 86 87=item setPrivateKey() 88 89 $smime->setPrivateKey($key, $crt); 90 $smime->setPrivateKey($key, $crt, $password); 91 92Store a private key and its X.509 certificate into the instance. The private key 93will be used for signing and decryption. Note that this method takes a PEM 94string, not a name of a file which contains a key or a certificate. 95J<< ja; 96秘密鍵を設定する。ここで設定された秘密鍵は署名と復号の際に用いられる。 97ファイル名ではなく、鍵本体を渡す。 98>> 99 100The private key and certificate must be encoded in PEM format. The method dies 101if it fails to load the key. 102J<< ja; 103対応しているフォーマットは PEM のみ。鍵の読み込みに失敗した場合はdieする。 104>> 105 106=item setPrivateKeyPkcs12() 107 108 $smime->setPrivateKeyPkcs12($key, $pkcs12); 109 $smime->setPrivateKeyPkcs12($key, $pkcs12, $password); 110 111Load a private key and its X.509 certificate from PKCS#12 into the instance. 112The private key will be used for signing and decryption. The method dies if 113it fails to load PKCS12. 114J<< ja; 115秘密鍵およびその X.509 証明書を PKCS#12 から読み込んで設定する。秘密鍵は署名と復号の際に用いられる。 116読み込みに失敗した場合は die する。 117>> 118 119=item setPublicKey() 120 121 $smime->setPublicKey($crt); 122 $smime->setPublicKey([$crt1, $crt2, ...]); 123 124Store one or more X.509 certificates into the instance. The public keys will be 125used for signing, verification and encryption. 126J<< ja; 127公開鍵を設定する。ここで設定された公開鍵は署名への添付、署名の検証、 128そして暗号化の際に用いられる。 129>> 130 131The certificates must be encoded in PEM format. The method dies if it fails to 132load the certificates. 133J<< ja; 134対応しているフォーマットは PEM のみ。鍵の読み込みに失敗した場合はdieする。 135>> 136 137=item setPublicKeyStore() 138 139 $smime->setPublicKeyStore($path, ...); 140 141Set the paths of file or directory containing trusted certificates. 142The certificate stores will be used for verification. 143J<< ja; 144信頼している証明書 (複数可) 145が入ったファイルやディレクトリのパス (複数可) 146を設定する。ここで設定された証明書ストアは、署名の検証の際に用いられる。 147>> 148 149The method dies if it fails to load the certificate stores. 150J<< ja; 151証明書ストアの読み込みに失敗した場合はdieする。 152>> 153 154=item sign() 155 156 $signed_mime = $smime->sign($raw_mime); 157 158Sign a MIME message and return an S/MIME message. The signature is always 159detached. 160J<< ja; 161署名を行い、MIMEメッセージを返す。可能な署名はクリア署名のみ。 162>> 163 164Any headers except C<Content-*>, C<MIME-*> and C<Subject> will be moved to the 165top-level of the MIME message. C<Subject> header will be copied to both of the 166plain text part and the top-level for mail clients which can't properly handle 167S/MIME messages. 168J<< ja; 169C<Content-*>, C<MIME-*> 及び C<Subject> を除いたヘッダは 170multipartのトップレベルに移される。 171C<Subject> はS/MIMEを認識できないメーラのために, multipartの 172トップレベルと保護されるメッセージの両側に配置される。 173>> 174 175The resulting message will be tainted if any of the original MIME 176message, the private key or its certificate is tainted. 177J<< ja; 178元の MIME メッセージ、秘密鍵、またはその証明書のいずれかが汚染されている 179(tainted) ならば、署名されたメッセージも汚染される。 180>> 181 182=item signonly() 183 184 $sign = $smime->signonly($prepared_mime); 185 186Generate a signature from a MIME message. The resulting signature is encoded in 187Base64. The MIME message to be passed to this method should be preprocessed 188beforehand by the prepareSmimeMessage() method. You would rarely need to call 189this method directly. 190J<< ja; 191署名の計算を行う。 192C<$sign> はBASE64でエンコードされて返る。 193C<$prepared_mime> には, L</prepareSmimeMessage> で返される値を渡す。 194>> 195 196The resulting signature will be tainted if any of the original MIME 197message, the private key or its certificate is tainted. 198J<< ja; 199元の MIME メッセージ、秘密鍵、またはその証明書のいずれかが汚染されている 200(tainted) ならば、生成された署名も汚染される。 201>> 202 203=item prepareSmimeMessage() 204 205 ($prepared_mime, $outer_header) 206 = $smime->prepareSmimeMessage($source_mime); 207 208Preprocess a MIME message to be signed. C<$prepared_mime> will be a string 209containing the processed MIME message, and C<$outer_header> will be a string 210that is a list of headers to be moved to the top-level of MIME message. You 211would rarely need to call this method directly. 212J<< ja; 213署名用のメッセージを準備する。 214C<$prepared_mime> には署名用に修正されたMIMEメッセージを返す。 215C<$outer_header> は、S/MIMEの外側に付与するヘッダを返す。 216>> 217 218The entity body of C<$source_mime> will be directly copied to 219C<$prepared_mime>. Any headers of C<$source_mime> except C<Content-*>, C<MIME-*> 220and C<Subject> will be copied to C<$prepared_mime>, and those excluded headers 221will be copied to C<$outer_header>. Note that the C<Subject> header will be 222copied to both side exceptionally. 223J<< ja; 224C<$prepared_mime> の本文はC<$source_mime>と同じ物となるが、 225ヘッダに関してはC<Content-*>, C<MIME-*>, C<Subject> を除く全てが 226取り除かれる。取り除かれたヘッダは C<$outer_header> に返される。 227S/MIMEメッセージを構築する際にはこれをS/MIMEメッセージのヘッダに追加する。 228C<Subject> ヘッダのみは C<$prepared_mime> と C<$outer_header> の両方に 229現れる点に注意。 230>> 231 232=item check() 233 234 use Crypt::SMIME qw(:constants); 235 236 $source_mime = $smime->check($signed_mime); 237 $source_mime = $smime->check($signed_mime, $flags); 238 239Verify a signature of S/MIME message and return a MIME message. The method dies 240if it fails to verify it. 241J<< ja; 242検証を行う。検証に失敗した場合はその理由と共にdieする。 243>> 244 245When the option C<Crypt::SMIME::NO_CHECK_CERTIFICATE> is given as 246C<$flags>, the signer's certificate chain is not verified. The default 247value for C<$flags> is C<0>, which performs all the verifications. 248J<< ja; 249C<$flags> として C<Crypt::SMIME::NO_CHECK_CERTIFICATE> 250オプションを指定した場合には、署名者の証明書チェーンを検証しない。 251C<$flags> のデフォルト値は C<0> 252であり、この場合には全ての整合性についての検証を行う。 253>> 254 255The resulting message will be tainted if the original S/MIME message, 256the C<$flags>, verification time (L</"setAtTime()">) or at least one 257of the provided public keys are tainted. 258J<< ja; 259元の S/MIME メッセージ, C<$flags>, 検証時刻 (L</"setAtTime">), または 260公開鍵の少なくとも一つが汚染されている(tainted) ならば、検証されたメッセージも汚染される。 261>> 262 263=item encrypt() 264 265 $encrypted_mime = $smime->encrypt($raw_mime); 266 267Encrypt a MIME message and return a S/MIME message. 268J<< ja; 269暗号化を行う。 270>> 271 272Any headers except C<Content-*>, C<MIME-*> and C<Subject> will be moved to the 273top-level of the MIME message. C<Subject> header will be copied to both of the 274plain text part and the top-level for mail clients which can't properly handle 275S/MIME messages. 276J<< ja; 277C<Content-*>, C<MIME-*> 及び C<Subject> を除いたヘッダは 278multipartのトップレベルにコピーされる。 279C<Subject> はS/MIMEを認識できないメーラのために, multipartの 280トップレベルと保護されるメッセージの両側に配置される。 281>> 282 283The resulting message will be tainted if the original MIME message or 284at least one public key is tainted. 285J<< ja; 286元の MIME メッセージ、または公開鍵の少なくとも一つが汚染されている 287(tainted) ならば、暗号化されたメッセージも汚染される。 288>> 289 290=item decrypt() 291 292 $decrypted_mime = $smime->decrypt($encrypted_mime); 293 294Decrypt an S/MIME and return a MIME message. This method dies if it fails to 295decrypt it. 296J<< ja; 297復号を行う。復号に失敗した場合はその理由と共にdieする。 298>> 299 300The resulting message will be tainted if any of the original S/MIME 301message, the private key or its certificate is tainted. 302J<< ja; 303元の S/MIME メッセージ、秘密鍵、またはその証明書のいずれかが汚染されている 304(tainted) ならば、復号されたメッセージも汚染される。 305>> 306 307=item isSigned() 308 309 $is_signed = $smime->isSigned($mime); 310 311Return true if the given string is a signed S/MIME message. Note that if the 312message was encrypted after signing, this method returns false because in that 313case the signature is hidden in the encrypted message. 314J<< ja; 315渡されたMIMEメッセージがS/MIMEで署名されたものなら真を返す。 316クリア署名かどうかは問わない。 317署名後に暗号化したメッセージを渡した場合は、署名が直接見えない為、 318偽を返す事に注意。 319>> 320 321=item isEncrypted() 322 323 $is_encrypted = $smime->isEncrypted($mime); 324 325Return true if the given string is an encrypted S/MIME message. Note that if the 326message was signed with non-detached signature after encryption, this method 327returns false because in that case the encrypted message is hidden in the 328signature. 329J<< ja; 330渡されたMIMEメッセージがS/MIMEで暗号化されたものなら真を返す。 331暗号化後に署名したメッセージを渡した場合は、暗号文が直接見えない為、 332偽を返す事に注意。 333>> 334 335=back 336 337=item setAtTime() 338 339 $yesterday = time - (60*60*24); 340 $smime->setAtTime($yesterday); 341 342Set the time to use for verification. Default is to use the current time. 343Must be an unix epoch timestamp. 344J<< ja; 345検証時に用いる時刻を設定する。デフォルトは現在時刻。 346UNIX epoch 形式でなければならない。 347>> 348 349=back 350 351=head1 FUNCTIONS 352 353=over 4 354 355=item extractCertificates() 356 357 use Crypt::SMIME qw(:constants); 358 359 @certs = @{Crypt::SMIME::extractCertificates($data)}; 360 @certs = @{Crypt::SMIME::extractCertificates($data, FORMAT_SMIME)}; 361 362Get all X.509 certificates (and CRLs, if any) included in S/MIME 363message or PKCS#7 object $data. Optional C<$type> parameter may 364specify type of data: 365C<Crypt::SMIME::FORMAT_SMIME> (default) for S/MIME message; 366C<Crypt::SMIME::FORMAT_ASN1> for binary format; 367C<Crypt::SMIME::FORMAT_PEM> for PEM format. 368J<< ja; 369<S/MIMEメッセージまたはPKCS#7オブジェクトに含まれるX.509証明書 370(や証明書失効リスト) をすべて取得する。 371オプションの C<$type> パラメータでデータの種類を指定できる。 372C<Crypt::SMIME::FORMAT_SMIME> (初期値) はS/MIMEメッセージ、 373C<Crypt::SMIME::FORMAT_ASN1>はバイナリ形式、 374C<Crypt::SMIME::FORMAT_PEM>はPEM形式。 375>> 376 377=item getSigners() 378 379 @certs = @{Crypt::SMIME::getSigners($data)}; 380 @certs = @{Crypt::SMIME::getSigners($data, $type)}; 381 382Get X.509 certificates of signers included in S/MIME message or PKCS#7 object. 383Optional $type parameter may specify type of data. 384J<< ja; 385S/MIMEメッセージまたはPKCS#7オブジェクトに含まれる、署名者の 386X.509証明書を取得する。オプションの$typeパラメータでデータの種類を指定できる。 387>> 388 389Note that any public keys returned by this function are not verified. 390check() should be executed to ensure public keys are valid. 391J<< ja; 392この関数が返す公開鍵は検証されていないことに注意。 393公開鍵が有効であることを確かめるにはcheck()を実行すること。 394>> 395 396=back 397 398=head1 AUTHOR 399 400Copyright 2006-2014 YMIRLINK Inc. All Rights Reserved. 401 402This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself 403 404Bug reports and comments to: tl@tripletail.jp 405 406=for comment 407Local Variables: 408mode: cperl 409End: 410 411=cut 412