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

要約

Diffie-Hellman 鍵共有クラス

Diffie-Hellman 鍵共有プロトコルは署名ができないため、 OpenSSL::PKey::PKey#sign や OpenSSL::PKey::PKey#verify を呼び署名や署名の検証を行おうとすると例外 OpenSSL::PKey::PKeyError が発生します。

Diffie-Hellman はこのライブラリでは基本的には鍵共有にしか利用できません。

例

鍵共有の例。

require 'openssl'

# パラメータの生成
dh = OpenSSL::PKey::DH.generate(1024, 5)
# パラメータのチェック
raise "bad DH parameter" unless dh.params_ok?
# 以下、dh1 と dh2 が通信の両端であるとする
#  dh1 と dh2 は鍵パラメータ p と g を共有しなければならない
#  そのためここでは、単純に2つ複製することにしている

# dh1 は dh をそのまま使う
dh1 = dh
# パラメータを複製して dh2 に渡す
dh2 = OpenSSL::PKey::DH.new(dh)

# 両端が鍵パラメータから鍵対を生成する
dh1.generate_key!
dh2.generate_key!
# 通信の両端で公開鍵を交換する
#  公開鍵の交換は秘密で行われる必要はないが、それが確かに
#  相手の公開鍵であることを確認しなければならない。
#  (さもなければ中間者攻撃などによって秘密情報は危険にさらされる)
#  そのため自分の公開鍵を DSA などで署名してから交換する必要がある
#  ここでは例を簡単にするため、そのような処置はしていない
# dh1 の秘密鍵と dh2 の公開鍵、共有された鍵パラメータを
# 用いて dh1 側で鍵となる文字列を得る
key1 = dh1.compute_key(dh2.pub_key)
# dh2 の秘密鍵と dh1 の公開鍵、共有された鍵パラメータを
# 用いて dh2 側で鍵となる文字列を得る
key2 = dh1.compute_key(dh1.pub_key)
# key1 と key2 は同じ文字列となり、しかもこれは秘密鍵なしでは
# 得られないため、安全に秘密情報(ランダムな鍵文字列)を交換
# できたこととなる
p(key1 == key2)

継承しているメソッド

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

sign
verify

特異メソッド

generate(size, generator = 2) -> PKey::DH[permalink][rdoc][edit]

generate(size, generator = 2) {|u,n| ... } -> PKey::DH

DH 鍵共有プロトコルのパラメータを生成し、DH オブジェクトを返します。

size は無作為に生成する素数 p (鍵パラメータ)のサイズで、単位はビットです。 generatorは1より大きい小さい数で、通常2か5を指定します。

生成した値は OpenSSL::PKey::DH#params_ok? で安全かどうかチェックしてから利用してください。

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

n個目の素数候補を生成した場合、u=0 でブロックが呼びだされる
生成した素数候補がn回目の素数テスト(Miller-Robin)に成功した場合、u=1 でブロックが呼び出される
n個目に生成した素数が鍵として不適切な場合には、u=2 でブロックが呼びだされる
パラメータとして適当な素数 p が見付かった場合には、 u=3, n=0 でブロックが呼び出される

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

この場合鍵対も同時に生成されます。

[PARAM] size:: 鍵パラメータの素数のサイズ(ビット数)
[PARAM] generator:: 鍵パラメータの生成元(2以上の整数、通常2か5)
[EXCEPTION] OpenSSL::PKey::DHError:: パラメータの生成に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::DH#generate_key!

new(size, generator = 2) -> OpenSSL::PKey::DH[permalink][rdoc][edit]

new(obj) -> OpenSSL::PKey::DH

new() -> OpenSSL::PKey::DH

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

第1引数に整数を渡した場合は、OpenSSL::PKey::DH#generate と同じです。

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

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

この場合鍵対は空です。

引数をまったく与えない場合は空の DH オブジェクトが生成されます。このオブジェクトには鍵パラメータも鍵対も設定されていません。

