Класс SSLParameters

java.lang.Object

javax.net.ssl.SSLParameters

public class SSLParameters extends Object

Запрещает параметры для подключения SSL/TLS/DTLS. Параметры — это список наборов шифрования, которые должны быть приняты при установлении соединения SSL/TLS/DTLS, список разрешённых протоколов, алгоритм идентификации конечной точки во время установления соединения SSL/TLS/DTLS, указание имени сервера (SNI), максимальный размер сетевого пакета, ограничения алгоритмов и то, должны ли серверы SSL/TLS/DTLS запрашивать или требовать аутентификацию клиента и т. д.

SSLParameters можно создать с помощью конструкторов в этом классе. Объекты также можно получить с помощью методов getSSLParameters() в SSLSocket, SSLServerSocket и SSLEngine или методов getDefaultSSLParameters() и getSupportedSSLParameters() в SSLContext.

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);

Since:

1.6

См. также:

Краткое описание конструкторов

Конструктор	Описание
`SSLParameters()`	Создаёт SSLParameters.
`SSLParameters(String[] cipherSuites)`	Создаёт SSLParameters из указанного массива наборов шифрования.
`SSLParameters(String[] cipherSuites, String[] protocols)`	Создаёт SSLParameters из указанного массива наборов шифрования и протоколов.

Краткое описание методов

Модификатор и тип	Метод	Описание
`AlgorithmConstraints`	`getAlgorithmConstraints()`	Возвращает ограничения криптографических алгоритмов.
`String[]`	`getApplicationProtocols()`	Возвращает упорядоченный массив имён протоколов прикладного уровня, которые могут быть согласованы с протоколами SSL/TLS/DTLS.
`String[]`	`getCipherSuites()`	Возвращает копию массива наборов шифрования или null, если они не заданы.
`boolean`	`getEnableRetransmissions()`	Возвращает, должны ли быть включены повторные передачи рукопожатия DTLS.
`String`	`getEndpointIdentificationAlgorithm()`	Возвращает алгоритм идентификации конечной точки.
`int`	`getMaximumPacketSize()`	Возвращает максимальный ожидаемый размер сетевого пакета в байтах для записей SSL/TLS/DTLS.
`boolean`	`getNeedClientAuth()`	Возвращает, требуется ли аутентификация клиента.
`String[]`	`getProtocols()`	Возвращает копию массива протоколов или null, если они не заданы.
`final List<SNIServerName>`	`getServerNames()`	Возвращает `List`, содержащий все `SNIServerName` параметров указания имени сервера (SNI), или null, если они не заданы.
`final Collection<SNIMatcher>`	`getSNIMatchers()`	Возвращает `Collection`, содержащий все `SNIMatcher` параметров указания имени сервера (SNI), или null, если они не заданы.
`final boolean`	`getUseCipherSuitesOrder()`	Возвращает, следует ли учитывать предпочтения локальных наборов шифрования.
`boolean`	`getWantClientAuth()`	Возвращает, должна ли быть запрошена аутентификация клиента.
`void`	`setAlgorithmConstraints(AlgorithmConstraints constraints)`	Устанавливает ограничения криптографических алгоритмов, которые будут использоваться дополнительно к любым, настроенным средой выполнения.
`void`	`setApplicationProtocols(String[] protocols)`	Устанавливает упорядоченный массив имён протоколов прикладного уровня, которые могут быть согласованы с протоколами SSL/TLS/DTLS.
`void`	`setCipherSuites(String[] cipherSuites)`	Устанавливает массив наборов шифрования.
`void`	`setEnableRetransmissions(boolean enableRetransmissions)`	Устанавливает, должны ли быть включены повторные передачи рукопожатия DTLS.
`void`	`setEndpointIdentificationAlgorithm(String algorithm)`	Устанавливает алгоритм идентификации конечной точки.
`void`	`setMaximumPacketSize(int maximumPacketSize)`	Устанавливает максимальный ожидаемый размер сетевого пакета в байтах для записей SSL/TLS/DTLS.
`void`	`setNeedClientAuth(boolean needClientAuth)`	Устанавливает, требуется ли аутентификация клиента.
`void`	`setProtocols(String[] protocols)`	Устанавливает массив протоколов.
`final void`	`setServerNames(List<SNIServerName> serverNames)`	Устанавливает желаемые `SNIServerName` параметров указания имени сервера (SNI).
`final void`	`setSNIMatchers(Collection<SNIMatcher> matchers)`	Устанавливает `SNIMatcher` параметров указания имени сервера (SNI).
`final void`	`setUseCipherSuitesOrder(boolean honorOrder)`	Устанавливает, следует ли учитывать предпочтения локальных наборов шифрования.
`void`	`setWantClientAuth(boolean wantClientAuth)`	Устанавливает, должна ли быть запрошена аутентификация клиента.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Подробное описание конструкторов

