JavaTM 2 Platform
Standard Ed. 5.0

javax.net.ssl
クラス SSLEngine

java.lang.Object
  上位を拡張 javax.net.ssl.SSLEngine

public abstract class SSLEngine
extends Object

Secure Sockets Layer (SSL) や IETF RFC 2246 の Transport Layer Security (TLS) プロトコルを使用し、転送に依存することなくセキュア通信を有効にするクラスです。

セキュア通信モードでは、次のセキュリティ保護が実施されます。

これらのセキュリティ保護は、「符号化方式」を使用して指定します。符号化方式は、指定された SSL 接続で使用される暗号化アルゴリズムの組み合わせです。ネゴシエーションを行うには、2 つの終端が同じ符号化方式を選択し、その符号化方式が両方の環境で使用可能でなければなりません。共通の符号化方式がない場合は、SSL 接続を確立できず、データを交換できません。

使用される符号化方式は、「ハンドシェーク」と呼ばれるネゴシエーションプロセスによって確立されます。ハンドシェークでは、セッションの作成または参加が行われます。作成または参加したセッションは、無効になるまでさまざまな接続を保護します。ハンドシェークが完了すると、getSession() メソッドを使用してセッション属性にアクセスできます。

SSLSocket クラスもほぼ同じセキュリティ機能を提供しますが、すべての着信および発信データは、意図的にブロックモデルを使用する配下の Socket により自動的に送信されます。この処理は多くのアプリケーションに対して適切ですが、このモデルは大規模サーバに必要な拡張性をもたらしません。

SSLEngine の主な特長として、転送機構に依存することなく着信/送信バイトストリームを操作できる点が挙げられます。SSLEngine ユーザは、ピアにおける入出力転送の信頼性を確保する必要があります。SSL/TLS 抽象化オブジェクトを入出力転送機構から切り離すことにより、SSLEngine をさまざまな入出力で広範囲に利用することができます。たとえば、非ブロック入出力 (ポーリング)選択型非ブロック入出力のほか、Socket および従来の Input/OutputStream、ローカルの ByteBuffers、バイト配列、future asynchronous 入出力モデルなどの入出力で利用可能です。

上層部では、SSLEngine は次のように表されます。


                   app data

                |           ^
                |     |     |
                v     |     |
           +----+-----|-----+----+
           |          |          |
           |       SSL|Engine    |
   wrap()  |          |          |  unwrap()
           | OUTBOUND | INBOUND  |
           |          |          |
           +----+-----|-----+----+
                |     |     ^
                |     |     |
                v           |

                   net data
 
アプリケーションデータ (別名「プレーンテキスト」または「クリアテキスト」) は、アプリケーションによって生成または消費されるデータです。アプリケーションデータと対になるものとして、ネットワークデータがあります。ネットワークデータは、ハンドシェークや暗号化データで構成され、入出力機構を介して転送されるデータです。着信データはピアから受信されるデータ、送信データはピアへ送信されるデータです。

SSLEngine のコンテキストでは、セキュア接続の確立および制御目的で交換されるデータを「ハンドシェークデータ」と総称します。ハンドシェークデータには、SSL/TLS メッセージ alert、change_cipher_spec、handshake などがあります。

SSLEngine は、次の 5 つの段階をたどります。

  1. 作成 - SSLEngine の作成と初期化は完了しましたが、まだ使用されてはいません。この段階では、アプリケーションにより、SSLEngine 固有のあらゆる設定 (暗号群の有効化、SSLEngine がクライアントモードとサーバモードのどちらでハンドシェークを行うかなど) を行うことができます。ハンドシェークが始まると、次のハンドシェークからクライアント/サーバモードの設定を除く (下記参照) 新しい設定が使用されます。
  2. 初期ハンドシェーク - SSLSession が確立されるまでの間、2 つのピアが通信パラメータを交換する手続きです。この段階では、アプリケーションデータは送信できません。
  3. アプリケーションデータ - 通信パラメータが確立され、ハンドシェークが完了すると、SSLEngine からアプリケーションデータが送信されます。送信アプリケーションメッセージは暗号化され、データの整合性が確保されます。着信メッセージでは、この逆の手続きが行われます。
  4. 再ハンドシェーク - 「アプリケーションデータ」段階では、どちら側のピアからでも、必要に応じてセッションの再ネゴシエーションを要求できます。アプリケーションデータに新しいハンドシェークデータを混ぜることができます。再ハンドシェークを開始する前に、アプリケーションは、SSL/TLS 通信パラメータ (例: 有効な暗号群のリスト)や、クライアント認証を使用するかどうかの設定をリセットできます。しかし、クライアントモードとサーバモードを切り替えることはできません。前回と同様に、ハンドシェークが始まってから次のハンドシェークまで、新しい SSLEngine 設定は使用されません。
  5. 終了 - 接続が不要になったとき、アプリケーションは、SSLEngine を終了し、ピアと送受信するメッセージが残っている場合は送受信を完了してから、配下の転送機構を終了する必要があります。終了されたエンジンは、再利用できません。新しい SSLEngine を作成する必要があります。
