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

要約

RSA 暗号鍵のクラスです。

通常このクラスで利用するのは、 OpenSSL::PKey::RSA.generate, OpenSSL::PKey::RSA.new, OpenSSL::PKey::RSA#public?, OpenSSL::PKey::RSA#private?, OpenSSL::PKey::RSA#public_key, OpenSSL::PKey::RSA#to_text, OpenSSL::PKey::RSA#to_pem, OpenSSL::PKey::RSA#to_der のいずれかでしょう。これ以外のメソッドを利用するときは RSA についてよく理解し、必要な場合のみにすべきです。

例

require 'openssl'

# initialize random seed
OpenSSL::Random.seed(File.read("/dev/random", 16))
# 鍵対を生成
rsa = OpenSSL::PKey::RSA.generate(2048)
# 秘密鍵をAES256で暗号化して private_key.pem に PEM 形式で保存
passphrase = "!secret passphrase!"
File.open("private_key.pem", "w") do |f|
  f.write(rsa.export(OpenSSL::Cipher.new("aes256"), passphrase))
end
# 公開鍵をpublic_key.pemに保存
public_key = rsa.public_key
File.open("public_key.pem", "w") do |f|
  f.write(public_key.export)
end
  
# 秘密鍵で署名
data = "foobar"
sign = rsa.sign("sha256", data)
# 公開鍵で検証
p public_key.verify("sha256", sign, data)
# 不正なデータを検証
p public_key.verify("sha256", sign, "foobarbaz")

継承しているメソッド

OpenSSL::PKey::PKeyから継承しているメソッド

特異メソッド

generate(size, exponent = 65537) -> OpenSSL::PKey::RSA[permalink][rdoc][edit]

generate(size, exponent = 65537) {|u,n| ... } -> OpenSSL::PKey::RSA

乱数により RSA 公開鍵と秘密鍵のペアを生成して、RSA オブジェクトを返します。

このメソッドを呼ぶ前に OpenSSL::Random の各モジュール関数によって乱数が適切に初期化されている必要があります。

size で鍵の modulus のビット数つまりは鍵のサイズを指定します。最低でも1024を指定してください。 exponent で public exponent を指定します。exponent には奇数を指定し、大抵の場合、3、17 あるいは 65537 を指定します。

このメソッドにブロックが渡された場合には、鍵生成の途中経過の情報を引数としてブロックが呼び出されます。

n個目の素数候補を生成した場合、u=0 でブロックが呼びだされる
生成した素数候補がn回目の素数テスト(Miller-Robin)に成功した場合、u=1 でブロックが呼び出される
n個目に生成した素数が鍵として不適切な場合には、u=2 でブロックが呼びだされる
p-1 が e と互いに素であるような素数 p が見付かった場合には、 u=3, n=0 でブロックが呼び出される
以上の素数生成をもう一度繰り返し、適切な素数 q が見付かった場合には、 u=3, n=1 でブロックが呼び出される

RSA 鍵ペアの生成には時間がかかるため、鍵生成の途中経過をユーザに表示したい場合にこの機能を使います。

[PARAM] size:: 鍵のサイズ
[PARAM] exponent:: public exponent

new(size, exponent = 65537) -> OpenSSL::PKey::RSA[permalink][rdoc][edit]

new(size, exponent = 65537) {|u,n| ... } -> OpenSSL::PKey::RSA

new(obj, pass = nil) -> OpenSSL::PKey::RSA

new(obj, pass = nil) {|flag| ... } -> OpenSSL::PKey::RSA

RSA 暗号鍵オブジェクトを生成します。

引数なしでの呼び出しは ArgumentError が発生するため使用できません。新しい鍵を生成する場合は OpenSSL::PKey::RSA.generate を使用してください。

第一引数に整数を指定した場合には、OpenSSL::PKey::RSA.generate により公開鍵と秘密鍵のペアを生成し、それを返します。

それ以外の場合には、以下のようにして鍵データを読みこみ、RSA オブジェクトを生成します。

第一引数が文字列の場合は、PEM 形式もしくは DER 形式と仮定して鍵データを読み込みます
第一引数が IO オブジェクトの場合は、その内容を読み込んで RSA オブジェクトを生成します。
第一引数が to_der メソッドを持つ場合は、それにより DER 形式の文字列に変換してから読み込みます

pass が指定された場合は、秘密鍵を pass を使って復号化します。

鍵データにパスフレーズが設定されているにもかかわらず、passが省略された場合は、渡されたブロックを呼びだしてパスフレーズを要求します。ブロックの返り値をパスフレーズとみなして復号します。ブロックの引数は通常は false が渡されますが、これはそのパスフレーズが秘密鍵の復号に使われることを意味します。ブロックが渡されなかった場合にはターミナルに問い合わせをします。

[PARAM] size:: 鍵生成をする場合の鍵のサイズ
[PARAM] exponent:: public exponent
[PARAM] obj:: 鍵データ
[PARAM] pass:: 鍵データに設定したパスフレーズ
[EXCEPTION] ArgumentError:: 引数なしで呼び出した場合に発生します。
[EXCEPTION] OpenSSL::PKey::RSAError:: 鍵の読み込みに失敗した場合に発生します。

