From 87c56602bc67907f0c689310dd25552e9a30c0d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Fri, 12 Apr 2019 17:13:17 +0200 Subject: ssl: Update standards_compliance.xml Change-Id: I4da2b5c4defeb4e8893e512020d4dbdb96813542 --- lib/ssl/doc/src/standards_compliance.xml | 61 ++++++++++++++++++++++---------- 1 file changed, 43 insertions(+), 18 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/standards_compliance.xml b/lib/ssl/doc/src/standards_compliance.xml index c20bab4e50..25840d0fc6 100644 --- a/lib/ssl/doc/src/standards_compliance.xml +++ b/lib/ssl/doc/src/standards_compliance.xml @@ -126,8 +126,33 @@
TLS 1.3 -

This section describes the current state of standards compliance for TLS 1.3.

-

(C = Compliant, NC = Non-Compliant, P = Partially-Compliant, NA = Not Applicable)

+

OTP-22 introduces basic support for TLS 1.3 on the server side. Basic functionality + covers a simple TLS 1.3 handshake with support of the mandatory extensions + (supported_groups, signature_algorithms, key_share, supported_versions and + signature_algorithms_cert). The server supports a selective set of cryptographic algorithms:

+ + Key Exchange: ECDHE + Groups: all standard groups supported for the Diffie-Hellman key exchange + Ciphers: TLS_AES_128_GCM_SHA256 and TLS_AES_256_GCM_SHA384 + Signature Algorithms: RSA and RSA PSS + Certificates: currently only certificates with RSA keys are supported + +

Other notable features:

+ + The server supports the HelloRetryRequest mechanism + PSK and session resumption not supported + Early data and 0-RTT not supported + Key and Initialization Vector Update not supported + +

For more detailed information see the + Standards Compliance below.

+

Note that the client side is not yet functional. It is planned to be released + later in OTP-22.

 + +

The following table describes the current state of standards compliance for TLS 1.3.

+

(C = Compliant, NC = Non-Compliant, PC = Partially-Compliant, + NA = Not Applicable)

+ Section @@ -155,7 +180,7 @@ RSASSA-PSS signature schemes - P + PC 22 @@ -178,7 +203,7 @@ - P + PC 22 @@ -240,7 +265,7 @@ - P + PC 22 @@ -783,7 +808,7 @@ Server - P + PC 22 @@ -1265,7 +1290,7 @@ Server - P + PC 22 @@ -1379,7 +1404,7 @@ Server - P + PC 22 @@ -1456,7 +1481,7 @@ Server - P + PC 22 @@ -1527,7 +1552,7 @@ Server - P + PC @@ -1762,7 +1787,7 @@ - P + PC 22 @@ -1924,7 +1949,7 @@ - P + PC 22 @@ -1949,7 +1974,7 @@ Digital signatures - P + PC 22 @@ -1997,7 +2022,7 @@ - P + PC 22 @@ -2108,7 +2133,7 @@ TLS 1.3 ServerHello - P + PC 22 @@ -2160,7 +2185,7 @@ - P + PC 22 @@ -2223,7 +2248,7 @@ - P + PC 22 @@ -2289,7 +2314,7 @@ - P + PC 22 -- cgit v1.2.3 From c4b87d79cd6a56a06c776b817885f93b330f7705 Mon Sep 17 00:00:00 2001 From: Kenneth Lundin Date: Fri, 12 Apr 2019 15:10:01 +0200 Subject: ssl: Changed function specs and ssl.xml Changed function specs and ssl.xml for generation of documentation according to the new way. Change-Id: I17b59b80f9072c3d2c20aea1b102f1e9c86987a0 --- lib/ssl/doc/src/ssl.xml | 326 +++++++++--------------------------------------- 1 file changed, 58 insertions(+), 268 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 74a0a0a03e..7c38928890 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -217,10 +217,6 @@ - - - - @@ -342,13 +338,6 @@ - - -

