javax.net.ssl.SSLEngine
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
public abstract class SSLEngine
Secure Sockets Layer (SSL) や IETF RFC 2246 の Transport Layer Security (TLS) プロトコルを使用し、転送に依存することなくセキュア通信を有効にするクラスです。
セキュア通信モードでは、次のセキュリティー保護が実施されます。
使用される暗号化方式群は、「ハンドシェーク」と呼ばれるネゴシエーションプロセスによって確立されます。ハンドシェークでは、セッションの作成または参加が行われます。 作成または参加したセッションは、無効になるまでさまざまな接続を保護します。ハンドシェークが完了すると、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 つの段階をたどります。
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 を返します。 |
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 |
| コンストラクタの詳細 |
|---|
protected SSLEngine()
SSLEngine のコンストラクタです。
SSLContext.createSSLEngine(),
SSLSessionContext
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 - 送信アプリケーションデータを格納する ByteBufferdst - 送信ネットワークデータを格納する ByteBuffer
SSLEngineResult
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。
エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - ReadOnlyBufferException dst バッファーが読み取り専用の場合
IllegalArgumentException - IllegalArgumentException src または dst が null の場合
IllegalStateException - IllegalStateException クライアント/サーバーモードが未設定の場合wrap(ByteBuffer [], int, int, ByteBuffer)
public SSLEngineResult wrap(ByteBuffer[] srcs,
ByteBuffer dst)
throws SSLException
このメソッド呼び出しの動作は、次の呼び出しの動作とまったく同じです。
engine.wrap(srcs, 0, srcs.length, dst);
srcs - 送信アプリケーションデータを格納する ByteBuffer の配列dst - 送信ネットワークデータを格納する ByteBuffer
SSLEngineResult
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。
エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - ReadOnlyBufferException dst バッファーが読み取り専用の場合
IllegalArgumentException - IllegalArgumentException src と dsts のどちらか一方が null の場合、または srcs に null の要素が含まれる場合
IllegalStateException - 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 - 送信アプリケーションデータを格納する ByteBuffer の配列offset - offset 最初のバイトの取得先となるバッファー配列内のオフセット。
srcs.length 以下のゼロまたは正の数length - length アクセス可能な最大バッファー数。
srcs.length - offset 以下のゼロまたは正の数dst - 送信ネットワークデータを格納する ByteBuffer
SSLEngineResult
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。
エンジンの終了の詳細は、クラスの説明を参照
IndexOutOfBoundsException - IndexOutOfBoundsException offset パラメータと length パラメータの前提条件が満たされていない場合
ReadOnlyBufferException - ReadOnlyBufferException dst バッファーが読み取り専用の場合
IllegalArgumentException - IllegalArgumentException srcs と dst のどちらか一方が null の場合、または指定された srcs サブシーケンスに null の要素が含まれる場合
IllegalStateException - IllegalStateException クライアント/サーバーモードが未設定の場合GatheringByteChannel,
java.nio.channels.GatheringByteChannel#write(
public SSLEngineResult unwrap(ByteBuffer src,
ByteBuffer dst)
throws SSLException
このメソッド呼び出しの動作は、次の呼び出しの動作とまったく同じです。
engine.unwrap(src, new ByteBuffer [] { dst }, 0, 1);
src - 着信ネットワークデータを格納する ByteBufferdst - 着信アプリケーションデータを格納する ByteBuffer
SSLEngineResult
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。
エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - ReadOnlyBufferException dst バッファーが読み取り専用の場合
IllegalArgumentException - IllegalArgumentException src または dst が null の場合
IllegalStateException - IllegalStateException クライアント/サーバーモードが未設定の場合unwrap(ByteBuffer, ByteBuffer [], int, int)
public SSLEngineResult unwrap(ByteBuffer src,
ByteBuffer[] dsts)
throws SSLException
このメソッド呼び出しの動作は、次の呼び出しの動作とまったく同じです。
engine.unwrap(src, dsts, 0, dsts.length);
src - 着信ネットワークデータを格納する ByteBufferdsts - 着信アプリケーションデータを格納する ByteBuffer の配列
SSLEngineResult
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。
エンジンの終了の詳細は、クラスの説明を参照
ReadOnlyBufferException - ReadOnlyBufferException 読み取り専用の dst バッファーが存在する場合
IllegalArgumentException - IllegalArgumentException srcs と dst のどちらか一方が null の場合、または dsts に null の要素が含まれる場合
IllegalStateException - 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 は、配下にあるそれぞれ別々のメモリーを使用する必要があります。
この呼び出しの結果、着信ネットワークバッファーが変更されることがあります。このため、二次的な目的でネットワークデータパケットが必要な場合は、このメソッドの呼び出しの前にデータを複製する必要があります。注:ネットワークデータを 2 番目の SSLEngine で使用することはできません。 各 SSLEngine が、SSL/TLS メッセージに影響を及ぼす一意のランダムな状態を持っているからです。
エンジンの終了の詳細は、クラスの説明を参照
src - 着信ネットワークデータを格納する ByteBufferdsts - 着信アプリケーションデータを格納する ByteBuffer の配列offset - 最初のバイトの転送先となるバッファー配列内のオフセット。dsts.length 以下のゼロまたは正の数length - length アクセス可能な最大バッファー数。
dsts.length - offset 以下のゼロまたは正の数
SSLEngineResult
SSLException - データ処理中に発生し、SSLEngine の異常終了の原因となった問題。
エンジンの終了の詳細は、クラスの説明を参照
IndexOutOfBoundsException - IndexOutOfBoundsException offset パラメータと length パラメータの前提条件が満たされていない場合
ReadOnlyBufferException - ReadOnlyBufferException 読み取り専用の dst バッファーが存在する場合
IllegalArgumentException - IllegalArgumentException src と dsts のどちらか一方が null の場合、または指定された dsts サブシーケンスに null の要素が含まれる場合
IllegalStateException - IllegalStateException クライアント/サーバーモードが未設定の場合ScatteringByteChannel,
java.nio.channels.ScatteringByteChannel#read(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 - SSLException このエンジンがピアから適切な SSL/TLS 終了通知メッセージを受け取っていない場合isInboundDone(),
isOutboundDone()public abstract boolean isInboundDone()
unwrap(ByteBuffer, ByteBuffer) が受け付ける着信データメッセージがまだあるかどうかを返します。
SSLEngine がこれ以上ネットワークデータを使用しない場合 (言い換えれば、これ以上アプリケーションデータを生成しない場合) は truecloseInbound()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 - パラメータに指定された暗号化方式群の一部がサポートされない場合、またはパラメータが 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 - パラメータに指定されたプロトコルの一部がサポートされない場合、またはパラメータが null の場合。getEnabledProtocols()public abstract SSLSession getSession()
SSLEngine で使用中の SSLSession を返します。 SSL セッションは有効期間が長く、ユーザーによってはログインセッション全体に対応することもあります。セッションには、セッション内のすべての接続で使用される暗号化方式群と、セッションのクライアントとサーバーの識別情報が指定されています。
このメソッドは、SSLSocket.getSession() とは異なり、ハンドシェークが完了するまでブロックされません。
初期ハンドシェークが完了すると、無効な暗号化方式群 SSL_NULL_WITH_NULL_NULL を報告するセッションオブジェクトを返します。
SSLEngine の SSLSessionSSLSession
public abstract void beginHandshake()
throws SSLException
このメソッドは、初期ハンドシェーク時には必要ありません。 ハンドシェークがまだ開始されていない場合は、wrap() メソッドと unwrap() メソッドによって暗黙的にこのメソッドが呼び出されるからです。
ピアも、適切なセッション再ネゴシエーションのハンドシェークメッセージを送信することにより、この SSLEngine とのセッションの再ネゴシエーションを要求することがあります。
このメソッドは、SSLSocket#startHandshake() メソッドとは異なり、ハンドシェークが完了するまでブロックされません。
強制的に SSL/TLS セッションの再ネゴシエーションを行う場合は、現在のセッションを無効にしてからこのメソッドを呼び出す必要があります。
既存のエンジン上で複数のハンドシェークをサポートせず、SSLException をスローするプロトコルもあります。
SSLException - SSLException SSLEngine に新しくハンドシェークを開始するように通知しているとき、問題が発生した場合。
エンジンの終了の詳細は、クラスの説明を参照
IllegalStateException - IllegalStateException クライアント/サーバーモードが未設定の場合SSLSession.invalidate()public abstract SSLEngineResult.HandshakeStatus getHandshakeStatus()
SSLEngine の現在のハンドシェーク状態を返します。
SSLEngineResult.HandshakeStatuspublic abstract void setUseClientMode(boolean mode)
このメソッドは、すべてのハンドシェークの前に呼び出す必要があります。いったんハンドシェークが開始されると、このエンジンの寿命が尽きるまで、現在のモードをリセットすることはできません。
通常、サーバーは自身を認証しますが、クライアントは必ずしもそうとは限りません。
mode - mode ハンドシェークをクライアントモードで開始する場合は true
IllegalArgumentException - 最初のハンドシェークが開始されてからモードを変更しようとした場合。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 - パラメータ
IllegalArgumentException - setEnabledCipherSuites() または the setEnabledProtocols() の呼び出しに失敗した場合
|
JavaTM Platform Standard Ed. 6 |
|||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
Copyright 2006 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。