class OpenSSL::PKCS7 (Ruby 3.0 リファレンスマニュアル)

要約

PKCS #7 クラス

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

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

S/MIME メッセージの種類

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

enveloped-only
signed-only
- signedData フォーマット
- multipart/signed フォーマット
Certificate-only

特異メソッド

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

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

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

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

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

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

OpenSSL::PKCS7::TEXT 暗号化するデータに text/plain タイプの MIME ヘッダを追加します。 MIME形式のデータを渡すときにはこれを使ってはいけません。
OpenSSL::PKCS7::BINARY data に MIME 正規化をほどこしません。

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

new -> OpenSSL::PKCS7[permalink][rdoc][edit]

new(obj) -> OpenSSL::PKCS7

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

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

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

[PARAM] obj:: データを読みこむ文字列もしくは IO オブジェクト

read_smime(obj) -> OpenSSL::PKCS7[permalink][rdoc][edit]

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

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

[PARAM] obj:: データを読み出すオブジェクト
[EXCEPTION] OpenSSL::PKCS7::PKCS7Error:: 読み込みに失敗した場合に発生します

sign(cert, key, data, certs = [], flags = 0) -> OpenSSL::PKCS7[permalink][rdoc][edit]

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

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

OpenSSL::PKCS7::TEXT text/plain 用の MIME ヘッダをデータに付け加える。
OpenSSL::PKCS7::NOCERTS 署名者の証明書を署名に含めません。送り先がすでに証明書をもっている場合など、他の方法で証明書を手に入れることができる場合にデータ量を減らすために用います。
OpenSSL::PKCS7::DETACHED クリア署名(multipart/signed)をする。
OpenSSL::PKCS7::BINARY data に MIME 正規化を施さない。
OpenSSL::PKCS7::NOATTR PKCS#7 autenticatedAttributes (署名時刻など)をオブジェクトに含めない。
OpenSSL::PKCS7::NOSMIMECAP 署名者が使用可能な暗号アルゴリズムの情報など(SMIMECapabilities)を省略する。

返り値は署名結果を含む 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][edit]

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

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

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

OpenSSL::PKCS7::DETACHED クリア署名をします。これは OpenSSL::PKCS7.sign で OpenSSL::PKCS7::DETACHED を渡した場合にのみ意味を持ちます。
OpenSSL::PKCS7::TEXT MIME ヘッダに text/plain を付加します。これは OpenSSL::PKCS7.sign で OpenSSL::PKCS7::DETACHED を渡した場合にのみ意味を持ちます。

例:

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][edit]

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

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

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

add_crl(crl) -> self[permalink][rdoc][edit]

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

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

data=(data)[permalink][rdoc][edit]

add_data(data) -> data

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

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

[PARAM] data:: 文字列

add_recipient(recipient) -> self[permalink][rdoc][edit]

送信者を追加します。

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

[PARAM] recipient:: 追加する送信者(OpenSSL::PKCS7::RecipientInfo)

add_signer(singer) -> self[permalink][rdoc][edit]

署名者を追加します。

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

[PARAM] signer:: 追加する署名者(OpenSSL::PKCS7::SignerInfo オブジェクト)

certificates -> [OpenSSL::X509::Certificate] | nil[permalink][rdoc][edit]

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

certificates=(certificates)[permalink][rdoc][edit]

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

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

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

cipher=(cipher)[permalink][rdoc][edit]

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

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

[PARAM] cipher:: 共通鍵暗号アルゴリズム(OpenSSL::Cipher オブジェクト)

crls -> [OpenSSL::X509::CRL][permalink][rdoc][edit]

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

crls=(crls)[permalink][rdoc][edit]

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

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

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

data -> String[permalink][rdoc][edit]

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

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

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

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

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

OpenSSL::PKCS7::TEXT 暗号化されたデータに付けられた text/plain タイプの MIME ヘッダを取り除きます。もしヘッダがなければエラーとなります。

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

detached? -> bool[permalink][rdoc][edit]

detached -> bool

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

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

detached=(b)[permalink][rdoc][edit]

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

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

[PARAM] b:: 設定する真偽値

error_string -> String | nil[permalink][rdoc][edit]

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

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

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

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

[SEE_ALSO] OpenSSL::PKCS7#error_string=

error_string=(str)[permalink][rdoc][edit]

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

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

[SEE_ALSO] OpenSSL::PKCS7#error_string

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

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

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

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

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

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

to_der -> String[permalink][rdoc][edit]

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

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

to_s -> String

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

type -> Symbol[permalink][rdoc][edit]

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

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

:signed
:encrypted
:enveloped
:signedAndEnveloped
:data

type=(type)[permalink][rdoc][edit]

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

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

[PARAM] type:: 設定するタイプ(シンボル)

verify(certs, store, indata = nil, flags = 0) -> bool[permalink][rdoc][edit]

署名を検証します。

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

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

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

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

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

OpenSSL::PKCS7::NOINTERN メッセージに添付された証明書を探索しません。これを指定した場合は、必要な証明書をすべて certs から渡す必要があります。ある特定の証明書による署名のみを検証したい場合などに用います。
OpenSSL::PKCS7::TEXT 署名対象のデータに含まれる text/plain タイプの MIME ヘッダを取り除きます。もしヘッダがない場合はエラーとなります。
OpenSSL::PKCS7::NOVERIFY 署名者の証明書を検証しません。
OpenSSL::PKCS7::NOCHAIN メッセージに含まれる証明書を中間 CA として利用しません。
OpenSSL::PKCS7::NOSIGS 署名を検証しません。

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

(もし存在するならば)メッセージに含まれる中間 CA 証明書の検証を行う
その中間 CA 証明書を用いて、署名者の証明書の検証を行う
署名者の証明書を用いて署名の検証を行う

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

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

検証に失敗した場合は 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][edit]

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

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

DETACHED -> Integer[permalink][rdoc][edit]

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

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

NOATTR -> Integer[permalink][rdoc][edit]

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

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

NOCERTS -> Integer[permalink][rdoc][edit]

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

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

NOCHAIN -> Integer[permalink][rdoc][edit]

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

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

NOINTERN -> Integer[permalink][rdoc][edit]

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

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

NOSIGS -> Integer[permalink][rdoc][edit]

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

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

NOSMIMECAP -> Integer[permalink][rdoc][edit]

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

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

NOVERIFY -> Integer[permalink][rdoc][edit]

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

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

TEXT -> Integer[permalink][rdoc][edit]

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

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

要約

S/MIME メッセージの種類

目次

特異メソッド

インスタンスメソッド

定数