モジュール java.base

パッケージ javax.net.ssl

インタフェースSSLSession

既知のすべての実装クラス:

ExtendedSSLSession

public interface SSLSession

SSLでは、2つのエンティティ間で進行中の関係がセッションと呼ばれます。 各SSL接続には、一度に1つのセッションが含まれますが、そのセッションがエンティティ間の接続に、同時に、または連続して何度も使用されることがあります。 1つの接続で使用されるセッションを別のセッションで置き換えることもできます。 セッションの作成または参加は、SSLハンドシェークのときに行われます。 セッションを無効にするには、セキュリティまたは資源使用状況に関連するポリシーを使用するか、アプリケーションから明示的にinvalidateを呼び出します。 セッション管理ポリシーは通常、パフォーマンスを調整するときに使用します。

SSLセッションには、標準セッション属性以外に、次の読込み専用属性があります。

• ピア識別情報。 セッションは、特定のクライアントと特定のサーバー間に生成される。 ピアの識別情報は、セッションのセットアップの一部として設定される場合がある。 通常はX.509証明書チェーンが使用される。
• 暗号化方式群名。 暗号化方式群は、特定のセッションの接続で使用される暗号化保護の種類を示す。
• ピア・ホスト。 セッション内のすべての接続は、同じ2つのホスト間に確立される。 接続先のホストのアドレスを使用できる。

セッションは、明示的に無効にします。 特定の種類のエラーが発生したときは、暗黙的に無効になります。

導入されたバージョン:

1.4

メソッドのサマリー

修飾子と型	メソッド	説明
int	getApplicationBufferSize()	このセッションの使用中に想定される最大アプリケーション・データの現在のサイズを取得します。
String	getCipherSuite()	このセッションのすべての接続に使用されるSSL暗号化方式群の名前を返します。
long	getCreationTime()	このセッションが作成された時刻を、UTC 1970年1月1日深夜零時からのミリ秒単位で返します。
byte[]	getId()	このセッションに割り当てられた識別子を返します。
long	getLastAccessedTime()	このセッションがセッション・レベルのインフラストラクチャによって最後にアクセスされた時刻を、UTC 1970年1月1日深夜零時からのミリ秒単位で返します。
Certificate[]	getLocalCertificates()	ハンドシェーク中にピアに送信された証明書を返します。
Principal	getLocalPrincipal()	ハンドシェーク中にピアに送信された主体を返します。
int	getPacketBufferSize()	このセッションの使用時に予想される最大のSSL/TLS/DTLSパケットの現在のサイズを取得します。
default X509Certificate[]	getPeerCertificateChain()	削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。 java.security.cert.Certificateの配列を返すgetPeerCertificates()メソッドを代わりに使用する必要があります。
Certificate[]	getPeerCertificates()	セッションを定義するときに設定された、ピアの識別情報を返します。
String	getPeerHost()	このセッションのピア・ホスト名を返します。
int	getPeerPort()	このセッションのピアのポート番号を返します。
Principal	getPeerPrincipal()	セッションを定義するときに設定された、ピアの識別情報を返します。
String	getProtocol()	このセッションのすべての接続に使用されるプロトコルの標準名を返します。
SSLSessionContext	getSessionContext()	このセッションがバインドされているコンテキストを返します。
Object	getValue(String name)	このセッションのアプリケーション層データ内で、指定された名前にバインドされているオブジェクトを返します。
String[]	getValueNames()	セッションにバインドされているアプリケーション層データ・オブジェクト名の配列を返します。
void	invalidate()	セッションを無効にします。
boolean	isValid()	再開や参加が可能な有効なセッションかどうかを返します。
void	putValue(String name, Object value)	指定されたnameを使用して、指定されたvalueオブジェクトをこのセッションのアプリケーション層データにバインドします。
void	removeValue(String name)	セッションのアプリケーション層データで、指定された名前にバインドされたオブジェクトを削除します。

