class OpenSSL::PKey::DH

要約

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)

目次

特異メソッド

• generate
• new

インスタンスメソッド

• compute_key
• export
• g
• generate_key!
• p
• params
• params_ok?
• priv_key
• private?
• pub_key
• public?
• public_key
• q
• set_key
• set_pqg
• to_der
• to_pem
• to_s
• to_text

継承しているメソッド

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

• compare?
• decapsulate
• decrypt
• derive
• encapsulate
• encrypt
• get_param
• oid
• private_to_der
• private_to_pem
• public_to_der
• public_to_pem
• raw_private_key
• raw_public_key
• sign
• sign_raw
• verify
• verify_raw
• verify_recover

特異メソッド

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 を返します。

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

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 を返します。

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

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 鍵共有プロトコルの秘密鍵を返します。

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

self が秘密鍵を保持しているかどうかを判定します。

秘密鍵は OpenSSL::PKey::DH#priv_key で取得できます。

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

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

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

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

self が公開鍵を保持しているかどうかを判定します。

公開鍵は OpenSSL::PKey::DH#pub_key で取得できます。

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

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

self の鍵パラメータ(p, g)だけを持つ新しい DH インスタンスを返します。

メソッド名に反して、返り値のオブジェクトは鍵パラメータのみを持ち、公開鍵(pub_key)は含まれません。

このメソッドは後方互換性のために提供されています。多くの場合、このメソッドを呼ぶ必要はありません。公開鍵をシリアライズしたい場合は OpenSSL::PKey::PKey#public_to_pem や OpenSSL::PKey::PKey#public_to_der を使ってください。パラメータを保持したまま鍵対を再生成したい場合は OpenSSL::PKey?.generate_key の利用を検討してください。

require "openssl"
dh1 = OpenSSL::PKey::DH.generate(2048)
p dh1.priv_key.class # => OpenSSL::BN
dhcopy = dh1.public_key
p dhcopy.priv_key # => nil

q -> OpenSSL::BNRuby 2.4.0 から[permalink][rdoc][edit]

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

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

set_key(pub_key, priv_key) -> selfRuby 2.4.0 から[permalink][rdoc][edit]

pub_key と priv_key を self に設定します。

[PARAM] pub_key:

設定する OpenSSL::BN オブジェクト

[PARAM] priv_key:

設定する OpenSSL::BN オブジェクトです。nil でもかまいません

[EXCEPTION] OpenSSL::PKey::PKeyError:

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

[SEE_ALSO] OpenSSL::PKey::DH#pub_key, OpenSSL::PKey::DH#priv_key

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

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

[PARAM] p:

設定する OpenSSL::BN オブジェクト

[PARAM] q:

設定する OpenSSL::BN オブジェクト

[PARAM] g:

設定する OpenSSL::BN オブジェクト

[EXCEPTION] OpenSSL::PKey::PKeyError:

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

[SEE_ALSO] OpenSSL::PKey::DH#p, OpenSSL::PKey::DH#q, OpenSSL::PKey::DH#g

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

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

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

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

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