Ruby 2.3.0 リファレンスマニュアル > ライブラリ一覧 > opensslライブラリ > OpenSSL::PKCS7クラス

class OpenSSL::PKCS7

クラスの継承リスト: OpenSSL::PKCS7 < Object < Kernel < BasicObject

要約

PKCS #7 クラス

PKCS #7 は暗号技術とともに用いられるデータのフォーマットの仕様です。 データやそれに対する署名、証明した日時など任意の属性を含むことができ、 S/MIME などに使用されています。

[RFC2315] を参照してください。

S/MIME メッセージの種類

S/MIME には以下の種類のメッセージがあります

目次

特異メソッド
encrypt new read_smime sign write_smime
インスタンスメソッド
add_certificate add_crl add_data data= add_recipient add_signer certificates certificates= cipher= crls crls= data decrypt detached detached? detached= error_string error_string= recipients signers to_der to_pem to_s type type= verify
定数
BINARY DETACHED NOATTR NOCERTS NOCHAIN NOINTERN NOSIGS NOSMIMECAP NOVERIFY TEXT

特異メソッド

encrypt(certs, data, cipher=nil, flags=0) -> OpenSSL::PKCS7[permalink][rdoc]

data を証明書の公開鍵で暗号化します。

暗号化は複数の公開鍵を用いてすることが可能です。そのためには 複数の証明書を配列で渡します。

data には任意の文字列を渡せますが、一般的には MIME 形式の文字列を渡します。 署名と暗号化の両方をしたい場合は、 署名(OpenSSL::PKCS7.sign)された S/MIME 形式の文字列を 渡すことが一般的です。

cipher は共通鍵暗号の方式を OpenSSL::Cipher オブジェクトで指定します。 nil を渡すと適当な方式が選ばれます。互換性を気にするのであれば triple DES を使うとよいでしょう。多くのクライアントで利用可能なはずです。

flags には以下のフラグを渡すことができます。

[PARAM] certs:
公開鍵を含む証明書(OpenSSL::X509::Certificate オブジェクト)の配列
[PARAM] data:
暗号化対象の文字列
[PARAM] cipher:
共通鍵暗号の方式(OpenSSL::Cipher オブジェクト)
[PARAM] flags:
フラグ
new -> OpenSSL::PKCS7[permalink][rdoc]
new(obj) -> OpenSSL::PKCS7

PKCS7 オブジェクトを生成します。

引数を渡さなかった場合は空のオブジェクトを作ります。

引数を渡した場合は、文字列もしくは IO オブジェクトから PEM 形式もしくは DER 形式の文字列を読み込み PKCS7 オブジェクトを生成します。

[PARAM] obj:
データを読みこむ文字列もしくは IO オブジェクト
read_smime(obj) -> OpenSSL::PKCS7[permalink][rdoc]

S/MIME 形式のデータを読み込み、PKCS7 オブジェクトを返します。

引数 obj からデータを読み込みます。文字列もしくは IO オブジェクトから読み出すことができます。

[PARAM] obj:
データを読み出すオブジェクト
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
読み込みに失敗した場合に発生します
sign(cert, key, data, certs = [], flags = 0) -> OpenSSL::PKCS7[permalink][rdoc]

data に証明書と秘密鍵で署名します。

cert に署名に使う証明書を、key にその証明書に対応する秘密鍵を 渡します。certs に OpenSSL::X509::Certificate オブジェクトの配列 を 渡すと OpenSSL::PKCS7 オブジェクトにそれらの証明書が追加で保持されます。 例えば中間 CA 証明書などを渡します。 flags は以下の値の OR を渡します。

返り値は署名結果を含む OpenSSL::PKCS7 オブジェクトを返します。

[PARAM] cert:
署名に用いる証明書(OpenSSL::X509::Certificate オブジェクト)
[PARAM] key:
署名に用いる秘密鍵(OpenSSL::PKey::PKey のサブクラスのオブジェクト)
[PARAM] data:
署名対象のデータ文字列
[PARAM] certs:
添付する証明書群(OpenSSL::X509::Certificate オブジェクトの配列)
[PARAM] flags:
フラグ(整数値)
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
署名に失敗した場合に発生します
write_smime(p7sig, data=nil, flags = 0) -> String[permalink][rdoc]

PKCS7 オブジェクトから S/MIME 形式の文字列を返します。

data には署名対象のデータを渡します。 data に nil を渡すと OpenSSL::PKCS7#data で得られる 文字列を用います。通常は nil を渡してください。

flags には以下の定数の or を渡します。

例:

require 'openssl'

data = "foobar"
p7 = OpenSSL::PKCS7.sign( OpenSSL::X509::Certificate.new(File.read('cert.pem')),
                          OpenSSL::PKey::RSA.new(File.read('privkey.pem')),
                          data)
