aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc/src/ssl.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssl/doc/src/ssl.xml')
-rw-r--r--lib/ssl/doc/src/ssl.xml87
1 files changed, 39 insertions, 48 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index aaf03d1cd8..82bede69d0 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -48,7 +48,7 @@
<item><p><c>true | false</c></p></item>
<tag><c>option() =</c></tag>
- <item><p><c>socketoption() | ssloption() | transportoption()</c></p>
+ <item><p><c>socketoption() | ssl_option() | transport_option()</c></p>
</item>
<tag><c>socketoption() =</c></tag>
@@ -60,7 +60,7 @@
<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages
in Kernel.</p></item>
- <tag><marker id="type-ssloption"/><c>ssloption() =</c></tag>
+ <tag><marker id="type-ssloption"/><c>ssl_option() =</c></tag>
<item>
<p><c>{verify, verify_type()}</c></p>
<p><c>| {verify_fun, {fun(), term()}}</c></p>
@@ -85,11 +85,11 @@
[binary()]} | {client | server, [binary()], binary()}}</c></p>
<p><c>| {log_alert, boolean()}</c></p>
<p><c>| {server_name_indication, hostname() | disable}</c></p>
- <p><c>| {sni_hosts, [{hostname(), ssloptions()}]}</c></p>
+ <p><c>| {sni_hosts, [{hostname(), [ssl_option()]}]}</c></p>
<p><c>| {sni_fun, SNIfun::fun()}</c></p>
</item>
- <tag><c>transportoption() =</c></tag>
+ <tag><c>transport_option() =</c></tag>
<item><p><c>{cb_info, {CallbackModule::atom(), DataTag::atom(),
ClosedTag::atom(), ErrTag:atom()}}</c></p>
@@ -144,7 +144,9 @@
<p>According to old API.</p></item>
<tag><c>ciphersuite() =</c></tag>
- <item><p><c>{key_exchange(), cipher(), hash()}</c></p></item>
+
+ <item><p><c>{key_exchange(), cipher(), MAC::hash()} |
+ {key_exchange(), cipher(), MAC::hash(), PRF::hash()}</c></p></item>
<tag><c>key_exchange()=</c></tag>
<item><p><c>rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk
@@ -156,7 +158,7 @@
| aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm</c></p></item>
<tag><c>hash() =</c></tag>
- <item><p><c>md5 | sha</c></p></item>
+ <item><p><c>md5 | sha | sha224 | sha256 | sha348 | sha512</c></p></item>
<tag><c>prf_random() =</c></tag>
<item><p><c>client_random | server_random</c></p></item>
@@ -166,7 +168,7 @@
| srp_4096 | srp_6144 | srp_8192</c></p></item>
<tag><c>SNIfun::fun()</c></tag>
- <item><p><c>= fun(ServerName :: string()) -> ssloptions()</c></p></item>
+ <item><p><c>= fun(ServerName :: string()) -> [ssl_option()]</c></p></item>
</taglist>
</section>
@@ -269,7 +271,11 @@ atom()}} |
terminate regarding verification failures and the connection is
established.</p></item>
<item><p>If called with an extension unknown to the user application,
- return value <c>{unknown, UserState}</c> is to be used.</p></item>
+ return value <c>{unknown, UserState}</c> is to be used.</p>
+
+ <p>Note that if the fun returns <c>unknown</c> for an extension marked
+ as critical, validation will fail.</p>
+ </item>
</list>
<p>Default option <c>verify_fun</c> in <c>verify_peer mode</c>:</p>
@@ -291,6 +297,8 @@ atom()}} |
<code>
{fun(_,{bad_cert, _}, UserState) ->
{valid, UserState};
+ (_,{extension, #'Extension'{critical = true}}, UserState) ->
+ {valid, UserState};
(_,{extension, _}, UserState) ->
{unknown, UserState};
(_, valid, UserState) ->
@@ -609,7 +617,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
selection. If set to <c>false</c> (the default), use the client
preference.</p></item>
- <tag><c>{sni_hosts, [{hostname(), ssloptions()}]}</c></tag>
+ <tag><c>{sni_hosts, [{hostname(), [ssl_option()]}]}</c></tag>
<item><p>If the server receives a SNI (Server Name Indication) from the client
matching a host listed in the <c>sni_hosts</c> option, the specific options for
that host will override previously specified options.
@@ -618,11 +626,11 @@ fun(srp, Username :: string(), UserState :: term()) ->
<tag><c>{sni_fun, SNIfun::fun()}</c></tag>
<item><p>If the server receives a SNI (Server Name Indication) from the client,
- the given function will be called to retrieve <c>ssloptions()</c> for the indicated server.
- These options will be merged into predefined <c>ssloptions()</c>.
+ the given function will be called to retrieve <c>[ssl_option()]</c> for the indicated server.
+ These options will be merged into predefined <c>[ssl_option()]</c>.
The function should be defined as:
- <c>fun(ServerName :: string()) -> ssloptions()</c>
+ <c>fun(ServerName :: string()) -> [ssl_option()]</c>
and can be specified as a fun or as named <c>fun module:function/1</c>
The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p></item>
@@ -702,7 +710,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
equivalent, connected socket to an SSL socket.</fsummary>
<type>
<v>Socket = socket()</v>
- <v>SslOptions = [ssloption()]</v>
+ <v>SslOptions = [ssl_option()]</v>
<v>Timeout = integer() | infinity</v>
<v>SslSocket = sslsocket()</v>
<v>Reason = term()</v>
@@ -754,20 +762,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
the following options set: <c>[{active, false}, {packet, 0}, {mode, binary}]</c></p>
</desc>
</func>
-
- <func>
- <name>connection_info(SslSocket) ->
- {ok, {ProtocolVersion, CipherSuite}} | {error, Reason}</name>
- <fsummary>Returns the Negotiated Protocol version and cipher suite.
- </fsummary>
- <type>
- <v>CipherSuite = ciphersuite()</v>
- <v>ProtocolVersion = protocol()</v>
- </type>
- <desc><p>Returns the Negotiated Protocol version and cipher suite.</p>
- </desc>
- </func>
-
+
<func>
<name>controlling_process(SslSocket, NewOwner) ->
ok | {error, Reason}</name>
@@ -786,40 +781,36 @@ fun(srp, Username :: string(), UserState :: term()) ->
<func>
<name>connection_information(SslSocket) ->
- {ok, Info} | {error, Reason} </name>
+ {ok, Result} | {error, Reason} </name>
<fsummary>Returns all the connection information.
</fsummary>
<type>
- <v>Info = [InfoTuple]</v>
- <v>InfoTuple = {protocol, Protocol} | {cipher_suite, CipherSuite} | {sni_hostname, SNIHostname}</v>
- <v>CipherSuite = ciphersuite()</v>
- <v>ProtocolVersion = protocol()</v>
- <v>SNIHostname = string()</v>
+ <v>Item = protocol | cipher_suite | sni_hostname | atom()</v>
+ <d>Meaningful atoms, not specified above, are the ssl option names.</d>
+ <v>Result = [{Item::atom(), Value::term()}]</v>
<v>Reason = term()</v>
</type>
- <desc><p>Return all the connection information containing negotiated protocol version, cipher suite, and the hostname of SNI extension.
- Info will be a proplists containing all the connection information on success, otherwise <c>{error, Reason}</c> will be returned.</p>
+ <desc><p>Returns all relevant information about the connection, ssl options that
+ are undefined will be filtered out.</p>
</desc>
</func>
<func>
<name>connection_information(SslSocket, Items) ->
- {ok, Info} | {error, Reason} </name>
+ {ok, Result} | {error, Reason} </name>
<fsummary>Returns the requested connection information.
</fsummary>
<type>
- <v>Items = [Item]</v>
- <v>Item = protocol | cipher_suite | sni_hostname</v>
- <v>Info = [InfoTuple]</v>
- <v>InfoTuple = {protocol, Protocol} | {cipher_suite, CipherSuite} | {sni_hostname, SNIHostname}</v>
- <v>CipherSuite = ciphersuite()</v>
- <v>ProtocolVersion = protocol()</v>
- <v>SNIHostname = string()</v>
+ <v>Items = [Item]</v>
+ <v>Item = protocol | cipher_suite | sni_hostname | atom()</v>
+ <d>Meaningful atoms, not specified above, are the ssl option names.</d>
+ <v>Result = [{Item::atom(), Value::term()}]</v>
<v>Reason = term()</v>
</type>
- <desc><p>Returns the connection information you requested. The connection information you can request contains protocol, cipher_suite, and sni_hostname.
- <c>{ok, Info}</c> will be returned if it executes successfully. <c>Info</c> is a proplist containing the information you requested.
- Otherwise, <c>{error, Reason}</c> will be returned.</p>
+ <desc><p>Returns the requested information items about the connection,
+ if they are defined.</p>
+ <note><p>If only undefined options are requested the
+ resulting list can be empty.</p></note>
</desc>
</func>
@@ -1032,7 +1023,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
<fsummary>Performs server-side SSL/TLS handshake.</fsummary>
<type>
<v>Socket = socket() | sslsocket() </v>
- <v>SslOptions = ssloptions()</v>
+ <v>SslOptions = [ssl_option()]</v>
<v>Timeout = integer()</v>
<v>Reason = term()</v>
</type>
@@ -1146,7 +1137,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
<seealso marker="#listen-2"> listen/2</seealso>, and <seealso
marker="#ssl_accept-2">ssl_accept/[1,2,3]</seealso>.
For the negotiated TLS/SSL version, see <seealso
- marker="#connection_info-1">ssl:connection_info/1
+ marker="#connection_information-1">ssl:connection_information/1
</seealso>.</item>
<tag><c>available</c></tag>
generated by cgit v1.2.3 (git 2.25.1) at 2024-08-04 03:18:25 +0000