class OpenSSL::SSL::SSLSocket

[edit]

要約

ソケットをラップして 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

目次

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

継承しているメソッド

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

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

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 通信をクライアントモードとして開始し、サーバとのハンドシェイクを実行します。

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

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

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

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

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

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=

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:
書き込みに失敗した場合に発生します
verify_result -> Integer[permalink][rdoc][edit]

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

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