SSLEngine を作成するには、初期化された SSLContext から SSLContext.createSSLEngine() を呼び出します。すべての設定パラメータの設定を完了してから、wrap()unwrap()、または beginHandshake() の最初の呼び出しを行います。これらのメソッドはすべて、初期ハンドシェークをトリガします。

データは、送信データに対して wrap() を呼び出したり、着信データに対して unwrap() を呼び出すことによって、エンジンから転送されます。SSLEngine の状態によっては、wrap() 呼び出しによってソースバッファのアプリケーションデータが使用され、宛先バッファにネットワークデータが書き出される場合もあります。送信データには、アプリケーションデータやハンドシェークデータが含まれます。unwrap() を呼び出すと、ソースバッファがチェックされ、その中のデータがハンドシェーク情報であればハンドシェークが実施されます。アプリケーションデータであれば、宛先バッファに格納されます。配下の SSL/TLS アルゴリズムの状態から、データの使用や生成のタイミングを判断できます。

wrap()unwrap() を呼び出すと、オペレーションの状態と、処理を続行する場合のエンジンとのやりとりの内容 (オプション) を示す SSLEngineResult が返されます。

SSLEngine は、完全な SSL/TLS パケットしか使用または生成しません。次の wrap() または unwrap() の呼び出しまでの間に、アプリケーションデータを内部に格納することはありません。したがって、生成されるレコードのうち一番サイズが大きいものを格納できるように、入出力 ByteBuffer のサイズを決定する必要があります。適切なバッファサイズを判定するには、SSLSession.getPacketBufferSize() および SSLSession.getApplicationBufferSize() の呼び出しを使用します。送信アプリケーションデータバッファのサイズは、通常、考慮する必要はありません。データの使用および生成に適したバッファ条件でない場合、アプリケーションは SSLEngineResult によって問題を特定し、修正したあと、再度呼び出しを試行しなければなりません。

SSLSocket とは異なり、SSLEngine のすべてのメソッドは非ブロックメソッドです。SSLEngine 実装のために必要なタスクは、完了までにかなり時間がかかったり、完了前にブロックされる可能性があります。たとえば、TrustManager は、リモート証明書確認サービスへの接続を求められることがあります。また、KeyManager は、クライアント認証の一環として使用するべき証明書を決定するようにユーザに要求することがあります。さらに、暗号化署名を作成し、これらを検証する場合、処理時間がかなり長くなり、処理がブロックされたように見えることがあります。

SSLEngine は、ブロックされる可能性があるあらゆるオペレーションに対して、Runnable 委譲タスクを生成します。SSLEngineResult により、委譲タスクの結果の必要性が示された場合、アプリケーションは getDelegatedTask() を呼び出して未実行の委譲タスクを取得し、その run() メソッドを呼び出す必要があります。呼び出しに使用されるスレッドは、計算方法によって異なります。アプリケーションは、すべての委譲タスクを取得すると、最初のオペレーションを再試行します。

アプリケーションは、通信セッションの終了時に SSL/TLS リンクを正常に終了する必要があります。SSL/TLS プロトコルはハンドシェーク終了メッセージを持っており、これらのメッセージは、SSLEngine が解放され、配下の転送機構が終了する前にピアに送信されることになっています。通信セッションの終了は、SSLException、ハンドシェーク終了メッセージの着信、または任意の終了メソッドによって開始されます。どの場合でも、エンジンからハンドシェーク終了メッセージが生成され、SSLEngineResult の状態が CLOSED になるか、isOutboundDone() の戻り値が true になるまで、wrap() が繰り返し呼び出されます。wrap() メソッドによって取得されたデータはすべてピアに送信されます。

アプリケーションから送信されるデータがもうないことをエンジンに通知するには、closeOutbound() を使用します。

ピアは、固有のハンドシェーク終了メッセージを送信することで、終了の意図を通知します。このメッセージがローカルの SSLEngineunwrap() 呼び出しによって受信および処理されると、アプリケーションは、unwrap() を呼び出し、状態が CLOSED の SSLEngineResult を検索します。条件に合うものが見つかるか、isInboundDone() の戻り値が true であれば、終了が確認されます。ピアが通信リンクを終了するとき、何らかの理由で正常な SSL/TLS 終了メッセージが送信されなかった場合、アプリケーションはストリームの終了位置を検出し、これ以上処理するべき着信メッセージがないことを、closeInbound() を介してエンジンに通知します。アプリケーションによっては、ピアからのシャットダウンメッセージを通常どおりに受け取る設定になっていることがあります。こうしたアプリケーションは、ストリームの終了位置ではなく、ハンドシェークメッセージによって終了をチェックします。

符号化方式を使用するときは、2 つのグループについて理解する必要があります。