SSLParameters

public SSLParameters()

Создаёт SSLParameters.

Значения cipherSuites, protocols, ограничений криптографических алгоритмов, алгоритма идентификации конечной точки, имён сервера и соответствий имён сервера установлены в null; useCipherSuitesOrder, wantClientAuth и needClientAuth установлены в false; enableRetransmissions установлен в true; максимальный размер сетевого пакета установлен в 0.

SSLParameters

public SSLParameters(String[] cipherSuites)

Создаёт SSLParameters из указанного массива наборов шифров.

Вызов этого конструктора эквивалентен вызову конструктора без аргументов, за которым следует setCipherSuites(cipherSuites);. Обратите внимание, что стандартный список имён наборов шифров можно найти в разделе Имена наборов шифров JSSE документации по стандартным именам алгоритмов Java Cryptography Architecture. Поставщики могут поддерживать имена наборов шифров, отсутствующие в этом списке.

Параметры:: cipherSuites - массив наборов шифров (или null)

SSLParameters

public SSLParameters(String[] cipherSuites, String[] protocols)

Создаёт SSLParameters из указанного массива наборов шифров и протоколов.

Вызов этого конструктора эквивалентен вызову конструктора без аргументов, за которым следует setCipherSuites(cipherSuites); setProtocols(protocols);. Обратите внимание, что стандартный список имён наборов шифров можно найти в разделе Имена наборов шифров JSSE документации по стандартным именам алгоритмов Java Cryptography Architecture. Поставщики могут поддерживать имена наборов шифров, отсутствующие в этом списке.

Параметры:: cipherSuites - массив наборов шифров (или null); protocols - массив протоколов (или null)

Подробное описание методов

getCipherSuites

public String[] getCipherSuites()

Возвращает копию массива наборов шифров или null, если они не были заданы.

Возвращаемый массив включает наборы шифров из списка стандартных имён наборов шифров в разделе Имена наборов шифров JSSE документации по стандартным именам алгоритмов Java Cryptography Architecture, а также может включать и другие наборы шифров, которые поддерживает поставщик.

Возвращает:: копию массива наборов шифров или null, если они не были заданы.

setCipherSuites

public void setCipherSuites(String[] cipherSuites)

Устанавливает массив наборов шифров.

Параметры:: cipherSuites - массив наборов шифров (или null). Обратите внимание, что стандартный список имён наборов шифров можно найти в разделе Имена наборов шифров JSSE документации по стандартным именам алгоритмов Java Cryptography Architecture. Поставщики могут поддерживать имена наборов шифров, отсутствующие в этом списке, или могут не использовать рекомендуемое имя для определённого набора шифров.

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, если ограничения не установлены

Since:

1.7

См. также:

setAlgorithmConstraints(AlgorithmConstraints)

setAlgorithmConstraints

public void setAlgorithmConstraints(AlgorithmConstraints constraints)

Устанавливает ограничения алгоритмов, которые будут использоваться дополнительно к любым, настроенным средой выполнения.

Если параметр constraints не равен null, каждый криптографический алгоритм, ключ и параметры алгоритма, используемые в фазе рукопожатия SSL/TLS/DTLS, должны быть разрешены ограничениями.

Параметры:: constraints - ограничения алгоритмов (или null)
Since:: 1.7

getEndpointIdentificationAlgorithm

public String getEndpointIdentificationAlgorithm()

Возвращает алгоритм идентификации конечной точки.

Возвращает:

алгоритм идентификации конечной точки или null, если он не был задан.

Since:

1.7

См. также:

X509ExtendedTrustManager
setEndpointIdentificationAlgorithm(String)

setEndpointIdentificationAlgorithm

public void setEndpointIdentificationAlgorithm(String algorithm)

Устанавливает алгоритм идентификации конечной точки.

Если параметр algorithm не равен null и не пуст, процедуры идентификации/верификации конечной точки должны обрабатываться во время рукопожатия SSL/TLS/DTLS. Это необходимо для предотвращения атак "человек посередине".

Параметры:

algorithm - Стандартное строковое имя алгоритма идентификации конечной точки (или null). Обратитесь к документу Стандартные имена алгоритмов Java Security для получения информации о стандартных именах алгоритмов.

Since:

1.7

См. также:

X509ExtendedTrustManager

setServerNames

public final void setServerNames(List<SNIServerName> serverNames)

Устанавливает требуемые SNIServerName параметра Server Name Indication (SNI).

Этот метод полезен только для SSLSocket или SSLEngine, работающих в режиме клиента.

Обратите внимание, что список serverNames клонируется для защиты от последующих изменений.

Параметры:

serverNames - список требуемых SNIServerName (или null)

Исключения:

NullPointerException - если список serverNames содержит элемент null

IllegalArgumentException - если список serverNames содержит более одного имени одного типа

Since:

1.8

См. также:

getServerNames

public final List<SNIServerName> getServerNames()

Возвращает List, содержащий все SNIServerName параметра Server Name Indication (SNI), или null, если значение не задано.

Этот метод полезен только для SSLSocket или SSLEngine, работающих в режиме клиента.

Для подключений SSL/TLS/DTLS, поставщик SSL/TLS/DTLS может указать значение по умолчанию для определенного типа имени сервера. В режиме клиента рекомендуется, чтобы поставщики по умолчанию включали указание имени сервера, когда сервер может быть найден по поддерживаемому типу имени сервера.

Рекомендуется, чтобы поставщики инициализировали значения по умолчанию для Server Name Indication при создании SSLSocket/SSLEngine. В следующих примерах имя сервера может быть представлено экземпляром SNIHostName, инициализированным именем хоста "www.example.com" и типом StandardConstants.SNI_HOST_NAME.

     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)

Устанавливает SNIMatcher параметра Server Name Indication (SNI).

Этот метод полезен только для SSLSocket или SSLEngine, работающих в режиме сервера.

Обратите внимание, что коллекция matchers клонируется для защиты от последующих изменений.

Параметры:

matchers - коллекция SNIMatcher (или null)

Исключения:

NullPointerException - если matchers содержит null элемент

IllegalArgumentException - если matchers содержит более одного имени одного типа

С:

1.8

См. также:

getSNIMatchers

public final Collection<SNIMatcher> getSNIMatchers()

Возвращает Collection, содержащий все SNIMatcher параметра Server Name Indication (SNI), или 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 должны быть отключены

С:

См. также:

getEnableRetransmissions()

getEnableRetransmissions

public boolean getEnableRetransmissions()

Возвращает, должны ли быть включены повторные передачи рукопожатия DTLS. Этот метод применим только к DTLS.

Возвращает:

true, если повторные передачи рукопожатия DTLS должны быть включены

С:

См. также:

setEnableRetransmissions(boolean)

setMaximumPacketSize

public void setMaximumPacketSize(int maximumPacketSize)

Устанавливает максимальный ожидаемый размер сетевого пакета в байтах для записей SSL/TLS/DTLS.

Примечание API:

Рекомендуется, чтобы максимальный размер пакета, по возможности, не был меньше 256 байт, чтобы маленькие сообщения рукопожатия, такие как HelloVerifyRequests, не фрагментировались.

Примечание реализации:

Если максимальный размер пакета слишком мал для хранения минимальной записи, реализация может попытаться сгенерировать как можно меньше записей. Однако это может привести к тому, что сгенерированный пакет будет больше максимального размера пакета.

Параметры:

maximumPacketSize - максимальный ожидаемый размер сетевого пакета в байтах, или 0 для использования неявного размера, автоматически указанного реализацией.

Исключения:

IllegalArgumentException - если maximumPacketSize отрицательно.

С:

См. также:

getMaximumPacketSize()

getMaximumPacketSize

public int getMaximumPacketSize()

Возвращает максимальный ожидаемый размер сетевого пакета в байтах для записей SSL/TLS/DTLS.

Примечание API:

Неявный размер может не быть фиксированным значением, особенно для реализации протоколов DTLS.

Примечание реализации:

Для подключений SSL/TLS/DTLS поставщик должен вычислить и указать неявное значение максимального ожидаемого размера сетевого пакета, если оно не настроено явно. Для любого объекта подключения, этот метод никогда не должен возвращать 0, чтобы приложения могли получить фактический неявный размер базовой реализации.

Реализация должна попытаться соответствовать настройке максимального размера пакета. Однако, если максимальный размер пакета слишком мал для хранения минимальной записи, реализация может попытаться сгенерировать как можно меньше записей. Это может привести к тому, что сгенерированный пакет будет больше максимального размера пакета.

Возвращает:

максимальный ожидаемый размер сетевого пакета, или 0 если используется неявный размер, автоматически указанный реализацией, и этот объект не был заполнен каким-либо подключением.

С:

См. также:

setMaximumPacketSize(int)

getApplicationProtocols

public String[] getApplicationProtocols()

Возвращает упорядоченный массив имен протоколов прикладного уровня, которые могут быть согласованы по протоколам SSL/TLS/DTLS.

Массив может быть пустым (нулевой длины), в этом случае указания протоколов не будут использоваться.

Этот метод будет возвращать новый массив каждый раз, когда он вызывается.

Возвращает:

не-null, возможно нулевой длины, массив имен протоколов приложений. Массив упорядочен по предпочтению протокола, причем protocols[0] является наиболее предпочтительным.

С:

См. также:

setApplicationProtocols(java.lang.String[])

Установить протоколы приложений

public void setApplicationProtocols(String[] protocols)

Устанавливает упорядоченный массив имён протоколов прикладного уровня, которые могут быть переговорены по протоколам SSL/TLS/DTLS.

Если протоколы прикладного уровня поддерживаются реализацией SSL/TLS, этот метод настраивает, какие значения могут быть переговорены протоколами, такими как RFC 7301 , протокол переговорной связи прикладного уровня (ALPN).

Если этому концу соединения необходимо предложить значения протоколов приложений, все протоколы, настроенные этим методом, будут отправлены партнёру.

Если этому концу соединения необходимо выбрать значение протокола приложения, значения, protocols настроенные этим методом, сравниваются со значениями, отправленными партнёром. Первое совпавшее значение становится переговорённым значением. Если ни одно из protocols не было запрошено партнёром, основной протокол определит, какое действие предпринять. (Например, ALPN отправит "no_application_protocol" сигнал об ошибке и завершит соединение.)

Значения String должны быть представлены в сетевом представлении, ожидаемом партнёром. Например, если должен быть обмен String ALPN, используя UTF-8, то String должны быть преобразованы в их byte[] представление и сохранены как байтовое String перед вызовом этого метода.

     // MEETEI MAYEK LETTERS HUK UN I (Unicode 0xabcd->0xabcf): 2 bytes
     byte[] bytes = "\uabcd\uabce\uabcf"
             .getBytes(StandardCharsets.UTF_8);
     String HUK_UN_I = new String(bytes, StandardCharsets.ISO_8859_1);

     // 0x00-0xFF:  1 byte
     String rfc7301Grease8A = "\u008A\u008A";

     SSLParameters p = sslSocket.getSSLParameters();
     p.setApplicationProtocols(new String[] {
             "h2", "http/1.1", rfc7301Grease8A, HUK_UN_I});
     sslSocket.setSSLParameters(p);

Требования к реализации:

Этот метод сделает копию массива protocols.

Параметры:

protocols - упорядоченный массив протоколов приложений, где protocols[0] имеет наивысший приоритет. Если массив пуст (длины 0), указания протокола не будут использоваться.

Исключения:

IllegalArgumentException - если protocols равен null или любой элемент в непустом массиве равен null или пустой строке (длины 0)

С:

См. также:

getApplicationProtocols()

© 1993, 2021, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/17/docs/api/java.base/javax/net/ssl/SSLParameters.html