Ruby 4.1 リファレンスマニュアル

class OpenSSL::SSL::SSLContext

[edit]

要約

SSL コンテキストクラス。

SSL コネクション(OpenSSL::SSL::SSLSocket や OpenSSL::SSL::SSLServer) オブジェクトを生成するためのファクトリクラスです。コネクションを生成するために必要なパラメータ(プロトコルのバージョン、証明書の情報、認証の要件など)を保持します。

コネクションを1度生成して以降は、コンテキストが保持しているパラメータを変更できません。一部のパラメータが共有されるため、安全性のため Object#freeze によってオブジェクトを変更不可能にします。ただしこの凍結は完全ではなく、この後もセッション管理機能によってオブジェクトのキャッシュ領域にセッションを追加したり削除したりできます。

Constants

verify_mode= と options= で指定できる定数に関しては OpenSSL::SSL を参照してください。

目次

特異メソッド
インスタンスメソッド
定数

特異メソッド

new(ssl_method) -> OpenSSL::SSL::SSLContext[permalink][rdoc][edit]
new -> OpenSSL::SSL::SSLContext

SSL コンテキストオブジェクトを生成します。

ssl_method で利用するプロトコルの種類を文字列もしくはシンボルで指定します。以下のいずれかが利用可能です。

  • 'TLSv1' TLSv1サーバクライアント両用
  • 'TLSv1_server' TLSv1サーバ用
  • 'TLSv1_client' TLSv1クライアント用
  • 'TLSv1_1'
  • 'TLSv1_1_server'
  • 'TLSv1_1_client'
  • 'TLSv1_2'
  • 'TLSv1_2_server'
  • 'TLSv1_2_client'
  • 'SSLv2' SSLv2サーバクライアント両用
  • 'SSLv2_server' SSLv2サーバ用
  • 'SSLv2_client' SSLv2クライアント用
  • 'SSLv3' SSLv3サーバクライアント両用
  • 'SSLv3_server' SSLv3サーバ用
  • 'SSLv3_client' SSLv3クライアント用
  • 'SSLv23' SSLv2,3/TLSv1サーバクライアント両用
  • 'SSLv23_server' SSLv2,3/TLSv1サーバ用
  • 'SSLv23_client' SSLv2,3/TLSv1クライアント用

SSLv2 はプロトコル上の脆弱性が明らかにされているため使うべきではありません。

SSLv2 は無効化して SSLv3 と TLSv1 の両方を有効化するためには 'SSLv23' を指定し、OpenSSL::SSL::SSLContext#options= で OpenSSL::SSL::OP_NO_SSLv2 を指定します。

[PARAM] ssl_method:
プロトコルを表す文字列もしくはシンボル

[SEE_ALSO] OpenSSL::SSL::SSLContext#ssl_version=

インスタンスメソッド

add_certificate(certificate, pkey, extra_certs = nil) -> selfRuby 2.5.0 から[permalink][rdoc][edit]

証明書とその秘密鍵を self に追加します。

certificate に対応する秘密鍵を pkey で指定します。公開鍵の種類(RSA、ECDSA など)が異なる証明書を複数回に分けて追加でき、ハンドシェイク時に OpenSSL がそのときの状況に最も適した証明書を選択します。

OpenSSL::SSL::SSLContext#cert=、OpenSSL::SSL::SSLContext#key=、OpenSSL::SSL::SSLContext#extra_chain_cert= は証明書を設定するための古い方法で、内部的にはこのメソッドを呼び出します。

[PARAM] certificate:
追加する証明書(OpenSSL::X509::Certificate のインスタンス)
[PARAM] pkey:
certificate に対応する秘密鍵(OpenSSL::PKey::PKey のインスタンス)
[PARAM] extra_certs:
certificate に続けて送信する証明書チェイン(OpenSSL::X509::Certificate の配列)
[EXCEPTION] ArgumentError:
certificate が公開鍵を含んでいない場合や、pkey が certificate の公開鍵と一致しない場合に発生します
[EXCEPTION] OpenSSL::SSL::SSLError:
証明書や秘密鍵の設定に失敗した場合に発生します 
ctx.add_certificate(rsa_cert, rsa_pkey, [ca_intermediate_cert])

[SEE_ALSO] OpenSSL::SSL::SSLContext#cert=, OpenSSL::SSL::SSLContext#key=, OpenSSL::SSL::SSLContext#extra_chain_cert=

alpn_protocols -> [String] | nilRuby 2.3.0 から[permalink][rdoc][edit]
alpn_protocols=(protocols)

Application-Layer Protocol Negotiation(ALPN)で通知するプロトコル名の一覧を取得・設定します。

alpn_protocols= で設定した文字列の配列がハンドシェイク時に ALPN 拡張として送信されます。クライアント側で設定するものであり、サーバ側で設定しても効果はありません。設定しなかった場合、ハンドシェイクに ALPN 拡張は含まれません。

サーバ側でクライアントが提示したプロトコルから選択するには OpenSSL::SSL::SSLContext#alpn_select_cb= を使います。

例 
require 'openssl'
ctx = OpenSSL::SSL::SSLContext.new
ctx.alpn_protocols = ["http/1.1", "spdy/2", "h2"]
[PARAM] protocols:
通知するプロトコル名の文字列の配列

[SEE_ALSO] OpenSSL::SSL::SSLContext#alpn_select_cb=, OpenSSL::SSL::SSLSocket#alpn_protocol

alpn_select_cb -> Proc | nilRuby 2.3.0 から[permalink][rdoc][edit]
alpn_select_cb=(cb)