デフォルトの実装で使用可能にする符号化方式では、サーバを認証し、機密性が保証されなければなりません。サーバ認証が行われず機密性が保証されない符号化方式を選択する場合は、サーバ認証が行われず非公開性が保証されない (暗号化されない) 通信が使用されることに 2 つの終端が明示的に同意する必要があります。

各SSL/TLS 接続にはクライアントとサーバが 1 台ずつ必要です。このため、各終端で担当するロールを決定する必要があります。この選択内容によって、どちら側からハンドシェーク処理を開始するか、また、お互いにどのようなメッセージを送信するかが決まります。モードの設定は、setUseClientMode(boolean) メソッドで行います。いったん初期ハンドシェークが開始されてからは、再ネゴシエーションの場合でも、SSLEngine のモードをクライアントからサーバ、サーバからクライアントに切り替えることはできません。

委譲タスクは別スレッドで処理することができます。SSLEngine が作成されると、現在の AccessControlContext が保存されます。その後、すべての委譲タスクはこのコンテキストで処理されます。つまり、アクセス制御の意思決定はすべて、エンジンの作成時のコンテキストで行われます。


並行処理について: 次の 2 点に注意してください。
  1. wrap() メソッドと unwrap() メソッドは、並列実行が可能です。
  2. SSL/TLS プロトコルはパケットを順番に利用します。アプリケーションは、生成されたパケットが正しい順番で配信する必要があります。パケットの到着順序が正しくないと、予期しない結果または致命的な結果を招くことがあります。

    次に例を示します。

                    synchronized (outboundLock) {               sslEngine.wrap(src, dst);
                        outboundQueue.put(dst);
                    }       
    最終的なパケットの順序を保証することができないので、結果的に、2 つのスレッドが同じメソッド (wrap() または unwrap()) を同時に呼び出すことはできません。

導入されたバージョン:
1.5
関連項目:
SSLContext, SSLSocket, SSLServerSocket, SSLSession, Socket

コンストラクタの概要
protected SSLEngine()
          内部セッションの再利用に関するヒントを提供しない SSLEngine のコンストラクタです。
protected SSLEngine(String peerHost, int peerPort)
          SSLEngine 用コンストラクタです。
 
メソッドの概要
abstract  void beginHandshake()
          この SSLEngine の初期ハンドシェークまたは再ネゴシエーションのハンドシェークを開始します。
abstract  void closeInbound()
          これ以上この SSLEngine に送信される着信ネットワークデータがないことを示す信号です。
abstract  void closeOutbound()
          これ以上この SSLEngine に送信される送信アプリケーションデータがないことを示す信号です。
abstract  Runnable getDelegatedTask()
          この SSLEngine のために委譲された Runnable タスクを返します。
abstract  String[] getEnabledCipherSuites()
          このエンジンで現在使用可能になっている SSL 符号化方式の名前を返します。
abstract  String[] getEnabledProtocols()
          この SSLEngine で現在使用可能になっているプロトコルのバージョンを返します。
abstract  boolean getEnableSessionCreation()
          このエンジンで新しい SSL セッションを確立できる場合は true を返します。
abstract  SSLEngineResult.HandshakeStatus getHandshakeStatus()
          この SSLEngine の現在のハンドシェーク状態を返します。
abstract  boolean getNeedClientAuth()
          このエンジンにクライアント認証が必須である場合は true を返します。
 String getPeerHost()
          ピアのホスト名を返します。
 int getPeerPort()
          ピアのポート番号を返します。
abstract  SSLSession getSession()
          この SSLEngine で使用中の SSLSession を返します。
abstract  String[] getSupportedCipherSuites()
          このエンジンで使用可能にできる符号化方式の名前を返します。
abstract  String[] getSupportedProtocols()
          この SSLEngine で使用することができるプロトコルの名前を返します。
abstract  boolean getUseClientMode()
          ハンドシェーク時にクライアントモードを使用するようにエンジンが設定されている場合は true
abstract  boolean getWantClientAuth()
          このエンジンがクライアント認証を要求する場合は true を返します。
abstract  boolean isInboundDone()
          unwrap(ByteBuffer, ByteBuffer) が受け付ける着信データメッセージがまだあるかどうかを返します。
abstract  boolean isOutboundDone()
          wrap(ByteBuffer, ByteBuffer) が生成する送信データメッセージがまだあるかどうかを返します。
abstract  void setEnabledCipherSuites(String[] suites)
          このエンジンで使用可能な符号化方式を設定します。
abstract  void setEnabledProtocols(String[] protocols)
          このエンジンで使用可能なプロトコルのバージョンを設定します。
abstract  void setEnableSessionCreation(boolean flag)
          このエンジンで新しい SSL セッションを確立できるかどうかを制御します。
abstract  void setNeedClientAuth(boolean need)
          クライアント認証が必須となるようにエンジンを設定します。
abstract  void setUseClientMode(boolean mode)
          ハンドシェーク時、エンジンがクライアント (またはサーバ) モードを使用するように設定します。
