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

要約

公開鍵暗号のための抽象クラスです。

以下のサブクラスを持ちます。

例

require "openssl"
# 署名用の鍵を新規作成
dsa512 = OpenSSL::PKey::DSA.new(512)
data = 'hoge'
# 署名
sign = dsa512.sign("dss1", data)
# 署名の検証
p dsa512.verify(dss1, sign, data)

インスタンスメソッド

compare?(other) -> boolRuby 3.1 から[permalink][rdoc][edit]

self と other が同じ鍵かどうかを比較します。

主に OpenSSL::X509::Certificate#public_key が返す公開鍵と、対応する秘密鍵を比較する際に使います。

[PARAM] other:: 比較対象の OpenSSL::PKey::PKey オブジェクト
[RETURN]: self と other のアルゴリズムの種類、パラメータ、公開鍵が一致すれば true、一致しなければ false
[EXCEPTION] TypeError:: self と other のアルゴリズムの種類が異なる場合に発生します
[EXCEPTION] OpenSSL::PKey::PKeyError:: 比較の実行に失敗した場合に発生します

require "openssl"
rsa_key = OpenSSL::PKey::RSA.generate(2048)
copy = OpenSSL::PKey.read(rsa_key.public_to_der)
p rsa_key.compare?(copy) # => true

decapsulate(ciphertext) -> StringRuby 4.1 から[permalink][rdoc][edit]

self の秘密鍵の部分を使って、鍵デカプセル化 (key decapsulation) を行います。OpenSSL::PKey::PKey#encapsulate が返した暗号化されたデータから、共有される秘密鍵を復元します。

[PARAM] ciphertext:: OpenSSL::PKey::PKey#encapsulate が返した暗号化されたデータ
[RETURN]: 復元された共有の秘密鍵の文字列
[EXCEPTION] OpenSSL::PKey::PKeyError:: デカプセル化に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::PKey#encapsulate

decrypt(data) -> StringRuby 3.1 から[permalink][rdoc][edit]

decrypt(data, options) -> String

self の秘密鍵の部分を使って data を復号します。

暗号化のパラメータの詳細と使用例は OpenSSL::PKey::PKey#encrypt を参照してください。

[PARAM] data:: 復号する文字列
[PARAM] options:: OpenSSL::PKey::PKey#encrypt を参照してください
[RETURN]: 復号されたデータの文字列
[EXCEPTION] OpenSSL::PKey::PKeyError:: 復号に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::PKey#encrypt

derive(peer_pkey) -> StringRuby 3.1 から[permalink][rdoc][edit]

self と peer_pkey から共有の秘密鍵を導出します。

self は秘密鍵の部分を、peer_pkey は公開鍵の部分を含んでいる必要があります。

[PARAM] peer_pkey:: 相手の公開鍵を含む OpenSSL::PKey::PKey オブジェクト
[RETURN]: 導出された共有の秘密鍵の文字列
[EXCEPTION] OpenSSL::PKey::PKeyError:: 導出に失敗した場合に発生します

encapsulate -> [String, String]Ruby 4.1 から[permalink][rdoc][edit]

self の公開鍵の部分を使って、鍵カプセル化 (key encapsulation) を行います。

[RETURN]: [暗号化されたデータ, 共有される秘密鍵] という 2 要素の配列
[EXCEPTION] OpenSSL::PKey::PKeyError:: カプセル化に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::PKey#decapsulate

encrypt(data) -> StringRuby 3.1 から[permalink][rdoc][edit]

encrypt(data, options) -> String

self の公開鍵の部分を使って data を暗号化します。

復号には OpenSSL::PKey::PKey#decrypt を使います。

[PARAM] data:: 暗号化する文字列
[PARAM] options:: OpenSSL に渡すアルゴリズム固有の制御用オプションを指定するハッシュです(省略可)。指定できる内容は OpenSSL のマニュアル EVP_PKEY_CTX_ctrl_str(3) を参照してください
[RETURN]: 暗号化されたデータの文字列
[EXCEPTION] OpenSSL::PKey::PKeyError:: 暗号化に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::PKey#decrypt

require "openssl"
pkey = OpenSSL::PKey.generate_key("RSA", "rsa_keygen_bits" => 2048)
data = "secret data"
encrypted = pkey.encrypt(data, rsa_padding_mode: "oaep")
decrypted = pkey.decrypt(encrypted, rsa_padding_mode: "oaep")
p decrypted # => "secret data"