[PARAM] size:: 鍵パラメータの素数のサイズ(ビット数)
[PARAM] generator:: 鍵パラメータの生成元(2以上の整数、通常2か5)
[PARAM] obj:: 鍵パラメータを読み込むオブジェクト
[EXCEPTION] OpenSSL::PKey::DHError:: オブジェクトの生成に失敗した場合に発生します

[SEE_ALSO] OpenSSL::PKey::DH#generate_key!

インスタンスメソッド

compute_key(bn) -> String[permalink][rdoc][edit]

自分の秘密鍵と相手の公開鍵から鍵文字列を計算し、返します。

相手の公開鍵は OpenSSL::BN か Integer である必要があります。

[PARAM] bn:: 相手の公開鍵(OpenSSL::BN)

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

to_pem -> String

to_s -> String

鍵パラメータを PEM 形式に変換します。

鍵対の値は出力されません。

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

DH 鍵共有プロトコルの鍵パラメータ g を返します。

この値は生成元と呼ばれます。

[SEE_ALSO] OpenSSL::PKey::DH#g=

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

DH 鍵共有プロトコルの鍵パラメータ g を設定します。

通常このメソッドで値を変更することはありません。よく考えて必要な場合のみ利用してください。

[PARAM] g:: 設定する整数値(OpenSSL::BN)

[SEE_ALSO] OpenSSL::PKey::DH#g

generate_key! -> self[permalink][rdoc][edit]

鍵パラメータ p と g から鍵対を生成しなおし、自身にセットします。

以前の鍵対の値は廃棄されます。

生成した値は OpenSSL::PKey::DH#params_ok? で安全かどうかチェックしてから利用してください。

[EXCEPTION] OpenSSL::PKey::DHError:: 鍵の生成に失敗した場合に発生します

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

DH 鍵共有プロトコルの鍵パラメータ p を返します。

このパラメータは安全な素数でなければなりません。

[SEE_ALSO] OpenSSL::PKey::DH#p=

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

DH 鍵共有プロトコルの鍵パラメータ p を設定します。

通常このメソッドで値を変更することはありません。よく考えて必要な場合のみ利用してください。

[PARAM] p:: 設定する整数値(OpenSSL::BN)

[SEE_ALSO] OpenSSL::PKey::DH#p

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

鍵パラメータと鍵対を {"パラメータ名" => パラメータ値} というハッシュテーブルで返します。

ハッシュテーブルのキーは "p", "g", "pub_key", "priv_key" の4つです。自身が内部に鍵対を持っていない場合は、 "pub_key" と "priv_key" に対応する値は 0 となります。

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

パラメータ p と g が安全かどうかを判定します。

[SEE_ALSO] OpenSSL::PKey::DH#generate_key!, OpenSSL::PKey::DH.generate

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

DH 鍵共有プロトコルの秘密鍵を返します。

[SEE_ALSO] OpenSSL::PKey::DH#priv_key=

priv_key=(private_key)[permalink][rdoc][edit]

DH 鍵共有プロトコルの秘密鍵を設定します。

通常このメソッドで値を変更することはありません。よく考えて必要な場合のみ利用してください。

[PARAM] private_key:: 設定する整数値(OpenSSL::BN)

[SEE_ALSO] OpenSSL::PKey::DH#priv_key, OpenSSL::PKey::DH#generate_key!

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

DH 鍵共有プロトコルの公開鍵を返します。

[SEE_ALSO] OpenSSL::PKey::DH#pub_key=

pub_key=(public_key)[permalink][rdoc][edit]

DH 鍵共有プロトコルの公開鍵を設定します。

通常このメソッドで値を変更することはありません。よく考えて必要な場合のみ利用してください。

[PARAM] public_key:: 設定する整数値(OpenSSL::BN)

[SEE_ALSO] OpenSSL::PKey::DH#pub_key, OpenSSL::PKey::DH#generate_key!

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

鍵パラメータをDER 形式に変換します。

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

鍵パラメータを人間が読める形式に変換します。

鍵対の値は出力されません。

要約

例

目次

継承しているメソッド

特異メソッド

インスタンスメソッド