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/src') 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