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

要約

ソケットをラップして SSL での認証と暗号通信を実現するためのクラスです。

例

SSL/TLS サーバに接続して write します。

require 'socket'
require 'openssl'
include OpenSSL
  
ctx = SSL::SSLContext.new
ctx.set_params(verify_mode: OpenSSL::SSL::VERIFY_PEER, verify_hostname: true)
  
soc = TCPSocket.new('www.example.com', 443)
ssl = SSL::SSLSocket.new(soc, ctx)
ssl.hostname = 'www.example.com' # SNI
ssl.connect
ssl.post_connection_check('www.example.com')
raise "verification error" if ssl.verify_result != OpenSSL::X509::V_OK
print ssl.peer_cert.to_text
  
# HTTP リクエストを送信
ssl.write("GET / HTTP/1.1\r\n")
ssl.write("Host: www.example.com\r\n")
ssl.write("Connection: close\r\n")
ssl.write("\r\n")
print ssl.read
  
ssl.close
soc.close

継承しているメソッド

Enumerableから継承しているメソッド

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

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

特異メソッド

new(socket) -> OpenSSL::SSL::SSLSocket[permalink][rdoc][edit]

new(socket, context) -> OpenSSL::SSL::SSLSocket

socket をラップして SSLSocket オブジェクトを生成します。

socket にはラップする TCPSocket オブジェクトを与え、 context には SSL の設定情報を所持している OpenSSL::SSL::SSLContext オブジェクトを与えます。

context を省略した場合は OpenSSL::SSL::SSLContext.new で新たにコンテキストを生成してそれを用います。

[PARAM] socket:: ラップするソケット
[PARAM] context:: SSL の設定情報を持つ SSL コンテキストオブジェクト
[EXCEPTION] OpenSSL::SSL::SSLError:: オブジェクトの生成に失敗した場合に発生します

インスタンスメソッド

accept -> self[permalink][rdoc][edit]

TLS/SSL 通信をサーバモードとして開始し、クライアントからのハンドシェイク開始を待ち、クライアントとのハンドシェイクを実行します。

[EXCEPTION] OpenSSL::SSL::SSLError:: ハンドシェイクに失敗した(VERIFY_PEER で証明書の検証に失敗した場合や、プロトコル合意に失敗したなど) 場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLSocket#connect, OpenSSL::SSL::SSLSocket#accept_nonblock

accept_nonblock -> self[permalink][rdoc][edit]

ノンブロッキング方式で TLS/SSL 通信をサーバモードとして開始し、クライアントとのハンドシェイクを実行します。

IO が読み込み待ち、もしくは書き込み待ちになった場合は例外を発生させ、ハンドシェイクを中断します。IO が読み込み/書き込み可能状態になってからこのメソッドをもう一度呼ぶとハンドシェイクを再開します。

[EXCEPTION] OpenSSL::SSL::SSLError:: ハンドシェイクに失敗した(VERIFY_PEER で証明書の検証に失敗した場合や、プロトコル合意に失敗したなど) 場合に発生します (実際は OpenSSL::SSL::SSLError をこのモジュールで extend した例外オブジェクトが生成されます)
[EXCEPTION] OpenSSL::SSL::SSLError:: ソケットが読み込み/書き込み可能状態になるのを待つ必要がある場合に発生します。読み込み可能状態を待つ必要がある場合には IO::WaitReadable を、書き込み可能状態を待つ必要がある場合には IO::WaitWritable を、それぞれ extend した例外オブジェクトが生成されます。

[SEE_ALSO] OpenSSL::SSL::SSLSocket#connect_nonblock, OpenSSL::SSL::SSLSocket#accept

alpn_protocol -> String | nilRuby 2.3.0 から[permalink][rdoc][edit]

ハンドシェイクの結果、Application-Layer Protocol Negotiation(ALPN)で最終的に選択されたプロトコルを表す文字列を返します。

ALPN が使われなかった場合や、まだハンドシェイクが行われていない場合は nil を返します。

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

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

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

自分自身を証明する証明書を使わなかった場合は nil を返します。 OpenSSL::SSL::SSLSocket#connect や OpenSSL::SSL::SSLSocket#accept で SSL/TLS ハンドシェイクを行う前にこのメソッドを呼んだ場合も nil を返します。

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

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