abstract  void setWantClientAuth(boolean want)
          クライアント認証を要求するようにエンジンを設定します。
 SSLEngineResult unwrap(ByteBuffer src, ByteBuffer dst)
          SSL/TLS ネットワークデータをプレーンテキストのアプリケーションデータバッファへ復号化しようとします。
 SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts)
          SSL/TLS ネットワークデータをプレーンテキストのアプリケーションデータバッファのシーケンスへ復号化しようとします。
abstract  SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length)
          SSL/TLS ネットワークデータをプレーンテキストのアプリケーションデータバッファのサブシーケンスへ復号化しようとします。
 SSLEngineResult wrap(ByteBuffer[] srcs, ByteBuffer dst)
          プレーンテキストバイトをデータバッファシーケンスから SSL/TLS ネットワークデータへ符号化しようとします。
abstract  SSLEngineResult wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst)
          プレーンテキストバイトをデータバッファのサブシーケンスから SSL/TLS ネットワークデータへ符号化しようとします。
 SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst)
          プレーンテキストのアプリケーションデータのバッファを SSL/TLS ネットワークデータへ符号化しようとします。
 
クラス java.lang.Object から継承されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

コンストラクタの詳細

SSLEngine

protected SSLEngine()
内部セッションの再利用に関するヒントを提供しない SSLEngine のコンストラクタです。

関連項目:
SSLContext.createSSLEngine(), SSLSessionContext

SSLEngine

protected SSLEngine(String peerHost,
                    int peerPort)
SSLEngine 用コンストラクタです。

SSLEngine 実装は、内部セッションを再利用するためのヒントとして、peerHost パラメータと peerPort パラメータを使用できます。

Kerberos など、リモートホスト名の情報を必要とする暗号群もあります。このクラスの実装は、このコンストラクタを使って Kerberos を使用します。

パラメータは、SSLEngine による認証を受けません。

パラメータ:
peerHost - ピアのホスト名
peerPort - ピアのポート番号
関連項目:
SSLContext.createSSLEngine(String, int), SSLSessionContext
メソッドの詳細

getPeerHost

public String getPeerHost()
ピアのホスト名を返します。

この値は認証されていないため、実際に使用することはできません。

戻り値:
ピアのホスト名。使用できるものがない場合は null

getPeerPort

public int getPeerPort()
ピアのポート番号を返します。

この値は認証されていないため、実際に使用することはできません。

戻り値:
ピアのポート番号。使用できるものがない場合は -1

wrap

public SSLEngineResult wrap(ByteBuffer src,
                            ByteBuffer dst)
                     throws SSLException
プレーンテキストのアプリケーションデータのバッファを SSL/TLS ネットワークデータへ符号化しようとします。

このメソッド呼び出しの動作は、次の呼び出しの動作とまったく同じです。

 engine.wrap(new ByteBuffer [] { src }, 0, 1, dst); 

パラメータ:
src - 送信アプリケーションデータを格納する ByteBuffer
dst - 送信ネットワークデータを格納する ByteBuffer
戻り値:
このオペレーションの結果を説明する SSLEngineResult
例外:
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - dst バッファが読み取り専用の場合
IllegalArgumentException - src または dst が null の場合
IllegalStateException - クライアント/サーバモードが未設定の場合
関連項目:
wrap(ByteBuffer [], int, int, ByteBuffer)

wrap

public SSLEngineResult wrap(ByteBuffer[] srcs,
                            ByteBuffer dst)
                     throws SSLException
プレーンテキストバイトをデータバッファシーケンスから SSL/TLS ネットワークデータへ符号化しようとします。

このメソッド呼び出しの動作は、次の呼び出しの動作とまったく同じです。

 engine.wrap(srcs, 0, srcs.length, dst); 

パラメータ:
srcs - 送信アプリケーションデータを格納する ByteBuffer の配列
dst - 送信ネットワークデータを格納する ByteBuffer
戻り値:
このオペレーションの結果を説明する SSLEngineResult
例外:
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - dst バッファが読み取り専用の場合
IllegalArgumentException - srcdsts のどちらか一方が null の場合、または srcs に null の要素が含まれる場合
IllegalStateException - クライアント/サーバモードが未設定の場合
関連項目:
wrap(ByteBuffer [], int, int, ByteBuffer)

wrap

public abstract SSLEngineResult wrap(ByteBuffer[] srcs,
                                     int offset,
                                     int length,
                                     ByteBuffer dst)
                              throws SSLException
プレーンテキストバイトをデータバッファのサブシーケンスから SSL/TLS ネットワークデータへ符号化しようとします。この「収集」オペレーションは、1 回の呼び出しで、単一のバイトシーケンスを 1 つ以上の指定のバッファシーケンスへ符号化できます。ラップ収集は、通常、ネットワークプロトコルやファイル形式 (たとえば、データを 1 個以上の固定長のヘッダと可変長の本体から成るセグメントにグループ化するようなファイル形式) を実装する際に便利です。収集の詳細は GatheringByteChannel、収集後の動作の詳細は GatheringByteChannel.write(ByteBuffer[], int, int) を参照してください。