メソッドの詳細

getId

byte[] getId()

このセッションに割り当てられた識別子を返します。

戻り値:

セッション識別子

getSessionContext

SSLSessionContext getSessionContext()

このセッションがバインドされているコンテキストを返します。

コンテキストは、一部の環境では取得できません。その場合はnullを返します。

コンテキストが取得できる環境でセキュリティ・マネージャがインストールされている場合は、呼び出すときにコンテキストに対するアクセス権が必要になることがあります。その場合、アクセス権がないときは、セキュリティ例外がスローされます。 Java環境では、セキュリティ・マネージャのcheckPermissionメソッドは、SSLPermission("getSSLSessionContext")アクセス権を指定して呼び出されます。

戻り値:

このセッションに使用されているセッション・コンテキスト。コンテキストを取得できない場合はnull。

例外:

SecurityException - 呼出し側スレッドに、SSLセッション・コンテキストを取得するのに必要なアクセス権がない場合。

getCreationTime

long getCreationTime()

このセッションが作成された時刻を、UTC 1970年1月1日深夜零時からのミリ秒単位で返します。

戻り値:

このセッションが作成された時刻

getLastAccessedTime

long getLastAccessedTime()

このセッションがセッション・レベルのインフラストラクチャによって最後にアクセスされた時刻を、UTC 1970年1月1日深夜零時からのミリ秒単位で返します。

アクセスとは、セッション・データを使用して新しい接続が確立されることを指します。 セッション関連の値を取得または設定するなど、アプリケーション・レベルの操作はこのアクセス時間に反映されません。

この情報は、特にセッション管理ポリシーで使用します。 たとえば、長時間使用されていないコンテキストでセッション・マネージャ・スレッドからセッションを解放したり、セッションを経過時間でソートしてタスクを最適化したりします。

戻り値:

このセッションが最後にアクセスされた時間

invalidate

void invalidate()

セッションを無効にします。

後続の接続では、このセッションを使用できません。 ただし、このセッションを使用している既存の接続は、接続が閉じるまで引き続き使用できます。

関連項目:

• isValid()

isValid

boolean isValid()

再開や参加が可能な有効なセッションかどうかを返します。

戻り値:

このセッションへの参加が可能な場合はtrue。

導入されたバージョン:

1.5

関連項目:

• invalidate()

putValue

void putValue(String name, Object value)

指定されたnameを使用して、指定されたvalueオブジェクトをこのセッションのアプリケーション層データにバインドします。

同じnameを使用している既存のバインディングは置き換えられます。 新しい(または既存の) valueがSSLSessionBindingListenerインタフェースを実装している場合、valueによって表されるオブジェクトには適切な方法で通知されます。

セキュリティ上の理由から、同じ名前の値は複数のアクセス制御コンテキストをまたがって表示できません。

パラメータ:

name - データ・オブジェクトがバインドされる名前。 nullは不可。

value - バインドされるデータ・オブジェクト。 nullは不可。

例外:

IllegalArgumentException - どちらかの引数がnullである場合。

getValue

Object getValue(String name)

このセッションのアプリケーション層データ内で、指定された名前にバインドされているオブジェクトを返します。 バインディングが存在しない場合はnullを返します。

セキュリティ上の理由から、同じ名前の値は複数のアクセス制御コンテキストをまたがって表示できません。

パラメータ:

name - 検索するバインディングの名前。

戻り値:

指定された名前にバインドされた値。バインディングが存在しない場合はnull。

例外:

IllegalArgumentException - 引数がnullである場合。

removeValue

void removeValue(String name)

セッションのアプリケーション層データで、指定された名前にバインドされたオブジェクトを削除します。 指定された名前にバインドされたオブジェクトが存在しない場合は、適用されません。 バインドされた既存のオブジェクトがSSLSessionBindingListenerインタフェースを実装している場合は、そのインタフェースに適切な方法で通知されます。