get_param(key) -> String | OpenSSL::BNRuby 4.1 から[permalink][rdoc][edit]

鍵からパラメータを取得します。OpenSSL 3.0 以降で利用できる EVP_PKEY_get_params() 関数への低レベルなインターフェースです。

対応するパラメータ名や返り値の型については、対応する EVP_PKEY-* のマニュアルページや、利用している OpenSSL プロバイダのドキュメントを確認してください。

[PARAM] key:: 取得したいパラメータの名前を表す文字列
[RETURN]: 取得したパラメータの値です。パラメータやアルゴリズムによって型が異なります
[EXCEPTION] OpenSSL::PKey::PKeyError:: key が認識できないパラメータ名である場合や、取得に失敗した場合に発生します

oid -> StringRuby 3.0 から[permalink][rdoc][edit]

self に関連付けられた OID のショートネームを返します。

require "openssl"
rsa_key = OpenSSL::PKey::RSA.generate(2048)
p rsa_key.oid # => "rsaEncryption"

private_to_der -> StringRuby 3.0 から[permalink][rdoc][edit]

private_to_der(cipher, password) -> String

秘密鍵を DER 形式の PKCS #8 形式にシリアライズします。

引数なしで呼び出した場合は、暗号化されていない PKCS #8 PrivateKeyInfo 形式を使います。cipher と password を指定して呼び出した場合は、PBES2 暗号化方式を使った PKCS #8 EncryptedPrivateKeyInfo 形式を使います。

[PARAM] cipher:: 秘密鍵を暗号化する暗号アルゴリズムの名前、または OpenSSL::Cipher オブジェクト
[PARAM] password:: 暗号化に使うパスワード

[SEE_ALSO] OpenSSL::PKey::PKey#private_to_pem

private_to_pem -> StringRuby 3.0 から[permalink][rdoc][edit]

private_to_pem(cipher, password) -> String

秘密鍵を PEM 形式の PKCS #8 形式にシリアライズします。

暗号化されていない場合は "-----BEGIN PRIVATE KEY-----" で、暗号化されている場合は "-----BEGIN ENCRYPTED PRIVATE KEY-----" で始まる PEM データになります。

詳細は OpenSSL::PKey::PKey#private_to_der を参照してください。

[PARAM] cipher:: OpenSSL::PKey::PKey#private_to_der を参照してください
[PARAM] password:: OpenSSL::PKey::PKey#private_to_der を参照してください

[SEE_ALSO] OpenSSL::PKey::PKey#private_to_der

public_to_der -> StringRuby 3.0 から[permalink][rdoc][edit]

公開鍵を DER 形式の X.509 SubjectPublicKeyInfo 形式にシリアライズします。

[EXCEPTION] OpenSSL::PKey::PKeyError:: 公開鍵やパラメータの情報が無い場合などに発生します

public_to_pem -> StringRuby 3.0 から[permalink][rdoc][edit]

公開鍵を PEM 形式の X.509 SubjectPublicKeyInfo 形式にシリアライズします。

PEM データは "-----BEGIN PUBLIC KEY-----" で始まります。

[EXCEPTION] OpenSSL::PKey::PKeyError:: 公開鍵やパラメータの情報が無い場合などに発生します

raw_private_key -> StringRuby 3.3 から[permalink][rdoc][edit]

self の生の秘密鍵をバイト列で返します。

X25519 や Ed25519 のように、raw private/public key 形式を使う公開鍵アルゴリズム向けのメソッドです。

[EXCEPTION] OpenSSL::PKey::PKeyError:: 取得に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::PKey#raw_public_key, OpenSSL::PKey?.new_raw_private_key

raw_public_key -> StringRuby 3.3 から[permalink][rdoc][edit]

self の生の公開鍵をバイト列で返します。

X25519 や Ed25519 のように、raw private/public key 形式を使う公開鍵アルゴリズム向けのメソッドです。

[EXCEPTION] OpenSSL::PKey::PKeyError:: 取得に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::PKey#raw_private_key, OpenSSL::PKey?.new_raw_public_key

sign(digest, data) -> String[permalink][rdoc][edit]

秘密鍵で data に署名し、署名の文字列を返します。

digest は利用するハッシュ関数の名前を "sha256" や "md5" といった文字列で指定します。

