From 07ae4f993de7dc717aec096943aa91b9029bada3 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Fri, 8 Dec 2017 15:16:41 +0100 Subject: ssl: Document DTLS --- lib/ssl/doc/src/ssl.xml | 80 ++++++++++++++++++++++++++----------------------- 1 file changed, 42 insertions(+), 38 deletions(-) (limited to 'lib/ssl/doc/src/ssl.xml') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 8fcda78ed5..ebef8bd69a 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -32,7 +32,7 @@ Interface Functions for Secure Socket Layer

- This module contains interface functions for the SSL/TLS protocol. + This module contains interface functions for the SSL/TLS/DTLS protocol. For detailed information about the supported standards see ssl(6).

@@ -40,7 +40,7 @@
DATA TYPES -

The following data types are used in the functions for SSL:

+

The following data types are used in the functions for SSL/TLS/DTLS:

@@ -56,9 +56,11 @@

The default socket options are [{mode,list},{packet, 0},{header, 0},{active, true}].

For valid options, see the - inet(3) and - gen_tcp(3) manual pages - in Kernel.

+ inet(3), + gen_tcp(3) and + gen_udp(3) + manual pages + in Kernel. Note that stream oriented options such as packet are only relevant for SSL/TLS and not DTLS

ssl_option() = @@ -95,13 +97,14 @@

{cb_info, {CallbackModule::atom(), DataTag::atom(), ClosedTag::atom(), ErrTag:atom()}}

-

Defaults to {gen_tcp, tcp, tcp_closed, tcp_error}. Can be used - to customize the transport layer. The callback module must implement a +

Defaults to {gen_tcp, tcp, tcp_closed, tcp_error} for TLS + and {gen_udp, udp, udp_closed, udp_error} for DTLS. Can be used + to customize the transport layer. For TLS the callback module must implement a reliable transport protocol, behave as gen_tcp, and have functions corresponding to inet:setopts/2, inet:getopts/2, inet:peername/1, inet:sockname/1, and inet:port/1. The callback gen_tcp is treated specially and calls inet - directly.

+ directly.

For DTLS this feature must be considered exprimental. CallbackModule =

atom()

 @@ -184,7 +187,7 @@
- SSL OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT + TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT

The following options have the same meaning in the client and the server:

@@ -289,11 +292,11 @@ atom()}} |

If the verify callback fun returns {fail, Reason}, the verification process is immediately stopped, an alert is - sent to the peer, and the TLS/SSL handshake terminates.

 + sent to the peer, and the TLS/DTLS handshake terminates.

If the verify callback fun returns {valid, UserState}, the verification process continues.

If the verify callback fun always returns - {valid, UserState}, the TLS/SSL handshake does not + {valid, UserState}, the TLS/DTLS handshake does not terminate regarding verification failures and the connection is established.

If called with an extension unknown to the user application, @@ -464,7 +467,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid See also ssl(6).

 {hibernate_after, integer()|undefined} -

When an integer-value is specified, ssl_connection +

When an integer-value is specified, TLS/DTLS-connection goes into hibernation after the specified number of milliseconds of inactivity, thus reducing its memory footprint. When undefined is specified (this is the default), the process @@ -524,7 +527,7 @@ fun(srp, Username :: string(), UserState :: term()) ->

- SSL OPTION DESCRIPTIONS - CLIENT SIDE + TLS/DTLS OPTION DESCRIPTIONS - CLIENT SIDE

The following options are client-specific or have a slightly different meaning in the client than in the server:

@@ -664,7 +667,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
- SSL OPTION DESCRIPTIONS - SERVER SIDE + TLS/DTLS OPTION DESCRIPTIONS - SERVER SIDE

The following options are server-specific or have a slightly different meaning in the server than in the client:

@@ -702,7 +705,7 @@ fun(srp, Username :: string(), UserState :: term()) ->

{fail_if_no_peer_cert, boolean()} -

Used together with {verify, verify_peer} by an SSL server. +

Used together with {verify, verify_peer} by an TLS/DTLS server. If set to true, the server fails if the client does not have a certificate to send, that is, sends an empty certificate. If set to false, it fails only if the client sends an invalid @@ -716,7 +719,7 @@ fun(srp, Username :: string(), UserState :: term()) -> {reuse_session, fun(SuggestedSessionId, PeerCert, Compression, CipherSuite) -> boolean()} -

Enables the SSL server to have a local policy +

Enables the TLS/DTLS server to have a local policy for deciding if a session is to be reused or not. Meaningful only if reuse_sessions is set to true. SuggestedSessionId is a binary(), PeerCert is @@ -814,7 +817,7 @@ fun(srp, Username :: string(), UserState :: term()) ->

General -

When an SSL socket is in active mode (the default), data from the +

When an TLS/DTLS socket is in active mode (the default), data from the socket is delivered to the owner of the socket in the form of messages:

@@ -872,20 +875,20 @@ fun(srp, Username :: string(), UserState :: term()) -> connect(Socket, SslOptions) -> - connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} + connect(Socket, SslOptions, Timeout) -> {ok, TLSSocket} | {error, Reason} Upgrades a gen_tcp, or - equivalent, connected socket to an SSL socket. + equivalent, connected socket to an TLS socket. Socket = socket() SslOptions = [ssl_option()] Timeout = integer() | infinity - SslSocket = sslsocket() + TLSSocket = sslsocket() Reason = term()

Upgrades a gen_tcp, or equivalent, - connected socket to an SSL socket, that is, performs the - client-side ssl handshake.

+ connected socket to an TLS socket, that is, performs the + client-side TLS handshake.

If the option verify is set to verify_peer the option server_name_indication shall also be specified, @@ -899,7 +902,7 @@ fun(srp, Username :: string(), UserState :: term()) -> connect(Host, Port, Options) -> connect(Host, Port, Options, Timeout) -> {ok, SslSocket} | {error, Reason} - Opens an SSL connection to Host, Port. + Opens an TLS/DTLS connection to Host, Port. Host = host() Port = integer() @@ -908,7 +911,7 @@ fun(srp, Username :: string(), UserState :: term()) -> SslSocket = sslsocket() Reason = term() -

Opens an SSL connection to Host, Port.

+

Opens an TLS/DTLS connection to Host, Port.

When the option verify is set to verify_peer the check public_key:pkix_verify_hostname/2 @@ -930,24 +933,24 @@ fun(srp, Username :: string(), UserState :: term()) -> close(SslSocket) -> ok | {error, Reason} - Closes an SSL connection. + Closes an TLS/DTLS connection. SslSocket = sslsocket() Reason = term() -

Closes an SSL connection.

+

Closes an TLS/DTLS connection.

 close(SslSocket, How) -> ok | {ok, port()} | {error, Reason} - Closes an SSL connection. + Closes an TLS connection. SslSocket = sslsocket() How = timeout() | {NewController::pid(), timeout()} Reason = term() -

Closes or downgrades an SSL connection. In the latter case the transport +

Closes or downgrades an TLS connection. In the latter case the transport connection will be handed over to the NewController process after receiving the TLS close alert from the peer. The returned transport socket will have the following options set: [{active, false}, {packet, 0}, {mode, binary}]

@@ -958,7 +961,7 @@ fun(srp, Username :: string(), UserState :: term()) -> controlling_process(SslSocket, NewOwner) -> ok | {error, Reason} Assigns a new controlling process to the - SSL socket. + TLS/DTLS socket. SslSocket = sslsocket() NewOwner = pid() @@ -1121,7 +1124,7 @@ fun(srp, Username :: string(), UserState :: term()) -> extra key material. It either takes user-generated values for Secret and Seed or atoms directing it to use a specific value from the session security parameters.

-

Can only be used with TLS connections; {error, undefined} +

Can only be used with TLS/DTLS connections; {error, undefined} is returned for SSLv3 connections.

 @@ -1221,7 +1224,7 @@ fun(srp, Username :: string(), UserState :: term()) -> Reason = term() -

Performs the SSL/TLS server-side handshake.

+

Performs the SSL/TLS/DTLS server-side handshake.

Socket is a socket as returned by ssl:transport_accept/[1,2]

@@ -1231,7 +1234,7 @@ fun(srp, Username :: string(), UserState :: term()) -> ssl_accept(Socket, SslOptions) -> ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason} - Performs server-side SSL/TLS handshake. + Performs server-side SSL/TLS/DTLS handshake. Socket = socket() | sslsocket() SslOptions = [ssl_option()] @@ -1248,10 +1251,10 @@ fun(srp, Username :: string(), UserState :: term()) -> by calling this function, else the upgrade succeeds or does not succeed depending on timing.

-

If Socket is an sslsocket(): provides extra SSL/TLS +

If Socket is an sslsocket(): provides extra SSL/TLS/DTLS options to those specified in ssl:listen/2 and then performs - the SSL/TLS handshake. + the SSL/TLS/DTLS handshake.

@@ -1310,7 +1313,7 @@ fun(srp, Username :: string(), UserState :: term()) -> The socket returned is to be passed to ssl:ssl_accept[2,3] to complete handshaking, that is, - establishing the SSL/TLS connection.

+ establishing the SSL/TLS/DTLS connection.

The socket returned can only be used with ssl:ssl_accept[2,3]. @@ -1342,17 +1345,17 @@ fun(srp, Username :: string(), UserState :: term()) -> The application version of the SSL application. supported - TLS/SSL versions supported by default. + SSL/TLS/DTLS versions supported by default. Overridden by a version option on connect/[2,3,4], listen/2, and ssl_accept/[1,2,3]. - For the negotiated TLS/SSL version, see ssl:connection_information/1 . available - All TLS/SSL versions supported by the SSL application. + All SSL/TLS/DTLS versions supported by the SSL application. TLS 1.2 requires sufficient support from the Crypto application. @@ -1365,6 +1368,7 @@ fun(srp, Username :: string(), UserState :: term()) -> SEE ALSO

inet(3) and gen_tcp(3) + gen_udp(3)

-- cgit v1.2.3