セキュリティ上の理由から、同じ名前の値は複数のアクセス制御コンテキストをまたがって表示できません。

パラメータ:

name - 削除するオブジェクトの名前。複数のアクセス制御コンテキストをまたがって表示できる

例外:

IllegalArgumentException - 引数がnullである場合。

getValueNames

String[] getValueNames()

セッションにバインドされているアプリケーション層データ・オブジェクト名の配列を返します。

セキュリティ上の理由から、同じ名前の値は複数のアクセス制御コンテキストをまたがって表示できません。

戻り値:

このセッションにバインドされているオブジェクト名の、null (空の場合もある)でない配列。

getPeerCertificates

Certificate[] getPeerCertificates() throws SSLPeerUnverifiedException

セッションを定義するときに設定された、ピアの識別情報を返します。

ノート: このメソッドを使用できるのは、証明書ベースの暗号化方式群を使用している場合だけです。Kerberosなどの証明書ベースでない暗号化方式群にこのメソッドを使用すると、SSLPeerUnverifiedExceptionがスローされます。

ノート: 戻り値は有効な証明書チェーンでない可能性があり、信頼のディシジョンに頼ってはいけません。

戻り値:

ピア証明書の配列。ピア自身の証明書、証明書発行局の順序に並んでいる。

例外:

SSLPeerUnverifiedException - ピアの識別情報が確認されていない場合

関連項目:

• getPeerPrincipal()

getLocalCertificates

Certificate[] getLocalCertificates()

ハンドシェーク中にピアに送信された証明書を返します。

ノート: このメソッドが役立つのは、証明書ベースの暗号化方式群を使用している場合だけです。

ハンドシェークを行うときに複数の証明書を使用できる場合は、最適な証明書チェーンが選択され、ピアに送信されます。 呼出し側は、このメソッドを使用して、実際に使用された証明書チェーンを把握することができます。

戻り値:

証明書の配列。ローカル証明書、証明書発行局の証明書の順序に並んでいる。 証明書が送信されなかった場合は、nullが返される。

関連項目:

• getLocalPrincipal()

getPeerCertificateChain

@Deprecated(since="9", forRemoval=true) default X509Certificate[] getPeerCertificateChain() throws SSLPeerUnverifiedException

削除予定のため非推奨: このAPI要素は、将来のバージョンで削除される可能性があります。

java.security.cert.Certificateの配列を返すgetPeerCertificates()メソッドを代わりに使用する必要があります。

セッションを定義するときに識別された、ピアの識別情報を返します。

ノート: このメソッドを使用できるのは、証明書ベースの暗号化方式群を使用している場合だけです。Kerberosなどの証明書ベースでない暗号化方式群にこのメソッドを使用すると、SSLPeerUnverifiedExceptionがスローされます。

ノート: 戻り値は有効な証明書チェーンでない可能性があり、信頼のディシジョンに頼ってはいけません。

ノート: このメソッドは、以前のリリースとの互換性を確保するために組み込まれています。 新しいアプリケーションでは、代わりにgetPeerCertificates()を使用するようにしてください。

実装要件:

このデフォルト実装では、UnsupportedOperationExceptionがスローされます。

戻り値:

ピアのX.509証明書の配列。ピア自身の証明書、証明書発行局の証明書の順序で並んでいる。 証明書の形式は、元のJSSE証明書X509Certificate形式である。

例外:

SSLPeerUnverifiedException - ピアの識別情報が確認されていない場合

UnsupportedOperationException - ベースとなるプロバイダがこの操作を実装していない場合。

関連項目:

• getPeerPrincipal()

getPeerPrincipal

Principal getPeerPrincipal() throws SSLPeerUnverifiedException

セッションを定義するときに設定された、ピアの識別情報を返します。

戻り値:

ピアの主体。 X509ベースの暗号化方式群の場合はエンド・エンティティ証明書のX500Principalを返し、Kerberos暗号化方式群の場合はKerberosPrincipalを返す。