現在実際に使われている暗号の情報を配列で返します。

返される配列の形式は以下の例のように [暗号名, TLS/SSLのバージョン, 鍵長, アルゴリズムで使われる bit 数] となります。

["DES-CBC3-SHA", "TLSv1/SSLv3", 168, 168]

OpenSSL::SSL::SSLSocket#connect や OpenSSL::SSL::SSLSocket#accept で SSL/TLS ハンドシェイクを行う前にこのメソッドを呼ぶと nil を返します。

client_ca -> [OpenSSL::X509::Name] | nilRuby 1.9.3 から[permalink][rdoc][edit]

クライアント証明書を要求する際に提示される CA のリストを、OpenSSL::X509::Name の配列で返します。

OpenSSL::SSL::SSLContext#client_ca= とは異なり、OpenSSL::X509::Certificate の配列ではなく、各 CA のサブジェクトの識別名(OpenSSL::X509::Name)の配列を返すことに注意してください。

サーバモードでは OpenSSL::SSL::SSLContext#client_ca= で設定したリストを返します。クライアントモードでは、サーバから送られてきたクライアント CA のリストを返します。

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

close_read -> nilRuby 3.4 から[permalink][rdoc][edit]

self の読み込み側を閉じます。

OpenSSL には読み込み側だけを閉じる合理的な方法がないため、実際には何も行いません。ただし IO との互換性のために用意されています。

[SEE_ALSO] IO#close_read, OpenSSL::SSL::SSLSocket#close_write

close_write -> nilRuby 3.4 から[permalink][rdoc][edit]

self の書き込み側を閉じます。

相手に 'close_notify' アラートを送信しますが、相手からの 'close_notify' の応答は待ちません。

動作は使われている OpenSSL のバージョンと TLS のプロトコルバージョンによって異なります。TLS 1.2 以前では、相手からの 'close_notify' を受信すると、self も 'close_notify' を返して即座に接続を閉じます。書き込みを待っているデータは破棄されます。そのため TLS 1.2 では、このメソッドの呼び出しによって接続全体が閉じられることになります。TLS 1.3 では、読み込み用に接続は開いたままになります。

[SEE_ALSO] IO#close_write, OpenSSL::SSL::SSLSocket#close_read

connect -> self[permalink][rdoc][edit]

TLS/SSl 通信をクライアントモードとして開始し、サーバとのハンドシェイクを実行します。

[EXCEPTION] OpenSSL::SSL::SSLError:: ハンドシェイクに失敗した(VERIFY_PEER で証明書の検証に失敗した場合や、プロトコル合意に失敗したなど) 場合に発生します

[SEE_ALSO] OpenSSL::SSL::SSLSocket#accept, OpenSSL::SSL::SSLSocket#connect_nonblock

connect_nonblock -> self[permalink][rdoc][edit]

ノンブロッキング方式で TLS/SSL 通信をクライアントモードとして開始し、サーバとのハンドシェイクを実行します。

[EXCEPTION] OpenSSL::SSL::SSLError:: ハンドシェイクに失敗した(VERIFY_PEER で証明書の検証に失敗した場合や、プロトコル合意に失敗したなど) 場合に発生します
[EXCEPTION] OpenSSL::SSL::SSLError:: ソケットが読み込み/書き込み可能状態になるのを待つ必要がある場合に発生します。読み込み可能状態を待つ必要がある場合には IO::WaitReadable を、書き込み可能状態を待つ必要がある場合には IO::WaitWritable を、それぞれ extend した例外オブジェクトが生成されます。

[SEE_ALSO] OpenSSL::SSL::SSLSocket#accept_nonblock, OpenSSL::SSL::SSLSocket#connect

context -> OpenSSL::SSL::SSLContext[permalink][rdoc][edit]

SSLSocket オブジェクトを生成する時に渡されたコンテクストを返します。

[SEE_ALSO] OpenSSL::SSL::SSLSocket.new

export_keying_material(label, length, context = nil) -> StringRuby 3.2 から[permalink][rdoc][edit]

