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.xml208
1 files changed, 136 insertions, 72 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index cdf6870c25..18d98e5efb 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -67,15 +67,15 @@
<taglist>
- <tag><c>boolean()</c></tag>
- <item><p><c>= true | false</c></p></item>
+ <tag><c>boolean() =</c></tag>
+ <item><p><c>true | false</c></p></item>
- <tag><c>option()</c></tag>
- <item><p><c>= socketoption() | ssloption() | transportoption()</c></p>
+ <tag><c>option() =</c></tag>
+ <item><p><c>socketoption() | ssloption() | transportoption()</c></p>
</item>
- <tag><c>socketoption()</c></tag>
- <item><p><c>= proplists:property()</c></p>
+ <tag><c>socketoption() =</c></tag>
+ <item><p><c>proplists:property()</c></p>
<p>The default socket options are
<c>[{mode,list},{packet, 0},{header, 0},{active, true}]</c>.</p>
<p>For valid options, see the
@@ -83,32 +83,37 @@
<seealso marker="kernel:gen_tcp">gen_tcp(3)</seealso> manual pages
in Kernel.</p></item>
- <tag><marker id="type-ssloption"></marker><c>ssloption()</c></tag>
- <item><p><c>= {verify, verify_type()}</c></p>
- <p><c>| {verify_fun, {fun(), term()}}</c></p>
- <p><c>| {fail_if_no_peer_cert, boolean()} {depth, integer()}</c></p>
- <p><c>| {cert, public_key:der_encoded()}</c></p>
- <p><c>| {certfile, path()}</c></p>
- <p><c>| {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey'
- | 'PrivateKeyInfo', public_key:der_encoded()}}</c></p>
- <p><c>| {keyfile, path()}</c></p>
- <p><c>| {password, string()}</c></p>
- <p><c>| {cacerts, [public_key:der_encoded()]}</c></p>
- <p><c>| {cacertfile, path()}</c></p>
- <p><c>| {dh, public_key:der_encoded()}</c></p>
- <p><c>| {dhfile, path()}</c></p>
- <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>| {client_preferred_next_protocols, {client | server,
- [binary()]} | {client | server, [binary()], binary()}}</c></p>
- <p><c>| {log_alert, boolean()}</c></p>
- <p><c>| {server_name_indication, hostname() | disable}</c></p></item>
-
- <tag><c>transportoption()</c></tag>
- <item><p><c>= {cb_info, {CallbackModule::atom(), DataTag::atom(),
+ <tag><marker id="type-ssloption"></marker><c>ssloption() =</c></tag>
+ <item>
+ <p><c>{verify, verify_type()}</c></p>
+ <p><c>| {verify_fun, {fun(), term()}}</c></p>
+ <p><c>| {fail_if_no_peer_cert, boolean()} {depth, integer()}</c></p>
+ <p><c>| {cert, public_key:der_encoded()}</c></p>
+ <p><c>| {certfile, path()}</c></p>
+ <p><c>| {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey'
+ | 'PrivateKeyInfo', public_key:der_encoded()}}</c></p>
+ <p><c>| {keyfile, path()}</c></p>
+ <p><c>| {password, string()}</c></p>
+ <p><c>| {cacerts, [public_key:der_encoded()]}</c></p>
+ <p><c>| {cacertfile, path()}</c></p>
+ <p><c>| {dh, public_key:der_encoded()}</c></p>
+ <p><c>| {dhfile, path()}</c></p>
+ <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>| {client_preferred_next_protocols, {client | server,
+ [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_fun, SNIfun::fun()}</c></p>
+ </item>
+
+ <tag><c>transportoption() =</c></tag>
+ <item><p><c>{cb_info, {CallbackModule::atom(), DataTag::atom(),
+
ClosedTag::atom(), ErrTag:atom()}}</c></p>
<p>Defaults to <c>{gen_tcp, tcp, tcp_closed, tcp_error}</c>. Can be used
to customize the transport layer. The callback module must implement a
@@ -118,70 +123,73 @@
The callback <c>gen_tcp</c> is treated specially and calls <c>inet</c>
directly.</p>
<taglist>
- <tag><c>CallbackModule</c></tag>
- <item><p><c>= atom()</c></p></item>
- <tag><c>DataTag</c></tag>
- <item><p><c>= atom()</c></p>
+ <tag><c>CallbackModule =</c></tag>
+ <item><p><c>atom()</c></p></item>
+ <tag><c>DataTag =</c></tag>
+ <item><p><c>atom()</c></p>
<p>Used in socket data message.</p></item>
- <tag><c>ClosedTag</c></tag>
- <item><p><c>= atom()</c></p>
+ <tag><c>ClosedTag =</c></tag>
+ <item><p><c>atom()</c></p>
<p>Used in socket close message.</p></item>
</taglist>
</item>
- <tag><c>verify_type()</c></tag>
- <item><p><c>= verify_none | verify_peer</c></p></item>
+ <tag><c>verify_type() =</c></tag>
+ <item><p><c>verify_none | verify_peer</c></p></item>
- <tag><c>path()</c></tag>
- <item><p><c>= string()</c></p>
+ <tag><c>path() =</c></tag>
+ <item><p><c>string()</c></p>
<p>Represents a file path.</p></item>
- <tag><c>public_key:der_encoded()</c></tag>
- <item><p><c>= binary()</c></p>
+ <tag><c>public_key:der_encoded() =</c></tag>
+ <item><p><c>binary()</c></p>
<p>ASN.1 DER-encoded entity as an Erlang binary.</p></item>
- <tag><c>host()</c></tag>
- <item><p><c>= hostname() | ipaddress()</c></p></item>
+ <tag><c>host() =</c></tag>
+ <item><p><c>hostname() | ipaddress()</c></p></item>
- <tag><c>hostname()</c></tag>
- <item><p><c>= string()</c></p></item>
+ <tag><c>hostname() =</c></tag>
+ <item><p><c>string()</c></p></item>
- <tag><c>ip_address()</c></tag>
- <item><p><c>= {N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6
+ <tag><c>ip_address() =</c></tag>
+ <item><p><c>{N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6
</c></p></item>
- <tag><c>sslsocket()</c></tag>
- <item><p>Opaque to the user.</p></item>
+ <tag><c>sslsocket() =</c></tag>
+ <item><p>opaque()</p></item>
- <tag><c>protocol()</c></tag>
- <item><p><c>= sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item>
+ <tag><c>protocol() =</c></tag>
+ <item><p><c>sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'</c></p></item>
- <tag><c>ciphers()</c></tag>
+ <tag><c>ciphers() =</c></tag>
<item><p><c>= [ciphersuite()] | string()</c></p>
<p>According to old API.</p></item>
- <tag><c>ciphersuite()</c></tag>
- <item><p><c>= {key_exchange(), cipher(), hash()}</c></p></item>
+ <tag><c>ciphersuite() =</c></tag>
+ <item><p><c>{key_exchange(), cipher(), hash()}</c></p></item>
- <tag><c>key_exchange()</c></tag>
- <item><p><c>= rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk
+ <tag><c>key_exchange()=</c></tag>
+ <item><p><c>rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk
| rsa_psk | srp_anon | srp_dss | srp_rsa | ecdh_anon | ecdh_ecdsa
| ecdhe_ecdsa | ecdh_rsa | ecdhe_rsa</c></p></item>
- <tag><c>cipher()</c></tag>
- <item><p><c>= rc4_128 | des_cbc | '3des_ede_cbc'
+ <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>
- <tag><c>hash()</c></tag>
- <item><p><c>= md5 | sha</c></p></item>
+ <tag><c>hash() =</c></tag>
+ <item><p><c>md5 | sha</c></p></item>
- <tag><c>prf_random()</c></tag>
- <item><p><c>= client_random | server_random</c></p></item>
+ <tag><c>prf_random() =</c></tag>
+ <item><p><c>client_random | server_random</c></p></item>
- <tag><c>srp_param_type()</c></tag>
- <item><p><c>= srp_1024 | srp_1536 | srp_2048 | srp_3072
+ <tag><c>srp_param_type() =</c></tag>
+ <item><p><c>srp_1024 | srp_1536 | srp_2048 | srp_3072
| 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>
+
</taglist>
</section>
@@ -268,7 +276,7 @@ atom()}} |
application. It differentiates between the peer
certificate and the CA certificates by using <c>valid_peer</c> or
<c>valid</c> as second argument to the verification fun. See the
- <seealso marker="public_key:cert_records">public_key User's
+ <seealso marker="public_key:public_key_records">public_key User's
Guide</seealso> for definition of <c>#'OTPCertificate'{}</c> and
<c>#'Extension'{}</c>.</p>
@@ -364,10 +372,10 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
empty argument list. The following arguments may be specified for the internal cache.</p>
<taglist>
<tag><c>{http, timeout()}</c></tag>
- <item>
+ <item><p>
Enables fetching of CRLs specified as http URIs in<seealso
- marker="public_key:cert_records"> X509 cerificate extensions.</seealso>
- Requires the OTP inets application.
+ marker="public_key:public_key_records"> X509 cerificate extensions.</seealso>
+ Requires the OTP inets application.</p>
</item>
</taglist>
</item>
@@ -624,7 +632,24 @@ 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>
+ <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 speicific options for
+ that host will override previously specified options.
+
+ The option <c>sni_fun</c>, and <c>sni_hosts</c> are mutually exclusive.</p></item>
+
+ <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 retrive <c>ssloptions()</c> for indicated server.
+ These options will be merged into predefined <c>ssloptions()</c>.
+
+ The function should be defined as:
+ <c>fun(ServerName :: string()) -> ssloptions()</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>
+
</taglist>
</section>
@@ -752,6 +777,45 @@ fun(srp, Username :: string(), UserState :: term()) ->
</func>
<func>
+ <name>connection_information(SslSocket) ->
+ {ok, Info} | {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>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>
+ </func>
+
+ <func>
+ <name>connection_information(SslSocket, Items) ->
+ {ok, Info} | {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>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 sucessfully. The Info is a proplists containing the information you requested.
+ Otherwise, <c>{error, Reason}</c> will be returned.</p>
+ </desc>
+ </func>
+
+ <func>
<name>format_error(Reason) -> string()</name>
<fsummary>Returns an error string.</fsummary>
<type>