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.xml140
1 files changed, 78 insertions, 62 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index 3029977745..586452efd4 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -28,7 +28,7 @@
<rev></rev>
<file>ssl.xml</file>
</header>
- <module>ssl</module>
+ <module since="">ssl</module>
<modulesummary>Interface Functions for Secure Socket Layer</modulesummary>
<description>
<p>
@@ -83,8 +83,9 @@
<p><c>| {ciphers, ciphers()}</c></p>
<p><c>| {user_lookup_fun, {fun(), term()}}, {psk_identity, string()},
{srp_identity, {string(), string()}}</c></p>
- <p><c>| {reuse_sessions, boolean()}</c></p>
- <p><c>| {reuse_session, fun()} {next_protocols_advertised, [binary()]}</c></p>
+ <p><c>| {reuse_sessions, boolean() | save()}</c></p>
+ <p><c>| {reuse_session, fun() | binary()} </c></p>
+ <p><c>| {next_protocols_advertised, [binary()]}</c></p>
<p><c>| {client_preferred_next_protocols, {client | server,
[binary()]} | {client | server, [binary()], binary()}}</c></p>
<p><c>| {log_alert, boolean()}</c></p>
@@ -575,11 +576,23 @@ fun(srp, Username :: string(), UserState :: term()) ->
<item><p>In mode <c>verify_none</c> the default behavior is to allow
all x509-path validation errors. See also option <c>verify_fun</c>.</p>
</item>
+
+ <tag><marker id="client_reuse_session"/><c>{reuse_session, binary()}</c></tag>
+ <item><p>Reuses a specific session earlier saved with the option
+ <c>{reuse_sessions, save} since ssl-9.2</c>
+ </p></item>
- <tag><c>{reuse_sessions, boolean()}</c></tag>
- <item><p>Specifies if the client is to try to reuse sessions
- when possible.</p></item>
-
+ <tag><c>{reuse_sessions, boolean() | save}</c></tag>
+ <item><p>When <c>save</c> is specified a new connection will be negotiated
+ and saved for later reuse. The session ID can be fetched with
+ <seealso marker="#connection_information">connection_information/2</seealso>
+ and used with the client option <seealso marker="#client_reuse_session">reuse_session</seealso>
+ The boolean value true specifies that if possible, automatized session reuse will
+ be performed. If a new session is created, and is unique in regard
+ to previous stored sessions, it will be saved for possible later reuse.
+ Value <c>save</c> since ssl-9.2
+ </p></item>
+
<tag><c>{cacerts, [public_key:der_encoded()]}</c></tag>
<item><p>The DER-encoded trusted certificates. If this option
is supplied it overrides option <c>cacertfile</c>.</p></item>
@@ -758,11 +771,14 @@ fun(srp, Username :: string(), UserState :: term()) ->
</item>
<tag><c>{reuse_sessions, boolean()}</c></tag>
- <item><p>Specifies if the server is to agree to reuse sessions
- when requested by the clients. See also option <c>reuse_session</c>.
+ <item><p>The boolean value true specifies that the server will
+ agree to reuse sessions. Setting it to false will result in an empty
+ session table, that is no sessions will be reused.
+ See also option <seealso marker="#server_reuse_session">reuse_session</seealso>
</p></item>
- <tag><c>{reuse_session, fun(SuggestedSessionId,
+ <tag><marker id="server_reuse_session"/>
+ <c>{reuse_session, fun(SuggestedSessionId,
PeerCert, Compression, CipherSuite) -> boolean()}</c></tag>
<item><p>Enables the TLS/DTLS server to have a local policy
for deciding if a session is to be reused or not.
@@ -873,7 +889,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
<funcs>
<func>
- <name>append_cipher_suites(Deferred, Suites) -> ciphers() </name>
+ <name since="OTP 20.3">append_cipher_suites(Deferred, Suites) -> ciphers() </name>
<fsummary></fsummary>
<type>
<v>Deferred = ciphers() | cipher_filters() </v>
@@ -889,8 +905,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>cipher_suites() -></name>
- <name>cipher_suites(Type) -> old_ciphers()</name>
+ <name since="OTP R14B">cipher_suites() -></name>
+ <name since="OTP R14B">cipher_suites(Type) -> old_ciphers()</name>
<fsummary>Returns a list of supported cipher suites.</fsummary>
<type>
<v>Type = erlang | openssl | all</v>
@@ -901,7 +917,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>cipher_suites(Supported, Version) -> ciphers()</name>
+ <name since="OTP 20.3">cipher_suites(Supported, Version) -> ciphers()</name>
<fsummary>Returns a list of all default or
all supported cipher suites.</fsummary>
<type>
@@ -915,8 +931,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>eccs() -></name>
- <name>eccs(protocol_version()) -> [named_curve()]</name>
+ <name since="OTP 19.2">eccs() -></name>
+ <name since="OTP 19.2">eccs(protocol_version()) -> [named_curve()]</name>
<fsummary>Returns a list of supported ECCs.</fsummary>
<desc><p>Returns a list of supported ECCs. <c>eccs()</c>
@@ -926,7 +942,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>clear_pem_cache() -> ok </name>
+ <name since="OTP 17.5">clear_pem_cache() -> ok </name>
<fsummary> Clears the pem cache</fsummary>
<desc><p>PEM files, used by ssl API-functions, are cached. The
@@ -938,8 +954,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>connect(Socket, SslOptions) -> </name>
- <name>connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext}
+ <name since="OTP R14B">connect(Socket, SslOptions) -> </name>
+ <name since="">connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext}
| {error, Reason}</name>
<fsummary>Upgrades a <c>gen_tcp</c>, or
equivalent, connected socket to an TLS socket.</fsummary>
@@ -975,8 +991,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>connect(Host, Port, Options) -></name>
- <name>connect(Host, Port, Options, Timeout) ->
+ <name since="">connect(Host, Port, Options) -></name>
+ <name since="">connect(Host, Port, Options, Timeout) ->
{ok, SslSocket}| {ok, SslSocket, Ext} | {error, Reason}</name>
<fsummary>Opens an TLS/DTLS connection to <c>Host</c>, <c>Port</c>.</fsummary>
<type>
@@ -1018,7 +1034,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>close(SslSocket) -> ok | {error, Reason}</name>
+ <name since="">close(SslSocket) -> ok | {error, Reason}</name>
<fsummary>Closes an TLS/DTLS connection.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1029,7 +1045,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}</name>
+ <name since="OTP 18.1">close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}</name>
<fsummary>Closes an TLS connection.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1044,7 +1060,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>controlling_process(SslSocket, NewOwner) ->
+ <name since="">controlling_process(SslSocket, NewOwner) ->
ok | {error, Reason}</name>
<fsummary>Assigns a new controlling process to the
TLS/DTLS socket.</fsummary>
@@ -1060,7 +1076,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>connection_information(SslSocket) ->
+ <name since="OTP 18.0">connection_information(SslSocket) ->
{ok, Result} | {error, Reason} </name>
<fsummary>Returns all the connection information.
</fsummary>
@@ -1081,7 +1097,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>connection_information(SslSocket, Items) ->
+ <name since="OTP 18.0">connection_information(SslSocket, Items) ->
{ok, Result} | {error, Reason} </name>
<fsummary>Returns the requested connection information.
</fsummary>
@@ -1103,7 +1119,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>filter_cipher_suites(Suites, Filters) -> ciphers()</name>
+ <name since="OTP 20.3">filter_cipher_suites(Suites, Filters) -> ciphers()</name>
<fsummary></fsummary>
<type>
<v> Suites = ciphers()</v>
@@ -1118,7 +1134,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>format_error(Reason) -> string()</name>
+ <name since="">format_error(Reason) -> string()</name>
<fsummary>Returns an error string.</fsummary>
<type>
<v>Reason = term()</v>
@@ -1129,7 +1145,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>getopts(SslSocket, OptionNames) ->
+ <name since="">getopts(SslSocket, OptionNames) ->
{ok, [socketoption()]} | {error, Reason}</name>
<fsummary>Gets the values of the specified options.</fsummary>
<type>
@@ -1143,9 +1159,9 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>getstat(SslSocket) ->
+ <name since="OTP 19.0">getstat(SslSocket) ->
{ok, OptionValues} | {error, inet:posix()}</name>
- <name>getstat(SslSocket, OptionNames) ->
+ <name since="OTP 19.0">getstat(SslSocket, OptionNames) ->
{ok, OptionValues} | {error, inet:posix()}</name>
<fsummary>Get one or more statistic options for a socket</fsummary>
<type>
@@ -1160,8 +1176,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>handshake(HsSocket) -> </name>
- <name>handshake(HsSocket, Timeout) -> {ok, SslSocket} | {error, Reason}</name>
+ <name since="OTP 21.0">handshake(HsSocket) -> </name>
+ <name since="OTP 21.0">handshake(HsSocket, Timeout) -> {ok, SslSocket} | {error, Reason}</name>
<fsummary>Performs server-side SSL/TLS handshake.</fsummary>
<type>
<v>HsSocket = SslSocket = sslsocket()</v>
@@ -1175,8 +1191,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>handshake(Socket, SslOptions) -> </name>
- <name>handshake(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason}</name>
+ <name since="OTP 21.0">handshake(Socket, SslOptions) -> </name>
+ <name since="OTP 21.0">handshake(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason}</name>
<fsummary>Performs server-side SSL/TLS/DTLS handshake.</fsummary>
<type>
<v>Socket = socket() | sslsocket() </v>
@@ -1214,7 +1230,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>handshake_cancel(SslSocket) -> ok </name>
+ <name since="OTP 21.0">handshake_cancel(SslSocket) -> ok </name>
<fsummary>Cancel handshake with a fatal alert</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1225,8 +1241,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>handshake_continue(HsSocket, SSLOptions) -> {ok, SslSocket} | {error, Reason}</name>
- <name>handshake_continue(HsSocket, SSLOptions, Timeout) -> {ok, SslSocket} | {error, Reason}</name>
+ <name since="OTP 21.0">handshake_continue(HsSocket, SSLOptions) -> {ok, SslSocket} | {error, Reason}</name>
+ <name since="OTP 21.0">handshake_continue(HsSocket, SSLOptions, Timeout) -> {ok, SslSocket} | {error, Reason}</name>
<fsummary>Continue the SSL/TLS handshake.</fsummary>
<type>
<v>HsSocket = SslSocket = sslsocket()</v>
@@ -1240,7 +1256,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>listen(Port, Options) ->
+ <name since="">listen(Port, Options) ->
{ok, ListenSocket} | {error, Reason}</name>
<fsummary>Creates an SSL listen socket.</fsummary>
<type>
@@ -1254,7 +1270,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, protocol_not_negotiated}</name>
+ <name since="OTP 18.0">negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, protocol_not_negotiated}</name>
<fsummary>Returns the protocol negotiated through ALPN or NPN extensions.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1268,7 +1284,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>peercert(SslSocket) -> {ok, Cert} | {error, Reason}</name>
+ <name since="">peercert(SslSocket) -> {ok, Cert} | {error, Reason}</name>
<fsummary>Returns the peer certificate.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1283,7 +1299,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>peername(SslSocket) -> {ok, {Address, Port}} |
+ <name since="">peername(SslSocket) -> {ok, {Address, Port}} |
{error, Reason}</name>
<fsummary>Returns the peer address and port.</fsummary>
<type>
@@ -1297,7 +1313,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>prepend_cipher_suites(Preferred, Suites) -> ciphers()</name>
+ <name since="OTP 20.3">prepend_cipher_suites(Preferred, Suites) -> ciphers()</name>
<fsummary></fsummary>
<type>
<v>Preferred = ciphers() | cipher_filters() </v>
@@ -1313,7 +1329,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()}</name>
+ <name since="OTP R15B01">prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()}</name>
<fsummary>Uses a session Pseudo-Random Function to generate key material.</fsummary>
<type>
<v>Socket = sslsocket()</v>
@@ -1333,8 +1349,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>recv(SslSocket, Length) -> </name>
- <name>recv(SslSocket, Length, Timeout) -> {ok, Data} | {error,
+ <name since="">recv(SslSocket, Length) -> </name>
+ <name since="">recv(SslSocket, Length, Timeout) -> {ok, Data} | {error,
Reason}</name>
<fsummary>Receives data on a socket.</fsummary>
<type>
@@ -1360,7 +1376,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>renegotiate(SslSocket) -> ok | {error, Reason}</name>
+ <name since="OTP R14B">renegotiate(SslSocket) -> ok | {error, Reason}</name>
<fsummary>Initiates a new handshake.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1373,7 +1389,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>send(SslSocket, Data) -> ok | {error, Reason}</name>
+ <name since="">send(SslSocket, Data) -> ok | {error, Reason}</name>
<fsummary>Writes data to a socket.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1387,7 +1403,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>setopts(SslSocket, Options) -> ok | {error, Reason}</name>
+ <name since="">setopts(SslSocket, Options) -> ok | {error, Reason}</name>
<fsummary>Sets socket options.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1400,7 +1416,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>shutdown(SslSocket, How) -> ok | {error, Reason}</name>
+ <name since="OTP R14B">shutdown(SslSocket, How) -> ok | {error, Reason}</name>
<fsummary>Immediately closes a socket.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1418,8 +1434,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>ssl_accept(SslSocket) -> </name>
- <name>ssl_accept(SslSocket, Timeout) -> ok | {error, Reason}</name>
+ <name since="">ssl_accept(SslSocket) -> </name>
+ <name since="">ssl_accept(SslSocket, Timeout) -> ok | {error, Reason}</name>
<fsummary>Performs server-side SSL/TLS handshake.</fsummary>
<type>
<v>SslSocket = sslsocket()</v>
@@ -1433,8 +1449,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>ssl_accept(Socket, SslOptions) -> </name>
- <name>ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}</name>
+ <name since="">ssl_accept(Socket, SslOptions) -> </name>
+ <name since="OTP R14B">ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}</name>
<fsummary>Performs server-side SSL/TLS/DTLS handshake.</fsummary>
<type>
<v>Socket = socket() | sslsocket() </v>
@@ -1449,7 +1465,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>sockname(SslSocket) -> {ok, {Address, Port}} |
+ <name since="">sockname(SslSocket) -> {ok, {Address, Port}} |
{error, Reason}</name>
<fsummary>Returns the local address and port.</fsummary>
<type>
@@ -1464,8 +1480,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>start() -> </name>
- <name>start(Type) -> ok | {error, Reason}</name>
+ <name since="OTP R14B">start() -> </name>
+ <name since="OTP R14B">start(Type) -> ok | {error, Reason}</name>
<fsummary>Starts the SSL application.</fsummary>
<type>
<v>Type = permanent | transient | temporary</v>
@@ -1477,7 +1493,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>stop() -> ok </name>
+ <name since="OTP R14B">stop() -> ok </name>
<fsummary>Stops the SSL application.</fsummary>
<desc>
<p>Stops the SSL application.</p>
@@ -1485,7 +1501,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>suite_to_str(CipherSuite) -> String</name>
+ <name since="OTP 21.0">suite_to_str(CipherSuite) -> String</name>
<fsummary>Returns the string representation of a cipher suite.</fsummary>
<type>
<v>CipherSuite = erl_cipher_suite()</v>
@@ -1497,8 +1513,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>transport_accept(ListenSocket) -></name>
- <name>transport_accept(ListenSocket, Timeout) ->
+ <name since="">transport_accept(ListenSocket) -></name>
+ <name since="">transport_accept(ListenSocket, Timeout) ->
{ok, SslSocket} | {error, Reason}</name>
<fsummary>Accepts an incoming connection and
prepares for <c>ssl_accept</c>.</fsummary>
@@ -1532,7 +1548,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
- <name>versions() -> [versions_info()]</name>
+ <name since="OTP R14B">versions() -> [versions_info()]</name>
<fsummary>Returns version information relevant for the
SSL application.</fsummary>
<type>
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-09 05:50:11 +0000