Ruby 2.6.0 リファレンスマニュアル > ライブラリ一覧 > opensslライブラリ > OpenSSL::SSL::SSLSocketクラス

class OpenSSL::SSL::SSLSocket

クラスの継承リスト: OpenSSL::SSL::SSLSocket < Enumerable < OpenSSL::SSL::SocketForwarder < OpenSSL::Buffering < Object < Kernel < BasicObject

要約

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

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

require 'socket'
require 'openssl'
include OpenSSL

soc = TCPSocket.new('www.example.com', 443)
ssl = SSL::SSLSocket.new(soc)
ssl.connect
ssl.post_connection_check('www.example.com')
raise "verification error" if ssl.verify_result != OpenSSL::X509::V_OK
ssl.write('hoge')
print ssl.peer_cert.to_text
ssl.close
soc.close

目次

特異メソッド
new
インスタンスメソッド
accept accept_nonblock cert cipher connect connect_nonblock context hostname hostname= io to_io peer_cert peer_cert_chain pending post_connection_check session session= session_reused? state sync_close sync_close= sysclose sysread syswrite verify_result

特異メソッド

new(socket) -> OpenSSL::SSL::SSLSocket[permalink][rdoc]
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]

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

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

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

accept_nonblock -> self[permalink][rdoc]

ノンブロッキング方式で 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

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

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

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

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

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

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

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

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

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

connect -> self[permalink][rdoc]

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

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

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

connect_nonblock -> self[permalink][rdoc]

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

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

[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]

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

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

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

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

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

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

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

hostname=(hostname)[permalink][rdoc]

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]
to_io -> IO

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

接続後検証を行います。

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

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

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

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

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

session=(sess)[permalink][rdoc]

ハンドシェイクで再利用する 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]

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

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

state -> String[permalink][rdoc]

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

sync_close -> bool[permalink][rdoc]

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

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

sync_close=(bool)[permalink][rdoc]

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

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

[PARAM] bool:
設定する真偽値
sysclose -> nil[permalink][rdoc]

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

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

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

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

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

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

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

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

IO#sysread と同様です。

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

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

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

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

IO#syswrite と同様です。

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

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

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