インスタンスメソッド

d -> OpenSSL::BN[permalink][rdoc][edit]

鍵の private exponent です。

これは秘密鍵の一部です。

dmp1 -> OpenSSL::BN[permalink][rdoc][edit]

鍵の exponent1 (d mod (p-1)) です。

秘密鍵の情報です。

dmq1 -> OpenSSL::BN[permalink][rdoc][edit]

鍵の exponent2 (d mod (q-1)) です。

秘密鍵の情報です。

e -> OpenSSL::BN[permalink][rdoc][edit]

鍵の public exponent を返します。

これは公開鍵の一部です。

export(cipher=nil, pass=nil) -> String[permalink][rdoc][edit]

export(cipher=nil, pass=nil) {|flag| ... } -> String

to_pem(cipher=nil, pass=nil) -> String

to_pem(cipher=nil, pass=nil) {|flag| ... } -> String

to_s(cipher=nil, pass=nil) -> String

to_s(cipher=nil, pass=nil) {|flag| ... } -> String

鍵を PEM 形式で出力します。

cipher と pass が指定された場合、秘密鍵を暗号 cipher OpenSSL::Cipher::Cipher とパスワード pass を使って暗号化します。

cipher を指定して pass を省略した場合は渡されたブロックを呼びだしてパスフレーズを要求します。ブロックの返り値をパスフレーズとみなして暗号化します。ブロックの引数は通常は true が渡されますが、これはそのパスフレーズが秘密鍵の暗号化に使われることを意味します。ブロックが渡されなかった場合にはターミナルに問い合わせをします。

公開鍵を出力する場合は cipher と pass は無視されます。

iqmp -> OpenSSL::BN[permalink][rdoc][edit]

鍵の coefficient (inverse of q mod p) です。

秘密鍵の情報です。

n -> OpenSSL::BN[permalink][rdoc][edit]

鍵の modulus です。

公開鍵、秘密鍵両方の一部です。

p -> OpenSSL::BN[permalink][rdoc][edit]

鍵の1つめの素数です。

秘密鍵の情報です。

params -> {String => OpenSSL::BN}[permalink][rdoc][edit]

