モジュール java.base
パッケージ javax.net.ssl

クラスSSLParameters


  • public class SSLParameters
extends Object
    SSL/TLS/DTLS接続のパラメータをカプセル化します。 パラメータは、SSL/TLS/DTLSハンドシェークで受け入れられる暗号スイートのリスト、許可されるプロトコルのリスト、SSL/TLS/DTLSハンドシェーク中のエンドポイント識別アルゴリズム、サーバー名の表示(SNI)、最大ネットワーク・パケット・サイズ、アルゴリズム制約、およびSSL/TLS/DTLSサーバー・クライアントの認証などをリクエストする必要があります。

    SSLParametersは、このクラスのコンストラクタを使用して作成することができます。 オブジェクトは、SSLSocket、SSLServerSocket、およびSSLEngineのgetSSLParameters()メソッド、またはSSLContextのgetDefaultSSLParameters()メソッドとgetSupportedSSLParameters()メソッドを使用して取得することもできます。

    SSLParametersは、SSLSocket.setSSLParameters()、SSLServerSocket.setSSLParameters()、およびSSLEngine.setSSLParameters()メソッドを使用して接続に適用できます。

    次に例を示します。 

         SSLParameters p = sslSocket.getSSLParameters();
     p.setProtocols(new String[] { "TLSv1.2" });
     p.setCipherSuites(
         new String[] { "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256", ... });
     p.setApplicationProtocols(new String[] {"h2", "http/1.1"});
     sslSocket.setSSLParameters(p);
    導入されたバージョン:
    1.6
    関連項目:
    SSLSocket, SSLEngine, SSLContext

    • コンストラクタの詳細

      • SSLParameters

        public SSLParameters​()
        SSLParametersを構築します。

        cipherSuites、プロトコル、暗号アルゴリズムの制約、エンドポイント識別アルゴリズム、サーバー名、サーバー名マッチャの値はnullに設定されています。useCipherSuitesOrder、wantClientAuthおよびneedClientAuthはfalseに設定されます。enableRetransmissionsはtrueに設定されます。最大ネットワーク・パケット・サイズは0に設定されます。

      • SSLParameters

        public SSLParameters​(String[] cipherSuites)
        指定された暗号化方式群の配列からSSLParametersを構築します。

        このコンストラクタの呼出しは、引数なしのコンストラクタに続いてsetCipherSuites(cipherSuites);を呼び出すことと同じです。 暗号スイート名の標準リストは、Java暗号化アーキテクチャの標準アルゴリズム名のドキュメントの「JSSE暗号スイート名」セクションにあります。 プロバイダは、このリストにない暗号スイート名をサポートすることがあります。

        パラメータ:
        cipherSuites - 暗号化方式群の配列(nullも可)

      • SSLParameters

        public SSLParameters​(String[] cipherSuites,
                     String[] protocols)
        指定された暗号化方式群とプロトコルの配列からSSLParametersを構築します。

        このコンストラクタの呼出しは、引数なしのコンストラクタに続いてsetCipherSuites(cipherSuites); setProtocols(protocols);を呼び出すことと同じです。 暗号スイート名の標準リストは、Java暗号化アーキテクチャの標準アルゴリズム名のドキュメントの「JSSE暗号スイート名」セクションにあります。 プロバイダは、このリストにない暗号スイート名をサポートすることがあります。

        パラメータ:
        cipherSuites - 暗号化方式群の配列(nullも可)
        protocols - プロトコルの配列(nullも可)

    • メソッドの詳細

      • getCipherSuites

        public String[] getCipherSuites​()
        暗号化方式群の配列のコピーを返します。設定されていない場合はnullを返します。

        返される配列には、Java Cryptography Architecture標準アルゴリズム名ドキュメントの「JSSE暗号スイート名」セクションの標準暗号スイート名のリストからの暗号スイートが含まれ、プロバイダがサポートする他の暗号スイートも含まれます。

        戻り値:
        暗号化方式群の配列のコピー。設定されていない場合はnull。

      • setCipherSuites

        public void setCipherSuites​(String[] cipherSuites)
        暗号化方式群の配列を設定します。
        パラメータ:
        cipherSuites - 暗号化方式群の配列(nullも可) 暗号スイート名の標準リストは、Java暗号化アーキテクチャの標準アルゴリズム名のドキュメントの「JSSE暗号スイート名」セクションにあります。 プロバイダは、このリストにない暗号スイート名をサポートしているか、特定の暗号スイートの推奨名を使用していない可能性があります。

      • getProtocols

        public String[] getProtocols​()
        プロトコルの配列のコピーを返します。設定されていない場合はnullを返します。
        戻り値:
        プロトコルの配列のコピー。設定されていない場合はnull。

      • setProtocols

        public void setProtocols​(String[] protocols)
        プロトコルの配列を設定します。
        パラメータ:
        protocols - プロトコルの配列(nullも可)

      • getWantClientAuth

        public boolean getWantClientAuth​()
        クライアント認証を要求するかどうかを返します。
        戻り値:
        クライアント認証を要求するかどうか。

      • setWantClientAuth

        public void setWantClientAuth​(boolean wantClientAuth)
        クライアント認証を要求するかどうかを設定します。 このメソッドを呼び出すと、needClientAuthフラグがクリアされます。
        パラメータ:
        wantClientAuth - クライアント認証が要求されるかどうか

      • getNeedClientAuth

        public boolean getNeedClientAuth​()
        クライアント認証を必須とするかどうかを返します。
        戻り値:
        クライアント認証を必須とするかどうか。

      • setNeedClientAuth

        public void setNeedClientAuth​(boolean needClientAuth)
        クライアント認証を必須とするかどうかを設定します。 このメソッドを呼び出すと、wantClientAuthフラグがクリアされます。
        パラメータ:
        needClientAuth - クライアント認証が必要かどうか

      • getAlgorithmConstraints

        public AlgorithmConstraints getAlgorithmConstraints​()
        暗号化アルゴリズムの制約を返します。
        戻り値:
        暗号化アルゴリズムの制約。制約が設定されていない場合はnull
        導入されたバージョン:
        1.7
        関連項目:
        setAlgorithmConstraints(AlgorithmConstraints)

      • setAlgorithmConstraints

        public void setAlgorithmConstraints​(AlgorithmConstraints constraints)
        実行環境によって構成された任意の制約に加えて使用される、暗号化アルゴリズムの制約を設定します。

        constraintsパラメータがnullでない場合、SSL/TLS/DTLSハンドシェイクで使用されるすべての暗号化アルゴリズム、キーおよびアルゴリズム・パラメータは、制約によって許可されなければなりません。

        パラメータ:
        constraints - アルゴリズムの制約(またはnull)
        導入されたバージョン:
        1.7

      • getEndpointIdentificationAlgorithm

        public String getEndpointIdentificationAlgorithm​()
        エンド・ポイント識別アルゴリズムを取得します。
        戻り値:
        エンド・ポイント識別アルゴリズム。設定されていない場合はnull。
        導入されたバージョン:
        1.7
        関連項目:
        X509ExtendedTrustManager, setEndpointIdentificationAlgorithm(String)

      • setEndpointIdentificationAlgorithm

        public void setEndpointIdentificationAlgorithm​(String algorithm)
        エンド・ポイント識別アルゴリズムを設定します。

        algorithmパラメータがnullでも空でもない場合は、SSL/TLS/DTLSハンドシェイク中にエンドポイントの識別/検証手順を処理する必要があります。 これを行うのは、man-in-the-middle攻撃を回避するためです。

        パラメータ:
        algorithm - エンド・ポイント識別アルゴリズムの標準名を表す文字列(またはnull)。 標準的なアルゴリズム名については、「Javaセキュリティ標準アルゴリズム名」のドキュメントを参照してください。
        導入されたバージョン:
        1.7
        関連項目:
        X509ExtendedTrustManager

      • setServerNames

        public final void setServerNames​(List<SNIServerName> serverNames)
        Server Name Indication (SNI)パラメータの必要なSNIServerNameを設定します。

        このメソッドが役立つのは、クライアント・モードで動作するSSLSocketまたはSSLEngineの場合のみです。

        以後の変更から保護するために、serverNamesリストのクローンが作成されます。

        パラメータ:
        serverNames - 必要なSNIServerNameのリスト(またはnull)
        例外:
        NullPointerException - serverNamesにnull要素が含まれている場合
        IllegalArgumentException - serverNamesに同じ名前タイプの名前が複数個含まれている場合
        導入されたバージョン:
        1.8
        関連項目:
        SNIServerName, getServerNames()

      • getServerNames

        public final List<SNIServerName> getServerNames​()
        Server Name Indication (SNI)パラメータのすべてのSNIServerNameを含むList(何も設定されていない場合はnull)を返します。

        このメソッドが役立つのは、クライアント・モードで動作するSSLSocketまたはSSLEngineの場合のみです。

        SSL/TLS/DTLS接続の場合、基になるSSL/TLS/DTLSプロバイダは、特定のサーバー名型のデフォルト値を指定することができます。 クライアント・モードでは、サポート対象のサーバー名タイプでサーバーを特定可能な場合には常に、プロバイダはデフォルトでサーバー名表示を含めるようにすることをお薦めします。

        SSLSocket/SSLEngineの作成時にプロバイダがデフォルトのサーバー名表示を初期化することをお薦めします。 次の例では、サーバー名は、ホスト名「www.example.com」とタイプStandardConstants.SNI_HOST_NAMEで初期化されたSNIHostNameのインスタンスとして表現できます。 

             Socket socket =
         sslSocketFactory.createSocket("www.example.com", 443);
        または 
             SSLEngine engine =
         sslContext.createSSLEngine("www.example.com", 443);
        戻り値:
        null、またはnull以外のSNIServerNameの不変なリスト
        導入されたバージョン:
        1.8
        関連項目:
        List, setServerNames(List)

      • setSNIMatchers

        public final void setSNIMatchers​(Collection<SNIMatcher> matchers)
        Server Name Indication (SNI)パラメータのSNIMatcherを設定します。

        このメソッドが役立つのは、サーバー・モードで動作するSSLSocketまたはSSLEngineの場合のみです。

        以後の変更から保護するために、matchersコレクションのクローンが作成されます。

        パラメータ:
        matchers - SNIMatcherのコレクション(またはnull)
        例外:
        NullPointerException - matchersにnull要素が含まれている場合
        IllegalArgumentException - matchersに同じ名前タイプの名前が複数個含まれている場合
        導入されたバージョン:
        1.8
        関連項目:
        Collection, SNIMatcher, getSNIMatchers()

      • getSNIMatchers

        public final Collection<SNIMatcher> getSNIMatchers​()
        Server Name Indication (SNI)パラメータのすべてのSNIMatcherを含むCollection(何も設定されていない場合はnull)を返します。

        このメソッドが役立つのは、サーバー・モードで動作するSSLSocketまたはSSLEngineの場合のみです。

        相互運用性を高めるため、プロバイダは一般にデフォルトのマッチャを定義しませんが、これは、サーバーがデフォルトでSNI拡張を無視してハンドシェークを続行するようにするためです。

        戻り値:
        null、またはnull以外のSNIMatcherの不変なコレクション
        導入されたバージョン:
        1.8
        関連項目:
        SNIMatcher, setSNIMatchers(Collection)

      • setUseCipherSuitesOrder

        public final void setUseCipherSuitesOrder​(boolean honorOrder)
        暗号化方式群のローカル設定を適用する必要があるかどうかを設定します。
        パラメータ:
        honorOrder - #getCipherSuitesでのローカル暗号スイートのオーダーがSSL/TLS/DTLSハンドシェイク中に尊重されるべきかどうか。
        導入されたバージョン:
        1.8
        関連項目:
        getUseCipherSuitesOrder()

      • getUseCipherSuitesOrder

        public final boolean getUseCipherSuitesOrder​()
        暗号化方式群のローカル設定を適用する必要があるかどうかを返します。
        戻り値:
        #getCipherSuitesのローカル暗号スイートのオーダーがSSL/TLS/DTLSハンドシェイク中に尊重されるべきかどうか。
        導入されたバージョン:
        1.8
        関連項目:
        setUseCipherSuitesOrder(boolean)

      • setEnableRetransmissions

        public void setEnableRetransmissions​(boolean enableRetransmissions)
        DTLSハンドシェイク再送信を有効にするかどうかを設定します。 このメソッドは、DTLSにのみ適用されます。
        パラメータ:
        enableRetransmissions - trueは、DTLSハンドシェイク再送信を有効にする必要があることを示します。falseは、DTLSハンドシェイク再送信を無効にする必要があることを示します
        導入されたバージョン:
        9
        関連項目:
        getEnableRetransmissions()

      • getEnableRetransmissions

        public boolean getEnableRetransmissions​()
        DTLSハンドシェイク再送信を有効にするかどうかを返します。 このメソッドは、DTLSにのみ適用されます。
        戻り値:
        DTLSハンドシェイク再送信を有効にする必要がある場合はtrue
        導入されたバージョン:
        9
        関連項目:
        setEnableRetransmissions(boolean)

      • setMaximumPacketSize

        public void setMaximumPacketSize​(int maximumPacketSize)
        SSL/TLS/DTLSレコードの最大予想ネットワーク・パケット・サイズをバイト単位で設定します。
        APIの注:
        可能であれば、HelloVerifyRequestsなどの小さなハンドシェーク・メッセージがフラグメント化されないように、最大パケット・サイズは256バイト未満にすることはお勧めしません。
        実装上の注意:
        最大パケット・サイズが小さすぎて最小レコードを保持できない場合、実装は可能な限り最小限のレコードを生成しようとする可能性があります。 しかし、これにより、生成されたパケットが最大パケット・サイズより大きくなる可能性があります。
        パラメータ:
        maximumPacketSize - 予想される最大ネットワーク・パケット・サイズ(バイト数)、または基礎となる実装によって自動的に指定される暗黙のサイズを使用する0。
        例外:
        IllegalArgumentException - maximumPacketSizeが負の場合。
        導入されたバージョン:
        9
        関連項目:
        getMaximumPacketSize()

      • getMaximumPacketSize

        public int getMaximumPacketSize​()
        SSL/TLS/DTLSレコードの最大予想ネットワーク・パケット・サイズをバイト単位で返します。
        APIの注:
        暗黙のサイズは、特にDTLSプロトコル実装の場合、固定値ではない可能性があります。
        実装上の注意:
        SSL/TLS/DTLS接続では、明示的に構成されていない場合、予想される最大ネットワーク・パケット・サイズの暗黙値を計算して指定する必要があります。 実装された接続オブジェクトの場合、このメソッドはアプリケーションが実際の暗黙的な実装のサイズを取得できるように、0を返すべきではありません。

        インプリメンテーションは、最大パケット・サイズ構成に準拠しようとする必要があります。 しかし、最大パケット・サイズが小さすぎて最小限のレコードを保持できない場合、実装は可能な限り最小限のレコードを生成しようとする可能性があります。 これにより、生成されたパケットが最大パケット・サイズより大きくなる可能性があります。

        戻り値:
        予想される最大ネットワーク・パケット・サイズ、または基本実装によって自動的に指定される暗黙的なサイズを使用する場合は0。このオブジェクトは接続によって生成されません。
        導入されたバージョン:
        9
        関連項目:
        setMaximumPacketSize(int)

      • getApplicationProtocols

        public String[] getApplicationProtocols​()
        SSL/TLS/DTLSプロトコルでネゴシエートできるアプリケーション層プロトコル名の優先順位付き配列を返します。

        配列は空の(zero-length)になることがあります。この場合、プロトコルの指示は使用されません。

        このメソッドは、呼び出されるたびに新しい配列を返します。

        戻り値:
        アプリケーション・プロトコルStringの非ヌル、場合によっては長さゼロの配列。 配列は、プロトコルの優先順位に基づいて順序付けされ、protocols[0]が最も優先されます。
        導入されたバージョン:
        9
        関連項目:
        setApplicationProtocols(java.lang.String[])

      • setApplicationProtocols

        public void setApplicationProtocols​(String[] protocols)
        SSL/TLS/DTLSプロトコルでネゴシエートできるアプリケーション層プロトコル名の優先順位付き配列を設定します。

        アプリケーション層プロトコルが基盤となるSSL/TLS実装でサポートされている場合、このメソッドは、RFC 7301、Application Layer Protocol Negotiation (ALPN)などのプロトコルでどの値をネゴシエートできるかを構成します。

        この接続の終わりがアプリケーション・プロトコル値を提供することが予想される場合、このメソッドで構成されたすべてのプロトコルがピアに送信されます。

        この接続の終わりがアプリケーション・プロトコル値を選択すると予想される場合、このメソッドで構成されたprotocolsはピアによって送信された値と比較されます。 最初に一致した値がネゴシエートされた値になります。 protocolsのどれもピアによって実際にリクエストされなかった場合は、基礎となるプロトコルが、どのようなアクションをとるかを決定します。 (たとえば、ALPNは"no_application_protocol"アラートを送信し、接続を終了します。)

        実装要件:
        このメソッドは、protocols配列のコピーを作成します。
        パラメータ:
        protocols - protocols[0]が最も優先されるアプリケーション・プロトコルの順序付けられた配列。 配列が空(zero-length)の場合は、プロトコルの指示は使用されません。
        例外:
        IllegalArgumentException - protocolsがnullの場合、または空でない配列の要素がnullまたは空の(zero-length)文字列の場合
        導入されたバージョン:
        9
        関連項目:
        getApplicationProtocols()