ALPN 拡張でクライアントが提示したプロトコルの中から、サーバが利用するプロトコルを選択するためのコールバックを取得・設定します。

コールバックにはクライアントが提示したプロトコル名の文字列の配列が渡され、その中から選んだプロトコル名を文字列で返さなければなりません。提示された中に受け入れられるものがない場合は、コールバック内で例外を発生させるとハンドシェイクが失敗します。

このコールバックを設定しない場合、サーバ側は ALPN 拡張をサポートしません。クライアント側で設定しても効果はありません。

デフォルトは nil です。 

proc{|protocols| ... }
[PARAM] cb:
コールバックオブジェクト(Proc や Method など)

[SEE_ALSO] OpenSSL::SSL::SSLContext#alpn_protocols=

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

接続相手の検証のために使う、信頼している CA 証明書ファイルのパスを返します。

設定されていない場合は nil を返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#ca_file=

ca_file=(ca)[permalink][rdoc][edit]

接続相手の検証のために使う、信頼している CA 証明書ファイルのパスを設定します。

ファイルは以下のように複数の証明書を含んでいても構いません。 

(ここに証明書の説明)

-----BEGIN CERTIFICATE-----
... (CA certificate in base64 encoding) ...
-----END CERTIFICATE-----

(ここに証明書の説明)

-----BEGIN CERTIFICATE-----
... (CA certificate in base64 encoding) ...
-----END CERTIFICATE-----

デフォルトは nil です。

[PARAM] ca:
CA証明書ファイルのパス文字列

[SEE_ALSO] OpenSSL::SSL::SSLContext#ca_file=

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

信頼している CA 証明書ファイルを含むディレクトリを返します。

設定されていない場合は nil を返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#ca_path=

ca_path=(ca)[permalink][rdoc][edit]

接続相手の証明書の検証のために使う、信頼している CA 証明書ファイルを含むディレクトリを設定します。

そのディレクトリに含まれる証明書のファイル名は証明書のハッシュ値文字列でなければなりません。

[PARAM] ca:
CA 証明書ファイルを含むディレクトリ名文字列

[SEE_ALSO] OpenSSL::SSL::SSLContext#ca_path

cert -> OpenSSL::X509::Certificate[permalink][rdoc][edit]

自分自身を証明するための証明書を返します。

デフォルトは nil (証明書なし)です。

[SEE_ALSO] OpenSSL::SSL::SSLContext#cert=

cert=(certificate)[permalink][rdoc][edit]

自分自身を証明するための証明書を設定します。

デフォルトは nil (証明書なし)です。

[PARAM] certificate:
設定する証明書(OpenSSL::X509::Certificate のインスタンス)

[SEE_ALSO] OpenSSL::SSL::SSLContext#cert

cert_store -> OpenSSL::X509::Store | nil[permalink][rdoc][edit]

接続相手の証明書の検証のために使う、信頼している CA 証明書を含む証明書ストアを返します。

デフォルトは nil です。

[SEE_ALSO] OpenSSL::SSL::SSLContext#cert_store=

cert_store=(store)[permalink][rdoc][edit]

接続相手の証明書の検証のために使う、信頼している CA 証明書を含む証明書ストアを設定します。

通常は OpenSSL::SSL::SSLContext#ca_path= や OpenSSL::SSL::SSLContext#ca_file= で証明書を設定しますが、 CRL を使いたいなど、より詳細な設定をしたい場合にはこれを使います。

デフォルトは nil (証明書ストアを指定しない)です。

[PARAM] store:
設定する証明書ストア(OpenSSL::X509::Store のインスタンス)

[SEE_ALSO] OpenSSL::SSL::SSLContext#cert_store

ciphers -> [[String, String, Integer, Integer]][permalink][rdoc][edit]

利用可能な共通鍵暗号の種類を配列で返します。

配列の各要素は以下のような配列です 

[暗号方式の名前の文字列, 利用可能なSSL/TLSのバージョン文字列, 鍵長(ビット数), アルゴリズムのビット長]
例 
require 'openssl'
ctx = OpenSSL::SSL::SSLContext.new('TLSv1')
p ctx.ciphers
# => [["DHE-RSA-AES256-SHA", "TLSv1/SSLv3", 256, 256], 
#     ["DHE-DSS-AES256-SHA", "TLSv1/SSLv3", 256, 256], ... ]
ciphers=(ciphers)[permalink][rdoc][edit]

利用可能な共通鍵暗号を設定します。

これによって、SSL コネクションにおいて特定の共通鍵暗号だけを利用可能にできます。

指定の方法は2種類あります。1つは 

"ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH"

のような文字列で指定する方法で、もう一つは配列で 

["ALL", "!ADH", "!LOW", "!EXP", "!MD5", "@STRENGTH"]

という配列で指定する方法です。上の2つの例は同じ内容を意味しています。詳しくは OpenSSL のマニュアルの SSL_CTX_set_cipher_list の項を見てください。

[PARAM] ciphers:
利用可能にする共通鍵暗号の種類
[EXCEPTION] OpenSSL::SSL::SSLError:
設定に失敗した場合に発生します
ciphersuites=(ciphers)Ruby 3.2 から[permalink][rdoc][edit]

TLS 1.3 で使う共通鍵暗号の一覧を設定します。

OpenSSL::SSL::SSLContext#ciphers= は TLS 1.2 以下向けの設定であり、TLS 1.3 の通信には影響しません。TLS 1.3 の暗号を設定するにはこのメソッドを使います。