SSLEngine の状態によっては、このメソッドは、アプリケーションデータを一切使用しないでネットワークデータを生成することがあります。たとえば、ハンドシェークデータがこれに該当します。

アプリケーションは、ネットワークデータをピアに安全に転送する必要があります。また、何回かの wrap() の呼び出しによって生成されたデータを生成順に転送する必要があります。さらに、このメソッドの複数の呼び出しを正しく同期化する必要があります。

この SSLEngine がまだ初期ハンドシェークを開始していない場合、このメソッドによって初期ハンドシェークが自動的に開始されます。

このメソッドは、単一の SSL/TLS パケットを生成しようとし、可能な限り多くのソースデータを消費します。しかし、各バッファに残っている合計バイト数以上を消費することはありません。各 ByteBuffer の位置は、消費または生成されたデータ量に合わせて更新されます。上限/下限値は変わりません。

srcs および dst の ByteBuffer は、配下にあるそれぞれ別々のメモリを使用する必要があります。

エンジンの終了の詳細は、クラスの説明を参照してください。

パラメータ:
srcs - 送信アプリケーションデータを格納する ByteBuffer の配列
offset - 最初のバイトの取得先となるバッファ配列内のオフセット。srcs.length 以下のゼロまたは正の数
length - アクセス可能な最大バッファ数。srcs.length - offset 以下のゼロまたは正の数
dst - 送信ネットワークデータを格納する ByteBuffer
戻り値:
このオペレーションの結果を説明する SSLEngineResult
例外:
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。エンジンの終了の詳細は、クラスの説明を参照
IndexOutOfBoundsException - offset パラメータと length パラメータの前提条件が満たされていない場合
ReadOnlyBufferException - dst バッファが読み取り専用の場合
IllegalArgumentException - srcsdst のどちらか一方が null の場合、または指定された srcs サブシーケンスに null の要素が含まれる場合
IllegalStateException - クライアント/サーバモードが未設定の場合
関連項目:
GatheringByteChannel, GatheringByteChannel.write( ByteBuffer[], int, int)

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer dst)
                       throws SSLException
SSL/TLS ネットワークデータをプレーンテキストのアプリケーションデータバッファへ復号化しようとします。

このメソッド呼び出しの動作は、次の呼び出しの動作とまったく同じです。

 engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1); 

パラメータ:
src - 着信ネットワークデータを格納する ByteBuffer
dst - 着信アプリケーションデータを格納する ByteBuffer
戻り値:
このオペレーションの結果を説明する SSLEngineResult
例外:
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - dst バッファが読み取り専用の場合
IllegalArgumentException - src または dst が null の場合
IllegalStateException - クライアント/サーバモードが未設定の場合
関連項目:
unwrap(ByteBuffer, ByteBuffer [], int, int)

unwrap

public SSLEngineResult unwrap(ByteBuffer src,
                              ByteBuffer[] dsts)
                       throws SSLException
SSL/TLS ネットワークデータをプレーンテキストのアプリケーションデータバッファのシーケンスへ復号化しようとします。

このメソッド呼び出しの動作は、次の呼び出しの動作とまったく同じです。

 engine.unwrap(src, dsts, 0, dsts.length); 

パラメータ:
src - 着信ネットワークデータを格納する ByteBuffer
dsts - 着信アプリケーションデータを格納する ByteBuffer の配列
戻り値:
このオペレーションの結果を説明する SSLEngineResult
例外:
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - 読み取り専用の dst バッファが存在する場合
IllegalArgumentException - srcsdst のどちらか一方が null の場合、または dsts に null の要素が含まれる場合
IllegalStateException - クライアント/サーバモードが未設定の場合
関連項目:
unwrap(ByteBuffer, ByteBuffer [], int, int)

unwrap

public abstract SSLEngineResult unwrap(ByteBuffer src,
                                       ByteBuffer[] dsts,
                                       int offset,
                                       int length)
                                throws SSLException
SSL/TLS ネットワークデータをプレーンテキストのアプリケーションデータバッファのサブシーケンスへ復号化しようとします。この「散布」オペレーションは、1 回の呼び出しで、単一のバイトシーケンスを 1 つ以上の指定のバッファシーケンスへ復号化できます。分散するアンラップは、通常、ネットワークプロトコルやファイル形式 (たとえば、データを 1 個以上の固定長のヘッダと可変長の本体から成るセグメントにグループ化するようなファイル形式) を実装する際に便利です。散布の詳細は ScatteringByteChannel、散布後の動作の詳細は ScatteringByteChannel.read(ByteBuffer[], int, int) を参照してください。

SSLEngine の状態によっては、このメソッドは、アプリケーションデータを一切生成しないでネットワークデータを使用することがあります。たとえば、ハンドシェークデータがこれに該当します。

アプリケーションは、ピアからネットワークデータを安全に取得する必要があります。また、受信した順にデータのラップを解除 (unwrap() 呼び出し) する必要があります。アプリケーションは、このメソッドの複数の呼び出しを正しく同期化する必要があります。

