Класс 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);
С момента:
1.6
См. также:
SSLSocket, SSLEngine, SSLContext

Конструкторы

Конструктор Описание
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, если они не заданы.
List<SNIServerName> getServerNames()

Возвращает List содержащий все SNIServerName параметров указания имени сервера (SNI) или null, если ни один не был задан.
Collection<SNIMatcher> getSNIMatchers()

Возвращает Collection содержащий все SNIMatcher параметров указания имени сервера (SNI) или null, если ни один не был задан.
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)

Устанавливает массив протоколов.
void setServerNames​(List<SNIServerName> serverNames)

Устанавливает желаемые SNIServerName параметров указания имени сервера (SNI).
void setSNIMatchers​(Collection<SNIMatcher> matchers)

Устанавливает SNIMatcher параметров указания имени сервера (SNI).
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 Cipher Suite Names документации по стандартным именам алгоритмов Java Cryptography Architecture, а также может включать и другие наборы шифров, поддерживаемые поставщиком.

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

setCipherSuites

public void setCipherSuites(String[] cipherSuites)

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

Параметры:
cipherSuites - массив наборов шифров (или null). Обратите внимание, что стандартный список имён наборов шифров можно найти в разделе JSSE Cipher Suite Names документации по стандартным именам алгоритмов 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 Standard Algorithm Names для получения информации о стандартных именах алгоритмов.
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
См. также:
SNIServerName, getServerNames()

getServerNames

public final List<SNIServerName> getServerNames()

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

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

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

Рекомендуется, чтобы поставщики инициализировали указания имени сервера по умолчанию при создании 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
Since:
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 содержит более одного имени одного типа
Since:
1.8
См. также:
Collection, SNIMatcher, getSNIMatchers()

getSNIMatchers

public final Collection<SNIMatcher> getSNIMatchers()

Возвращает Collection с содержанием всех SNIMatcher параметра Server Name Indication (SNI) или null, если он не задан.

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

Для лучшей совместимости поставщики обычно не определяют по умолчанию матчеров, чтобы по умолчанию серверы игнорировали расширение SNI и продолжали рукопожатие.

Возвращает:
null или неизменяемая коллекция не-null SNIMatcher
Since:
1.8
См. также:
SNIMatcher, setSNIMatchers(Collection)

setUseCipherSuitesOrder

public final void setUseCipherSuitesOrder(boolean honorOrder)

Устанавливает, следует ли учитывать порядок локальных наборов шифров.

Параметры:
honorOrder - следует ли учитывать порядок локальных наборов шифров в #getCipherSuites при рукопожатии SSL/TLS/DTLS.
Since:
1.8
См. также:
getUseCipherSuitesOrder()

getUseCipherSuitesOrder

public final boolean getUseCipherSuitesOrder()

Возвращает, следует ли учитывать порядок локальных наборов шифров.

Возвращает:
следует ли учитывать порядок локальных наборов шифров в #getCipherSuites при рукопожатии SSL/TLS/DTLS.
Since:
1.8
См. также:
setUseCipherSuitesOrder(boolean)

setEnableRetransmissions

public void setEnableRetransmissions(boolean enableRetransmissions)

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

Параметры:
enableRetransmissions - true указывает, что повторные передачи рукопожатия DTLS должны быть включены; false указывает, что повторные передачи рукопожатия DTLS должны быть отключены
Since:
9
См. также:
getEnableRetransmissions()

getEnableRetransmissions

public boolean getEnableRetransmissions()

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

Возвращает:
true, если повторные передачи рукопожатия DTLS должны быть разрешены
С тех пор как:
9
См. также:
setEnableRetransmissions(boolean)

setMaximumPacketSize

public void setMaximumPacketSize(int maximumPacketSize)

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

Примечание API:
Рекомендуется, чтобы максимальный размер пакета, если это возможно, не был меньше 256 байтов, чтобы небольшие сообщения рукопожатия, такие как HelloVerifyRequests, не фрагментировались.
Примечание реализации:
Если максимальный размер пакета слишком мал для размещения минимальной записи, реализация может попытаться сгенерировать минимальные записи. Однако это может привести к тому, что сгенерированный пакет будет больше максимального размера пакета.
Параметры:
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.

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

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

Возвращает:
не нулевой, возможно нулевой длины, массив имён протоколов прикладного уровня. Массив упорядочен по предпочтению протокола, где protocols[0] имеет наивысший приоритет.
С тех пор как:
9
См. также:
setApplicationProtocols(java.lang.String[])

setApplicationProtocols

public void setApplicationProtocols(String[] protocols)

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

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

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

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

Требования к реализации:
Этот метод создаст копию массива protocols.
Параметры:
protocols - упорядоченный массив протоколов прикладного уровня, где protocols[0] имеет наивысший приоритет. Если массив пустой (нулевой длины), указания протоколов не будут использоваться.
Изначает:
IllegalArgumentException - если protocols равен null или любой элемент в непустом массиве равен null или пустой (нулевой длины) строкой
С тех пор как:
9
См. также:
getApplicationProtocols()

© 1993, 2020, 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/11/docs/api/java.base/javax/net/ssl/SSLParameters.html

Spec-Zone .ru
спецификации, руководства, описания, API