指定の方法は OpenSSL::SSL::SSLContext#ciphers= と同様に、コロン区切りの文字列、もしくは名前の配列で指定します。

[PARAM] ciphers:
利用可能にする TLS 1.3 の共通鍵暗号の種類
[EXCEPTION] OpenSSL::SSL::SSLError:
設定に失敗した場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLContext#ciphers=

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

クライアント証明書を要求する時にクライアントに送る CA のリストを返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#client_ca=

client_ca=(ca)[permalink][rdoc][edit]

クライアント証明書を要求する時にクライアントに送る CA 証明書のリストを設定します。

クライアントは提示した CA から利用可能(署名されている)な証明書を送り返します。

このメソッドはサーバ側でのみ意味を持ちます。

OpenSSL::X509::Certificate の配列を渡します。1つの場合は OpenSSL::X509::Certificate オブジェクト自体を渡してもかまいません。

[PARAM] ca:
クライアント証明書を要求するときに提示する証明書の配列

[SEE_ALSO] OpenSSL::SSL::SSLContext#client_ca

client_cert_cb -> Proc | nil[permalink][rdoc][edit]

OpenSSL::SSL::SSLContext#cert= でクライアント証明書をセットしていなかった場合にサーバからクライアント証明書の要求が来たときに呼びだされるコールバックオブジェクトを返します。

デフォルトは nil (コールバックなし)です。

[SEE_ALSO] OpenSSL::SSL::SSLContext#client_cert_cb=

client_cert_cb=(cb)[permalink][rdoc][edit]

OpenSSL::SSL::SSLContext#cert= でクライアント証明書をセットしていなかった場合にサーバからクライアント証明書の要求が来たときに呼びだされるコールバックオブジェクトを設定します。

コールバックに渡される引数は以下のように 

proc{|sslsocket| ... }

1つで、利用している OpenSSL::SSL::SSLSocket オブジェクトが渡されます。そのオブジェクトから必要な証明書を見つけるのに必要な情報を取得します。コールバックはクライアント証明書(OpenSSL::X509::Certificate) とその秘密鍵(OpenSSL::PKey::PKey)のペアの配列を返さなければなりません。

証明書と鍵が見付からない場合は nil を返してください。また、このコールバック内で例外が発生すると、適当な証明書が見付からなかったと判断されます。このとき例外は OpenSSL のライブラリによって握り潰されてしまいます。

デフォルトは nil で、コールバックなしを意味します。この場合はクライアント証明書は利用されません。

このメソッドはクライアント側でのみ意味を持ちます。

例 
require 'openssl'
ctx = OpenSSL::SSL::SSLContext.new(ssl_method)
ctx.client_cert_cb = proc{|sslsocket|
  # sslsocket からコネクションの情報を取り出し、
  # クライアント証明書(cert)とその秘密鍵(privkey)を探しだす
  [cert, privkey]
}
[PARAM] cb:
コールバックオブジェクト(Proc、Method など)

[SEE_ALSO] OpenSSL::SSL::SSLContext#client_cert_cb

client_sigalgs=(sigalgs)Ruby 4.0 から[permalink][rdoc][edit]

クライアント認証のために使う「サポートする署名アルゴリズム」の一覧をコロン区切りの文字列で設定します。

TLS サーバの場合、この一覧は CertificateRequest メッセージの一部としてクライアントに送信されます。

サーバ認証における同等の設定については OpenSSL::SSL::SSLContext#sigalgs= を参照してください。

[PARAM] sigalgs:
コロン区切りの署名アルゴリズム名の文字列(例 "sigalg1:sigalg2:...")
[EXCEPTION] OpenSSL::SSL::SSLError:
設定に失敗した場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLContext#sigalgs=

ecdh_curves=(groups_list)Ruby 2.4.0 から[permalink][rdoc][edit]
groups=(groups_list)Ruby 4.0 から

鍵共有(キー交換)に用いるグループの一覧をコロン区切りの文字列で設定します。

TLS クライアントの場合、この一覧はそのまま "supported_groups" 拡張に使われます。TLS サーバの場合、OpenSSL が共有可能なグループの集合を決定するために使われ、その中から最も適切なものを選択します。

ecdh_curves= は groups= の非推奨の別名です。

例 
require 'openssl'
ctx1 = OpenSSL::SSL::SSLContext.new
ctx1.ecdh_curves = "X25519:P-256:P-224"

ctx2 = OpenSSL::SSL::SSLContext.new
ctx2.ecdh_curves = "P-256"
[PARAM] groups_list:
コロン区切りのグループ名の文字列(例 "X25519:P-256:P-224")
[EXCEPTION] OpenSSL::SSL::SSLError:
設定に失敗した場合に発生します
enable_fallback_scsv -> nilRuby 2.5.0 から[permalink][rdoc][edit]

この self に対して TLS_FALLBACK_SCSV を有効にします。

TLS_FALLBACK_SCSV は、クライアントがプロトコルバージョンのダウングレードを再試行していることをサーバに通知し、ダウングレード攻撃を検知できるようにする仕組みです。詳しくは [RFC7507] を参照してください。

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

自分自身を証明する証明書からルート CA までの証明書のリストです。

[SEE_ALSO] OpenSSL::SSL::SSLContext#extra_chain_cert=

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

自分自身を証明する証明書からルート CA までの証明書のリストを配列で設定します。

OpenSSL::SSL::SSLContext#cert で設定した証明書から相手が持っていると期待されるルート CA 証明書までのリストを渡します。