この SSLEngine がまだ初期ハンドシェークを開始していない場合、このメソッドによって初期ハンドシェークが自動的に開始されます。

このメソッドは、単一の完全な SSL/TLS ネットワークパケットを消費しようとしますが、バッファに残っている合計バイト数以上を消費することはありません。各 ByteBuffer の位置は、消費または生成されたデータ量に合わせて更新されます。上限/下限値は変わりません。

src および dsts の ByteBuffer は、配下にあるそれぞれ別々のメモリを使用する必要があります。

この呼び出しの結果、着信ネットワークバッファが変更されることがあります。このため、二次的な目的でネットワークデータパケットが必要な場合は、このメソッドの呼び出しの前にデータを複製する必要があります。注: ネットワークデータを 2 番目の SSLEngine で使用することはできません。各 SSLEngine が、SSL/TLS メッセージに影響を及ぼす一意のランダムな状態を持っているからです。

エンジンの終了の詳細は、クラスの説明を参照してください。

パラメータ:
src - 着信ネットワークデータを格納する ByteBuffer
dsts - 着信アプリケーションデータを格納する ByteBuffer の配列
offset - 最初のバイトの転送先となるバッファ配列内のオフセット。dsts.length 以下のゼロまたは正の数
length - アクセス可能な最大バッファ数。dsts.length - offset 以下のゼロまたは正の数
戻り値:
このオペレーションの結果を説明する SSLEngineResult
例外:
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。エンジンの終了の詳細は、クラスの説明を参照
IndexOutOfBoundsException - offset パラメータと length パラメータの前提条件が満たされていない場合
ReadOnlyBufferException - 読み取り専用の dst バッファが存在する場合
IllegalArgumentException - srcdsts のどちらか一方が null の場合、または指定された dsts サブシーケンスに null の要素が含まれる場合
IllegalStateException - クライアント/サーバモードが未設定の場合
関連項目:
ScatteringByteChannel, ScatteringByteChannel.read( ByteBuffer[], int, int)

getDelegatedTask

public abstract Runnable getDelegatedTask()
この SSLEngine のために委譲された Runnable タスクを返します。

SSLEngine オペレーションに必要なオペレーションの結果がブロックされたり、完了までにかなりの時間がかかることがあります。このメソッドは、未処理の Runnable オペレーション (タスク) を取得するために使用されます。各タスクには、run オペレーションを実行するスレッド (現在のスレッドも可) を割り当てる必要があります。run メソッドが終了したあと、不要になった Runnable オブジェクトは廃棄可能です。

委譲されたタスクは、AccessControlContext 内で、このオブジェクトが作成されたときに実行されます。

このメソッドの呼び出しは、未処理のタスクをそれぞれ 1 回だけ返します。

委譲された複数のタスクを並列実行することもできます。

戻り値:
委譲された Runnable タスク。使用できるものがない場合は null

closeInbound

public abstract void closeInbound()
                           throws SSLException
これ以上この SSLEngine に送信される着信ネットワークデータがないことを示す信号です。

アプリケーションが closeOutbound() を呼び出して終了処理を開始したとき、ピアの対応する終了メッセージを待つ必要がない場合があります (終了の警告の待機に関する詳細は、TLS 仕様のセクション 7.2.1(RFC 2246) を参照)。この場合、このメソッドの呼び出しは不要です。

これに対して、アプリケーションが終了処理を開始しなかった場合や、上記の状況に当てはまらない場合は、SSL/TLS データストリームの終了部分が着信するたびにこのメソッドを呼び出す必要があります。これにより、着信側の終了が保証され、ピアが SSL/TLS 終了手続きを適切に実行したことを確認し、値の切り詰めによる攻撃の可能性を検出することができます。

このメソッドは、べき等です。着信側がすでに終了している場合は、何も行いません。

残りのハンドシェークデータをフラッシュするには、wrap() を呼び出します。

例外:
SSLException - このエンジンがピアから適切な SSL/TLS 終了通知メッセージを受け取っていない場合
関連項目:
isInboundDone(), isOutboundDone()

isInboundDone

public abstract boolean isInboundDone()
unwrap(ByteBuffer, ByteBuffer) が受け付ける着信データメッセージがまだあるかどうかを返します。

戻り値:
SSLEngine がこれ以上ネットワークデータを使用しない場合 (言い換えれば、これ以上アプリケーションデータを生成しない場合) は true
関連項目:
closeInbound()

closeOutbound

public abstract void closeOutbound()
これ以上この SSLEngine に送信される送信アプリケーションデータがないことを示す信号です。

このメソッドは、べき等です。送信側がすでに終了している場合は、何も行いません。

残りのハンドシェークデータをフラッシュするには、wrap(ByteBuffer, ByteBuffer) を呼び出します。

関連項目:
isOutboundDone()

isOutboundDone

public abstract boolean isOutboundDone()
wrap(ByteBuffer, ByteBuffer) が生成する送信データメッセージがまだあるかどうかを返します。