Allows to specify the order of preference for named curves - and to restrict their usage when using a cipher suite supporting them.

- - - @@ -1109,13 +1098,8 @@ fun(srp, Username :: string(), UserState :: term()) -> - append_cipher_suites(Deferred, Suites) -> ciphers() + - - Deferred = ciphers() | - cipher_filters() - Suites = ciphers() -

Make Deferred suites become the least preferred suites, that is put them at the end of the cipher suite list Suites after removing them from Suites if @@ -1126,25 +1110,18 @@ fun(srp, Username :: string(), UserState :: term()) -> - cipher_suites() -> - cipher_suites(Type) -> [old_cipher_suite()] + + Returns a list of supported cipher suites. - - Type = erlang | openssl | all -

Deprecated in OTP 21, use cipher_suites/2 instead.

 - cipher_suites(Supported, Version) -> ciphers() + Returns a list of all default or all supported cipher suites. - - Supported = default | all | anonymous - Version = protocol_version() -

Returns all default or all supported (except anonymous), or all anonymous cipher suites for a TLS version

@@ -1152,16 +1129,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - eccs() -> - eccs(Version) -> NamedCurves + + Returns a list of supported ECCs. - - - Version = protocol_version() - NamedCurves = [named_curve()] - - -

Returns a list of supported ECCs. eccs() is equivalent to calling eccs(Protocol) with all supported protocols and then deduplicating the output.

@@ -1169,9 +1139,8 @@ fun(srp, Username :: string(), UserState :: term()) -> - clear_pem_cache() -> ok + Clears the pem cache -

PEM files, used by ssl API-functions, are cached. The cache is regularly checked to see if any cache entries should be invalidated, however this function provides a way to @@ -1181,19 +1150,10 @@ fun(srp, Username :: string(), UserState :: term()) -> - connect(Socket, Options) -> - connect(Socket, Options, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} - | {error, Reason} + + Upgrades a gen_tcp, or equivalent, connected socket to an TLS socket. - - Socket = socket() - Options = [tls_client_option()] - Timeout = timeout() - SslSocket = sslsocket() - Ext = protocol_extensions() - Reason = closed | timeout | error_alert() -

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

@@ -1225,18 +1185,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - connect(Host, Port, Options) -> - connect(Host, Port, Options, Timeout) -> - {ok, SslSocket}| {ok, SslSocket, Ext} | {error, Reason} + + Opens an TLS/DTLS connection to Host, Port. - - Host = host() - Port = inet:port_number() - Options = [tls_client_option()] - Timeout = timeout() - SslSocket = sslsocket() - Reason = closed | timeout | error_alert() -

Opens an TLS/DTLS connection to Host, Port.

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

Closes an TLS/DTLS connection.

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

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 @@ -1299,15 +1241,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - controlling_process(SslSocket, NewOwner) -> - ok | {error, Reason} + Assigns a new controlling process to the TLS/DTLS socket. - - SslSocket = sslsocket() - NewOwner = pid() - Reason = term() -

Assigns a new controlling process to the SSL socket. A controlling process is the owner of an SSL socket, and receives all messages from the socket.

@@ -1315,17 +1251,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - connection_information(SslSocket) -> - {ok, Result} | {error, Reason} + Returns all the connection information. - - SslSocket = sslsocket() - Item = protocol | selected_cipher_suite | sni_hostname | ecc | session_id | atom() - Meaningful atoms, not specified above, are the ssl option names. - Result = [{Item::atom(), Value::term()}] - Reason = term() -

Returns the most relevant information about the connection, ssl options that are undefined will be filtered out. Note that values that affect the security of the connection will only be returned if explicitly requested by connection_information/2.