これによって接続相手はチェインを辿ることでその相手が信頼していない証明書の信頼性を順に確認し、自分自身を証明する証明書の信頼性を確認します。

[PARAM] certificates:
設定する証明書チェイン(OpenSSL::X509::Certificate の配列)

[SEE_ALSO] OpenSSL::SSL::SSLContext#extra_chain_cert

flush_sessions(time=nil) -> self[permalink][rdoc][edit]

自身が保持しているセッションキャッシュを破棄します。

time に nil を渡すと現在時刻で期限切れになっているキャッシュを破棄します。

time に Time オブジェクトを渡すと、その時刻で時間切れになるキャッシュを破棄します。

[PARAM] time:
キャッシュ破棄の基準時刻

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_cache_mode=

key -> OpenSSL::PKey::PKey | nil[permalink][rdoc][edit]

OpenSSL::SSL::SSLContext#cert で得られる自分自身を証明するための証明書の公開鍵に対応する秘密鍵を返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#key=

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

OpenSSL::SSL::SSLContext#cert= で設定された自分自身を証明するための証明書の公開鍵に対応する秘密鍵を設定します。

デフォルトは nil です。

[PARAM] key:
設定する秘密鍵(OpenSSL::PKey::PKey のサブクラスのインスタンス)

[SEE_ALSO] OpenSSL::SSL::SSLContext#key

keylog_cb -> Proc | nilRuby 3.2 から[permalink][rdoc][edit]
keylog_cb=(cb)

TLS の鍵情報が生成、あるいは受信されたときに呼び出されるコールバックを取得・設定します。

コールバックには OpenSSL::SSL::SSLSocket オブジェクトと、NSS の SSLKEYLOGFILE デバッグ出力形式のキー情報を含む文字列が渡されます。この情報をファイルに保存しておくことで、Wireshark などのツールで通信内容を復号してデバッグするのに使えます。

OpenSSL 1.1.1 以降でのみ利用できます。 

proc{|sslsocket, line| ... }
[PARAM] cb:
コールバックオブジェクト(Proc や Method など)
例 
require 'openssl'
context = OpenSSL::SSL::SSLContext.new
context.keylog_cb = proc do |_sock, line|
  File.open('ssl_keylog_file', "a") do |f|
    f.write("#{line}\n")
  end
end
max_version=(version)Ruby 2.5.0 から[permalink][rdoc][edit]

サポートする SSL/TLS プロトコルバージョンの上限を設定します。指定できる値は OpenSSL::SSL::SSLContext#min_version= と同様です。

[PARAM] version:
設定するプロトコルバージョンの上限(整数の定数、シンボル、もしくは nil)
[EXCEPTION] OpenSSL::SSL::SSLError:
バージョンの設定に失敗した場合に発生します
[EXCEPTION] ArgumentError:
version が認識できない値の場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLContext#min_version=

min_version=(version)Ruby 2.5.0 から[permalink][rdoc][edit]

サポートする SSL/TLS プロトコルバージョンの下限を設定します。

version には OpenSSL::SSL::TLS1_2_VERSION のような整数の定数、:TLS1_2 のようなシンボル、もしくは nil を指定します。nil は「バージョンの制限なし」を意味します。

例 
require 'openssl'
ctx = OpenSSL::SSL::SSLContext.new
ctx.min_version = OpenSSL::SSL::TLS1_1_VERSION
ctx.max_version = OpenSSL::SSL::TLS1_2_VERSION
[PARAM] version:
設定するプロトコルバージョンの下限(整数の定数、シンボル、もしくは nil)
[EXCEPTION] OpenSSL::SSL::SSLError:
バージョンの設定に失敗した場合に発生します
[EXCEPTION] ArgumentError:
version が認識できない値の場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLContext#max_version=

npn_protocols -> [String] | nilRuby 2.0.0 から[permalink][rdoc][edit]
npn_protocols=(protocols)

Next Protocol Negotiation(NPN)で通知するプロトコル名の一覧を取得・設定します。

サーバ側でのみ効果があります。設定しなかった場合、ハンドシェイクで NPN 拡張は送信されません。

例 
require 'openssl'
ctx = OpenSSL::SSL::SSLContext.new
ctx.npn_protocols = ["http/1.1", "spdy/2"]
[PARAM] protocols:
通知するプロトコル名の文字列の配列

[SEE_ALSO] OpenSSL::SSL::SSLSocket#npn_protocol

npn_select_cb -> Proc | nilRuby 2.0.0 から[permalink][rdoc][edit]
npn_select_cb=(cb)

NPN 拡張でサーバが提示したプロトコルの中から、クライアントが利用するプロトコルを選択するためのコールバックを取得・設定します。

クライアント側でのみ効果があります。コールバックにはサーバが提示したプロトコル名の文字列の配列が渡され、その中から選んだプロトコル名を文字列で返さなければなりません。サーバが提示したものの中に受け入れられるものがない場合は、コールバック内で例外を発生させるとハンドシェイクが失敗します。このコールバックを設定しない場合、クライアント側は NPN 拡張をサポートせず、サーバから提示されたプロトコルはすべて無視されます。 

proc{|protocols| ... }
[PARAM] cb:
コールバックオブジェクト(Proc や Method など)
options -> Integer | nil[permalink][rdoc][edit]

設定されているオプションフラグを返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#options=

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

オプションを設定します。

以下の値の OR で指定します。

[PARAM] options:
設定するオプションフラグ(整数値)

[SEE_ALSO] OpenSSL::SSL::SSLContext#options

renegotiation_cb -> nil | ProcRuby 2.0.0 から[permalink][rdoc][edit]