終了段階で、SSLEngine は、ピアに送信するハンドシェーク終了データを生成します。このデータを生成するには、wrap() を呼び出す必要があります。このメソッドの戻り値が true の場合、これ以上送信データは生成されません。

戻り値:
SSLEngine がこれ以上ネットワークデータを生成しない場合は true
関連項目:
closeOutbound(), closeInbound()

getSupportedCipherSuites

public abstract String[] getSupportedCipherSuites()
このエンジンで使用可能にできる符号化方式の名前を返します。通常は、これらの符号化方式の一部だけが、デフォルト実装で使用可能になります。一部の符号化方式は、デフォルト実装のサービス品質要件を満たしていないことがあるためです。これらの符号化方式は、特殊なアプリケーションで使用されます。

戻り値:
符号化方式名の配列
関連項目:
getEnabledCipherSuites(), setEnabledCipherSuites(String [])

getEnabledCipherSuites

public abstract String[] getEnabledCipherSuites()
このエンジンで現在使用可能になっている SSL 符号化方式の名前を返します。SSL エンジンが最初に作成されたときに、使用可能になっているすべての符号化方式で、最小限のサービス品質が保証されます。環境によっては、この値は空の場合もあります。

符号化方式は、たとえ有効でも使用されないことがあります。たとえば、ピアが符号化方式をサポートしない場合、この符号化に必要な証明書や非公開鍵を使用することができない場合、または、匿名の符号化方式が利用可能であっても認証が要求される場合などです。

戻り値:
符号化方式名の配列
関連項目:
getSupportedCipherSuites(), setEnabledCipherSuites(String [])

setEnabledCipherSuites

public abstract void setEnabledCipherSuites(String[] suites)
このエンジンで使用可能な符号化方式を設定します。

suites パラメータに指定された各符号化方式は、getSupportedCipherSuites() でリストされていなければなりません。そうでない場合、メソッドは失敗します。このメソッドの呼び出しが正常に行われたとき、suites パラメータにリストされた符号化方式のみ、使用することができます。

なぜ特定の符号化方式をエンジンで使用することができないかについては、getEnabledCipherSuites() を参照してください。

パラメータ:
suites - 使用可能にするすべての符号化方式の名前
例外:
IllegalArgumentException - パラメータに指定された符号化方式の一部がサポートされない場合、またはパラメータが null の場合
関連項目:
getSupportedCipherSuites(), getEnabledCipherSuites()

getSupportedProtocols

public abstract String[] getSupportedProtocols()
この SSLEngine で使用することができるプロトコルの名前を返します。

戻り値:
サポートされているプロトコルの配列

getEnabledProtocols

public abstract String[] getEnabledProtocols()
この SSLEngine で現在使用可能になっているプロトコルのバージョンを返します。

戻り値:
プロトコルの配列
関連項目:
setEnabledProtocols(String [])

setEnabledProtocols

public abstract void setEnabledProtocols(String[] protocols)
このエンジンで使用可能なプロトコルのバージョンを設定します。

プロトコルは、getSupportedProtocols() により、サポート対象としてリストされていなければなりません。このメソッドの呼び出しが正常に行われたとき、protocols パラメータにリストされたプロトコルのみ、使用することができます。

パラメータ:
protocols - 使用可能にするすべてのプロトコルの名前
例外:
IllegalArgumentException - パラメータに指定されたプロトコルの一部がサポートされない場合、またはパラメータが null の場合
関連項目:
getEnabledProtocols()

getSession

public abstract SSLSession getSession()
この SSLEngine で使用中の SSLSession を返します。

SSL セッションは有効期間が長く、ユーザによってはログインセッション全体に対応することもあります。セッションには、セッション内のすべての接続で使用される符号化方式と、セッションのクライアントとサーバの識別情報が指定されています。

このメソッドは、SSLSocket.getSession() とは異なり、ハンドシェークが完了するまでブロックされません。

初期ハンドシェークが完了すると、無効な暗号群 SSL_NULL_WITH_NULL_NULL を報告するセッションオブジェクトを返します。

戻り値:
この SSLEngineSSLSession
関連項目:
SSLSession

beginHandshake

public abstract void beginHandshake()
                             throws SSLException
この SSLEngine の初期ハンドシェークまたは再ネゴシエーションのハンドシェークを開始します。

このメソッドは、初期ハンドシェーク時には必要ありません。ハンドシェークがまだ開始されていない場合は、wrap() メソッドと unwrap() メソッドによって暗黙的にこのメソッドが呼び出されるからです。

ピアも、適切なセッション再ネゴシエーションのハンドシェークメッセージを送信することにより、この SSLEngine とのセッションの再ネゴシエーションを要求することがあります。

このメソッドは、SSLSocket#startHandshake() メソッドとは異なり、ハンドシェークが完了するまでブロックされません。

強制的に SSL/TLS セッションの再ネゴシエーションを行う場合は、現在のセッションを無効にしてからこのメソッドを呼び出す必要があります。