[RFC5705] に従って、共有されているセッション鍵の材料をエクスポートします。

TLS のマスターシークレットから label(と、指定した場合は context)を使って length バイトのデータを導出します。これは、TLS 接続の上位で追加の暗号鍵を安全に生成する場合などに使えます。

[PARAM] label:: 鍵導出に使うラベルを表す文字列
[PARAM] length:: 生成するデータのバイト数
[PARAM] context:: 鍵導出に使う追加のコンテキスト文字列
[EXCEPTION] OpenSSL::SSL::SSLError:: 鍵材料のエクスポートに失敗した場合に発生します

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

直近に送信した Finished メッセージを返します。

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

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

TLS の Server Name Indication 拡張で利用するサーバのホスト名を返します。

OpenSSL::SSL::SSLSocket#hostname= で設定した値がそのまま返されます。

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

[SEE_ALSO] OpenSSL::SSL::SSLSocket#hostname=

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

TLS の Server Name Indication(SNI) 拡張で利用するサーバのホスト名を設定します。

Server Name Indication については [RFC3546] を参照してください。

このメソッドはハンドシェイク時にクライアント側がサーバ側にサーバのホスト名を伝えるために用います。そのため、クライアント側が OpenSSL::SSL::SSLSocket#connect を呼ぶ前にこのメソッドでホスト名を指定する必要があります。

hostname に nil を渡すと SNI 拡張を利用しません。

サーバ側については OpenSSL::SSL::SSLContext#servername_cb= を参照してください。

[PARAM] hostname:: ホスト名文字列

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

io -> IO[permalink][rdoc][edit]

to_io -> IO

SSLSocket オブジェクトを生成する時に渡されたソケットを返します。

[SEE_ALSO] OpenSSL::SSL::SSLSocket.new

npn_protocol -> String | nilRuby 2.0.0 から[permalink][rdoc][edit]

ハンドシェイクの結果、Next Protocol Negotiation(NPN)でクライアントが最終的に選択したプロトコルを表す文字列を返します。

NPN が使われなかった場合や、まだハンドシェイクが行われていない場合は nil を返します。

[SEE_ALSO] OpenSSL::SSL::SSLContext#npn_protocols=, OpenSSL::SSL::SSLContext#npn_select_cb=

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

接続相手の証明書オブジェクトを返します。

OpenSSL::SSL::SSLSocket#connect や OpenSSL::SSL::SSLSocket#accept で SSL/TLS ハンドシェイクを行う前にこのメソッドを呼ぶと nil を返します。

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

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

接続相手の証明書チェインを OpenSSL::X509::Certificate オブジェクトの配列で返します。

OpenSSL::SSL::SSLSocket#connect や OpenSSL::SSL::SSLSocket#accept で SSL/TLS ハンドシェイクを行う前にこのメソッドを呼ぶと nil を返します。

以下の順の配列を返します。

[接続相手の証明書, 下位CAの証明書,... 中間CAの証明書]

ルート CA の証明書は含まれないことに注意してください。

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

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

直近に受信した Finished メッセージを返します。

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

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

OpenSSL内部のバッファが保持している、直ちに読み取り可能なデータのバイト数を返します。

ハンドシェイク開始前には nil を返します。

post_connection_check(hostname) -> true[permalink][rdoc][edit]

接続後検証を行います。

検証に成功した場合は true を返し、失敗した場合は例外 OpenSSL::SSL::SSLError を発生させます。

OpenSSL の API では、 OpenSSL::SSL::SSLSocket#connect や OpenSSL::SSL::SSLSocket#accept での検証は実用的には不完全です。 CA が証明書に署名してそれが失効していないことしか確認しません。実用上は証明書に記載されている事項を見て、接続先が妥当であるかを確認する必要があります。通常は接続先ホストの FQDN と証明書に記載されている FQDN が一致しているかどうかを調べます。このメソッドはその FQDN のチェックを行ないます。

[PARAM] hostname:: チェックする FQDN の文字列
[EXCEPTION] OpenSSL::SSL::SSLError:: チェックに失敗した場合に発生します

session -> OpenSSL::SSL::Session[permalink][rdoc][edit]