ハンドシェイク開始時に呼び出されるコールバックを得ます。

[SEE_ALSO] OpenSSL::SSL::SSLContext#renegotiation_cb=

renegotiation_cb=(cb)Ruby 2.0.0 から[permalink][rdoc][edit]

[TODO]

ハンドシェイク開始時に呼び出されるコールバックを設定します。

コールバックには OpenSSL::SSL::SSLSocket オブジェクトが渡されます。

このコールバック内で何らかの例外が生じた場合には以降のSSLの処理を停止します。

再ネゴシエーションのたびにこのコールバックが呼び出されるため、何らかの理由で再ネゴシエーションを禁止したい場合などに利用できます。

nil を渡すとコールバックは無効になります。

以下の例は再ネゴシエーションを一切禁止します。 

num_handshakes = 0
ctx.renegotiation_cb = lambda do |ssl|
  num_handshakes += 1
  raise RuntimeError.new("Client renegotiation disabled") if num_handshakes > 1
end
[PARAM] cb:
コールバック(Proc, Method など)もしくは nil

[SEE_ALSO] OpenSSL::SSL::SSLContext#renegotiation_cb

security_level -> IntegerRuby 2.4.0 から[permalink][rdoc][edit]
security_level=(level)

コンテキストのセキュリティレベルを取得・設定します。

OpenSSL はこのレベルに応じて暗号スイート、楕円曲線・グループ、鍵長、証明書の署名アルゴリズム、プロトコルバージョンなどのパラメータを制限します。例えばレベル 1 では、MAC に MD5 を使う暗号スイートや 1024 ビット未満の RSA 鍵など、80 ビット未満のセキュリティ強度しか持たないパラメータが拒否されます。

すでに設定されているパラメータがそのレベルの基準を満たさない場合、レベルの引き上げも拒否されることに注意してください。その場合は先にレベルを下げる必要があります。

OpenSSL 1.1.0 未満ではこの機能はサポートされておらず、0 以外の値を設定しようとすると NotImplementedError が発生します。レベル 0 はすべてのパラメータを許可することを意味し、これは以前のバージョンの OpenSSL と同じ動作です。

[PARAM] level:
設定するセキュリティレベル(整数)
[EXCEPTION] NotImplementedError:
OpenSSL 1.1.0 未満で 0 以外の値を設定しようとした場合に発生します
servername_cb -> Proc | nil[permalink][rdoc][edit]

TLS の Server Name Indication(SNI) 拡張でクライアント側からホスト名が伝えられてきた場合に呼びだされるコールバックを返します。

詳しくは OpenSSL::SSL::SSLContext#servername_cb= を見てください。

servername_cb=(pr)[permalink][rdoc][edit]

TLS の Server Name Indication(SNI) 拡張でクライアント側からホスト名が伝えられてきた場合に呼びだされるコールバックを設定します。

このコールバックはハンドシェイク時にクライアント側がサーバのホスト名を伝えてきた場合にサーバ側で呼びだされます。このコールバック内でサーバ側に提示する証明書を調整したりします。

Proc や Method をコールバックオブジェクトとして渡します。コールバックに渡される引数は以下のように 

proc{|sslsocket, hostname| ... }

2つで、1つ目は認証および暗号化通信に使われる OpenSSL::SSL::SSLSocket オブジェクトで、2つ目がクライアント側から伝えられてきたホスト名です。

コールバックの返り値には認証と暗号化の設定を含んだ OpenSSL::SSL::SSLContext オブジェクト、もしくは nil を返さなければなりません。これで得られたコンテキストオブジェクトが sslsocket に設定され、コンテキストが持っている証明書などの各情報を用いてハンドシェイクを継続します。コールバックが nil を返した場合には sslsocket が用いるコンテキストは変更されません。

[PARAM] pr:
コールバックオブジェクト

[SEE_ALSO] OpenSSL::SSL::SSLContext#servername_cb

session_add(sess) -> bool[permalink][rdoc][edit]

セッションを OpenSSL::SSL::SSLContext 内部のキャッシュ領域に追加します。

成功時には真を返します。すでにキャッシュ領域にあるセッションを追加しようとした場合は追加されずに偽を返します。

[PARAM] sess:
追加するセッション(OpenSSL::SSL::Session)
session_cache_mode -> Integer[permalink][rdoc][edit]

セッションキャッシュのモードを返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_cache_mode=

session_cache_mode=(mode)[permalink][rdoc][edit]

セッションキャッシュのモードを指定します。

以下の定数のORを引数として渡します。

デフォルト値は OpenSSL::SSL::SSLContext::SESSION_CACHE_SERVER です。

[PARAM] mode:
設定するモード(整数値)

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_cache_mode

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

自身が保持可能なセッションキャッシュのサイズを返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_cache_size=

session_cache_size=(size)[permalink][rdoc][edit]

自身が保持可能なセッションキャッシュのサイズを指定します。

size に 0 を渡すと制限なしを意味します。

デフォルトは 1024*20 で、20000 セッションまでキャッシュを保持できます。

[PARAM] size:
セッションキャッシュのサイズ(整数値)

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_cache_size

session_cache_stats -> {Symbol -> Integer}[permalink][rdoc][edit]

セッションキャッシュの内部統計情報をハッシュテーブルで返します。