既存のエンジン上で複数のハンドシェークをサポートせず、SSLException をスローするプロトコルもあります。

例外:
SSLException - SSLEngine に新しくハンドシェークを開始するように通知しているとき、問題が発生した場合。エンジンの終了の詳細は、クラスの説明を参照
IllegalStateException - クライアント/サーバモードが未設定の場合
関連項目:
SSLSession.invalidate()

getHandshakeStatus

public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus()
この SSLEngine の現在のハンドシェーク状態を返します。

戻り値:
現在の SSLEngineResult.HandshakeStatus

setUseClientMode

public abstract void setUseClientMode(boolean mode)
ハンドシェーク時、エンジンがクライアント (またはサーバ) モードを使用するように設定します。

このメソッドは、すべてのハンドシェークの前に呼び出す必要があります。いったんハンドシェークが開始されると、このエンジンの寿命が尽きるまで、現在のモードをリセットすることはできません。

通常、サーバは自身を認証しますが、クライアントは必ずしもそうとは限りません。

パラメータ:
mode - ハンドシェークをクライアントモードで開始する場合は true
例外:
IllegalArgumentException - 最初のハンドシェークが開始されてからモードを変更しようとした場合
関連項目:
getUseClientMode()

getUseClientMode

public abstract boolean getUseClientMode()
ハンドシェーク時にクライアントモードを使用するようにエンジンが設定されている場合は true

戻り値:
クライアントモードでハンドシェークを行う場合は true
関連項目:
setUseClientMode(boolean)

setNeedClientAuth

public abstract void setNeedClientAuth(boolean need)
クライアント認証が必須となるようにエンジンを設定します。このオプションは、サーバモードのエンジンだけで使用できます。

エンジンのクライアント認証設定は、次のいずれかになります。

setWantClientAuth(boolean) の場合とは異なり、このオプションが設定されていて、かつクライアント認証情報が提供されない場合は、ネゴシエーションが停止し、エンジンは、終了プロシージャを開始します。

このメソッドを呼び出すと、これまでにこのメソッドまたは setWantClientAuth(boolean) によって設定された内容がオーバーライドされます。

パラメータ:
need - クライアント認証が必須の場合は true、クライアント認証が不要な場合は false
関連項目:
getNeedClientAuth(), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

getNeedClientAuth

public abstract boolean getNeedClientAuth()
このエンジンにクライアント認証が必須である場合は true を返します。このオプションは、サーバモードのエンジンだけで使用します。

戻り値:
クライアント認証が必須の場合は true、クライアント認証が不要な場合は false
関連項目:
setNeedClientAuth(boolean), setWantClientAuth(boolean), getWantClientAuth(), setUseClientMode(boolean)

setWantClientAuth

public abstract void setWantClientAuth(boolean want)
クライアント認証を要求するようにエンジンを設定します。このオプションは、サーバモードのエンジンだけで使用できます。

エンジンのクライアント認証設定は、次のいずれかになります。

setNeedClientAuth(boolean) と異なり、このオプションが設定されていて、かつクライアント認証情報が提供されない場合でも、ネゴシエーションは続行されます。

このメソッドを呼び出すと、これまでにこのメソッドまたは setNeedClientAuth(boolean) によって設定された内容がオーバーライドされます。

パラメータ:
want - クライアント認証が要求された場合は true、クライアント認証が不要な場合は false
関連項目:
getWantClientAuth(), setNeedClientAuth(boolean), getNeedClientAuth(), setUseClientMode(boolean)

getWantClientAuth

public abstract boolean getWantClientAuth()
このエンジンがクライアント認証を要求する場合は true を返します。このオプションは、サーバモードのエンジンだけで使用します。

戻り値:
クライアント認証が要求された場合は true、クライアント認証が不要な場合は false
関連項目:
setNeedClientAuth(boolean), getNeedClientAuth(), setWantClientAuth(boolean), setUseClientMode(boolean)

setEnableSessionCreation

public abstract void setEnableSessionCreation(boolean flag)
このエンジンで新しい SSL セッションを確立できるかどうかを制御します。セッションを作成できず、再開できる既存のセッションがない場合、ハンドシェークは成功しません。

パラメータ:
flag - セッションを作成できる場合は true (デフォルト)。既存のセッションを再開する場合は false
関連項目:
getEnableSessionCreation()

getEnableSessionCreation

public abstract boolean getEnableSessionCreation()
このエンジンで新しい SSL セッションを確立できる場合は true を返します。

戻り値:
セッションを作成できる場合は true (デフォルト)。既存のセッションを再開する場合は false
関連項目:
setEnableSessionCreation(boolean)

JavaTM 2 Platform
Standard Ed. 5.0

バグの報告と機能のリクエスト
さらに詳しい API リファレンスおよび開発者ドキュメントについては、Java 2 SDK SE 開発者用ドキュメントを参照してください。開発者向けの詳細な解説、概念の概要、用語の定義、バグの回避策、およびコード実例が含まれています。

Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。