利用している SSL セッションを OpenSSL::SSL::Session オブジェクトで返します。

[SEE_ALSO] OpenSSL::SSL::SSLSocket#session=, OpenSSL::SSL::SSLSocket#session_reused?

session=(sess)[permalink][rdoc][edit]

ハンドシェイクで再利用する SSL セッションを設定します。

このメソッドはクライアント側でのみ有用です。セッションを再利用する場合は、 OpenSSL::SSL::SSLSocket#connect を呼ぶ前にこのメソッドでセッションオブジェクト (OpenSSL::SSL::Session のインスタンス) を設定します。

サーバ側の場合 OpenSSL::SSL::SSLContext がキャッシュの保持と管理を行います。

[PARAM] sess:: 設定するセッション

[SEE_ALSO] OpenSSL::SSL::SSLSocket#session, OpenSSL::SSL::SSLSocket#session_reused?

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

利用している SSL セッションが再利用されたものである場合に真を返します。

[SEE_ALSO] OpenSSL::SSL::Session, OpenSSL::SSL::SSLSocket#session, OpenSSL::SSL::SSLSocket#session=

ssl_version -> StringRuby 2.0.0 から[permalink][rdoc][edit]

コネクションで使われている SSL/TLS のバージョンを表す文字列を返します。

例えば "TLSv1.2" のような文字列を返します。

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

現在の状態をアルファベット 6 文字の文字列で返します。

sync_close -> bool[permalink][rdoc][edit]

SSLSocket を close するときにラップしているソケットも close するかどうかを返します。

true でソケットも close します。

sync_close=(bool)[permalink][rdoc][edit]

SSLSocket を close するときにラップしているソケットも close するかどうかを設定します。

true でソケットも close するようになります。

[PARAM] bool:: 設定する真偽値

sysclose -> nil[permalink][rdoc][edit]

接続を閉じます。相手に'close notify'を送ります。

このメソッドは openssl ライブラリ内で管理しているバッファをフラッシュせずに接続を閉じます。そのため、通常はこれではなく OpenSSL::Buffering#close を呼ぶべきです。

OpenSSL::SSL::SSLSocket#sync_close が真である場合はこのメソッドを呼びだした時点で自身が保持しているソケットを同時に閉じます。

sysread(length, buf=nil) -> String[permalink][rdoc][edit]

データをバッファを経由せずに暗号化通信路から読み込み、読み込んだデータを文字列で返します。

基本的にはこのメソッドは使わず、OpenSSL::Buffering のメソッドを使ってデータを読み込むべきです。

length で読み込むバイト数を指定します。

bufに文字列を指定するとその文字列のメモリ領域にデータを直接書き込み、その String オブジェクトを返します。

IO#sysread と同様です。

[PARAM] length:: 読み込むバイト数を指定します
[PARAM] buf:: データを書き込むバッファ
[EXCEPTION] EOFError:: 入力が終端に達した場合に発生します
[EXCEPTION] OpenSSL::SSL::SSLError:: 読み込みに失敗した場合に発生します

syswrite(string) -> Integer[permalink][rdoc][edit]

データをバッファを経由せずに暗号化通信路に書き込みます。

書き込んだバイト数を整数で返します。

基本的にはこのメソッドは使わず、OpenSSL::Buffering のメソッドを使ってデータを書き込むべきです。

IO#syswrite と同様です。

[PARAM] string:: 書き込むデータ文字列
[EXCEPTION] OpenSSL::SSL::SSLError:: 書き込みに失敗した場合に発生します

tmp_key -> OpenSSL::PKey::PKey | nilRuby 2.4.0 から[permalink][rdoc][edit]

Forward Secrecy(前方秘匿性)を持つ暗号スイートが使われた場合の、一時的な鍵を返します。

Forward Secrecy を持つ暗号スイートが使われなかった場合は nil を返します。

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

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

検証結果のエラーコードを整数値で返します。

エラーコードの整数値は OpenSSL::X509 に定数が定義されています。詳しくは OpenSSL::X509/検証時エラー定数を見てください。検証に成功した場合は OpenSSL::X509::V_OK を返します。

要約

例

目次

継承しているメソッド

特異メソッド

インスタンスメソッド