ハッシュテーブルの各キーとその意味は以下の通りです。

  • :cache_num 内部キャッシュに保持されているセッションの数
  • :connect クライアント側でハンドシェイクした回数
  • :connect_good クライアント側でハンドシェイクが成功した回数
  • :connect_renegotiate クライアント側で再ネゴシエイトした回数
  • :accept サーバ側でハンドシェイクした回数
  • :accept_good サーバ側でハンドシェイクが成功した回数
  • :accept_renegotiate サーバ側で再ネゴシエイトした回数
  • :cache_hits サーバ側で内部キャッシュにヒットした数
  • :cb_hits サーバ側で外部キャッシュにヒットした数
  • :cache_full キャッシュが満杯で破棄したセッションの数
  • :timeouts ヒットしたキャッシュがタイムアウトしてしまっていた回数
session_get_cb -> Proc | nil[permalink][rdoc][edit]

セッションキャッシュを探索し、内部のキャッシュテーブルには見付からなかった場合に呼び出されるコールバックを返します。

設定されていないときは nil を返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_get_cb=

session_get_cb=(cb)[permalink][rdoc][edit]

セッションキャッシュを探索し、内部のキャッシュテーブルには見付からなかった場合に呼び出されるコールバックを設定します。

コールバックオブジェクトを call するときの引数は 

[ 接続オブジェクト(OpenSSL::SSL::SSLSocket), セッションID(文字列) ]

という配列です。このコールバックの返り値が OpenSSL::SSL::Session オブジェクトならば、それをキャッシュ値として利用します。それ以外を返したならば、キャッシュは見つからなかったものとして取り扱われます。

セッションキャッシュについて詳しくは OpenSSL::SSL::Session を見てください。

[PARAM] cb:
コールバックオブジェクト(Proc もしくは Method)

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_get_cb

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

セッション ID コンテキスト文字列を返します。

設定されていない場合は nil を返します。

[SEE_ALSO] OpenSSL::SSL::Session, OpenSSL::SSL::SSLContext#session_id_context=

session_id_context=(id_context)[permalink][rdoc][edit]

セッション ID コンテキストを文字列で設定します。

セッション ID コンテキストは、セッションをグループ化するための識別子で、セッション ID コンテキストとセッション ID の両方が一致する場合に同一のセッションであると判別されます。この OpenSSL::SSL::SSLContext オブジェクトで生成されたコネクション(OpenSSL::SSL::SSLSocket)に関連付けられたセッションはセッション ID コンテキストを共有します。

セッション ID コンテキストはセッションのグループを識別するための識別子であり、一方セッション ID は各セッションを識別するための識別子であり、この2つは異なる概念であることに注意してください。

クライアント側では意味を持ちません。

[PARAM] id_context:
セッション ID コンテキスト文字列(最大32バイト)

[SEE_ALSO] OpenSSL::SSL::Session, OpenSSL::SSL::SSLContext#session_id_context, OpenSSL::SSL::SSLContext#session_cache_mode=

session_new_cb -> Proc | nil[permalink][rdoc][edit]

セッションが生成されたときに呼び出されるコールバックを返します。

設定されていないときは nil を返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_new_cb=

session_new_cb=(cb)[permalink][rdoc][edit]

新たなセッションが作られたときに呼び出されるコールバックを指定します。

コールバックオブジェクトを call するときの引数は 

[ 接続オブジェクト(OpenSSL::SSL::SSLSocket), 新たなセッション(OpenSSL::SSL::Session)]

という配列です。

セッションキャッシュについて詳しくは OpenSSL::SSL::Session を見てください。

[PARAM] cb:
コールバックオブジェクト(Proc もしくは Method)

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_new_cb

session_remove(sess) -> bool[permalink][rdoc][edit]

セッションを OpenSSL::SSL::SSLContext 内部のキャッシュ領域から取り除きます。

成功時には真を返します。キャッシュ領域に存在しないセッションを削除しようとした場合は偽を返します。

[PARAM] sess:
削除するセッション(OpenSSL::SSL::Session)
session_remove_cb -> Proc | nil[permalink][rdoc][edit]

セッションが内部キャッシュから破棄されたときに呼び出されるコールバックを返します。

設定されていないときは nil を返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_remove_cb=

session_remove_cb=(cb)[permalink][rdoc][edit]

セッションが内部キャッシュから破棄されたときに呼び出されるコールバックを設定します。

コールバックオブジェクトを call するときの引数は 

[ SSLContextオブジェクト(OpenSSL::SSL::SSLContext), 
  破棄されるセッション(OpenSSL::SSL::Session)]

という配列です。

セッションキャッシュについて詳しくは OpenSSL::SSL::Session を見てください。

[PARAM] cb:
コールバックオブジェクト(Proc もしくは Method)

[SEE_ALSO] OpenSSL::SSL::SSLContext#session_remove_cb

set_params(params) -> Hash[permalink][rdoc][edit]

パラメータをハッシュで設定します。

渡すハッシュテーブルは { パラメータ名のシンボル => パラメータの値 } という形をしていなければなりません。

以下のパラメータを設定できます。

指定されなかったパラメータは OpenSSL::SSL::SSLContext::DEFAULT_PARAMS の値で初期化されます。

setup -> true | nil[permalink][rdoc][edit]

self の設定を確定させ、内部状態を準備します。

このメソッドは OpenSSL::SSL::SSLSocket オブジェクトが生成されるときに自動的に呼び出されます。ただしスレッドセーフではないため、複数のスレッドを使うプログラムでは SSLSocket オブジェクトを生成する前に明示的に呼び出しておく必要があります。

初めて呼び出したときは true を返します。すでに呼び出し済みの場合は何もせず nil を返します。

sigalgs=(sigalgs)Ruby 4.0 から[permalink][rdoc][edit]

