diff options
Diffstat (limited to 'lib/ssl/doc/src/ssl.xml')
| -rw-r--r-- | lib/ssl/doc/src/ssl.xml | 202 |
1 files changed, 163 insertions, 39 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index e831f73530..916b41742e 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> @@ -155,7 +155,7 @@ <tag><c>cipher() =</c></tag> <item><p><c>rc4_128 | des_cbc | '3des_ede_cbc' - | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm</c></p></item> + | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm | chacha20_poly1305</c></p></item> <tag><c>hash() =</c></tag> <item><p><c>md5 | sha | sha224 | sha256 | sha348 | sha512</c></p></item> @@ -168,7 +168,15 @@ | 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> + + <tag><c>named_curve() =</c></tag> + <item><p><c>sect571r1 | sect571k1 | secp521r1 | brainpoolP512r1 + | sect409k1 | sect409r1 | brainpoolP384r1 | secp384r1 + | sect283k1 | sect283r1 | brainpoolP256r1 | secp256k1 | secp256r1 + | sect239k1 | sect233k1 | sect233r1 | secp224k1 | secp224r1 + | sect193r1 | sect193r2 | secp192k1 | secp192r1 | sect163k1 + | sect163r1 | sect163r2 | secp160k1 | secp160r1 | secp160r2</c></p></item> </taglist> </section> @@ -217,6 +225,11 @@ Anonymous cipher suites are supported for testing purposes only and are not be used when security matters.</p></item> + <tag><c>{eccs, [named_curve()]}</c></tag> + <item><p> Allows to specify the order of preference for named curves + and to restrict their usage when using a cipher suite supporting them. + </p></item> + <tag><c>{secure_renegotiate, boolean()}</c></tag> <item><p>Specifies if to reject renegotiation attempt that does not live up to @@ -331,39 +344,96 @@ 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> + + <tag><c>max_handshake_size</c></tag> + <item> + <p>Integer (24 bits unsigned). Used to limit the size of + valid TLS handshake packets to avoid DoS attacks. + Defaults to 256*1024.</p> + </item> + + </taglist> + </item> <tag><c>{partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | @@ -415,12 +485,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 +619,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 +635,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 +737,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 +746,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> @@ -687,6 +772,11 @@ fun(srp, Username :: string(), UserState :: term()) -> (the default), use the client's preference. </item> + <tag><c>{honor_ecc_order, boolean()}</c></tag> + <item>If true, use the server's preference for ECC curve selection. If false + (the default), use the client's preference. + </item> + <tag><c>{signature_algs, [{hash(), ecdsa | rsa | dsa}]}</c></tag> <item><p> The algorithms specified by this option will be the ones accepted by the server in a signature algorithm @@ -694,6 +784,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> @@ -734,6 +830,17 @@ fun(srp, Username :: string(), UserState :: term()) -> </func> <func> + <name>eccs() -></name> + <name>eccs(protocol()) -> [named_curve()]</name> + <fsummary>Returns a list of supported ECCs.</fsummary> + + <desc><p>Returns a list of supported ECCs. <c>eccs()</c> + is equivalent to calling <c>eccs(Protocol)</c> with all + supported protocols and then deduplicating the output.</p> + </desc> + </func> + + <func> <name>clear_pem_cache() -> ok </name> <fsummary> Clears the pem cache</fsummary> @@ -753,7 +860,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> @@ -828,7 +935,7 @@ fun(srp, Username :: string(), UserState :: term()) -> <fsummary>Returns all the connection information. </fsummary> <type> - <v>Item = protocol | cipher_suite | sni_hostname | atom()</v> + <v>Item = protocol | cipher_suite | sni_hostname | ecc | 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> @@ -883,6 +990,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 +1190,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> |