public abstract class SSLEngine extends Object
セキュア通信モードでは、次のセキュリティ保護が実施されます。
使用される暗号化方式群は、「ハンドシェーク」と呼ばれるネゴシエーション・プロセスによって確立されます。ハンドシェークでは、セッションの作成またはセッションへの参加が行われます。このセッションは、時間の経過とともにさまざまな接続を保護します。ハンドシェークが完了すると、getSession()
メソッドを使用してセッション属性にアクセスできます。
SSLSocket
クラスもほぼ同じセキュリティ機能を提供しますが、すべての着信および発信データは、意図的にブロック・モデルを使用する配下のSocket
により自動的に送信されます。この処理は多くのアプリケーションに対して適切ですが、このモデルは大規模サーバーに必要な拡張性をもたらしません。
SSLEngine
の主な特長として、転送メカニズムに依存することなくインバウンド/アウトバウンドのバイト・ストリームに作用する点があげられます。SSLEngine
ユーザーは、ピアに対する入出力転送の信頼性を確保する必要があります。SSL/TLS抽象を入出力転送メカニズムから切り離すことにより、SSLEngine
をさまざまな入出力タイプで使用できます。たとえば、非ブロック入出力(ポーリング)
、選択可能な非ブロック入出力
、Socket
や従来のInput/OutputStream、ローカルのByteBuffer
やバイト配列、将来の非同期入出力モデルなどで使用できます。
高レベルでは、SSLEngine
は次のように表されます。
app data | ^ | | | v | | +----+-----|-----+----+ | | | | SSL|Engine | wrap() | | | unwrap() | OUTBOUND | INBOUND | | | | +----+-----|-----+----+ | | ^ | | | v | net dataアプリケーション・データ(別名「プレーン・テキスト」または「クリアテキスト」)は、アプリケーションによって生成または使用されるデータです。アプリケーション・データと対になるものとして、ネットワーク・データがあります。ネットワーク・データは、ハンドシェークまたは暗号文(暗号化された)、またはその両方のいずれかで構成され、入出力メカニズムを介して転送されるデータです。インバウンド・データはピアから受信されるデータ、アウトバウンド・データはピアへ送信されるデータです。
SSLEngine
のコンテキストでは、セキュア接続の確立および制御目的で交換されるデータを「ハンドシェーク・データ」と総称します。ハンドシェーク・データには、SSL/TLSメッセージalert、change_cipher_spec、handshakeなどがあります。
SSLEngine
は、次の5つの段階をたどります。
SSLEngine
の作成と初期化は完了しましたが、まだ使用されてはいません。この段階では、アプリケーションにより、SSLEngine
固有のあらゆる設定(暗号化方式群の有効化、SSLEngine
がクライアント・モードとサーバー・モードのどちらでハンドシェークを行うかなど)を行うことができます。ハンドシェークが始まると、次のハンドシェークからクライアント/サーバー・モードの設定を除く(下記参照)新しい設定が使用されます。
SSLEngine
からアプリケーション・データが送信されます。アウトバウンド・アプリケーション・メッセージは暗号化され、データの整合性が確保されます。インバウンド・メッセージでは、この逆の手続きが行われます。
SSLEngine
構成設定は使用されません。
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つのグループについて理解する必要があります。
getSupportedCipherSuites()
を使用して報告される。
setEnabledCipherSuites(String [])
メソッドを使用して設定し、getEnabledCipherSuites()
メソッドを使用して照会する。新しいエンジンでは、最小限の推奨構成を表すデフォルトの暗号化方式群が使用可能になっている。
各SSL/TLS接続にはクライアントとサーバーが1台ずつ必要です。このため、各端点で担当するロールを決定する必要があります。この選択内容によって、どちら側からハンドシェーク処理を開始するか、また、お互いにどのタイプのメッセージを送信するかが決まります。setUseClientMode(boolean)
メソッドはモードを構成します。いったん初期ハンドシェークが開始されてからは、再ネゴシエーションを実行する場合でも、SSLEngine
のモードをクライアントからサーバー、サーバーからクライアントに切り替えることはできません。
アプリケーションにより、委譲タスクを別スレッドで処理するように選択できます。SSLEngine
が作成されると、現在のAccessControlContext
が保存されます。その後、すべての委譲タスクはこのコンテキストで処理されます。つまり、アクセス制御の意思決定はすべて、エンジンの作成時のに前方参照されたコンテキストを使用してなされます。
wrap()
メソッドとunwrap()
メソッドは、並行実行が可能です。
例を示します。
synchronized (outboundLock) { sslEngine.wrap(src, dst); outboundQueue.put(dst); }最終的なパケットの順序を保証することができないので、結果的に、2つのスレッドが同じメソッド(
wrap()
またはunwrap()
)を並行して呼び出すことはできません。
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ネットワーク・データへエンコードしようとします。
|
protected SSLEngine()
SSLEngine
のコンストラクタ。protected SSLEngine(String peerHost, int peerPort)
SSLEngine
のコンストラクタ。
SSLEngine
実装は、内部セッションを再利用するためのヒントとして、peerHost
パラメータとpeerPort
パラメータを使用できます。
Kerberosなど、リモート・ホスト名の情報を必要とする暗号化方式群もあります。このクラスの実装は、このコンストラクタを使ってKerberosを使用します。
パラメータは、SSLEngine
による認証を受けません。
peerHost
- ピアのホスト名peerPort
- ピアのポート番号SSLContext.createSSLEngine(String, int)
, SSLSessionContext
public String getPeerHost()
この値は認証されていないため、実際に使用することはできません。
public int getPeerPort()
この値は認証されていないため、実際に使用することはできません。
public SSLEngineResult wrap(ByteBuffer src, ByteBuffer dst) throws SSLException
このメソッド呼出しの動作は、次の呼出しの動作とまったく同じです。
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)
public SSLEngineResult wrap(ByteBuffer[] srcs, ByteBuffer dst) throws SSLException
このメソッド呼出しの動作は、次の呼出しの動作とまったく同じです。
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)
public abstract SSLEngineResult wrap(ByteBuffer[] srcs, int offset, int length, ByteBuffer dst) throws SSLException
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)
public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer dst) throws SSLException
このメソッド呼出しの動作は、次の呼出しの動作とまったく同じです。
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)
public SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts) throws SSLException
このメソッド呼出しの動作は、次の呼出しの動作とまったく同じです。
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)
public abstract SSLEngineResult unwrap(ByteBuffer src, ByteBuffer[] dsts, int offset, int length) throws SSLException
ScatteringByteChannel
、散布後の動作の詳細はScatteringByteChannel.read(ByteBuffer[], int, int)
を参照してください。
SSLEngineの状態によっては、このメソッドは、アプリケーション・データを一切生成しないでネットワーク・データを使用することがあります。たとえば、ハンドシェーク・データがこれに該当します。
アプリケーションは、ピアからネットワーク・データを安全に取得する必要があります。また、受信した順にデータのラップを解除(unwrap()呼び出し)する必要があります。アプリケーションは、このメソッドの複数の呼出しを正しく同期化する必要があります。
このSSLEngine
がまだ初期ハンドシェークを開始していない場合は、このメソッドによって初期ハンドシェークが自動的に開始されます。
このメソッドは、単一の完全なSSL/TLSネットワーク・パケットを消費しようとしますが、バッファに残っている合計バイト数以上を消費することはありません。各ByteBuffer
の位置は、消費または生成されたデータの量を反映するように更新されます。上限/下限値は変わりません。
src
およびdsts ByteBuffer
は、配下にあるそれぞれ別々のメモリーを使用する必要があります。
この呼出しの結果、インバウンドのネットワーク・バッファが変更されることがあります。このため、二次的な目的でネットワーク・データ・パケットが必要な場合は、このメソッドの呼出しの前にデータを複製する必要があります。注: 各SSLEngineには、SSL/TLSメッセージに影響を及ぼす一意のランダムな状態が含まれているため、ネットワーク・データは2番目のSSLEngineでは役に立ちません。
エンジンの終了の詳細は、クラスの説明を参照。
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)
public abstract Runnable getDelegatedTask()
SSLEngine
に委譲されたRunnable
タスクを返します。
SSLEngine
オペレーションに必要なオペレーションの結果がブロックされたり、完了までにかなりの時間がかかることがあります。このメソッドは、未処理のRunnable
オペレーション(タスク)を取得するために使用されます。各タスクには、run
オペレーションを実行するスレッド(現在のスレッドも可)を割り当てる必要があります。run
メソッドが終了したあと、不要になったRunnable
オブジェクトは廃棄可能です。
委譲されたタスクは、AccessControlContext
内で、このオブジェクトが作成されたときに実行されます。
このメソッドの呼出しは、未処理のタスクをそれぞれ1回だけ返します。
委譲された複数のタスクを並列実行することもできます。
Runnable
タスク。使用できるものがない場合はnull。public abstract void closeInbound() throws SSLException
SSLEngine
にこれ以上の着信ネットワーク・データが送信されないことを示す信号。
アプリケーションがcloseOutbound()
を呼び出して終了処理を開始したとき、ピアの対応する終了メッセージを待つ必要がない場合があります。(終了の警告の待機に関する詳細は、TLS仕様のセクション7.2.1(RFC 2246)を参照)。この場合、このメソッドの呼出しは不要です。
これに対して、アプリケーションが終了処理を開始しなかった場合や、上記の状況に当てはまらない場合は、SSL/TLSデータ・ストリームの終了部分が着信するたびにこのメソッドを呼び出す必要があります。これにより、着信側の終了が保証され、ピアがSSL/TLS終了手続きを適切に実行したことを確認し、値の切詰めによる攻撃の可能性を検出することができます。
このメソッドは、べき等です。着信側がすでに終了している場合は、何も行いません。
残りのハンドシェーク・データをフラッシュするには、wrap()
を呼び出すようにしてください。
SSLException
- このエンジンがピアから適切なSSL/TLS終了通知メッセージを受け取っていない場合。isInboundDone()
, isOutboundDone()
public abstract boolean isInboundDone()
unwrap(ByteBuffer, ByteBuffer)
がこれ以上の着信データ・メッセージを受け入れるかどうかを返します。SSLEngine
がこれ以上ネットワーク・データを使用しない場合(言い換えれば、これ以上アプリケーション・データを生成しない場合)はtrue。closeInbound()
public abstract void closeOutbound()
SSLEngine
でこれ以上の送信アプリケーション・データが送信されないことを示す信号。
このメソッドは、べき等です。送信側がすでに終了している場合は、何も行いません。
残りのハンドシェーク・データをフラッシュするには、wrap(ByteBuffer, ByteBuffer)
を呼び出すようにしてください。
isOutboundDone()
public abstract boolean isOutboundDone()
wrap(ByteBuffer, ByteBuffer)
がこれ以上の送信データ・メッセージを生成するかどうかを返します。
終了段階で、SSLEngine
は、ピアに送信するハンドシェーク終了データを生成します。このデータを生成するには、wrap()
を呼び出す必要があります。このメソッドの戻り値がtrueの場合、これ以上アウトバウンド・データは生成されません。
SSLEngine
がこれ以上ネットワーク・データを生成しない場合はtruecloseOutbound()
, closeInbound()
public abstract String[] getSupportedCipherSuites()
getEnabledCipherSuites()
, setEnabledCipherSuites(String [])
public abstract String[] getEnabledCipherSuites()
暗号化方式群は、たとえ有効でも使用されないことがあります。たとえば、ピアが暗号化方式群をサポートしない場合、この暗号化方式群に必要な証明書や非公開鍵を使用することができない場合、または、匿名の暗号化方式群が利用可能であっても認証が要求される場合などです。
getSupportedCipherSuites()
, setEnabledCipherSuites(String [])
public abstract void setEnabledCipherSuites(String[] suites)
suites
パラメータ内の各暗号化方式群はgetSupportedCipherSuites()でリストされている必要があります。そうでない場合、このメソッドは失敗します。このメソッドの呼出しが成功したあと、suites
パラメータに示されている暗号化方式群のみが使用可能になります。
なぜ特定の暗号化方式群をエンジンで使用することができないかについては、getEnabledCipherSuites()
を参照してください。
suites
- 有効にするすべての暗号化方式群の名前IllegalArgumentException
- パラメータで指定された暗号化方式群の1つ以上がサポートされていないか、またはパラメータがnullである場合。getSupportedCipherSuites()
, getEnabledCipherSuites()
public abstract String[] getSupportedProtocols()
SSLEngine
で使用可能にできるプロトコルの名前を返します。public abstract String[] getEnabledProtocols()
SSLEngine
で現在使用可能になっているプロトコル・バージョンの名前を返します。setEnabledProtocols(String [])
public abstract void setEnabledProtocols(String[] protocols)
プロトコルは、getSupportedProtocols()により、サポート対象としてリストされていなければいけません。このメソッドの呼出しが成功したあと、protocols
パラメータに示されているプロトコルのみが使用可能になります。
protocols
- 有効にするすべてのプロトコルの名前。IllegalArgumentException
- パラメータで指定されたプロトコルの1つ以上がサポートされていないか、またはprotocolsパラメータがnullである場合。getEnabledProtocols()
public abstract SSLSession getSession()
SSLEngine
で使用されているSSLSession
を返します。
SSLセッションは有効期間が長く、ユーザーによってはログイン・セッション全体に対応することもあります。セッションには、セッション内のすべての接続で使用される暗号化方式群と、セッションのクライアントとサーバーの識別情報が指定されています。
このメソッドは、SSLSocket.getSession()
とは異なり、ハンドシェークが完了するまでブロックされません。
初期ハンドシェークが完了すると、無効な暗号化方式群SSL_NULL_WITH_NULL_NULLを報告するセッション・オブジェクトを返します。
SSLEngine
のSSLSession
SSLSession
public SSLSession getHandshakeSession()
SSLSession
を返します。
TLSプロトコルでは、このクラスのインスタンスを使用しているとき、ただしSSLSession
が完全に初期化され、getSession
によって使用可能になる前に必要なパラメータのネゴシエーションを行う可能性があります。たとえば、有効な署名アルゴリズムのリストによって、TrustManagerの決定中に使用できる証明書の種類が制限される可能性があります。または、ネットワーク環境をより適切にサポートするために、最大TLSフラグメント・パケット・サイズが変更される場合があります。
このメソッドでは、構築されているSSLSession
に早期にアクセスできます。ハンドシェークの進捗状況によっては、一部のデータがまだ使用できない可能性があります。たとえば、リモート・サーバーが証明書チェーンを送信しようとしているが、そのチェーンがまだ処理されていない場合、SSLSession
のgetPeerCertificates
メソッドはSSLPeerUnverifiedExceptionをスローします。そのチェーンの処理が完了すると、getPeerCertificates
は適切な値を返します。
SSLSession
を返します。UnsupportedOperationException
- ベースとなるプロバイダがこの操作を実装していない場合。SSLSocket
, SSLSession
, ExtendedSSLSession
, X509ExtendedKeyManager
, X509ExtendedTrustManager
public abstract void beginHandshake() throws SSLException
このメソッドは、初期ハンドシェーク時には必要ありません。ハンドシェークがまだ開始されていない場合は、wrap()
メソッドとunwrap()
メソッドによって暗黙的にこのメソッドが呼び出されるからです。
ピアも、適切なセッション再ネゴシエーションのハンドシェーク・メッセージを送信することにより、このSSLEngine
とのセッションの再ネゴシエーションを要求することがあります。
このメソッドは、SSLSocket#startHandshake()
メソッドとは異なり、ハンドシェークが完了するまでブロックされません。
強制的にSSL/TLSセッションの再ネゴシエーションを行う場合は、現在のセッションを無効にしてからこのメソッドを呼び出す必要があります。
既存のエンジン上で複数のハンドシェークをサポートせず、SSLException
をスローするプロトコルもあります。
SSLException
- SSLEngine
に新しくハンドシェークを開始するように通知しているとき、問題が発生した場合。エンジンの終了の詳細は、クラスの説明を参照。IllegalStateException
- クライアント/サーバー・モードがまだ設定されていない場合。SSLSession.invalidate()
public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus()
SSLEngine
の現在のハンドシェーク状態を返します。SSLEngineResult.HandshakeStatus
。public abstract void setUseClientMode(boolean mode)
このメソッドは、すべてのハンドシェークの前に呼び出す必要があります。いったんハンドシェークが開始されると、このエンジンの寿命が尽きるまで、現在のモードをリセットすることはできません。
通常、サーバーは自身を認証しますが、クライアントは必ずしもそうとはかぎりません。
mode
- ハンドシェークをクライアント・モードで開始する場合はtrueIllegalArgumentException
- 最初のハンドシェークが開始されてからモードを変更しようとした場合。getUseClientMode()
public abstract boolean getUseClientMode()
setUseClientMode(boolean)
public abstract void setNeedClientAuth(boolean need)
エンジンのクライアント認証設定は、次のいずれかになります。
setWantClientAuth(boolean)
の場合とは異なり、このオプションが設定されていて、かつクライアント認証情報が提供されない場合は、ネゴシエーションが停止し、エンジンは、終了プロシージャを開始します。
このメソッドを呼び出すと、このメソッドまたはsetWantClientAuth(boolean)
によって行われた以前の設定がすべてオーバーライドされます。
need
- クライアント認証が必要な場合はtrueに、クライアント認証が不要な場合はfalseに設定される。getNeedClientAuth()
, setWantClientAuth(boolean)
, getWantClientAuth()
, setUseClientMode(boolean)
public abstract boolean getNeedClientAuth()
setNeedClientAuth(boolean)
, setWantClientAuth(boolean)
, getWantClientAuth()
, setUseClientMode(boolean)
public abstract void setWantClientAuth(boolean want)
エンジンのクライアント認証設定は、次のいずれかになります。
setNeedClientAuth(boolean)
とは異なり、このオプションが設定されていて、かつクライアントが自身に関する認証情報を提供しないことを選択した場合でも、ネゴシエーションは続行されます。
このメソッドを呼び出すと、このメソッドまたはsetNeedClientAuth(boolean)
によって行われた以前の設定がすべてオーバーライドされます。
want
- クライアント認証が要求されている場合はtrueに、クライアント認証が不要な場合はfalseに設定される。getWantClientAuth()
, setNeedClientAuth(boolean)
, getNeedClientAuth()
, setUseClientMode(boolean)
public abstract boolean getWantClientAuth()
setNeedClientAuth(boolean)
, getNeedClientAuth()
, setWantClientAuth(boolean)
, setUseClientMode(boolean)
public abstract void setEnableSessionCreation(boolean flag)
flag
- セッションを作成できる場合はtrue (デフォルト)。既存のセッションを再開する場合はfalsegetEnableSessionCreation()
public abstract boolean getEnableSessionCreation()
setEnableSessionCreation(boolean)
public SSLParameters getSSLParameters()
public void setSSLParameters(SSLParameters params)
これは次のことを意味します。
params.getCipherSuites()
がnull以外の場合は、その値を使用してsetEnabledCipherSuites()
が呼び出される。params.getProtocols()
がnull以外の場合は、その値を使用してsetEnabledProtocols()
が呼び出される。params.getNeedClientAuth()
またはparams.getWantClientAuth()
がtrue
を返した場合は、それぞれsetNeedClientAuth(true)
とsetWantClientAuth(true)
が呼び出される。それ以外の場合はsetWantClientAuth(false)
が呼び出される。params.getServerNames()
がnull以外の場合、エンジンはサーバー名をその値で構成する。params.getSNIMatchers()
がnull以外の場合、エンジンはSNIマッチャをその値で構成する。params
- パラメータIllegalArgumentException
- setEnabledCipherSuites()またはsetEnabledProtocols()の呼出しが失敗した場合 バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright© 1993, 2014, Oracle and/or its affiliates. All rights reserved.