aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc/src
diff options
context:
space:
mode:
Diffstat (limited to 'lib/ssl/doc/src')
-rw-r--r--lib/ssl/doc/src/book.xml2
-rw-r--r--lib/ssl/doc/src/notes.xml2
-rw-r--r--lib/ssl/doc/src/pkix_certs.xml2
-rw-r--r--lib/ssl/doc/src/release_notes.xml2
-rw-r--r--lib/ssl/doc/src/ssl.xml161
-rw-r--r--lib/ssl/doc/src/ssl_app.xml37
-rw-r--r--lib/ssl/doc/src/ssl_crl_cache_api.xml15
-rw-r--r--lib/ssl/doc/src/ssl_distribution.xml13
-rw-r--r--lib/ssl/doc/src/usersguide.xml2
-rw-r--r--lib/ssl/doc/src/using_ssl.xml2
10 files changed, 177 insertions, 61 deletions
diff --git a/lib/ssl/doc/src/book.xml b/lib/ssl/doc/src/book.xml
index a0890a028d..056c958f0f 100644
--- a/lib/ssl/doc/src/book.xml
+++ b/lib/ssl/doc/src/book.xml
@@ -4,7 +4,7 @@
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<header titlestyle="normal">
<copyright>
- <year>1999</year><year>2013</year>
+ <year>1999</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/ssl/doc/src/notes.xml b/lib/ssl/doc/src/notes.xml
index 5b0b5ead20..c427db24a4 100644
--- a/lib/ssl/doc/src/notes.xml
+++ b/lib/ssl/doc/src/notes.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>1999</year><year>2013</year>
+ <year>1999</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/ssl/doc/src/pkix_certs.xml b/lib/ssl/doc/src/pkix_certs.xml
index a5793af5ca..f365acef4d 100644
--- a/lib/ssl/doc/src/pkix_certs.xml
+++ b/lib/ssl/doc/src/pkix_certs.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/ssl/doc/src/release_notes.xml b/lib/ssl/doc/src/release_notes.xml
index 4c9b18f900..2e263c69a7 100644
--- a/lib/ssl/doc/src/release_notes.xml
+++ b/lib/ssl/doc/src/release_notes.xml
@@ -4,7 +4,7 @@
<part xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>1999</year><year>2013</year>
+ <year>1999</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index e831f73530..abba5aaf59 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1999</year><year>2015</year>
+ <year>1999</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -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>
@@ -168,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>
@@ -331,39 +331,88 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
<tag><c>{crl_check, boolean() | peer | best_effort }</c></tag>
<item>
- Perform CRL (Certificate Revocation List) verification
+ <p>Perform CRL (Certificate Revocation List) verification
<seealso marker="public_key:public_key#pkix_crls_validate-3">
(public_key:pkix_crls_validate/3)</seealso> on all the certificates during the path validation
<seealso
marker="public_key:public_key#pkix_path_validation-3">(public_key:pkix_path_validation/3)
</seealso>
- of the certificate chain. Defaults to false.
+ of the certificate chain. Defaults to <c>false</c>.</p>
- <p><c>peer</c> - check is only performed on
- the peer certificate.</p>
+ <taglist>
+ <tag><c>peer</c></tag>
+ <item>check is only performed on the peer certificate.</item>
- <p><c>best_effort</c> - if certificate revocation status can not be determined
- it will be accepted as valid.</p>
+ <tag><c>best_effort</c></tag>
+ <item>if certificate revocation status can not be determined
+ it will be accepted as valid.</item>
+ </taglist>
<p>The CA certificates specified for the connection will be used to
construct the certificate chain validating the CRLs.</p>
- <p>The CRLs will be fetched from a local or external cache see
+ <p>The CRLs will be fetched from a local or external cache. See
<seealso marker="ssl:ssl_crl_cache_api">ssl_crl_cache_api(3)</seealso>.</p>
</item>
<tag><c>{crl_cache, {Module :: atom(), {DbHandle :: internal | term(), Args :: list()}}}</c></tag>
<item>
- <p>Module defaults to ssl_crl_cache with <c> DbHandle </c> internal and an
- empty argument list. The following arguments may be specified for the internal cache.</p>
+ <p>Specify how to perform lookup and caching of certificate revocation lists.
+ <c>Module</c> defaults to <seealso marker="ssl:ssl_crl_cache">ssl_crl_cache</seealso>
+ with <c> DbHandle </c> being <c>internal</c> and an
+ empty argument list.</p>
+
+ <p>There are two implementations available:</p>
+
<taglist>
- <tag><c>{http, timeout()}</c></tag>
- <item><p>
- Enables fetching of CRLs specified as http URIs in<seealso
- marker="public_key:public_key_records"> X509 certificate extensions.</seealso>
- Requires the OTP inets application.</p>
- </item>
- </taglist>
+ <tag><c>ssl_crl_cache</c></tag>
+ <item>
+ <p>This module maintains a cache of CRLs. CRLs can be
+ added to the cache using the function <seealso
+ marker="ssl:ssl_crl_cache#insert-1">ssl_crl_cache:insert/1</seealso>,
+ and optionally automatically fetched through HTTP if the
+ following argument is specified:</p>
+
+ <taglist>
+ <tag><c>{http, timeout()}</c></tag>
+ <item><p>
+ Enables fetching of CRLs specified as http URIs in<seealso
+ marker="public_key:public_key_records">X509 certificate extensions</seealso>.
+ Requires the OTP inets application.</p>
+ </item>
+ </taglist>
+ </item>
+
+ <tag><c>ssl_crl_hash_dir</c></tag>
+ <item>
+ <p>This module makes use of a directory where CRLs are
+ stored in files named by the hash of the issuer name.</p>
+
+ <p>The file names consist of eight hexadecimal digits
+ followed by <c>.rN</c>, where <c>N</c> is an integer,
+ e.g. <c>1a2b3c4d.r0</c>. For the first version of the
+ CRL, <c>N</c> starts at zero, and for each new version,
+ <c>N</c> is incremented by one. The OpenSSL utility
+ <c>c_rehash</c> creates symlinks according to this
+ pattern.</p>
+
+ <p>For a given hash value, this module finds all
+ consecutive <c>.r*</c> files starting from zero, and those
+ files taken together make up the revocation list. CRL
+ files whose <c>nextUpdate</c> fields are in the past, or
+ that are issued by a different CA that happens to have the
+ same name hash, are excluded.</p>
+
+ <p>The following argument is required:</p>
+
+ <taglist>
+ <tag><c>{dir, string()}</c></tag>
+ <item><p>Specifies the directory in which the CRLs can be found.</p></item>
+ </taglist>
+
+ </item>
+ </taglist>
+
</item>
<tag><c>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} |
@@ -415,12 +464,29 @@ fun(srp, Username :: string(), UserState :: term()) ->
<tag><c>{padding_check, boolean()}</c></tag>
<item><p>Affects TLS-1.0 connections only.
If set to <c>false</c>, it disables the block cipher padding check
- to be able to interoperate with legacy software.</p></item>
+ to be able to interoperate with legacy software.</p>
+ <warning><p>Using <c>{padding_check, boolean()}</c> makes TLS
+ vulnerable to the Poodle attack.</p></warning>
+ </item>
- </taglist>
+
+
+ <tag><c>{beast_mitigation, one_n_minus_one | zero_n | disabled}</c></tag>
+ <item><p>Affects SSL-3.0 and TLS-1.0 connections only. Used to change the BEAST
+ mitigation strategy to interoperate with legacy software.
+ Defaults to <c>one_n_minus_one</c>.</p>
+
+ <p><c>one_n_minus_one</c> - Perform 1/n-1 BEAST mitigation.</p>
+
+ <p><c>zero_n</c> - Perform 0/n BEAST mitigation.</p>
+
+ <p><c>disabled</c> - Disable BEAST mitigation.</p>
+
+ <warning><p>Using <c>{beast_mitigation, disabled}</c> makes SSL or TLS
+ vulnerable to the BEAST attack.</p></warning>
+ </item>
+ </taglist>
- <warning><p>Using <c>{padding_check, boolean()}</c> makes TLS
- vulnerable to the Poodle attack.</p></warning>
</section>
<section>
@@ -532,7 +598,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
TLS handshake. If no lower TLS versions than 1.2 are supported,
the client will send a TLS signature algorithm extension
with the algorithms specified by this option.
- Defaults to
+ Defaults to</p>
<code>[
%% SHA2
@@ -548,13 +614,11 @@ fun(srp, Username :: string(), UserState :: term()) ->
{sha, ecdsa},
{sha, rsa},
{sha, dsa},
-%% MD5
-{md5, rsa}
]</code>
-
+<p>
The algorithms should be in the preferred order.
Selected signature algorithm can restrict which hash functions
- that may be selected.
+ that may be selected. Default support for {md5, rsa} removed in ssl-8.0
</p>
</item>
</taglist>
@@ -652,7 +716,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.
@@ -661,11 +725,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>
@@ -694,6 +758,12 @@ fun(srp, Username :: string(), UserState :: term()) ->
client certificate is requested. For more details see the <seealso marker="#client_signature_algs">corresponding client option</seealso>.
</p> </item>
+ <tag><c>{v2_hello_compatible, boolean()}</c></tag>
+ <item>If true, the server accepts clients that send hello messages on SSL-2.0 format but offers
+ supported SSL/TLS versions. Defaults to false, that is the server will not interoperate with clients that
+ offers SSL-2.0.
+ </item>
+
</taglist>
</section>
@@ -753,7 +823,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>
@@ -883,6 +953,23 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
+ <name>getstat(Socket) ->
+ {ok, OptionValues} | {error, inet:posix()}</name>
+ <name>getstat(Socket, OptionNames) ->
+ {ok, OptionValues} | {error, inet:posix()}</name>
+ <fsummary>Get one or more statistic options for a socket</fsummary>
+ <type>
+ <v>Socket = sslsocket()</v>
+ <v>OptionNames = [atom()]</v>
+ <v>OptionValues = [{inet:stat_option(), integer()}]</v>
+ </type>
+ <desc>
+ <p>Gets one or more statistic options for the underlying TCP socket.</p>
+ <p>See inet:getstat/2 for statistic options description.</p>
+ </desc>
+ </func>
+
+ <func>
<name>listen(Port, Options) ->
{ok, ListenSocket} | {error, Reason}</name>
<fsummary>Creates an SSL listen socket.</fsummary>
@@ -1066,7 +1153,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>
diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml
index 6c82e32a74..0b3fa9a8a9 100644
--- a/lib/ssl/doc/src/ssl_app.xml
+++ b/lib/ssl/doc/src/ssl_app.xml
@@ -4,7 +4,7 @@
<appref>
<header>
<copyright>
- <year>1999</year><year>2015</year>
+ <year>1999</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -43,6 +43,8 @@
<item>For security reasons SSL-2.0 is not supported.</item>
<item>For security reasons SSL-3.0 is no longer supported by default,
but can be configured.</item>
+ <item>For security reasons DES cipher suites are no longer supported by default,
+ but can be configured.</item>
<item>Ephemeral Diffie-Hellman cipher suites are supported,
but not Diffie Hellman Certificates cipher suites.</item>
<item>Elliptic Curve cipher suites are supported if the Crypto
@@ -55,8 +57,8 @@
motivated to implement them.</item>
<item>CRL validation is supported.</item>
<item>Policy certificate extensions are not supported.</item>
- <item>'Server Name Indication' extension client side
- (RFC 6066, Section 3) is supported.</item>
+ <item>'Server Name Indication' extension
+ (<url href="http://www.ietf.org/rfc/rfc6066.txt">RFC 6066</url>) is supported.</item>
</list>
</description>
@@ -92,7 +94,10 @@
to <c>ssl:connect/[2,3]</c> and <c>ssl:listen/2</c>.</p></item>
<tag><c><![CDATA[session_lifetime = integer() <optional>]]></c></tag>
- <item><p>Maximum lifetime of the session data in seconds.</p></item>
+ <item><p>Maximum lifetime of the session data in seconds. Defaults to 24 hours which is the maximum
+ recommended lifetime by <url href="http://www.ietf.org/rfc/5246rfc.txt">RFC 5246</url>. However
+ sessions may be invalidated earlier due to the maximum limitation of the session cache table.
+ </p></item>
<tag><c><![CDATA[session_cb = atom() <optional>]]></c></tag>
<item><p>Name of the session cache callback module that implements
@@ -104,17 +109,25 @@
<item><p>List of extra user-defined arguments to the <c>init</c> function
in the session cache callback module. Defaults to <c>[]</c>.</p></item>
- <tag><c><![CDATA[session_cache_client_max = integer() <optional>]]></c><br/>
- <c><![CDATA[session_cache_server_max = integer() <optional>]]></c></tag>
- <item><p>Limits the growth of the clients/servers session cache,
- if the maximum number of sessions is reached, the current cache entries will
- be invalidated regardless of their remaining lifetime. Defaults to 1000.
- </p></item>
+ <tag><c><![CDATA[session_cache_client_max = integer() <optional>]]></c><br/></tag>
+ <item><p>Limits the growth of the clients session cache, that is
+ how many sessions towards servers that are cached to be used by
+ new client connections. If the maximum number of sessions is
+ reached, the current cache entries will be invalidated
+ regardless of their remaining lifetime. Defaults to
+ 1000.</p></item>
+
+ <tag> <c><![CDATA[session_cache_server_max = integer() <optional>]]></c></tag>
+ <item><p>Limits the growth of the servers session cache, that is
+ how many client sessions are cached by the server. If the
+ maximum number of sessions is reached, the current cache entries
+ will be invalidated regardless of their remaining
+ lifetime. Defaults to 1000.</p></item>
<tag><c><![CDATA[ssl_pem_cache_clean = integer() <optional>]]></c></tag>
<item>
<p>
- Number of milliseconds between PEM cache validations.
+ Number of milliseconds between PEM cache validations. Defaults to 2 minutes.
</p>
<seealso
marker="ssl#clear_pem_cache-0">ssl:clear_pem_cache/0</seealso>
@@ -129,8 +142,6 @@
shutdown gracefully. Defaults to 5000 milliseconds.
</p>
</item>
-
-
</taglist>
</section>
diff --git a/lib/ssl/doc/src/ssl_crl_cache_api.xml b/lib/ssl/doc/src/ssl_crl_cache_api.xml
index 03ac010bfe..7440b6ef04 100644
--- a/lib/ssl/doc/src/ssl_crl_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache_api.xml
@@ -76,10 +76,13 @@
</func>
<func>
+ <name>lookup(DistributionPoint, Issuer, DbHandle) -> not_available | CRLs </name>
<name>lookup(DistributionPoint, DbHandle) -> not_available | CRLs </name>
<fsummary> </fsummary>
<type>
<v> DistributionPoint = dist_point() </v>
+ <v> Issuer = <seealso
+ marker="public_key:public_key">public_key:issuer_name()</seealso> </v>
<v> DbHandle = cache_ref() </v>
<v> CRLs = [<seealso
marker="public_key:public_key">public_key:der_encoded()</seealso>] </v>
@@ -87,6 +90,18 @@
<desc> <p>Lookup the CRLs belonging to the distribution point <c> Distributionpoint</c>.
This function may choose to only look in the cache or to follow distribution point
links depending on how the cache is administrated. </p>
+
+ <p>The <c>Issuer</c> argument contains the issuer name of the
+ certificate to be checked. Normally the returned CRL should
+ be issued by this issuer, except if the <c>cRLIssuer</c> field
+ of <c>DistributionPoint</c> has a value, in which case that
+ value should be used instead.</p>
+
+ <p>In an earlier version of this API, the <c>lookup</c>
+ function received two arguments, omitting <c>Issuer</c>. For
+ compatibility, this is still supported: if there is no
+ <c>lookup/3</c> function in the callback module,
+ <c>lookup/2</c> is called instead.</p>
</desc>
</func>
diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml
index 14f2eb5db9..4bd5f67202 100644
--- a/lib/ssl/doc/src/ssl_distribution.xml
+++ b/lib/ssl/doc/src/ssl_distribution.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2000</year><year>2013</year>
+ <year>2000</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -197,6 +197,9 @@ Eshell V5.0 (abort with ^G)
<item><c>password</c></item>
<item><c>cacertfile</c></item>
<item><c>verify</c></item>
+ <item><c>verify_fun</c> (write as <c>{Module, Function, InitialUserState}</c>)</item>
+ <item><c>crl_check</c></item>
+ <item><c>crl_cache</c> (write as Erlang term)</item>
<item><c>reuse_sessions</c></item>
<item><c>secure_renegotiate</c></item>
<item><c>depth</c></item>
@@ -204,6 +207,10 @@ Eshell V5.0 (abort with ^G)
<item><c>ciphers</c> (use old string format)</item>
</list>
+ <p>Note that <c>verify_fun</c> needs to be written in a different
+ form than the corresponding SSL option, since funs are not
+ accepted on the command line.</p>
+
<p>The server can also take the options <c>dhfile</c> and
<c>fail_if_no_peer_cert</c> (also prefixed).</p>
@@ -211,10 +218,6 @@ Eshell V5.0 (abort with ^G)
initiates a connection to another node. <c>server_</c>-prefixed
options are used when accepting a connection from a remote node.</p>
- <p>More complex options, such as <c>verify_fun</c>, are currently not
- available, but a mechanism to handle such options may be added in
- a future release.</p>
-
<p>Raw socket options, such as <c>packet</c> and <c>size</c> must not
be specified on the command line.</p>
diff --git a/lib/ssl/doc/src/usersguide.xml b/lib/ssl/doc/src/usersguide.xml
index 7bd0ae5c4c..23ccf668c3 100644
--- a/lib/ssl/doc/src/usersguide.xml
+++ b/lib/ssl/doc/src/usersguide.xml
@@ -4,7 +4,7 @@
<part xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>2000</year><year>2013</year>
+ <year>2000</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml
index b6a4bb5bec..f84cd6e391 100644
--- a/lib/ssl/doc/src/using_ssl.xml
+++ b/lib/ssl/doc/src/using_ssl.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2016</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>