public static final class DtlsConnectorConfig.Builder extends Object
DtlsConnectorConfig
based on the builder pattern.| Constructor and Description |
|---|
DtlsConnectorConfig.Builder()
Creates a new instance for setting configuration options
for a
DTLSConnector instance. |
DtlsConnectorConfig.Builder(DtlsConnectorConfig initialConfiguration)
Create a builder from an existing DtlsConnectorConfig.
|
| Modifier and Type | Method and Description |
|---|---|
DtlsConnectorConfig |
build()
Creates an instance of
DtlsConnectorConfig based on the properties
set on this builder. |
DtlsConnectorConfig |
getIncompleteConfig()
Returns a potentially incomplete configuration.
|
DtlsConnectorConfig.Builder |
setAddress(InetSocketAddress address)
Sets the IP address and port the connector should bind to
Note: using IPv6 interfaces with multiple addresses including
permanent and temporary (with potentially several different prefixes)
currently causes issues on the server side.
|
DtlsConnectorConfig.Builder |
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier verifier)
Sets the logic in charge of validating a X.509 certificate chain.
|
DtlsConnectorConfig.Builder |
setAdvancedPskStore(AdvancedPskStore advancedPskStore)
Sets the advanced key store to use for authenticating clients based on a
pre-shared key.
|
DtlsConnectorConfig.Builder |
setApplicationLevelInfoSupplier(ApplicationLevelInfoSupplier supplier)
Sets a supplier of application level information for an authenticated peer's identity.
|
DtlsConnectorConfig.Builder |
setAutoResumptionTimeoutMillis(Long timeoutInMillis)
Set the timeout of automatic session resumption in milliseconds.
|
DtlsConnectorConfig.Builder |
setBackOffRetransmission(Integer count)
Number of retransmissions before the attempt to transmit a flight in
back-off mode.
|
DtlsConnectorConfig.Builder |
setCertificateVerifier(CertificateVerifier verifier)
Deprecated.
use
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period. |
DtlsConnectorConfig.Builder |
setCidUpdateAddressOnNewerRecordFilter(boolean enable)
Use filter to update the ip-address from DTLS 1.2 CID records only
for newer records based on epoch/sequence_number.
|
DtlsConnectorConfig.Builder |
setCipherSuiteSelector(CipherSuiteSelector cipherSuiteSelector)
Sets the cipher suite selector.
|
DtlsConnectorConfig.Builder |
setClientAuthenticationRequired(boolean authRequired)
Sets whether the connector requires DTLS clients to authenticate
during the handshake.
|
DtlsConnectorConfig.Builder |
setClientAuthenticationWanted(boolean authWanted)
Sets whether the connector wants (requests) DTLS clients to
authenticate during the handshake.
|
DtlsConnectorConfig.Builder |
setClientOnly()
Indicates that the DTLSConnector will only be used as a
DTLS client.
|
DtlsConnectorConfig.Builder |
setConnectionIdGenerator(ConnectionIdGenerator connectionIdGenerator)
Sets the connection id generator.
|
DtlsConnectorConfig.Builder |
setConnectionListener(ConnectionListener connectionListener) |
DtlsConnectorConfig.Builder |
setConnectionThreadCount(int threadCount)
Set the number of thread which should be used to handle DTLS
connection.
|
DtlsConnectorConfig.Builder |
setDefaultHandshakeMode(String defaultHandshakeMode)
Set the DTLSConnector default handshake mode.
|
DtlsConnectorConfig.Builder |
setEarlyStopRetransmission(boolean activate)
Activate/Deactivate experimental feature: Stop retransmission at
first received handshake message.
|
DtlsConnectorConfig.Builder |
setEnableAddressReuse(boolean enable)
Enables address reuse for the socket.
|
DtlsConnectorConfig.Builder |
setEnableMultiHandshakeMessageRecords(boolean enable)
Enable to use dtls records with multiple handshake messages.
|
DtlsConnectorConfig.Builder |
setEnableMultiRecordMessages(boolean enable)
Enable to use UDP messages with multiple dtls records.
|
DtlsConnectorConfig.Builder |
setHealthHandler(DtlsHealth healthHandler)
Set the health handler.
|
DtlsConnectorConfig.Builder |
setHealthStatusInterval(Integer healthStatusIntervalSeconds)
Set the health status interval.
|
DtlsConnectorConfig.Builder |
setIdentity(PrivateKey privateKey,
Certificate[] certificateChain,
CertificateType... certificateTypes)
Sets the connector's identifying properties by means of a private key
and a corresponding issuer certificates chain.
|
DtlsConnectorConfig.Builder |
setIdentity(PrivateKey privateKey,
Certificate[] certificateChain,
List<CertificateType> certificateTypes)
Sets the connector's identifying properties by means of a private key
and a corresponding issuer certificates chain.
|
DtlsConnectorConfig.Builder |
setIdentity(PrivateKey privateKey,
PublicKey publicKey)
Sets the connector's identifying properties by means of a private and
public key pair.
|
DtlsConnectorConfig.Builder |
setKeyUsageVerification(boolean enable)
Use key usage verification for x509.
|
DtlsConnectorConfig.Builder |
setLoggingTag(String tag)
Set instance logging tag.
|
DtlsConnectorConfig.Builder |
setMaxConnections(int maxConnections)
Sets the maximum number of active connections the connector should support.
|
DtlsConnectorConfig.Builder |
setMaxDeferredProcessedIncomingRecordsSize(int maxDeferredProcessedIncomingRecordsSize)
Set maximum size of deferred processed incoming records.
|
DtlsConnectorConfig.Builder |
setMaxDeferredProcessedOutgoingApplicationDataMessages(int maxDeferredProcessedOutgoingApplicationDataMessages)
Set maximum number of deferred processed outgoing application data
messages.
|
DtlsConnectorConfig.Builder |
setMaxFragmentedHandshakeMessageLength(Integer length)
Set maximum length of handshake message.
|
DtlsConnectorConfig.Builder |
setMaxFragmentLengthCode(Integer lengthCode)
Sets the maximum amount of payload data that can be received and processed by this connector
in a single DTLS record.
|
DtlsConnectorConfig.Builder |
setMaxRetransmissions(int count)
Sets the maximum number of times a flight of handshake messages gets re-transmitted
to a peer.
|
DtlsConnectorConfig.Builder |
setMaxTransmissionUnit(int mtu)
Set maximum transmission unit.
|
DtlsConnectorConfig.Builder |
setMaxTransmissionUnitLimit(int limit)
Set maximum transmission unit limit for auto detection.
|
DtlsConnectorConfig.Builder |
setNoServerSessionId(boolean flag)
Set whether session id is used by this server or not.
|
DtlsConnectorConfig.Builder |
setOutboundMessageBufferSize(int capacity)
Sets the number of outbound messages that can be buffered in memory before
dropping messages.
|
DtlsConnectorConfig.Builder |
setPreselectedCipherSuites(CipherSuite... cipherSuites)
Sets the preselected cipher suites for the connector.
|
DtlsConnectorConfig.Builder |
setPreselectedCipherSuites(List<CipherSuite> cipherSuites)
Sets the preselected cipher suites for the connector.
|
DtlsConnectorConfig.Builder |
setPreselectedCipherSuites(String... cipherSuites)
Sets the preselected cipher suites for the connector.
|
DtlsConnectorConfig.Builder |
setProtocolVersionForHelloVerifyRequests(ProtocolVersion protocolVersion)
Set the protocol version to be used to send hello verify requests.
|
DtlsConnectorConfig.Builder |
setPskStore(PskStore pskStore)
Deprecated.
use
setAdvancedPskStore(AdvancedPskStore)
instead. AdvancedSinglePskStore and
AdvancedMultiPskStore may be used for simple
setups. More complex ones may require a custom
implementation. During migration you may also use the
BridgePskStore in order to use old
implementations for that period. |
DtlsConnectorConfig.Builder |
setReceiverThreadCount(int threadCount)
Set the number of thread which should be used to receive
datagrams from the socket.
|
DtlsConnectorConfig.Builder |
setRecommendedCipherSuitesOnly(boolean recommendedCipherSuitesOnly)
Set usage of recommended cipher suites.
|
DtlsConnectorConfig.Builder |
setRecommendedSupportedGroupsOnly(boolean recommendedSupportedGroupsOnly)
Set usage of recommended supported groups (curves).
|
DtlsConnectorConfig.Builder |
setRecordSizeLimit(Integer recordSizeLimit)
Sets record size limit.
|
DtlsConnectorConfig.Builder |
setRetransmissionTimeout(int timeout)
Sets the (starting) time to wait before a handshake package gets re-transmitted.
|
DtlsConnectorConfig.Builder |
setRpkTrustAll()
Deprecated.
use
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period. |
DtlsConnectorConfig.Builder |
setRpkTrustStore(TrustedRpkStore store)
Deprecated.
use
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period. |
DtlsConnectorConfig.Builder |
setServerOnly(boolean enable)
Indicates that the DTLSConnector will only act as server.
|
DtlsConnectorConfig.Builder |
setSniEnabled(boolean flag)
Sets whether the connector should support the use of the TLS
Server Name Indication extension in the DTLS handshake.
|
DtlsConnectorConfig.Builder |
setSocketReceiveBufferSize(Integer size)
Set the size of the socket receive buffer.
|
DtlsConnectorConfig.Builder |
setSocketSendBufferSize(Integer size)
Set the size of the socket send buffer.
|
DtlsConnectorConfig.Builder |
setStaleConnectionThreshold(long threshold)
Sets the maximum number of seconds without any data being exchanged before a connection
is considered stale.
|
DtlsConnectorConfig.Builder |
setSupportedCipherSuites(CipherSuite... cipherSuites)
Sets the cipher suites supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedCipherSuites(List<CipherSuite> cipherSuites)
Sets the cipher suites supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedCipherSuites(String... cipherSuites)
Sets the cipher suites supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedGroups(List<XECDHECryptography.SupportedGroup> supportedGroups)
Sets the groups (curves) supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedGroups(String... supportedGroups)
Sets the groups (curves) supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedGroups(XECDHECryptography.SupportedGroup... supportedGroups)
Sets the groups (curves) supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedSignatureAlgorithms(List<SignatureAndHashAlgorithm> supportedSignatureAlgorithms)
Sets the signature algorithms supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedSignatureAlgorithms(SignatureAndHashAlgorithm... supportedSignatureAlgorithms)
Sets the signature algorithms supported by the connector.
|
DtlsConnectorConfig.Builder |
setSupportedSignatureAlgorithms(String... supportedSignatureAlgorithms)
Sets the signature algorithms supported by the connector.
|
DtlsConnectorConfig.Builder |
setTrustCertificateTypes(CertificateType... certificateTypes)
Sets the certificate types for the trust of the other peer.
|
DtlsConnectorConfig.Builder |
setTrustStore(Certificate[] trustedCerts)
Deprecated.
use
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period. |
DtlsConnectorConfig.Builder |
setUseAntiReplayFilter(boolean enable)
Use anti replay filter.
|
DtlsConnectorConfig.Builder |
setUseExtendedWindowFilter(int level)
Use extended window filter.
|
DtlsConnectorConfig.Builder |
setUseHandshakeStateValidation(boolean enable)
Use the handshake state validation to verify valid handshakes.
|
DtlsConnectorConfig.Builder |
setUseTruncatedCertificatePathForClientsCertificateMessage(boolean enable)
Use truncated certificate paths for client's certificate message.
|
DtlsConnectorConfig.Builder |
setUseTruncatedCertificatePathForValidation(boolean enable)
Use truncated certificate paths for validation.
|
DtlsConnectorConfig.Builder |
setUseWindowFilter(boolean enable)
Deprecated.
use
setUseExtendedWindowFilter(int) with
-1, instead. |
DtlsConnectorConfig.Builder |
setVerifyPeersOnResumptionThreshold(int threshold)
Sets threshold in percent of
setMaxConnections(int), whether
a HELLO_VERIFY_REQUEST should be used also for session resumption. |
public DtlsConnectorConfig.Builder()
DTLSConnector instance.
Once all options are set, clients should use the build()
method to create an immutable DtlsConfigurationConfig
instance which can be passed into the DTLSConnector
constructor.
The builder is initialized to the following default values
InetSocketAddress.InetSocketAddress(int)truesetPskStore(PskStore)
or setIdentity(PrivateKey, PublicKey) methods need to be used to
get a working configuration for a DTLSConnector that can be used
as a client and server.
It is possible to create a configuration for a DTLSConnector that can operate
as a client only without the need for setting an identity. However, this is possible
only if the server does not require clients to authenticate, i.e. this only
works with the ECDH based cipher suites. If you want to create such a client-only
configuration, you need to use the setClientOnly() method on the builder.public DtlsConnectorConfig.Builder(DtlsConnectorConfig initialConfiguration)
initialConfiguration - initial configurationpublic DtlsConnectorConfig.Builder setAddress(InetSocketAddress address)
address - the IP address and port the connector should bind toIllegalArgumentException - if the given address is unresolvedpublic DtlsConnectorConfig.Builder setEnableAddressReuse(boolean enable)
enable - true if addresses should be reused.public DtlsConnectorConfig.Builder setRecommendedCipherSuitesOnly(boolean recommendedCipherSuitesOnly)
recommendedCipherSuitesOnly - true allow only
recommended cipher suites, false, also allow not
recommended cipher suites. Default value is truepublic DtlsConnectorConfig.Builder setRecommendedSupportedGroupsOnly(boolean recommendedSupportedGroupsOnly)
recommendedSupportedGroupsOnly - true allow only
recommended supported groups, false, also allow not
recommended supported groups. Default value is truepublic DtlsConnectorConfig.Builder setClientOnly()
build() method will allow creation of a configuration
without any identity being set under the following conditions:
IllegalStateException - if client only is in contradiction to
server side configurationpublic DtlsConnectorConfig.Builder setServerOnly(boolean enable)
enable - true if the connector acts only as server.IllegalStateException - if server only is enabled in
contradiction to client side configurationpublic DtlsConnectorConfig.Builder setDefaultHandshakeMode(String defaultHandshakeMode)
defaultHandshakeMode - DtlsEndpointContext.HANDSHAKE_MODE_AUTO or
DtlsEndpointContext.HANDSHAKE_MODE_NONEIllegalStateException - if configuration is server only and
DtlsEndpointContext.HANDSHAKE_MODE_AUTO is
providedIllegalArgumentException - if mode is neither
DtlsEndpointContext.HANDSHAKE_MODE_AUTO nor
DtlsEndpointContext.HANDSHAKE_MODE_NONEpublic DtlsConnectorConfig.Builder setRecordSizeLimit(Integer recordSizeLimit)
recordSizeLimit - the record size limit, betwee 64 and 65535. Or
null, if not used.public DtlsConnectorConfig.Builder setMaxFragmentLengthCode(Integer lengthCode)
The value of this property is used to indicate to peers the Maximum Fragment Length as defined in RFC 6066, Section 4. It is also used to determine the amount of memory that will be allocated for receiving UDP datagrams sent by peers from the network interface.
The code must be eithernull or one of the following:
If this property is set to null, the DTLSConnector will
derive its value from the network interface's Maximum Transmission Unit.
This means that it will set it to a value small enough to make sure that inbound
messages fit into a UDP datagram having a size less or equal to the MTU.
lengthCode - the code indicating the maximum length or null to determine
the maximum fragment length based on the network interface's MTUIllegalArgumentException - if the code is not one of {1, 2, 3, 4}public DtlsConnectorConfig.Builder setMaxFragmentedHandshakeMessageLength(Integer length)
length - maximum length of handshake messagepublic DtlsConnectorConfig.Builder setEnableMultiRecordMessages(boolean enable)
enable - true, to enabled, false, otherwise.public DtlsConnectorConfig.Builder setEnableMultiHandshakeMessageRecords(boolean enable)
enable - true, to enabled, false, otherwise.public DtlsConnectorConfig.Builder setProtocolVersionForHelloVerifyRequests(ProtocolVersion protocolVersion)
protocolVersion - fixed protocol version to send hello verify
requests. null to reply the client's version.HelloVerifyRequestpublic DtlsConnectorConfig.Builder setSocketReceiveBufferSize(Integer size)
size - the socket receive buffer size in bytes, or null,
to use the OS default.public DtlsConnectorConfig.Builder setSocketSendBufferSize(Integer size)
size - the socket send buffer size in bytes, or null, to
use the OS default.public DtlsConnectorConfig.Builder setHealthStatusInterval(Integer healthStatusIntervalSeconds)
healthStatusIntervalSeconds - health status interval in seconds.
null disable health status.public DtlsConnectorConfig.Builder setHealthHandler(DtlsHealth healthHandler)
healthHandler - health handler.public DtlsConnectorConfig.Builder setOutboundMessageBufferSize(int capacity)
capacity - the number of messages to bufferIllegalArgumentException - if capacity < 1public DtlsConnectorConfig.Builder setBackOffRetransmission(Integer count)
DtlsConnectorConfig.useMultiHandshakeMessageRecords() and
DtlsConnectorConfig.useMultiRecordMessages() has precedence over the back-off
definition.
Value 0, to disable it, null, for default of
DtlsConnectorConfig.maxRetransmissions / 2.count - the number of re-transmissions to use the back-off modepublic DtlsConnectorConfig.Builder setMaxRetransmissions(int count)
count - the maximum number of re-transmissionspublic DtlsConnectorConfig.Builder setMaxTransmissionUnit(int mtu)
mtu - maximum transmission unitIllegalArgumentException - if
setMaxTransmissionUnitLimit(int) was already setpublic DtlsConnectorConfig.Builder setMaxTransmissionUnitLimit(int limit)
setMaxTransmissionUnit(int).limit - maximum transmission unit limit. Default
DtlsConnectorConfig.DEFAULT_MAX_TRANSMISSION_UNIT_LIMITIllegalArgumentException - if
setMaxTransmissionUnit(int) was already setpublic DtlsConnectorConfig.Builder setClientAuthenticationWanted(boolean authWanted)
false. Only used by the DTLS server side.authWanted - true if clients wanted to authenticateIllegalStateException - if configuration is for client onlyIllegalArgumentException - if authWanted is true, but
setClientAuthenticationRequired(boolean) was set
to true before.public DtlsConnectorConfig.Builder setClientAuthenticationRequired(boolean authRequired)
true. If
setClientAuthenticationWanted(boolean) is set to
true, the default is false. Only used by the DTLS
server side.authRequired - true if clients need to authenticateIllegalStateException - if configuration is for client onlyIllegalArgumentException - if authWanted is true, but
setClientAuthenticationWanted(boolean) was set
to true before.public DtlsConnectorConfig.Builder setCipherSuiteSelector(CipherSuiteSelector cipherSuiteSelector)
The connector will use these selector to determine the cipher suite and parameters during the handshake.
cipherSuiteSelector - the cipher suite selector. Default
(DefaultCipherSuiteSelector.public DtlsConnectorConfig.Builder setPreselectedCipherSuites(CipherSuite... cipherSuites)
CipherSuite to be automatically selected as supported
cipher suites depending on other setting (e.g. if settings allow only
PSK, only PSK compatible cipher suite from this list will be
selected).
Not used, if supported cipher suites are provided.cipherSuites - the preselected cipher suitespublic DtlsConnectorConfig.Builder setPreselectedCipherSuites(List<CipherSuite> cipherSuites)
CipherSuite to be automatically selected as supported
cipher suites depending on other setting (e.g. if settings allow only
PSK, only PSK compatible cipher suite from this list will be
selected).
Not used, if supported cipher suites are provided.cipherSuites - the preselected cipher suitesIllegalArgumentException - if the list is empty, or
"TLS_NULL_WITH_NULL_NULL" is contained.public DtlsConnectorConfig.Builder setPreselectedCipherSuites(String... cipherSuites)
CipherSuite to be automatically selected as supported
cipher suites depending on other setting (e.g. if settings allow only
PSK, only PSK compatible cipher suite from this list will be
selected).
Not used, if supported cipher suites are provided.cipherSuites - the names of the preselected cipher suitesIllegalArgumentException - if at least one name is not
available, or "TLS_NULL_WITH_NULL_NULL" is contained.public DtlsConnectorConfig.Builder setSupportedCipherSuites(CipherSuite... cipherSuites)
The connector will use these cipher suites (in exactly the same order) during the DTLS handshake when negotiating a cipher suite with a peer.
cipherSuites - the supported cipher suites in the order of
preferenceNullPointerException - if the given array is nullIllegalArgumentException - if the given array is empty,
contains CipherSuite.TLS_NULL_WITH_NULL_NULL,
contains a cipher suite, not supported by the JVM, or
violates the
setRecommendedCipherSuitesOnly(boolean) setting.public DtlsConnectorConfig.Builder setSupportedCipherSuites(List<CipherSuite> cipherSuites)
The connector will use these cipher suites (in exactly the same order) during the DTLS handshake when negotiating a cipher suite with a peer.
cipherSuites - the supported cipher suites in the order of
preferenceNullPointerException - if the given list is nullIllegalArgumentException - if the given list is empty,
contains CipherSuite.TLS_NULL_WITH_NULL_NULL,
contains a cipher suite, not supported by the JVM, or
violates the
setRecommendedCipherSuitesOnly(boolean) setting.public DtlsConnectorConfig.Builder setSupportedCipherSuites(String... cipherSuites)
The connector will use these cipher suites (in exactly the same order) during the DTLS handshake when negotiating a cipher suite with a peer.
cipherSuites - the names of supported cipher suites in the order
of preference (see
IANA registry for a list of cipher suite names)NullPointerException - if the given array is nullIllegalArgumentException - if the given array is empty,
contains CipherSuite.TLS_NULL_WITH_NULL_NULL,
contains a cipher suite, not supported by the JVM,
contains a name, which is not supported, or violates the
setRecommendedCipherSuitesOnly(boolean) setting.public DtlsConnectorConfig.Builder setSupportedSignatureAlgorithms(SignatureAndHashAlgorithm... supportedSignatureAlgorithms)
The connector will use these signature algorithms (in exactly the same order) during the DTLS handshake.
supportedSignatureAlgorithms - the supported signature
algorithms in the order of preference. No arguments, if no
specific extension is to be used for a client, and the
server uses SignatureAndHashAlgorithm.DEFAULT.public DtlsConnectorConfig.Builder setSupportedSignatureAlgorithms(List<SignatureAndHashAlgorithm> supportedSignatureAlgorithms)
The connector will use these signature algorithms (in exactly the same order) during the DTLS handshake.
supportedSignatureAlgorithms - the list of supported signature
algorithms in the order of preference. Empty, if no
specific extension is to be used for a client, and the
server uses SignatureAndHashAlgorithm.DEFAULT.public DtlsConnectorConfig.Builder setSupportedSignatureAlgorithms(String... supportedSignatureAlgorithms)
The connector will use these signature algorithms (in exactly the same order) during the DTLS handshake.
supportedSignatureAlgorithms - the list of supported signature
algorithm names in the order of preference. Empty, if no
specific extension is to be used for a client, and the
server uses SignatureAndHashAlgorithm.DEFAULT.SignatureAndHashAlgorithm.valueOf(String)public DtlsConnectorConfig.Builder setSupportedGroups(XECDHECryptography.SupportedGroup... supportedGroups)
The connector will use these supported groups (in exactly the same order) during the DTLS handshake when negotiating a curve with a peer. According RFC 8422, 5.1. Client Hello Extensions, Actions of the receiver This affects both, curves for ECDH and the certificates for ECDSA.
supportedGroups - the supported groups (curves) in the order of
preferenceNullPointerException - if the given array is nullIllegalArgumentException - if the given array is empty,
contains a group (curve), not supported by the JVM, or
violates the
setRecommendedCipherSuitesOnly(boolean) setting.public DtlsConnectorConfig.Builder setSupportedGroups(List<XECDHECryptography.SupportedGroup> supportedGroups)
The connector will use these supported groups (in exactly the same order) during the DTLS handshake when negotiating a curve with a peer. According RFC 8422, 5.1. Client Hello Extensions, Actions of the receiver This affects both, curves for ECDH and the certificates for ECDSA.
supportedGroups - the supported groups (curves) in the order of
preferenceNullPointerException - if the given list is nullIllegalArgumentException - if the given list is empty,
contains a group (curve), not supported by the JVM, or
violates the
setRecommendedCipherSuitesOnly(boolean) setting.public DtlsConnectorConfig.Builder setSupportedGroups(String... supportedGroups)
The connector will use these supported groups (in exactly the same order) during the DTLS handshake when negotiating a curve with a peer. According RFC 8422, 5.1. Client Hello Extensions, Actions of the receiver This affects both, curves for ECDH and the certificates for ECDSA.
supportedGroups - the names of supported groups (curves) in the
order of preference (see
IANA registry for a list of supported group names)NullPointerException - if the given array is nullIllegalArgumentException - if the given array is empty,
contains a group (curve), not supported by the JVM, or
violates the
setRecommendedCipherSuitesOnly(boolean) setting.public DtlsConnectorConfig.Builder setEarlyStopRetransmission(boolean activate)
activate - Set it to true if retransmissions should be stopped
as soon as we receive a handshake messagepublic DtlsConnectorConfig.Builder setRetransmissionTimeout(int timeout)
timeout - the time in millisecondsIllegalArgumentException - if the given timeout is negative@Deprecated public DtlsConnectorConfig.Builder setPskStore(PskStore pskStore)
setAdvancedPskStore(AdvancedPskStore)
instead. AdvancedSinglePskStore and
AdvancedMultiPskStore may be used for simple
setups. More complex ones may require a custom
implementation. During migration you may also use the
BridgePskStore in order to use old
implementations for that period.setIdentity(PrivateKey, PublicKey) or
setIdentity(PrivateKey, Certificate[], CertificateType...)
the default preference uses the certificate based cipher suites. To
change that, use setSupportedCipherSuites(CipherSuite...) or
setSupportedCipherSuites(String...).
Also set the advanced PSK store using
AdvancedInMemoryPskStore.pskStore - the key storepublic DtlsConnectorConfig.Builder setAdvancedPskStore(AdvancedPskStore advancedPskStore)
setIdentity(PrivateKey, PublicKey) or
setIdentity(PrivateKey, Certificate[], CertificateType...)
the default preference uses the certificate based cipher suites. To
change that, use setSupportedCipherSuites(CipherSuite...) or
setSupportedCipherSuites(String...).
Resets setPskStore(PskStore) to null.advancedPskStore - the advanced key storepublic DtlsConnectorConfig.Builder setIdentity(PrivateKey privateKey, PublicKey publicKey)
Using this method implies that the connector only supports
RawPublicKey mode for authenticating to a peer. Please ensure,
that you setup setRpkTrustStore(TrustedRpkStore), or
setRpkTrustAll(), if you want to trust the other peer using
RAW_PUBLIC_KEY also.
If X_509 is intended to be supported together with RAW_PUBLIC_KEY,
please use
setIdentity(PrivateKey, Certificate[], CertificateType...)
instead and provide RAW_PUBLIC_KEY together with X_509 in the wanted
preference order.
If used together with setPskStore(PskStore), the default
preference uses this certificate based cipher suites. To change that,
use setSupportedCipherSuites(CipherSuite...) or
setSupportedCipherSuites(String...).
privateKey - the private key used for creating signaturespublicKey - the public key a peer can use to verify possession
of the private keyNullPointerException - if any of the given keys is
nullsetRpkTrustAll(),
setRpkTrustStore(TrustedRpkStore)public DtlsConnectorConfig.Builder setIdentity(PrivateKey privateKey, Certificate[] certificateChain, CertificateType... certificateTypes)
In server mode the key and certificates are used to prove the
server's identity to the client. In client mode the key and
certificates are used to prove the client's identity to the server.
Please ensure, that you setup either
setCertificateVerifier(CertificateVerifier),
setTrustStore(Certificate[]), setRpkTrustAll(),
setRpkTrustStore(TrustedRpkStore), if you want to trust the
other peer also using certificates.
If used together with setPskStore(PskStore), the default
preference uses this certificate based cipher suites. To change that,
use setSupportedCipherSuites(CipherSuite...) or
setSupportedCipherSuites(String...).
privateKey - the private key used for creating signaturescertificateChain - the chain of X.509 certificates asserting the
private key subject's identity. The endpoint's certificate
must be at position 0, the certificate signed by a trusted
CA must be at the highest position. A self-signed
top-level certificate will be removed for outgoing
CertificateMessage. If used for a client side
CertificateMessage, the chain will be truncated to
the first certificate of one of the received certificate
authorities.certificateTypes - list of certificate types in the order of
preference. Default is X_509. To support RAW_PUBLIC_KEY
also, use X_509 and RAW_PUBLIC_KEY in the order of the
preference. If only RAW_PUBLIC_KEY is used, the
certificate chain will be set to null.NullPointerException - if the given private key or certificate
chain is nullIllegalArgumentException - if the certificate chain does not
contain any certificates, or contains a non-X.509
certificatesetTrustStore(Certificate[]),
setCertificateVerifier(CertificateVerifier),
setRpkTrustAll(),
setRpkTrustStore(TrustedRpkStore)public DtlsConnectorConfig.Builder setIdentity(PrivateKey privateKey, Certificate[] certificateChain, List<CertificateType> certificateTypes)
In server mode the key and certificates are used to prove the
server's identity to the client. In client mode the key and
certificates are used to prove the client's identity to the server.
Please ensure, that you setup either
setCertificateVerifier(CertificateVerifier),
setTrustStore(Certificate[]), setRpkTrustAll(),
setRpkTrustStore(TrustedRpkStore), if you want to trust the
other peer also using certificates.
If used together with setPskStore(PskStore), the default
preference uses this certificate based cipher suites. To change that,
use setSupportedCipherSuites(CipherSuite...) or
setSupportedCipherSuites(String...).
privateKey - the private key used for creating signaturescertificateChain - the chain of X.509 certificates asserting the
private key subject's identity. The endpoint's certificate
must be at position 0, the certificate signed by a trusted
CA must be at the highest position. A self-signed
top-level certificate will be removed for outgoing
CertificateMessage. If used for a client side
CertificateMessage, the chain will be truncated to
the first certificate of one of the received certificate
authorities.certificateTypes - list of certificate types in the order of
preference. Default is X_509. To support RAW_PUBLIC_KEY
also, use X_509 and RAW_PUBLIC_KEY in the order of the
preference. If only RAW_PUBLIC_KEY is used, the
certificate chain will be set to null.NullPointerException - if the given private key or certificate
chain is nullIllegalArgumentException - if the certificate chain does not
contain any certificates, or contains a non-X.509
certificate. Or the provide certificateTypes is empty.setTrustStore(Certificate[]),
setCertificateVerifier(CertificateVerifier),
setRpkTrustAll(),
setRpkTrustStore(TrustedRpkStore)@Deprecated public DtlsConnectorConfig.Builder setTrustStore(Certificate[] trustedCerts)
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period.CertificateVerifier to this
builder.trustedCerts MUST NOT contain several certificates with same
subject. If you need that you should consider to use
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead.
This method must not be called, if
setCertificateVerifier(CertificateVerifier) or
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
is already set.
Note: since 2.5 supports null to reset the trusted
certificates in order to use specific
NewAdvancedCertificateVerifier instead of the default
implementation.trustedCerts - the trusted root certificates. If empty (length
of zero), trust all valid certificate chains without
limiting the trust to specific trust anchors. If
null, reset trusted certificates.IllegalArgumentException - if the array contains a non-X.509
certificate or several certificates with same subjectsIllegalStateException - if
setCertificateVerifier(CertificateVerifier) or
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
is already set.setTrustCertificateTypes(org.eclipse.californium.scandium.dtls.CertificateType...)@Deprecated public DtlsConnectorConfig.Builder setCertificateVerifier(CertificateVerifier verifier)
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period.setTrustStore(Certificate[]) is already set.verifier - certificate verifierNullPointerException - if the given certificate verifier is
nullIllegalStateException - if
setTrustStore(Certificate[]) or
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
is already set.setTrustCertificateTypes(org.eclipse.californium.scandium.dtls.CertificateType...)public DtlsConnectorConfig.Builder setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier verifier)
setTrustStore(Certificate[]) is already set.verifier - new advanced certificate verifierNullPointerException - if the given certificate verifier is
nullIllegalStateException - if
setTrustStore(Certificate[]) is already set.setTrustCertificateTypes(org.eclipse.californium.scandium.dtls.CertificateType...)public DtlsConnectorConfig.Builder setApplicationLevelInfoSupplier(ApplicationLevelInfoSupplier supplier)
supplier - The supplier.NullPointerException - if supplier is null.@Deprecated public DtlsConnectorConfig.Builder setRpkTrustStore(TrustedRpkStore store)
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period.store - the raw public keys trust storesetTrustCertificateTypes(org.eclipse.californium.scandium.dtls.CertificateType...)@Deprecated public DtlsConnectorConfig.Builder setRpkTrustAll()
setAdvancedCertificateVerifier(NewAdvancedCertificateVerifier)
instead. StaticNewAdvancedCertificateVerifier may
be used for simple setups. More complex ones may require a
custom implementation. During migration you may also use
the BridgeCertificateVerifier in order to use old
implementations for that period.public DtlsConnectorConfig.Builder setTrustCertificateTypes(CertificateType... certificateTypes)
build() will throw a
IllegalStateException.certificateTypes - certificate types in order of preferenceNullPointerException - if the given certificate types is
nullIllegalArgumentException - if the certificate types are emptysetRpkTrustAll(),
setRpkTrustStore(TrustedRpkStore),
setCertificateVerifier(CertificateVerifier),
setTrustStore(Certificate[])public DtlsConnectorConfig.Builder setMaxDeferredProcessedOutgoingApplicationDataMessages(int maxDeferredProcessedOutgoingApplicationDataMessages)
maxDeferredProcessedOutgoingApplicationDataMessages - maximum
number of deferred processed messagesIllegalArgumentException - if the given limit is < 0.public DtlsConnectorConfig.Builder setMaxDeferredProcessedIncomingRecordsSize(int maxDeferredProcessedIncomingRecordsSize)
maxDeferredProcessedIncomingRecordsSize - maximum size of all
deferred handshake recordsIllegalArgumentException - if the given limit is < 0.public DtlsConnectorConfig.Builder setMaxConnections(int maxConnections)
An active connection is a connection that has been used within the last staleConnectionThreshold seconds. After that it is considered to be stale.
Once the maximum number of active connections is reached, new connections will only be accepted by the connector, if stale connections exist (which will be evicted one-by-one on an oldest-first basis).
The default value of this property is DtlsConnectorConfig.DEFAULT_MAX_CONNECTIONS.
maxConnections - The maximum number of active connections to support.IllegalArgumentException - if the given limit is < 1.setStaleConnectionThreshold(long)public DtlsConnectorConfig.Builder setStaleConnectionThreshold(long threshold)
Once a connection becomes stale, it is eligible for eviction when a peer wants to establish a new connection and the connector already has maxConnections connections with peers established. Note that a connection is no longer considered stale, once data is being exchanged over it before it got evicted.
threshold - The number of seconds.IllegalArgumentException - if the given threshold is < 1.setMaxConnections(int)public DtlsConnectorConfig.Builder setConnectionIdGenerator(ConnectionIdGenerator connectionIdGenerator)
connectionIdGenerator - connection id generator. null
for not supported. The generator may only support the use
of a connection id without using it by itself. In that
case ConnectionIdGenerator.useConnectionId() must
return false.public DtlsConnectorConfig.Builder setConnectionThreadCount(int threadCount)
The default value is 6 * #(CPU cores).
threadCount - the number of threads.public DtlsConnectorConfig.Builder setReceiverThreadCount(int threadCount)
The default value is half of #(CPU cores).
threadCount - the number of threads.public DtlsConnectorConfig.Builder setAutoResumptionTimeoutMillis(Long timeoutInMillis)
The default value is null, for no automatic session
resumption. The configured value may be overridden by the endpoint
context attribute DtlsEndpointContext.KEY_RESUMPTION_TIMEOUT.
timeoutInMillis - the number of milliseconds. Usually values
around 30000 milliseconds are useful, depending on the
setup of NATS on the path. Smaller timeouts are only
useful for unit test, they would trigger too many
resumption handshakes.IllegalArgumentException - if the timeout is below 1
millisecondpublic DtlsConnectorConfig.Builder setSniEnabled(boolean flag)
The default value of this property is null. If this property
is not set explicitly, then the build() method
will set it to true.
flag - true if SNI should be used.public DtlsConnectorConfig.Builder setVerifyPeersOnResumptionThreshold(int threshold)
setMaxConnections(int), whether
a HELLO_VERIFY_REQUEST should be used also for session resumption.
Note: a value larger than 0 will call
SessionCache.get(org.eclipse.californium.scandium.dtls.SessionId).
If that implementation is expensive, please ensure, that this value
is configured with 0. Otherwise, CLIENT_HELLOs with invalid
session ids may be spoofed and gets too expensive.
Note: if spoofing is considered to be relevant for the used network
environment, please set this to 0 in order to disable this
function.threshold - 0 := always use HELLO_VERIFY_REQUEST, 1 ... 100 :=
dynamically determine to use HELLO_VERIFY_REQUEST. Default
is based on
DtlsConnectorConfig.DEFAULT_VERIFY_PEERS_ON_RESUMPTION_THRESHOLD_IN_PERCENTIllegalArgumentException - if threshold is not between 0 and
100public DtlsConnectorConfig.Builder setNoServerSessionId(boolean flag)
flag - true if no session id is used by this server.IllegalArgumentException - if no session id should be used and
the configuration is for client only.public DtlsConnectorConfig.Builder setUseAntiReplayFilter(boolean enable)
enable - true to enable filter. Default true.IllegalArgumentException - if window filter is active.@Deprecated public DtlsConnectorConfig.Builder setUseWindowFilter(boolean enable)
enable - true to enable filter. Default false.IllegalArgumentException - if anti replay window filter is
active.public DtlsConnectorConfig.Builder setUseExtendedWindowFilter(int level)
-1 will set that calculated value to 0.
Messages between lower receive window boundary and that calculated
value will pass the filter, for other messages the filter is applied.level - value to extend lower receive window boundary, 0
to disable the extended lower boundary. For backwards
compatibility use -1, to extend the lower boundary
down to 0, Default 0 for disabled.IllegalArgumentException - if anti replay window filter is
active.public DtlsConnectorConfig.Builder setCidUpdateAddressOnNewerRecordFilter(boolean enable)
setConnectionIdGenerator(ConnectionIdGenerator) is provided,
which "uses" CID. If the "anti-replay-filter is switched off, it's
not recommended to switch this off also!enable - true to enable filter, false to disable
filter. Default true.public DtlsConnectorConfig.Builder setUseHandshakeStateValidation(boolean enable)
enable - true to enable state machine. Default
true.public DtlsConnectorConfig.Builder setKeyUsageVerification(boolean enable)
enable - true to verify the key usage of x509
certificates. Default true.public DtlsConnectorConfig.Builder setUseTruncatedCertificatePathForClientsCertificateMessage(boolean enable)
CertificateRequest for the client's
CertificateMessage.enable - true to truncate the certificate path according
the received certificate authorities. Default
true.public DtlsConnectorConfig.Builder setUseTruncatedCertificatePathForValidation(boolean enable)
enable - true to truncate the certificate path according
the available trusted certificates. Default true.public DtlsConnectorConfig.Builder setLoggingTag(String tag)
tag - logging tag of configure instancepublic DtlsConnectorConfig.Builder setConnectionListener(ConnectionListener connectionListener)
public DtlsConnectorConfig getIncompleteConfig()
DtlsConnectorConfig use build()
instead.public DtlsConnectorConfig build()
DtlsConnectorConfig based on the properties
set on this builder.
If the supportedCipherSuites property has not been set, the builder tries to derive a reasonable set of cipher suites from the pskStore and identity properties as follows:
{TLS_PSK_WITH_AES_128_CCM_8,
TLS_PSK_WITH_AES_128_CBC_SHA256}{TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8,
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256}{TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8, TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,
TLS_PSK_WITH_AES_128_CCM_8, TLS_PSK_WITH_AES_128_CBC_SHA256}IllegalStateException - if the configuration is inconsistentCopyright © 2023 Eclipse Foundation. All rights reserved.