このコンテキストで使う「サポートする署名アルゴリズム」の一覧をコロン区切りの文字列で設定します。

TLS クライアントの場合、この一覧は ClientHello メッセージの "signature_algorithms" 拡張に使われます。TLS サーバの場合、OpenSSL が共有可能な署名アルゴリズムの集合を決定するために使われ、その中から最も適切なものを選択します。

クライアント認証における同等の設定については OpenSSL::SSL::SSLContext#client_sigalgs= を参照してください。

[PARAM] sigalgs:
コロン区切りの署名アルゴリズム名の文字列(例 "sigalg1:sigalg2:...")
[EXCEPTION] OpenSSL::SSL::SSLError:
設定に失敗した場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLContext#client_sigalgs=

timeout -> Integer | nil[permalink][rdoc][edit]
ssl_timeout -> Integer | nil

このコンテキストから生成するセッションのタイムアウト秒数を返します。

デフォルト値は nil です。

[SEE_ALSO] OpenSSL::SSL::SSLContext#timeout=

timeout=(seconds)[permalink][rdoc][edit]
ssl_timeout=(seconds)

このコンテキストから生成するセッションのタイムアウト秒数を設定します。

nil を指定すると OpenSSL のデフォルトのタイムアウト秒数(300秒)を用います。

[PARAM] seconds:
タイムアウト秒数(整数)

[SEE_ALSO] OpenSSL::SSL::Session#timeout

ssl_version=(ver)[permalink][rdoc][edit]

利用するプロトコルの種類を文字列もしくはシンボルで指定します。

OpenSSL::SSL::SSLContext.new で指定できるものと同じです。

[PARAM] ver:
利用するプロトコルの種類
tmp_dh=(pkey)Ruby 3.1 から[permalink][rdoc][edit]

一時的 DH 鍵交換で使う DH パラメータを設定します。サーバ側でのみ意味を持ちます。

pkey には OpenSSL::PKey::DH のインスタンスを指定します。このオブジェクトが保持している鍵の成分があっても無視され、サーバはハンドシェイクのたびに新しい鍵ペアを生成します。

OpenSSL::SSL::SSLContext#tmp_dh_callback= よりもこちらの利用が推奨されます。 

ctx = OpenSSL::SSL::SSLContext.new
ctx.tmp_dh = OpenSSL::PKey::DH.generate(2048)
svr = OpenSSL::SSL::SSLServer.new(tcp_svr, ctx)
Thread.new { svr.accept }
[PARAM] pkey:
一時的 DH 鍵交換で使う DH パラメータ(OpenSSL::PKey::DH のインスタンス)
[EXCEPTION] OpenSSL::SSL::SSLError:
pkey が DH 鍵でない場合や、設定に失敗した場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLContext#tmp_dh_callback=

tmp_dh_callback -> Proc | nil[permalink][rdoc][edit]

一時的 DH 鍵を生成するためのコールバックを返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#tmp_dh_callback=

tmp_dh_callback=(cb)[permalink][rdoc][edit]

一時的 DH 鍵を生成するためのコールバックを設定します。

コールバックには Proc や Method を渡します。

暗号で一時的な DH 鍵を利用する場合にはこのコールバックが呼びだされ、呼びだされたブロックは適切な鍵パラメータを返さなければなりません。これで設定するブロックは 

proc{|sslsocket, is_export, keylen| ... }

という引数を取るようにします。それぞれの引数の意味は

  • sslsocket 通信に使われる OpenSSL::SSL::SSLSocket オブジェクト
  • is_export 輸出規制のある暗号を利用するかどうかを0か0以外かで指定
  • keylen 鍵長

となります。ブロックの返り値には適切な鍵パラメータを含む OpenSSL::PKey::DH オブジェクトを返します。鍵パラメータは keylen で指定された鍵長に対応したものでなければなりません。

OpenSSL::PKey::DH は DH パラメータと DH 鍵対を保持していますが、これで返されるオブジェクトはパラメータしか用いられません。

cb に nil を指定するとデフォルトのパラメータが利用されます。

デフォルト値は nil です。

[PARAM] cb:
設定するコールバック

[SEE_ALSO] OpenSSL::SSL::SSLContext#tmp_dh_callback

verify_callback -> Proc | nil[permalink][rdoc][edit]

オブジェクトに設定されている検証をフィルタするコールバックを返します。

デフォルトのコールバックが設定されている場合には nil を返します。

[SEE_ALSO] OpenSSL::X509::Store#verify_callback, OpenSSL::SSL::SSLContext#verify_callback=

verify_callback=(proc)[permalink][rdoc][edit]

検証をフィルタするコールバックを設定します。

OpenSSL::X509::Store#verify_callback= と同じ働きをします。

コールバックには Proc や Method を渡します。

渡されたコールバックオブジェクトは証明書チェインの検証時にチェインに含まれる各証明書の署名を検証するたびに呼びだされます。そのときに渡される引数は2つで、1つめは検証が成功したかの真偽値、 2つめは検証後の状態を保存した OpenSSL::X509::StoreContext オブジェクトです。このコールバックには2つの役割があります。1つ目はコンテキストオブジェクトを調べることで詳細なエラー情報を得ることです。2つ目は検証をカスタマイズすることです。このコールバックが true を返すと、たとえ OpenSSL が検証失敗と判定しても、検証が成功したものと判断し証明書チェインの検証を続けます。逆に false を返すと、検証が失敗したものとみなされ検証を停止し、検証メソッドは検証失敗を返します。詳細なエラー情報を得たいだけの場合はコールバックは第一引数をそのまま返すようにしてください。