@@ -1336,34 +1264,23 @@ fun(srp, Username :: string(), UserState :: term()) -> - connection_information(SslSocket, Items) -> - {ok, Result} | {error, Reason} + Returns the requested connection information. - - SslSocket = sslsocket() - Items = [Item] - Item = protocol | cipher_suite | sni_hostname | ecc | session_id | client_random - | server_random | master_secret | atom() - Note that client_random, server_random and master_secret are values - that affect the security of connection. Meaningful atoms, not specified above, are the ssl option names. - Result = [{Item::atom(), Value::term()}] - Reason = term() -

Returns the requested information items about the connection, if they are defined.

+

Note that client_random, server_random and master_secret are values + that affect the security of connection. Meaningful atoms, not specified + above, are the ssl option names.

+

If only undefined options are requested the resulting list can be empty.

 - filter_cipher_suites(Suites, Filters) -> ciphers() + - - Suites = ciphers() - Filters = cipher_filters() -

Removes cipher suites if any of the filter functions returns false for any part of the cipher suite. This function also calls default filter functions to make sure the cipher @@ -1373,24 +1290,16 @@ fun(srp, Username :: string(), UserState :: term()) -> - format_error(Reason) -> string() + Returns an error string. - - Reason = term() -

Presents the error returned by an SSL function as a printable string.

 - getopts(SslSocket, OptionNames) -> - {ok, [socketoption()]} | {error, Reason} + Gets the values of the specified options. - - Socket = sslsocket() - OptionNames = [atom()] -

Gets the values of the specified socket options.

@@ -1398,16 +1307,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - getstat(SslSocket) -> - {ok, OptionValues} | {error, inet:posix()} - getstat(SslSocket, OptionNames) -> - {ok, OptionValues} | {error, inet:posix()} + + Get one or more statistic options for a socket - - SslSocket = sslsocket() - OptionNames = [atom()] - OptionValues = [{inet:stat_option(), integer()}] -

Gets one or more statistic options for the underlying TCP socket.

See inet:getstat/2 for statistic options description.

@@ -1415,14 +1317,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - handshake(HsSocket) -> - handshake(HsSocket, Timeout) -> {ok, SslSocket} | {error, Reason} + + Performs server-side SSL/TLS handshake. - - HsSocket = SslSocket = sslsocket() - Timeout = timeout() - Reason = closed | timeout | error_alert() -

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

Returns a new TLS/DTLS socket if the handshake is successful.

@@ -1435,19 +1332,11 @@ fun(srp, Username :: string(), UserState :: term()) -> - handshake(Socket, Options) -> - handshake(Socket, Options, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} + + Performs server-side SSL/TLS/DTLS handshake. - - Socket = socket() | socket() - SslSocket = sslsocket() - Ext = protocol_extensions() - Options = [server_option()] - Timeout = timeout() - Reason = closed | timeout | error_alert() - -

If Socket is a ordinary socket(): upgrades a gen_tcp, +

If TcpSocket is a ordinary socket(): upgrades a gen_tcp, or equivalent, socket to an SSL socket, that is, performs the SSL/TLS server-side handshake and returns a TLS socket.

@@ -1481,52 +1370,33 @@ fun(srp, Username :: string(), UserState :: term()) -> - handshake_cancel(SslSocket) -> ok + Cancel handshake with a fatal alert - - SslSocket = sslsocket() -

Cancel the handshake with a fatal USER_CANCELED alert.

 - handshake_continue(HsSocket, Options) -> {ok, SslSocket} | {error, Reason} - handshake_continue(HsSocket, Options, Timeout) -> {ok, SslSocket} | {error, Reason} + + Continue the SSL/TLS handshake. - - HsSocket = SslSocket = sslsocket() - Options = tls_option() - Timeout = timeout() - Reason = closed | timeout | error_alert() -

Continue the SSL/TLS handshake possiby with new, additional or changed options.

 - listen(Port, Options) -> - {ok, ListenSocket} | {error, Reason} + Creates an SSL listen socket. - - Port = inet:port_number() - Options = [server_option()] - ListenSocket = sslsocket() -