smime = PKCS7.write_smime(p7)
[PARAM] p7sig:
PKCS#7 オブジェクト
[PARAM] data:
署名されたデータ文字列
[PARAM] flags:
フラグ(整数値)
[EXCEPTION] OpenSSL::PKCS::PKCS7Error:
S/MIME形式への変換に失敗した場合に発生します

インスタンスメソッド

add_certificate(cert) -> self[permalink][rdoc]

署名に添付する証明書を追加します。

通常は OpenSSL::PKCS7.sign の引数で添付する証明書を指定した ほうがよいでしょう。

[PARAM] cert:
追加する証明書(OpenSSL::X509::Certificate オブジェクト)
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
追加に失敗した場合に発生します。
add_crl(crl) -> self[permalink][rdoc]

署名に添付する CRL を追加します。

[PARAM] crl:
追加する CLR (OpenSSL::X509::CRL オブジェクト)
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
追加に失敗した場合に発生します。
data=(data)[permalink][rdoc]
add_data(data) -> data

署名対象のデータを設定します。

このメソッドは使わないでください。 このメソッドは PKCS#7 の低レベル API であり、正しく使うのは 難しいでしょう。

[PARAM] data:
文字列
add_recipient(recipient) -> self[permalink][rdoc]

送信者を追加します。

このメソッドは使わないでください。 このメソッドは PKCS#7 の低レベル API であり、正しく使うのは 難しいでしょう。

[PARAM] recipient:
追加する送信者(OpenSSL::PKCS7::RecipientInfo)
add_signer(singer) -> self[permalink][rdoc]

署名者を追加します。

このメソッドは使わないでください。 このメソッドは PKCS#7 の低レベル API であり、正しく使うのは 難しいでしょう。

[PARAM] signer:
追加する署名者(OpenSSL::PKCS7::SignerInfo オブジェクト)
certificates -> [OpenSSL::X509::Certificate] | nil[permalink][rdoc]

署名に添付される証明書を配列で返します。

certificates=(certificates)[permalink][rdoc]

署名に付ける証明書を指定します。

PKCS7 オブジェクトに元々つけられていた証明書はクリアされます。 通常は OpenSSL::PKCS7.sign の引数で添付する証明書を指定した ほうがよいでしょう。

[PARAM] certificates:
証明書(OpenSSL::X509::Certificate オブジェクト)の配列
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
変更に失敗した場合に発生します。
cipher=(cipher)[permalink][rdoc]

使用する共通鍵暗号アルゴリズムを指定します。

このメソッドは使わないでください。 このメソッドは PKCS#7 の低レベル API であり、正しく使うのは 難しいでしょう。

[PARAM] cipher:
共通鍵暗号アルゴリズム(OpenSSL::Cipher オブジェクト)
crls -> [OpenSSL::X509::CRL][permalink][rdoc]

署名に添付されている CRL を配列で返します。

crls=(crls)[permalink][rdoc]

署名に添付される CRL を配列で設定します。

元々付けられていた CRL はクリアされます。

[PARAM] crls:
更新する CRL(OpenSSL::X509::CRL オブジェクト) の配列
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
変更に失敗した場合に発生します。
data -> String[permalink][rdoc]

署名対象のデータを文字列で返します。

decrypt(pkey, cert, flags = 0) -> String[permalink][rdoc]

暗号化されたデータを復号化し、復号化されたデータを返します。

復号には暗号化に使った公開鍵に対応する秘密鍵と、その公開鍵を 含む証明書が必要です。

flags には以下のいずれかを指定できます。

[PARAM] pkey:
復号化に使う秘密鍵(OpenSSL::PKey::PKey オブジェクト)
[PARAM] cert:
対応する証明書(OpenSSL::X509::Certificate オブジェクト)
[PARAM] flags:
フラグ
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
復号に失敗した場合に発生します
detached? -> bool[permalink][rdoc]
detached -> bool

平文に署名を付ける形式(multipart/signed)かどうかを返します。

OpenSSL::PKCS7.sign で flags に OpenSSL::PKCS7::DETACHED を渡した場合に真になります。

detached=(b)[permalink][rdoc]

平文に署名を付ける形式(multipart/signed)かどうかを設定します。

このメソッドは使わないでください。 このメソッドは PKCS#7 の低レベル API であり、正しく使うのは 難しいでしょう。

[PARAM] b:
設定する真偽値
error_string -> String | nil[permalink][rdoc]

検証エラーの理由を表す文字列を返します。

OpenSSL::PKCS7#verify で検証を した場合のみ更新されます。

OpenSSL::PKCS7#verify で検証をする前は nil を返します。

検証に成功した場合は nil を返します。

[SEE_ALSO] OpenSSL::PKCS7#error_string=

error_string=(str)[permalink][rdoc]

検証エラーの理由を表す文字列を設定します。

[PARAM] str:
設定するエラー文字列

[SEE_ALSO] OpenSSL::PKCS7#error_string

recipients -> [OpenSSL::PKCS7::RecipientInfo][permalink][rdoc]