例外:

SSLPeerUnverifiedException - ピアの識別情報が確認されていない場合

導入されたバージョン:

1.5

関連項目:

• getPeerCertificates()
• getLocalPrincipal()

getLocalPrincipal

Principal getLocalPrincipal()

ハンドシェーク中にピアに送信された主体を返します。

戻り値:

ピアに送信された主体。 X509ベースの暗号化方式群の場合はエンド・エンティティ証明書のX500Principalを返し、Kerberos暗号化方式群の場合はKerberosPrincipalを返す。 主体が送信されなかった場合はnullが返される。

導入されたバージョン:

1.5

関連項目:

• getLocalCertificates()
• getPeerPrincipal()

getCipherSuite

String getCipherSuite()

このセッションのすべての接続に使用されるSSL暗号化方式群の名前を返します。

これは、使用される暗号の種類や認証方法の設定など、接続時に送信されるデータに適用される保護のレベルを決定します。

戻り値:

セッションの暗号化方式群の名前

getProtocol

String getProtocol()

このセッションのすべての接続に使用されるプロトコルの標準名を返します。

このプロトコルには、接続で使用されるプロトコルを定義します。

戻り値:

このセッションのすべての接続に使用されるプロトコルの標準名。

getPeerHost

String getPeerHost()

このセッションのピア・ホスト名を返します。

サーバーの場合は、クライアントのホスト名になります。クライアントの場合は、サーバーのホスト名になります。 この名前は、完全修飾ホスト名や実際のホスト名ではなく、ピアのネットワーク・アドレスの文字列エンコーディングを示します。 完全修飾ホスト名や実際のホスト名が必要な場合は、このメソッドから返された値に基づいてネーム・サービスを使用すれば解決できます。

この値は認証されていないため、実際に使用することはできません。 主に、SSLSessionのキャッシュ方法に関するヒントとして使用されます。

戻り値:

ピア・ホストのホスト名。情報がない場合はnull。

getPeerPort

int getPeerPort()

このセッションのピアのポート番号を返します。

サーバーの場合は、クライアントのポート番号になります。クライアントの場合は、サーバーのポート番号になります。

この値は認証されていないため、実際に使用することはできません。 主に、SSLSessionのキャッシュ方法に関するヒントとして使用されます。

戻り値:

ピア・ホストのポート番号。情報がない場合は -1。

導入されたバージョン:

1.5

getPacketBufferSize

int getPacketBufferSize()

このセッションの使用時に予想される最大のSSL/TLS/DTLSパケットの現在のサイズを取得します。

このセッションを使用するSSLEngineは、このメソッドによって戻される値まで、および戻される値を含む任意のサイズのSSL/TLS/DTLSパケットを生成できます。 wrapやunwrapの実行時に容量不足の問題を防ぐために、SSLEngineのネットワーク・バッファのサイズはすべてこの値以上にしてください。

戻り値:

現在想定されるネットワーク・パケットの最大サイズ

導入されたバージョン:

1.5

関連項目:

• SSLEngine.wrap(ByteBuffer, ByteBuffer)
• SSLEngine.unwrap(ByteBuffer, ByteBuffer)

getApplicationBufferSize

int getApplicationBufferSize()

このセッションの使用中に想定される最大アプリケーション・データの現在のサイズを取得します。

SSLEngineのアプリケーション・データ・バッファには、着信するアプリケーション・データ・パケットに含まれているアプリケーション・データを保持するために十分なサイズが必要です。 通常、送信アプリケーション・データ・バッファは、どのようなサイズでもかまいません。

戻り値:

現在想定されるアプリケーション・パケットの最大サイズ

導入されたバージョン:

1.5

関連項目:

• SSLEngine.wrap(ByteBuffer, ByteBuffer)
• SSLEngine.unwrap(ByteBuffer, ByteBuffer)