public interface SecureDatagramConnection extends UDPDatagramConnection
A SecureDatagramConnection provides support for the Datagram Transport Layer Security protocol DTLS 1.2 ( RFC 6347) or DTLS 1.0 ( RFC 4347) over UDP.
Secure datagram connections are similar to regular datagram connections except that all datagrams are encrypted using the DTLS protocol.
The parameter string describing the target of a connection takes the following form:
dtls://{host}:{port}
Using Connector.open
a secure datagram connection can be only opened
in "client" mode.
Examples:
A secure datagram connection for sending to a server:
dtls://123.156.189.12:1234
A secure datagram connection for sending to a server using an IPv6 address:
dtls://[2001:db8::7]:2345
The port number must be present and is that of the target port; the local port is always dynamically allocated. A receiving port is always opened and security checks occur to insure that the application is allowed by the security policy to listen for and receive secure datagrams.
The SecureDatagramConnection
follows the behavior of the UDPDatagramConnection
and provides the same API semantics with some additional constraints:
Connector.Open
will throw an IOException
.
receive
method only returns datagrams that were received
from the host, that was used during Connector.Open
. Datagrams from
any other host are silently ignored.
getNominalLength
returns the nominal length of the unencrypted datagram.
getMaximumLength
returns the maximum length of the unencrypted datagram.
The SecureDatagramConnection
supports the same connection options as
DatagramConnection
.
The following settings can be used during Connector.open
to
customize the behavior of the connection.
The minimum protocol version of the DTLS protocol can be selected by using an additional ConnectionOption
with a Protocol
value of "DTLS1.0"
or "DTLS1.2"
.
Without an explicit choice the connection defaults to the highest version of
the DTLS protocol as available on the platform.
Customized behavior, such as the selection of a certificate or a cipher suite
can be achieved by using additional ConnectionOptions
as listed below.
The table lists all possible names for protocols and cipher suites;
the set of supported protocols and cipher suites are platform-dependent.
On any attempts to use a protocol unsupported by the platform or if none of the
selected cipher suites can be used for the connection, Connector.open
fails with a ConnectionNotFoundException
.
Name | Type | Values | Description |
---|---|---|---|
"Certificate" | String | Subject distinguished name | Example: "cn=Duke Inc,dc=example,dc=com" |
"Protocol" | String | "DTLS1.0", "DTLS1.2" | The protocol parameter is case insensitive, only one protocol option is permitted. It denotes the minimum requested protocol version. |
"CipherSuite" | String | Those String values in the "Description" column of the TLS Cipher Suite Registry table at http://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml, where the column "DTLS-OK" contains "Y". | Multiple cipher suites may be specified in one Connector.open call
simultaneously. The sequence of these cipher suites indicates the order
in which the negotiation with the communication partner shall be performed. |
Certificate
is used to supply a string containing the Subject distinguished name
of the X.509 certificate in the string representation defined by clause 3 of
RFC 4514.
If the secure connection cannot be established due to errors related to certificates, a
CertificateException
is thrown.
Options with invalid values or the use of "server"-mode options on a "client"
connection must result in IllegalArgumentException
to be thrown from Connector.open
.
Modifier and Type | Method and Description |
---|---|
SecurityInfo |
getSecurityInfo()
Return the security information associated with this connection
when it was opened.
|
getLocalAddress, getLocalPort
getAccessPoints, getMaximumLength, getNominalLength, newDatagram, newDatagram, newDatagram, newDatagram, receive, send
close
SecurityInfo getSecurityInfo() throws java.io.IOException
java.io.IOException
- if an arbitrary connection failure occursCopyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.