メッセージの送信先の情報を配列で返します。

これは暗号化した場合のみ意味があります。

signers -> [OpenSSL::PKCS7::SignerInfo][permalink][rdoc]

メッセージの署名者を表す OpenSSL::PKCS7::SignerInfo オブジェクトの 配列を返します。

これはメッセージを署名した場合にのみ意味があります。

to_der -> String[permalink][rdoc]

DER 形式のバイナリ列に変換します。

to_pem -> String[permalink][rdoc]
to_s -> String

PEM 形式の文字列に変換します。

type -> Symbol[permalink][rdoc]

PKCS7 オブジェクトのタイプを Symbol オブジェクトで返します。

次のうちのいずれかの値をとります。

type=(type)[permalink][rdoc]

PKCS7 オブジェクトのタイプを Symbol オブジェクトで設定します。

このメソッドは使わないでください。 このメソッドは PKCS#7 の低レベル API であり、正しく使うのは 難しいでしょう。

[PARAM] type:
設定するタイプ(シンボル)
verify(certs, store, indata = nil, flags = 0) -> bool[permalink][rdoc]

署名を検証します。

検証に成功した場合は真を、失敗した場合は偽を返します。

certs には署名者の証明書を含む配列を渡します。 通常 S/MIME 署名には証明者の証明書が含まれていますが、 OpenSSL::PKCS7.signOpenSSL::PKCS7::NOCERTS を渡した 場合には含まれていないので、明示的に渡す必要があります。 このメソッドは配列から適切な証明書を自動的に選択します。

store には検証に用いる証明書ストアを渡します。 検証に必要な信頼できる CA 証明書をあらかじめ証明書ストアに含めておく 必要があります。

indata は署名の対象となった文字列を渡します。 nil を渡すと OpenSSL::PKCS7#data で得られる文字列 を用います。通常は nil を渡すべきです。

flags には以下の値の OR を渡します。

通常、これらのフラグを渡さなかった場合、

という順で検証が行われます。

この検証は署名者証明書の持ち主が署名したという事実のみを検証します。 署名者証明書の持ち主が本当に意図した相手であるかどうかは保証されません。 証明書の内容から(ユーザに確認を取るなど)適切に判断する必要があります。

検証に失敗した場合は OpenSSL::PKCS7#error_string に 失敗した理由を表す文字列がセットされます。

[PARAM] certs:
証明書(OpenSSL::X509::Certificate オブジェクト)の配列
[PARAM] store:
証明書ストア(OpenSSL::X509::Store オブジェクト)
[PARAM] indata:
署名対象の文字列
[PARAM] flags:
フラグ
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:
検証に失敗した場合に発生します

定数

BINARY -> Integer[permalink][rdoc]

MIME canonical format への変換を行いません。

OpenSSL::PKCS7.signOpenSSL::PKCS7.encrypt で利用可能なフラグです。

DETACHED -> Integer[permalink][rdoc]

平文に署名を付ける形式 (multipart/signed) で行います。

OpenSSL::PKCS7.signOpenSSL::PKCS7.write_smime で利用可能なフラグです。

NOATTR -> Integer[permalink][rdoc]

PKCS#7 autenticatedAttributes(署名した時間などの情報) を省略します。

OpenSSL::PKCS7.sign で利用可能なフラグです。

NOCERTS -> Integer[permalink][rdoc]

署名者の証明書を署名に含めません。送り先がすでに証明書をもっている場合 など、他の方法で証明書を手に入れることができる場合に データ量を減らすために用います。

OpenSSL::PKCS7.sign で利用可能なフラグです。

NOCHAIN -> Integer[permalink][rdoc]

署名検証時に、メッセージに含まれる証明書を中間 CA として利用しません。

OpenSSL::PKCS7#verify で利用可能なフラグです。

NOINTERN -> Integer[permalink][rdoc]

署名検証時に、署名者の証明書をメッセージに添付された証明書から探索しません。

OpenSSL::PKCS7#verify でのみ利用可能なフラグです。

NOSIGS -> Integer[permalink][rdoc]

署名の検証を行いません。

OpenSSL::PKCS7#verify で利用可能なフラグです。

NOSMIMECAP -> Integer[permalink][rdoc]

署名者が使用可能な暗号アルゴリズムの情報など(SMIMECapabilities)を省略します。

OpenSSL::PKCS7.sign で利用可能なフラグです。

NOVERIFY -> Integer[permalink][rdoc]

署名検証時に署名者の証明書の検証を行いません。

OpenSSL::PKCS7#verify で利用可能なフラグです。

TEXT -> Integer[permalink][rdoc]

text/plain タイプの MIME ヘッダーを取り扱います。

OpenSSL::PKCS7.sign, OpenSSL::PKCS7.write_smime, OpenSSL::PKCS7#verify, OpenSSL::PKCS7.encrypt, OpenSSL::PKCS7#decrypt で利用可能なフラグです。