Creates an SSL listen socket.

 - negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, protocol_not_negotiated} + Returns the protocol negotiated through ALPN or NPN extensions. - - SslSocket = sslsocket() - Protocol = binary() -

Returns the protocol negotiated through ALPN or NPN extensions. @@ -1535,12 +1405,8 @@ fun(srp, Username :: string(), UserState :: term()) -> - peercert(SslSocket) -> {ok, Cert} | {error, Reason} + Returns the peer certificate. - - SslSocket = sslsocket() - Cert = binary() -

The peer certificate is returned as a DER-encoded binary. The certificate can be decoded with @@ -1550,27 +1416,16 @@ fun(srp, Username :: string(), UserState :: term()) -> - peername(SslSocket) -> {ok, {Address, Port}} | - {error, Reason} + Returns the peer address and port. - - SslSocket = sslsocket() - Address = ipaddress() - Port = inet:port_number() -

Returns the address and port number of the peer.

 - prepend_cipher_suites(Preferred, Suites) -> ciphers() + - - Preferred = ciphers() | - cipher_filters() - Suites = ciphers() -

Make Preferred suites become the most preferred suites that is put them at the head of the cipher suite list Suites after removing them from Suites if @@ -1581,15 +1436,8 @@ fun(srp, Username :: string(), UserState :: term()) -> - prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()} + Uses a session Pseudo-Random Function to generate key material. - - Socket = sslsocket() - Secret = binary() | master_secret - Label = binary() - Seed = [binary() | prf_random()] - WantedLength = non_neg_integer() -

Uses the Pseudo-Random Function (PRF) of a TLS session to generate extra key material. It either takes user-generated values for @@ -1601,16 +1449,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - recv(SslSocket, Length) -> - recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, - Reason} + + Receives data on a socket. - - SslSocket = sslsocket() - Length = integer() - Timeout = timeout() - Data = [char()] | binary() -

Receives a packet from a socket in passive mode. A closed socket is indicated by return value @@ -1628,11 +1469,8 @@ fun(srp, Username :: string(), UserState :: term()) -> - renegotiate(SslSocket) -> ok | {error, Reason} + Initiates a new handshake. - - SslSocket = sslsocket() -

Initiates a new handshake. A notable return value is {error, renegotiation_rejected} indicating that the peer refused to go through with the renegotiation, but the connection @@ -1641,40 +1479,27 @@ fun(srp, Username :: string(), UserState :: term()) -> - send(SslSocket, Data) -> ok | {error, Reason} + Writes data to a socket. - - SslSocket = sslsocket() - Data = iodata() - -

Writes Data to Socket.

+

Writes Data to SslSocket.

A notable return value is {error, closed} indicating that the socket is closed.

 - setopts(SslSocket, Options) -> ok | {error, Reason} + Sets socket options. - - SslSocket = sslsocket() - Options = [socket_option()] -

Sets options according to Options for socket - Socket.

+ SslSocket.

 - shutdown(SslSocket, How) -> ok | {error, Reason} + Immediately closes a socket. - - SslSocket = sslsocket() - How = read | write | read_write - Reason = reason() -

Immediately closes a socket in one or two directions.

How == write means closing the socket for writing, @@ -1686,14 +1511,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - ssl_accept(SslSocket) -> - ssl_accept(SslSocket, Timeout) -> ok | {error, Reason} + + Performs server-side SSL/TLS handshake. - - SslSocket = sslsocket() - Timeout = timeout() - Reason = closed | timeout | error_alert() -

Deprecated in OTP 21, use handshake/[1,2] instead.

handshake/[1,2] always returns a new socket.

 @@ -1701,15 +1521,8 @@ fun(srp, Username :: string(), UserState :: term()) -> - ssl_accept(Socket, Options) -> - ssl_accept(Socket, Options, Timeout) -> {ok, Socket} | ok | {error, Reason} + Performs server-side SSL/TLS/DTLS handshake. - - Socket = socket() | sslsocket() - Options = [server_option()] - Timeout = timeout() - Reason = closed | timeout | error_alert() -

