aboutsummaryrefslogtreecommitdiffstats
path: root/lib/ssl/doc
diff options
context:
space:
mode:
authorIngela Anderton Andin <[email protected]>2015-04-07 22:06:39 +0200
committerIngela Anderton Andin <[email protected]>2015-04-09 09:11:28 +0200
commit76943d42da43395f6d3f2dfb7f52e2552a47be26 (patch)
tree65ac5e3f5421562ff7c9fc664d22432780f212fc /lib/ssl/doc
parenta0e30203ab652e50215244944f1ffbf12ee3b8ef (diff)
downloadotp-76943d42da43395f6d3f2dfb7f52e2552a47be26.tar.gz
otp-76943d42da43395f6d3f2dfb7f52e2552a47be26.tar.bz2
otp-76943d42da43395f6d3f2dfb7f52e2552a47be26.zip
ssl: Document enhancements
Diffstat (limited to 'lib/ssl/doc')
-rw-r--r--lib/ssl/doc/src/ssl.xml56
-rw-r--r--lib/ssl/doc/src/ssl_app.xml6
-rw-r--r--lib/ssl/doc/src/ssl_crl_cache.xml47
-rw-r--r--lib/ssl/doc/src/ssl_protocol.xml8
-rw-r--r--lib/ssl/doc/src/ssl_session_cache_api.xml8
5 files changed, 61 insertions, 64 deletions
diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml
index f357e90526..d070cb4019 100644
--- a/lib/ssl/doc/src/ssl.xml
+++ b/lib/ssl/doc/src/ssl.xml
@@ -88,20 +88,19 @@
<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, der_encoded()}</c></p>
+ <p><c>| {cert, public_key:der_encoded()}</c></p>
<p><c>| {certfile, path()}</c></p>
<p><c>| {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey'
- | 'PrivateKeyInfo', der_encoded()}}</c></p>
+ | 'PrivateKeyInfo', public_key:der_encoded()}}</c></p>
<p><c>| {keyfile, path()}</c></p>
<p><c>| {password, string()}</c></p>
- <p><c>| {cacerts, [der_encoded()]}</c></p>
+ <p><c>| {cacerts, [public_key:der_encoded()]}</c></p>
<p><c>| {cacertfile, path()}</c></p>
- <p><c>| {dh, der_encoded()}</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>| {ssl_imp, ssl_imp()}</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,
@@ -138,7 +137,7 @@
<item><p><c>= string()</c></p>
<p>Represents a file path.</p></item>
- <tag><c>der_encoded()</c></tag>
+ <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>
@@ -195,7 +194,7 @@
<taglist>
- <tag><c>{cert, der_encoded()}</c></tag>
+ <tag><c>{cert, public_key:der_encoded()}</c></tag>
<item><p>The DER-encoded users certificate. If this option
is supplied, it overrides option <c>certfile</c>.</p></item>
@@ -203,7 +202,7 @@
<item><p>Path to a file containing the user certificate.</p></item>
<tag><c>{key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey'
- |'PrivateKeyInfo', der_encoded()}}</c></tag>
+ |'PrivateKeyInfo', public_key:der_encoded()}}</c></tag>
<item><p>The DER-encoded user's private key. If this option
is supplied, it overrides option <c>keyfile</c>.</p></item>
@@ -217,10 +216,6 @@
<item><p>String containing the user's password. Only used if the
private keyfile is password-protected.</p></item>
- <tag><c>{cacerts, [der_encoded()]}</c></tag>
- <item><p>The DER-encoded trusted certificates. If this option
- is supplied it overrides option <c>cacertfile</c>.</p></item>
-
<tag><c>{ciphers, ciphers()}</c></tag>
<item><p>Supported cipher suites. The function
<c>cipher_suites/0</c> can be used to find all ciphers that are
@@ -229,16 +224,12 @@
(<url href="http://www.ietf.org/rfc/rfc4279.txt">RFC 4279</url> and
<url href="http://www.ietf.org/rfc/rfc5487.txt">RFC 5487</url>),
Secure Remote Password
- (<url href="http://www.ietf.org/rfc/rfc5054.txt">RFC 5054</url>),
+ (<url href="http://www.ietf.org/rfc/rfc5054.txt">RFC 5054</url>), RC4 cipher suites,
and anonymous cipher suites only work if explicitly enabled by
this option; they are supported/enabled by the peer also.
Anonymous cipher suites are supported for testing purposes
only and are not be used when security matters.</p></item>
- <tag><c>{ssl_imp, new | old}</c></tag>
- <item><p>Has no longer any meaning as the old implementation is
- removed; it is ignored.</p></item>
-
<tag><c>{secure_renegotiate, boolean()}</c></tag>
<item><p>Specifies if to reject renegotiation attempt that does
not live up to
@@ -364,7 +355,7 @@ marker="public_key:public_key#pkix_path_validation-3">public_key:pkix_path_valid
<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
+ <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>
@@ -455,6 +446,10 @@ fun(srp, Username :: string(), UserState :: term()) ->
<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>{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>
<tag><c>{cacertfile, path()}</c></tag>
<item><p>Path to a file containing PEM-encoded CA certificates. The CA
@@ -462,7 +457,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
client certificate chain.</p>
</item>
- <tag><c>{{alpn_advertised_protocols, [binary()]}</c></tag>
+ <tag><c>{alpn_advertised_protocols, [binary()]}</c></tag>
<item>
<p>The list of protocols supported by the client to be sent to the
server to be used for an Application-Layer Protocol Negotiation (ALPN).
@@ -499,7 +494,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
<tag><c>{psk_identity, string()}</c></tag>
<item><p>Specifies the identity the client presents to the server.
- The matching secret is found by calling <c>user_look_fun</c>.</p>
+ The matching secret is found by calling <c>user_lookup_fun</c>.</p>
</item>
<tag><c>{srp_identity, {Username :: string(), Password :: string()}
@@ -508,14 +503,13 @@ fun(srp, Username :: string(), UserState :: term()) ->
to the server.</p></item>
<tag><c>{server_name_indication, hostname()}</c></tag>
- <item></item>
- <tag><c>{server_name_indication, disable}</c></tag>
- <item>
- <p>Can be specified when upgrading a TCP socket to a TLS
- socket to use the TLS Server Name Indication extension.</p>
+ <item><p>Can be specified when upgrading a TCP socket to a TLS
+ socket to use the TLS Server Name Indication extension.</p></item>
+ <tag><c>{server_name_indication, disable}</c></tag>
+ <item>
<p>When starting a TLS connection without upgrade, the Server Name
- Indication extension is sent if possible. This option can also be
+ Indication extension is sent if possible. This option can be
used to disable that behavior.</p>
</item>
<tag><c>{fallback, boolean()}</c></tag>
@@ -523,7 +517,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
<p> Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired TLS version downgrade.
Defaults to false</p>
<warning><p>Note this option is not needed in normal TLS usage and should not be used
- to implement new clients. But legacy clients that that retries connections in the following manner</p>
+ to implement new clients. But legacy clients that retries connections in the following manner</p>
<p><c> ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1', 'tlsv1', 'sslv3']}])</c></p>
<p><c> ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1', 'sslv3']}, {fallback, true}])</c></p>
@@ -545,6 +539,10 @@ fun(srp, Username :: string(), UserState :: term()) ->
meaning in the server than in the client:</p>
<taglist>
+
+ <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>
<tag><c>{cacertfile, path()}</c></tag>
<item><p>Path to a file containing PEM-encoded CA
@@ -555,7 +553,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
is no need to verify the client and if there are no
intermediate CAs for the server certificate.</p></item>
- <tag><c>{dh, der_encoded()}</c></tag>
+ <tag><c>{dh, public_key:der_encoded()}</c></tag>
<item><p>The DER-encoded Diffie-Hellman parameters. If specified,
it overrides option <c>dhfile</c>.</p></item>
@@ -577,7 +575,7 @@ fun(srp, Username :: string(), UserState :: term()) ->
If set to <c>true</c>, the server fails if the client does not have
a certificate to send, that is, sends an empty certificate. If set to
<c>false</c>, it fails only if the client sends an invalid
- certificate (an empty certificate is considered valid).</p>
+ certificate (an empty certificate is considered valid). Defaults to false.</p>
</item>
<tag><c>{reuse_sessions, boolean()}</c></tag>
diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml
index 2b2d08124f..43c69ba377 100644
--- a/lib/ssl/doc/src/ssl_app.xml
+++ b/lib/ssl/doc/src/ssl_app.xml
@@ -54,10 +54,10 @@
<p>The environment parameters can be set on the command line,
for example:</p>
- <p><c>erl ... -ssl protocol_version '[sslv3, tlsv1]' ...</c>.</p>
+ <p><c>erl -ssl protocol_version "['tlsv1.2', 'tlsv1.1']"</c></p>
<taglist>
- <tag><c><![CDATA[protocol_version = [sslv3|tlsv1] <optional>]]></c>.</tag>
+ <tag><c><![CDATA[protocol_version = <seealso marker="kernel:error_logger">ssl:protocol()</seealso> <optional>]]></c>.</tag>
<item><p>Protocol supported by started clients and
servers. If this option is not set, it defaults to all
protocols currently supported by the <c>ssl</c> application.
@@ -91,7 +91,7 @@
<section>
<title>ERROR LOGGER AND EVENT HANDLERS</title>
- <p>The <c>ssl</c> applications has no error logger or event handlers.</p>
+ <p>The <c>ssl</c> applications uses the default <seealso marker="kernel:error_logger">OTP error logger</seealso> to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the <c>log_alert</c> option. </p>
</section>
<section>
diff --git a/lib/ssl/doc/src/ssl_crl_cache.xml b/lib/ssl/doc/src/ssl_crl_cache.xml
index ce5bc15215..62bf2ea7b7 100644
--- a/lib/ssl/doc/src/ssl_crl_cache.xml
+++ b/lib/ssl/doc/src/ssl_crl_cache.xml
@@ -36,31 +36,30 @@
<funcs>
<func>
- <name>insert(CRLSrc) -> ok | {error, Reason}</name>
- <name>insert(URI, CRLSrc) -> ok | {error, Reason}</name>
- <fsummary> </fsummary>
- <type>
- <v> CRLSrc = {file, string()} | {der, [ <seealso
+ <name>delete(Entries) -> ok | {error, Reason} </name>
+ <fsummary> </fsummary>
+ <type>
+ <v> Entries = <seealso marker="inets:http_uri">http_uri:uri() </seealso> | {file, string()} | {der, [<seealso
+ marker="public_key:public_key"> public_key:der_encoded() </seealso>]}</v>
+ <v> Reason = term()</v>
+ </type>
+ <desc>
+ Delete CRLs from the ssl applications local cache.
+ </desc>
+ </func>
+ <func>
+ <name>insert(CRLSrc) -> ok | {error, Reason}</name>
+ <name>insert(URI, CRLSrc) -> ok | {error, Reason}</name>
+ <fsummary> </fsummary>
+ <type>
+ <v> CRLSrc = {file, string()} | {der, [ <seealso
marker="public_key:public_key"> public_key:der_encoded() </seealso> ]}</v>
- <v> URI = <seealso marker="inets:http_uri">http_uri:uri() </seealso> </v>
- <v> Reason = term()</v>
- </type>
- <desc>
+ <v> URI = <seealso marker="inets:http_uri">http_uri:uri() </seealso> </v>
+ <v> Reason = term()</v>
+ </type>
+ <desc>
Insert CRLs into the ssl applications local cache.
- </desc>
- </func>
-
- <func>
- <name>delete(Entries) -> ok | {error, Reason} </name>
- <fsummary> </fsummary>
- <type>
- <v> Entries = <seealso marker="inets:http_uri">http_uri:uri() </seealso> | {file, string()} | {der, [<seealso
- marker="public_key:public_key"> public_key:der_encoded() </seealso>]}</v>
- <v> Reason = term()</v>
- </type>
- <desc>
- Delete CRLs from the ssl applications local cache.
- </desc>
- </func>
+ </desc>
+ </func>
</funcs>
</erlref> \ No newline at end of file
diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml
index 79162389ae..20f53c98e1 100644
--- a/lib/ssl/doc/src/ssl_protocol.xml
+++ b/lib/ssl/doc/src/ssl_protocol.xml
@@ -4,7 +4,7 @@
<chapter>
<header>
<copyright>
- <year>2003</year><year>2013</year>
+ <year>2003</year><year>2015</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -105,9 +105,9 @@
</section>
<section>
- <title>Authentication of Sender</title>
+ <title>Peer Authentication</title>
- <p>Authentication of the sender is done by public key path
+ <p>Authentication of the peer is done by public key path
validation as defined in RFC 3280. This means basically
the following:</p>
<list type="bulleted">
@@ -115,7 +115,7 @@
previous one.</item>
<item>The certificates attributes are valid.</item>
<item>The root certificate is a trusted certificate that is present
- in the trusted certificate database kept by the peer./</item>
+ in the trusted certificate database kept by the peer.</item>
</list>
<p>The server always sends a certificate chain as part of
diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml
index 39db03c91c..9cd16c5f58 100644
--- a/lib/ssl/doc/src/ssl_session_cache_api.xml
+++ b/lib/ssl/doc/src/ssl_session_cache_api.xml
@@ -28,11 +28,11 @@
<file>ssl_session_cache_api.xml</file>
</header>
<module>ssl_session_cache_api</module>
- <modulesummary>Defines the API for the TLS session cache so
- that the data storage scheme can be replaced by
- defining a new callback module implementing this API.</modulesummary>
+ <modulesummary>TLS session cache API</modulesummary>
- <description></description>
+ <description>Defines the API for the TLS session cache so
+ that the data storage scheme can be replaced by
+ defining a new callback module implementing this API.</description>
<section>
<title>DATA TYPES</title>