SSLEngine (Java Platform SE 7)

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/TLS により、メッセージを盗聴による改ざんから保護する。
- 認証。ほとんどの SSL/TLS モードでは、ピア認証が提供される。通常は、サーバー認証が行われる。サーバーからの要求に応じて、クライアント認証も行われる。
- 機密性 (プライバシの保護)。ほとんどの SSL/TLS モードでは、クライアントとサーバー間で送信されるデータが暗号化され、データの機密性が保護される。この結果、受動的な盗聴によって、金融情報や個人情報などの機密性の高いデータが盗聴されることがない。
これらのセキュリティー保護は、「暗号化方式群」を使用して指定します。暗号化方式群は、指定された SSL 接続で使用される暗号化アルゴリズムの組み合わせです。ネゴシエーションを行うには、2 つの終端が同じ暗号化方式群を選択し、その暗号化方式群が両方の環境で使用可能である必要があります。共通の暗号化方式群がない場合は、SSL 接続を確立できず、データを交換できません。
使用される暗号化方式群は、「ハンドシェーク」と呼ばれるネゴシエーションプロセスによって確立されます。ハンドシェークでは、セッションの作成または参加が行われます。作成または参加したセッションは、無効になるまでさまざまな接続を保護します。ハンドシェークが完了すると、getSession() メソッドを使用してセッション属性にアクセスできます。
SSLSocket クラスもほぼ同じセキュリティー機能を提供しますが、すべての着信および発信データは、意図的にブロックモデルを使用する配下の Socket により自動的に送信されます。この処理は多くのアプリケーションに対して適切ですが、このモデルは大規模サーバーに必要な拡張性をもたらしません。
SSLEngine の主な特長として、転送メカニズムに依存することなく着信/送信バイトストリームを操作できる点が挙げられます。SSLEngine ユーザーは、ピアにおける入出力転送の信頼性を確保する必要があります。SSL/TLS 抽象化オブジェクトを入出力転送メカニズムから切り離すことにより、SSLEngine をさまざまな入出力タイプで広範囲に利用することができます。たとえば、non-blocking I/O (polling)、selectable non-blocking I/O、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 によって問題を特定し、修正したあと、再度呼び出しを試行しなければいけません。
たとえば、有効な宛先バッファーの容量が不十分であるとエンジンが判定した場合、unwrap() は SSLEngineResult.Status.BUFFER_OVERFLOW の結果を返します。必要に応じて、アプリケーションで SSLSession.getApplicationBufferSize() を呼び出し、その値と宛先バッファー内の有効な容量を比較して、バッファーを大きくするようにしてください。同様に、unwrap() が SSLEngineResult.Status.BUFFER_UNDERFLOW を返そうとした場合は、アプリケーションで SSLSession.getPacketBufferSize() を呼び出して、レコードを保持するのに十分な容量をソースバッファーに確保し (また、必要に応じて拡張し)、より多くの着信データを取得するようにしてください。
```
   SSLEngineResult r = engine.unwrap(src, dst);
   switch (r.getStatus()) {
   BUFFER_OVERFLOW:
       // Could attempt to drain the dst buffer of any already obtained
       // data, but we'll just increase it to the size needed.
       int appSize = engine.getSession().getApplicationBufferSize();
       ByteBuffer b = ByteBuffer.allocate(appSize + dst.position());
       dst.flip();
       b.put(dst);
       dst = b;
       // retry the operation.
       break;
   BUFFER_UNDERFLOW:
       int netSize = engine.getSession().getPacketBufferSize();
       // Resize buffer if needed.
       if (netSize > dst.capacity()) {
           ByteBuffer b = ByteBuffer.allocate(netSize);
           src.flip();
           b.put(src);
           src = b;
       }
       // Obtain more inbound network data for src,
       // then retry the operation.
       break;
   // other cases: CLOSED, OK.
   }
 
```
SSLSocket とは異なり、SSLEngine のすべてのメソッドは非ブロックメソッドです。SSLEngine 実装のために必要なタスクは、完了までにかなり時間がかかったり、完了前にブロックされる可能性があります。たとえば、TrustManager は、リモート証明書確認サービスへの接続を求められることがあります。また、KeyManager は、クライアント認証の一環として使用するべき証明書を決定するようにユーザーに要求することがあります。さらに、暗号化署名を作成し、これらを検証する場合、処理時間がかなり長くなり、処理がブロックされたように見えることがあります。
SSLEngine は、ブロックされる可能性があるあらゆるオペレーションに対して、Runnable 委譲タスクを生成します。SSLEngineResult により、委譲タスクの結果の必要性が示された場合、アプリケーションは getDelegatedTask() を呼び出して未実行の委譲タスクを取得し、その run() メソッドを呼び出す必要があります。呼び出しに使用されるスレッドは、計算方法によって異なります。アプリケーションは、すべての委譲タスクを取得すると、最初のオペレーションを再試行します。
アプリケーションは、通信セッションの終了時に SSL/TLS リンクを正常に終了する必要があります。SSL/TLS プロトコルはハンドシェーク終了メッセージを持っており、これらのメッセージは、SSLEngine が解放され、配下の転送メカニズムが終了する前にピアに送信されることになっています。通信セッションの終了は、SSLException、ハンドシェーク終了メッセージの着信、または任意の終了メソッドによって開始されます。どの場合でも、エンジンからハンドシェーク終了メッセージが生成され、SSLEngineResult の状態が CLOSED になるか、isOutboundDone() の戻り値が true になるまで、wrap() が繰り返し呼び出されます。wrap() メソッドによって取得されたデータはすべてピアに送信されます。
アプリケーションから送信されるデータがもうないことをエンジンに通知するには、closeOutbound() を使用します。
ピアは、固有のハンドシェーク終了メッセージを送信することで、終了の意図を通知します。このメッセージがローカルの SSLEngine の unwrap() 呼び出しによって受信および処理されると、アプリケーションは、unwrap() を呼び出し、状態が CLOSED の SSLEngineResult を検索します。条件に合うものが見つかるか、isInboundDone() の戻り値が true であれば、終了が確認されます。ピアが通信リンクを終了するとき、なんらかの理由で正常な SSL/TLS 終了メッセージが送信されなかった場合、アプリケーションはストリームの終了位置を検出し、これ以上処理するべき着信メッセージがないことを、closeInbound() を介してエンジンに通知します。アプリケーションによっては、ピアからのシャットダウンメッセージを通常どおりに受け取る設定になっていることがあります。こうしたアプリケーションは、ストリームの終了位置ではなく、ハンドシェークメッセージによって終了をチェックします。
暗号化方式群を使用するときは、2 つのグループについて理解する必要があります。
- サポートされる暗号化方式群: SSL 実装でサポートされるすべての暗号化方式群。このリストは、getSupportedCipherSuites() を使用して報告される。
- 有効になっている暗号化方式群。サポートされる暗号化方式群の完全なセットより少ないことがある。このグループは、setEnabledCipherSuites(String []) メソッドを使用して設定し、getEnabledCipherSuites() メソッドを使用して照会する。新しいエンジンでは、最小限の推奨構成を表すデフォルトの暗号化方式群が使用可能になっている。
デフォルトの実装で使用可能にする暗号化方式群では、サーバーを認証し、機密性が保証されなければいけません。サーバー認証が行われず機密性が保証されない暗号化方式群を選択する場合は、サーバー認証が行われず非公開性が保証されない (暗号化されない) 通信が使用されることに 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 を返します。
`SSLSession`	`getHandshakeSession()` SSL/TLS ハンドシェーク時に構築中の `SSLSession` を返します。
`abstract SSLEngineResult.HandshakeStatus`	`getHandshakeStatus()` この `SSLEngine` の現在のハンドシェーク状態を返します。
`abstract boolean`	`getNeedClientAuth()` エンジンにクライアント認証が必要な場合は true を返します。
`String`	`getPeerHost()` ピアのホスト名を返します。
`int`	`getPeerPort()` ピアのポート番号を返します。
`abstract SSLSession`	`getSession()` この `SSLEngine` で使用されている `SSLSession` を返します。
`SSLParameters`	`getSSLParameters()` この SSLEngine で有効な SSLParameters を返します。
`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)` クライアント認証が必要なようにエンジンを構成します。
`void`	`setSSLParameters(SSLParameters params)` このエンジンに SSLParameters を適用します。
`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 - 送信アプリケーションデータを含む ByteBuffers の配列
    dst - 送信ネットワークデータを保持する ByteBuffer
    
    戻り値:
    このオペレーションの結果を説明する SSLEngineResult。
    
    例外:
    
    SSLException - データの処理中に問題が検出され、それが SSLEngine の異常終了の原因になった場合。エンジンの終了の詳細は、クラスの説明を参照。
    
    ReadOnlyBufferException - dst バッファーが読み取り専用である場合。
    
    IllegalArgumentException - srcs と dst のどちらかが 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 - 送信アプリケーションデータを含む ByteBuffers の配列
    offset - バイトの取得元となる最初のバッファー配列内のオフセット。srcs.length 以下の負でない値である必要があります
    length - アクセスされる最大バッファー数。srcs.length - offset 以下の負でない値である必要があります
    dst - 送信ネットワークデータを保持する ByteBuffer
    
    戻り値:
    このオペレーションの結果を説明する SSLEngineResult。
    
    例外:
    
    SSLException - データの処理中に問題が検出され、それが SSLEngine の異常終了の原因になった場合。エンジンの終了の詳細は、クラスの説明を参照。
    
    IndexOutOfBoundsException - offset パラメータと length パラメータの前提条件が満たされていない場合。
    
    ReadOnlyBufferException - dst バッファーが読み取り専用である場合。
    
    IllegalArgumentException - srcs と dst のどちらかが 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 - src と dsts のどちらかが 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 - src と dsts のどちらかが 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 - パラメータで指定された暗号化方式群の 1 つ以上がサポートされていないか、またはパラメータが 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 - パラメータで指定されたプロトコルの 1 つ以上がサポートされていないか、または protocols パラメータが null である場合。
    関連項目:
    getEnabledProtocols()
  - getSession
```
public abstract SSLSession getSession()
```
    この SSLEngine で使用されている SSLSession を返します。
    SSL セッションは有効期間が長く、ユーザーによってはログインセッション全体に対応することもあります。セッションには、セッション内のすべての接続で使用される暗号化方式群と、セッションのクライアントとサーバーの識別情報が指定されています。
    このメソッドは、SSLSocket.getSession() とは異なり、ハンドシェークが完了するまでブロックされません。
    初期ハンドシェークが完了すると、無効な暗号化方式群 SSL_NULL_WITH_NULL_NULL を報告するセッションオブジェクトを返します。
    
    戻り値:
    この SSLEngine の SSLSession
    関連項目:
    SSLSession
  - getHandshakeSession
```
public SSLSession getHandshakeSession()
```
    SSL/TLS ハンドシェーク時に構築中の SSLSession を返します。
    TLS プロトコルでは、このクラスのインスタンスを使用しているとき、ただし SSLSession が完全に初期化され、getSession によって使用可能になる前に必要なパラメータのネゴシエーションを行う可能性があります。たとえば、有効な署名アルゴリズムのリストによって、TrustManager の決定中に使用できる証明書の種類が制限される可能性があります。または、ネットワーク環境をより適切にサポートするために、最大 TLS フラグメントパケットサイズが変更される場合があります。
    このメソッドでは、構築されている SSLSession に早期にアクセスできます。ハンドシェークの進捗状況によっては、一部のデータがまだ使用できない可能性があります。たとえば、リモートサーバーが証明書チェーンを送信しようとしているが、そのチェーンがまだ処理されていない場合、SSLSession の getPeerCertificates メソッドは SSLPeerUnverifiedException をスローします。そのチェーンの処理が完了すると、getPeerCertificates は適切な値を返します。
    
    戻り値:
    このインスタンスが現在ハンドシェークしていない場合、または現在のハンドシェークが基本的な SSLSession を作成できる程十分に進捗していない場合は null。それ以外の場合、このメソッドは、現在ネゴシエーションが行われている SSLSession を返します。
    
    例外:
    
    UnsupportedOperationException - ベースとなるプロバイダがこの操作を実装していない場合。
    導入されたバージョン:
    
    1.7
    
    関連項目:
    SSLSocket, SSLSession, ExtendedSSLSession, X509ExtendedKeyManager, X509ExtendedTrustManager
  - 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)
  - getSSLParameters
```
public SSLParameters getSSLParameters()
```
    この SSLEngine で有効な SSLParameters を返します。返される SSLParameters の暗号化方式群とプロトコルは、常に null 以外です。
    
    戻り値:
    この SSLEngine で有効な SSLParameters。
    導入されたバージョン:
    
    1.6
  - setSSLParameters
```
public void setSSLParameters(SSLParameters params)
```
    このエンジンに SSLParameters を適用します。
    これは次のことを意味します。
    - params.getCipherSuites() が null 以外の場合は、その値を使用して setEnabledCipherSuites() が呼び出される
    - params.getProtocols() が null 以外の場合は、その値を使用して setEnabledProtocols() が呼び出される
    - params.getNeedClientAuth() または params.getWantClientAuth() が true を返した場合は、それぞれ setNeedClientAuth(true) と setWantClientAuth(true) が呼び出される。それ以外の場合は setWantClientAuth(false) が呼び出される。
    パラメータ:
    params - パラメータ
    
    例外:
    
    IllegalArgumentException - setEnabledCipherSuites() または setEnabledProtocols() の呼び出しが失敗した場合
    導入されたバージョン:
    
    1.6

バグまたは機能を送信
詳細な API リファレンスおよび開発者ドキュメントについては、Java SE のドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2013, Oracle and/or its affiliates. All rights reserved.

クラス SSLEngine

コンストラクタのサマリー

メソッドのサマリー

クラス java.lang.Object から継承されたメソッド

コンストラクタの詳細

SSLEngine

SSLEngine

メソッドの詳細

getPeerHost

getPeerPort

wrap

wrap

wrap

unwrap

unwrap

unwrap

getDelegatedTask

closeInbound

isInboundDone

closeOutbound

isOutboundDone

getSupportedCipherSuites

getEnabledCipherSuites

setEnabledCipherSuites

getSupportedProtocols

getEnabledProtocols

setEnabledProtocols

getSession

getHandshakeSession

beginHandshake

getHandshakeStatus

setUseClientMode

getUseClientMode

setNeedClientAuth

getNeedClientAuth

setWantClientAuth

getWantClientAuth

setEnableSessionCreation

getEnableSessionCreation

getSSLParameters

setSSLParameters