nil を設定するとデフォルトのコールバック(単に第一引数をそのまま返すだけ) が使われます。

初期状態は nil です。

[PARAM] proc:
設定する Proc オブジェクト

[SEE_ALSO] OpenSSL::SSL::SSLContext#verify_callback, OpenSSL::X509::Store#verify_callback=

verify_depth -> Integer | nil[permalink][rdoc][edit]

証明書チェイン上の検証する最大の深さを返します。

デフォルトは nil です。

[SEE_ALSO] OpenSSL::SSL::SSLContext#verify_depth=

verify_depth=(depth)[permalink][rdoc][edit]

証明書チェイン上の検証する最大の深さを設定します。

デフォルトは nil で、この場合 OpenSSL のデフォルト値(9)が使われます。

[PARAM] depth:
最大深さを表す整数

[SEE_ALSO] OpenSSL::SSL::SSLContext#verify_depth

verify_hostname -> boolRuby 2.4.0 から[permalink][rdoc][edit]
verify_hostname=(bool)

サーバ証明書がホスト名に対して有効かどうかを検証するかどうかを取得・設定します。

これを機能させるには、OpenSSL::SSL::SSLContext#verify_mode= に OpenSSL::SSL::VERIFY_PEER を設定し、かつ OpenSSL::SSL::SSLSocket#hostname= でサーバのホスト名を設定しておく必要があります。

[PARAM] bool:
検証を行うかどうかを true か false で指定します

[SEE_ALSO] OpenSSL::SSL::SSLContext#verify_mode=, OpenSSL::SSL::SSLSocket#hostname=

verify_mode -> Integer | nil[permalink][rdoc][edit]

検証モードを返します。

デフォルトは nil です。

[SEE_ALSO] OpenSSL::SSL::SSLContext#verify_mode=

verify_mode=(mode)[permalink][rdoc][edit]

検証モードを設定します。

以下の定数の OR を取って指定します。

これらの定数の意味はクライアントモードとサーバモードでは異なる意味を持ちます。

デフォルトは nil で、VERIFY_NONE を意味します。

[PARAM] mode:
設定するモード(整数値)

[SEE_ALSO] OpenSSL::SSL::SSLContext#verify_mode

定数

DEFAULT_CERT_STORE -> OpenSSL::X509::Store[permalink][rdoc][edit]

OpenSSL::SSL::SSLContext#set_params で信頼する CA 証明書 (ca_file, ca_path, cert_store) を一切指定しなかった場合にデフォルトで使われる証明書ストアです。

OpenSSL::X509::Store#set_default_paths でシステムが提供する証明書を利用するように設定されています。

DEFAULT_PARAMS -> { Symbol -> object }[permalink][rdoc][edit]

OpenSSL::SSL::SSLContext#set_params でデフォルト値として使われるパラメータです。

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

利用可能なメソッド(プロトコル)を Symbol の配列で返します。 

require 'openssl'
p OpenSSL::SSL::SSLContext::METHODS
# => [:TLSv1, :TLSv1_server, :TLSv1_client, :SSLv2, :SSLv2_server, ...]
SESSION_CACHE_BOTH -> Integer[permalink][rdoc][edit]

サーバ側、クライアント側両方でセッションをキャッシュすることを意味します。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

実際には OpenSSL::SSL::SSLContext::SESSION_CACHE_SERVER と OpenSSL::SSL::SSLContext::SESSION_CACHE_CLIENT のビット論理和を取った値です。

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

クライアント側セッションをキャッシュに追加することを意味します。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

クライアント側においては、OpenSSL ライブラリがどのセッションを再利用するべきか確実に判定する方法はないので、再利用する場合は OpenSSL::SSL::SSLSocket#session= によって明示的にセッションを指定しなければなりません。

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

OpenSSL::SSL::SSLContext 内部のセッションキャッシュ領域を自動的にクリアしないことを意味します。

通常では255コネクションごとにキャッシュを破棄しますが、このフラグを有効にするとそれをしなくなります。代わりに適当なタイミングで OpenSSL::SSL::SSLContext#flush_sessions を呼びキャッシュを破棄しなければなりません。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

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

OpenSSL::SSL::SSLContext::SESSION_CACHE_NO_INTERNAL_STORE と OpenSSL::SSL::SSLContext::SESSION_CACHE_NO_INTERNAL_LOOKUP の両方を有効にすることを意味します。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

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

サーバ側でセッションキャッシュが必要になった場合 OpenSSL::SSL::SSLContext が保持するキャッシュ領域を探索しないことを意味します。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

このフラグを ON にすると、キャッシュの探索が必要になった場合必ずコールバック(OpenSSL::SSL::SSLContext#session_get_cb= で設定したもの)を呼ぶようになります。

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

セッションキャッシュを OpenSSL::SSL::SSLContext 内部のキャッシュ領域に保持しないことを意味します。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

ハンドシェイクによってセッションが開始された場合にはそのセッションを OpenSSL::SSL::SSLContext 内部にキャッシュとして保持しますが、このフラグを有効にすると自動的にキャッシュされることはなくなります。

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

セッションをキャッシュしないことを意味します。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

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

サーバ側でセッションをキャッシュすることを意味します。

OpenSSL::SSL::SSLContext#session_cache_mode= に渡すフラグとして用います。

このフラグが立っているとサーバ側の OpenSSL::SSL::SSLContext でセッションキャッシュの保持と管理、再利用が行われます。

このフラグはデフォルトで有効になっています。