Deprecated in OTP 21, use handshake/[2,3] instead.

handshake/[2,3] always returns a new socket.

 @@ -1717,27 +1530,18 @@ fun(srp, Username :: string(), UserState :: term()) -> - sockname(SslSocket) -> {ok, {Address, Port}} | - {error, Reason} + Returns the local address and port. - - SslSocket = sslsocket() - Address = ip_address() - Port = inet:port_number() -

Returns the local address and port number of socket - Socket.

+ SslSocket.

 - start() -> + start(Type) -> ok | {error, Reason} Starts the SSL application. - - Type = permanent | transient | temporary -

Starts the SSL application. Default type is temporary.

@@ -1745,7 +1549,7 @@ fun(srp, Username :: string(), UserState :: term()) -> - stop() -> ok + Stops the SSL application.

Stops the SSL application.

@@ -1753,28 +1557,18 @@ fun(srp, Username :: string(), UserState :: term()) -> - suite_to_str(CipherSuite) -> String + Returns the string representation of a cipher suite. - - CipherSuite = erl_cipher_suite() - String = string() -

Returns the string representation of a cipher suite.

 - transport_accept(ListenSocket) -> - transport_accept(ListenSocket, Timeout) -> - {ok, SslSocket} | {error, Reason} + + Accepts an incoming connection and prepares for ssl_accept. - - ListenSocket = SslSocket = sslsocket() - Timeout = timeout() - Reason = reason() -

Accepts an incoming connection request on a listen socket. ListenSocket must be a socket returned from @@ -1800,13 +1594,9 @@ fun(srp, Username :: string(), UserState :: term()) -> - versions() -> [versions_info()] + Returns version information relevant for the SSL application. - - versions_info() = {app_vsn, string()} | {supported | available, [ssl_tls_protocol()]} | - {supported_dtls | available_dtls, [dtls_protocol()]} -

Returns version information relevant for the SSL application.

-- cgit v1.2.3 From 3e2e2f502c627feb5a0688f56004aa96ae17701e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Wed, 17 Apr 2019 14:36:45 +0200 Subject: ssl: Fix missing anchor warning Change-Id: Iafbf60765b4635d6a50286080716c67231bb5cd9 --- lib/ssl/doc/src/ssl.xml | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 7c38928890..add31c9698 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -249,6 +249,10 @@ + + + + TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT -- cgit v1.2.3 From 8a47f7f5b7312e6491c2ca72e826832477b351bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Tue, 16 Apr 2019 16:37:21 +0200 Subject: ssl: Fix dialyzer warnings Change-Id: Ic4895195569073916f158a06b95061939f15cfc0 --- lib/ssl/doc/src/ssl.xml | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index add31c9698..69ab522da6 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -136,14 +136,26 @@ - + + + + + - + + + + + - + + + + + @@ -151,9 +163,8 @@ - - - + + @@ -1340,7 +1351,7 @@ fun(srp, Username :: string(), UserState :: term()) -> Performs server-side SSL/TLS/DTLS handshake. -

If TcpSocket is a ordinary socket(): upgrades a gen_tcp, +

If Socket is a ordinary socket(): upgrades a gen_tcp, or equivalent, socket to an SSL socket, that is, performs the SSL/TLS server-side handshake and returns a TLS socket.

-- cgit v1.2.3 From 94254dfffa9cb4b53a95873e1fbbbce4ce7049ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Thu, 18 Apr 2019 14:51:50 +0200 Subject: ssl: Add type specs for http_packet() Change-Id: I07231ceab14d49c740967a0edfc9494328b96a62 --- lib/ssl/doc/src/ssl.xml | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 69ab522da6..422bd6a19d 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -264,6 +264,46 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT -- cgit v1.2.3