DSA で署名をする場合はハッシュ関数には "dss1" を指定してください。

[PARAM] digest:: 利用するハッシュ関数の名前
[PARAM] data:: 署名する文字列
[EXCEPTION] OpenSSL::PKey::PKeyError:: 署名時にエラーが起きた場合に発生します

sign_raw(digest, data) -> StringRuby 3.1 から[permalink][rdoc][edit]

sign_raw(digest, data, options) -> String

秘密鍵の部分を使って data に署名します。OpenSSL::PKey::PKey#sign と異なり、data はこのメソッドの中ではハッシュ化されません。

検証には OpenSSL::PKey::PKey#verify_raw を使います。

[PARAM] digest:: 利用するメッセージダイジェストアルゴリズムの名前を表す文字列です。鍵の種類によってダイジェストアルゴリズムを必要としない場合は nil を指定します。このメソッドは data をハッシュ化しませんが、署名アルゴリズムによってはこの引数が必要になることがあります
[PARAM] data:: 署名するデータの文字列
[PARAM] options:: OpenSSL に渡すアルゴリズム固有の制御用オプションを指定するハッシュです(省略可)。指定できる内容は OpenSSL のマニュアル EVP_PKEY_CTX_ctrl_str(3) を参照してください

[SEE_ALSO] OpenSSL::PKey::PKey#verify_raw

require "openssl"
data = "Sign me!"
hash = OpenSSL::Digest.digest("SHA256", data)
pkey = OpenSSL::PKey.generate_key("RSA", "rsa_keygen_bits" => 2048)
signopts = { "rsa_padding_mode" => "pss" }
signature = pkey.sign_raw("SHA256", hash, signopts)
pub_key = pkey.public_key
p pub_key.verify_raw("SHA256", signature, hash, signopts) # => true

verify(digest, sign, data) -> bool[permalink][rdoc][edit]

data を秘密鍵で署名したその署名文字列が sign であることを公開鍵を使って検証し、検証に成功すれば true を返します。

digest は利用するハッシュ関数の名前を "sha256" や "md5" といった文字列で指定します。

DSA で検証をする場合はハッシュ関数には "dss1" を指定してください。

検証に失敗した、つまり署名時と異なるハッシュ関数を使った、 sign が正しい署名でなかった場合などは false を返します。

[PARAM] digest:: 利用するハッシュ関数の名前
[PARAM] sign:: 検証に利用する署名文字列
[PARAM] data:: 検証対象の文字列
[EXCEPTION] OpenSSL::PKey::PKeyError:: 検証時にエラーが起きた場合に発生します。正しい署名でなかった場合など、検証に失敗した場合はこの例外は発生しないことに注意してください

verify_raw(digest, signature, data) -> boolRuby 3.1 から[permalink][rdoc][edit]

verify_raw(digest, signature, data, options) -> bool

公開鍵の部分を使って、signature が data の署名として正しいかどうかを検証します。OpenSSL::PKey::PKey#verify と異なり、data はこのメソッドの中ではハッシュ化されません。

署名の生成には OpenSSL::PKey::PKey#sign_raw を使います。

検証に成功した場合は true を、失敗した場合は false を返します。呼び出し側で返り値を確認する必要があります。

[PARAM] digest:: OpenSSL::PKey::PKey#sign_raw を参照してください
[PARAM] signature:: 検証する署名の文字列
[PARAM] data:: 検証対象のデータの文字列
[PARAM] options:: OpenSSL::PKey::PKey#sign_raw を参照してください
[RETURN]: 検証に成功すれば true、失敗すれば false

[SEE_ALSO] OpenSSL::PKey::PKey#sign_raw

verify_recover(digest, signature) -> StringRuby 3.1 から[permalink][rdoc][edit]

verify_recover(digest, signature, options) -> String

公開鍵の部分を使って、signature から署名対象のデータを復元します。すべての署名アルゴリズムがこの操作に対応しているわけではありません。

[PARAM] digest:: OpenSSL::PKey::PKey#sign_raw を参照してください
[PARAM] signature:: 検証する署名の文字列
[PARAM] options:: OpenSSL::PKey::PKey#sign_raw を参照してください
[RETURN]: signature から復元されたデータの文字列
[EXCEPTION] OpenSSL::PKey::PKeyError:: 復元に失敗した場合に発生します

要約

目次

インスタンスメソッド