From 1ba4c1a4edae3a818b9f6cd934f8e44ef2b420d7 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 Conflicts: lib/ssl/doc/src/ssl.xml lib/ssl/src/ssl.erl --- lib/ssl/doc/src/ssl.xml | 319 +++++++++--------------------------------------- 1 file changed, 58 insertions(+), 261 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 24d063e1bd..c4fd866446 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -208,10 +208,6 @@ - - - - @@ -1071,13 +1067,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 @@ -1088,25 +1079,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

@@ -1114,16 +1098,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.

@@ -1131,9 +1108,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 @@ -1143,19 +1119,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.

@@ -1187,18 +1154,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 @@ -1235,24 +1193,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 @@ -1261,15 +1210,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.

@@ -1277,17 +1220,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.

@@ -1298,34 +1233,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 @@ -1335,24 +1259,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.

@@ -1360,16 +1276,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.

@@ -1377,14 +1286,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.

@@ -1397,19 +1301,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.

@@ -1443,52 +1339,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. @@ -1497,12 +1374,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 @@ -1512,27 +1385,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 @@ -1543,15 +1405,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 @@ -1563,16 +1418,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 @@ -1590,11 +1438,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 @@ -1603,40 +1448,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, @@ -1648,14 +1480,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.

 @@ -1663,15 +1490,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.

 @@ -1679,27 +1499,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.

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

Stops the SSL application.

@@ -1715,28 +1526,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 @@ -1762,13 +1563,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 2a840a9686b160418f5a9c815bc83a2ed58880ab 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 c4fd866446..f33a4f17e6 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -240,6 +240,10 @@ + + + + TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT -- cgit v1.2.3 From 0d160208d41d708fe18325f973fdd8ac849309fc 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 Conflicts: lib/ssl/doc/src/ssl.xml lib/ssl/src/ssl.erl --- lib/ssl/doc/src/ssl.xml | 24 ++++++++++++++++++------ 1 file changed, 18 insertions(+), 6 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index f33a4f17e6..9b3935bbca 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -136,19 +136,31 @@ - + + + + + - + + + + + - + + + + + - - + + @@ -1309,7 +1321,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 e7a51b4877d98be1b76da7cb98892ca46e2a6e7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Wed, 24 Apr 2019 12:42:26 +0200 Subject: ssl: Update function ssl:eccs/1 Remove support of version tuples (e.g. {3,3}) from API function ssl:eccs/1. Update function spec and documentation. Change-Id: I891e42a2ca31c3e06b4edeeb866c0df874f2035b Conflicts: lib/ssl/doc/src/ssl.xml lib/ssl/src/ssl.erl --- lib/ssl/doc/src/ssl.xml | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 9b3935bbca..fcbffb53a3 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -128,7 +128,7 @@ - + @@ -136,26 +136,14 @@ - - - - - - - - - - - - -- cgit v1.2.3 From 8b78203da881bb56e71d44b17b7d335546ad89bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Wed, 24 Apr 2019 13:14:12 +0200 Subject: ssl: Update type spec of ssl:suite_to_str/1 Change-Id: I7987e80cca7af184a9f40cdcd8ea8f07c318ba0d --- lib/ssl/doc/src/ssl.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index fcbffb53a3..9c170d08af 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -1530,7 +1530,7 @@ fun(srp, Username :: string(), UserState :: term()) -> - + Returns the string representation of a cipher suite.

Returns the string representation of a cipher suite.

-- cgit v1.2.3 From 4507360b4701b48cf33f7f2251626da29bc8176a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Wed, 24 Apr 2019 15:10:16 +0200 Subject: ssl: Refer documentation of HttpPacket from erts Do not document http_packet() in ssl but refer to description of erlang:decode_packet/3. Change-Id: Ib2d0e4fc9605e40fe98bb249bc17fc39046d137a Conflicts: lib/ssl/src/ssl.erl --- lib/ssl/doc/src/ssl.xml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 9c170d08af..2ab21f43e0 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -1425,6 +1425,11 @@ fun(srp, Username :: string(), UserState :: term()) -> Receives data on a socket. + See the description of + HttpPacket in + erlang:decode_packet/3 + in ERTS. +

Receives a packet from a socket in passive mode. A closed socket is indicated by return value -- cgit v1.2.3 From 01d2d677916d5143b6e501bb7230d1ad13592ede Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 30 Apr 2019 16:52:11 +0200 Subject: ssl: Fix cherry-pick mistakes --- lib/ssl/doc/src/ssl.xml | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) (limited to 'lib/ssl/doc') diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 2ab21f43e0..c448d345de 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -332,14 +332,7 @@ matters.

 - - - -

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

- - - +

Specifies if to reject renegotiation attempt that does -- cgit v1.2.3