鍵のパラメータ(OpenSSL::PKey::RSA#e,OpenSSL::PKey::RSA#n, OpenSSL::PKey::RSA#dなど)を{パラメータ名文字列 => パラメータ値} というハッシュで返します。

鍵が公開鍵の場合、OpenSSL::PKey::RSA#d のように公開鍵が持っていない値は 0 になります。

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

自身が秘密鍵を持っているかどうか判定します。

private_decrypt(str, mode = OpenSSL::PKey::RSA::PKCS1_PADDING) -> String[permalink][rdoc][edit]

文字列 str を秘密鍵で復号化します。

復号化されたデータを文字列で返します。

mode でパディングモードを指定します。暗号化に利用したパディングモードと同じものを指定する必要があります。以下の4つのうちいずれかが利用可能です。

[PARAM] str:: 暗号化する文字列
[PARAM] mode:: パディングモード
[EXCEPTION] OpenSSL::PKey::RSAError:: 復号化に失敗した場合に発生します。公開鍵で復号しようとした場合、鍵が間違っていた場合、暗号化に使ったパディングモードと異なるモードを使った場合などに発生します。

private_encrypt(str, mode = OpenSSL::PKey::RSA::PKCS1_PADDING) -> String[permalink][rdoc][edit]

文字列 str を秘密鍵で暗号化します。

暗号化されたデータを文字列で返します。

mode でパディングモードを指定します。以下のいずれかが利用可能です。

[PARAM] str:: 暗号化する文字列
[PARAM] mode:: パディングモード
[EXCEPTION] OpenSSL::PKey::RSAError:: 暗号化に失敗した場合に発生します。自身が秘密鍵でない場合などに発生します。

public? -> true[permalink][rdoc][edit]

自身が公開鍵を持っているかどうか判定します。

秘密鍵は公開鍵も持っているため、常に true を返します。

public_decrypt(str, mode = OpenSSL::PKey::RSA::PKCS1_PADDING) -> String[permalink][rdoc][edit]

文字列 str を公開鍵で復号化します。

復号化されたデータを文字列で返します。

mode でパディングモードを指定します。以下のいずれかが利用可能です。暗号化に利用したパディングモードと同じものを指定する必要があります。

[PARAM] str:: 復号化する文字列
[PARAM] mode:: パディングモード
[EXCEPTION] OpenSSL::PKey::RSAError:: 復号化に失敗した場合に発生します。

public_encrypt(str, mode = OpenSSL::PKey::RSA::PKCS1_PADDING) -> String[permalink][rdoc][edit]

文字列 str を公開鍵で暗号化します。

暗号化されたデータを文字列で返します。

mode でパディングモードを指定します。以下の4つのうちいずれかが利用可能です。

[PARAM] str:: 暗号化する文字列
[PARAM] mode:: パディングモード
[EXCEPTION] OpenSSL::PKey::RSAError:: 暗号化に失敗した場合に発生します。

public_key -> OpenSSL::PKey::RSA[permalink][rdoc][edit]

公開鍵を複製して RSA オブジェクトとして返します。

q -> OpenSSL::BN[permalink][rdoc][edit]

鍵の2つめの素数です。

秘密鍵の情報です。

set_crt_params(dmp1, dmq1, iqmp) -> selfRuby 2.4.0 から[permalink][rdoc][edit]

dmp1, dmq1, iqmp を self に設定します。それぞれ d mod (p - 1)、d mod (q - 1)、q^(-1) mod p として計算される値です。

[PARAM] dmp1:: 設定する OpenSSL::BN オブジェクト
[PARAM] dmq1:: 設定する OpenSSL::BN オブジェクト
[PARAM] iqmp:: 設定する OpenSSL::BN オブジェクト
[EXCEPTION] OpenSSL::PKey::PKeyError:: OpenSSL 3.0 以降とリンクされている場合に発生します。鍵オブジェクトが変更不可(immutable)になるため、このメソッドは利用できません

[SEE_ALSO] OpenSSL::PKey::RSA#dmp1, OpenSSL::PKey::RSA#dmq1, OpenSSL::PKey::RSA#iqmp

set_factors(p, q) -> selfRuby 2.4.0 から[permalink][rdoc][edit]

p, q を self に設定します。

[PARAM] p:: 設定する OpenSSL::BN オブジェクト
[PARAM] q:: 設定する OpenSSL::BN オブジェクト
[EXCEPTION] OpenSSL::PKey::PKeyError:: OpenSSL 3.0 以降とリンクされている場合に発生します。鍵オブジェクトが変更不可(immutable)になるため、このメソッドは利用できません

[SEE_ALSO] OpenSSL::PKey::RSA#p, OpenSSL::PKey::RSA#q

set_key(n, e, d) -> selfRuby 2.4.0 から[permalink][rdoc][edit]

n, e, d を self に設定します。

[PARAM] n:: 設定する OpenSSL::BN オブジェクト
[PARAM] e:: 設定する OpenSSL::BN オブジェクト
[PARAM] d:: 設定する OpenSSL::BN オブジェクト
[EXCEPTION] OpenSSL::PKey::PKeyError:: OpenSSL 3.0 以降とリンクされている場合に発生します。鍵オブジェクトが変更不可(immutable)になるため、このメソッドは利用できません

[SEE_ALSO] OpenSSL::PKey::RSA#n, OpenSSL::PKey::RSA#e, OpenSSL::PKey::RSA#d

sign_pss(digest, data, salt_length:, mgf1_hash:) -> StringRuby 2.5.0 から[permalink][rdoc][edit]

RSA-PSS (Probabilistic Signature Scheme) を使って data に署名し、計算した署名を返します。

エラーが発生した場合は OpenSSL::PKey::PKeyError が発生します。

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

[PARAM] digest:: 利用するメッセージダイジェストアルゴリズムの名前を表す文字列
[PARAM] data:: 署名するデータの文字列
[PARAM] salt_length:: ソルトの長さ(オクテット単位)です。特別な値として、ダイジェストの長さを意味する :digest と、秘密鍵と選択したメッセージダイジェストアルゴリズムの組み合わせで可能な最大の長さを意味する :max が指定できます
[PARAM] mgf1_hash:: MGF1(サポートされているマスク生成関数(MGF))で使うハッシュアルゴリズム
[EXCEPTION] OpenSSL::PKey::PKeyError:: エラーが発生した場合に発生します

[SEE_ALSO] OpenSSL::PKey::RSA#verify_pss

require "openssl"
data = "Sign me!"
pkey = OpenSSL::PKey::RSA.generate(2048)
signature = pkey.sign_pss("SHA256", data, salt_length: :max, mgf1_hash: "SHA256")
pub_key = OpenSSL::PKey.read(pkey.public_to_der)
p pub_key.verify_pss("SHA256", signature, data, salt_length: :auto, mgf1_hash: "SHA256") # => true

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

自身を DER 形式に変換します。

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

鍵を人間が読める形式に変換します。

verify_pss(digest, signature, data, salt_length:, mgf1_hash:) -> boolRuby 2.5.0 から[permalink][rdoc][edit]

RSA-PSS を使って data の署名を検証します。

署名が正しい場合は true を、そうでない場合は false を返します。エラーが発生した場合は OpenSSL::PKey::PKeyError が発生します。

署名の生成については OpenSSL::PKey::RSA#sign_pss を参照してください。

[PARAM] digest:: 利用するメッセージダイジェストアルゴリズムの名前を表す文字列
[PARAM] signature:: 検証する署名の文字列
[PARAM] data:: 署名されたデータの文字列
[PARAM] salt_length:: ソルトの長さ(オクテット単位)です。特別な値として、ダイジェストの長さを意味する :digest と、署名をもとに長さを自動的に決定することを意味する :auto が指定できます
[PARAM] mgf1_hash:: MGF1 で使うハッシュアルゴリズム
[RETURN]: 署名が正しい場合は true、そうでない場合は false
[EXCEPTION] OpenSSL::PKey::PKeyError:: エラーが発生した場合に発生します