From 76943d42da43395f6d3f2dfb7f52e2552a47be26 Mon Sep 17 00:00:00 2001 From: Ingela Anderton Andin Date: Tue, 7 Apr 2015 22:06:39 +0200 Subject: ssl: Document enhancements --- lib/ssl/doc/src/ssl.xml | 56 +++++++++++++++---------------- lib/ssl/doc/src/ssl_app.xml | 6 ++-- lib/ssl/doc/src/ssl_crl_cache.xml | 47 +++++++++++++------------- lib/ssl/doc/src/ssl_protocol.xml | 8 ++--- lib/ssl/doc/src/ssl_session_cache_api.xml | 8 ++--- 5 files changed, 61 insertions(+), 64 deletions(-) (limited to 'lib/ssl/doc') 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 @@

= {verify, verify_type()}

| {verify_fun, {fun(), term()}}

| {fail_if_no_peer_cert, boolean()} {depth, integer()}

-

| {cert, der_encoded()}

+

| {cert, public_key:der_encoded()}

| {certfile, path()}

| {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' - | 'PrivateKeyInfo', der_encoded()}}

+ | 'PrivateKeyInfo', public_key:der_encoded()}}

| {keyfile, path()}

| {password, string()}

-

| {cacerts, [der_encoded()]}

+

| {cacerts, [public_key:der_encoded()]}

| {cacertfile, path()}

-

| {dh, der_encoded()}

+

| {dh, public_key:der_encoded()}

| {dhfile, path()}

| {ciphers, ciphers()}

| {user_lookup_fun, {fun(), term()}}, {psk_identity, string()}, {srp_identity, {string(), string()}}

-

| {ssl_imp, ssl_imp()}

| {reuse_sessions, boolean()}

| {reuse_session, fun()} {next_protocols_advertised, [binary()]}

| {client_preferred_next_protocols, {client | server, @@ -138,7 +137,7 @@

= string()

Represents a file path.

 - der_encoded() + public_key:der_encoded()

= binary()

ASN.1 DER-encoded entity as an Erlang binary.

 @@ -195,7 +194,7 @@ - {cert, der_encoded()} + {cert, public_key:der_encoded()}

The DER-encoded users certificate. If this option is supplied, it overrides option certfile.

 @@ -203,7 +202,7 @@

Path to a file containing the user certificate.

 {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' - |'PrivateKeyInfo', der_encoded()}} + |'PrivateKeyInfo', public_key:der_encoded()}}

The DER-encoded user's private key. If this option is supplied, it overrides option keyfile.

 @@ -217,10 +216,6 @@

String containing the user's password. Only used if the private keyfile is password-protected.

 - {cacerts, [der_encoded()]} -

The DER-encoded trusted certificates. If this option - is supplied it overrides option cacertfile.

 - {ciphers, ciphers()}

Supported cipher suites. The function cipher_suites/0 can be used to find all ciphers that are @@ -229,16 +224,12 @@ (RFC 4279 and RFC 5487), Secure Remote Password - (RFC 5054), + (RFC 5054), 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.

 - {ssl_imp, new | old} -

Has no longer any meaning as the old implementation is - removed; it is ignored.

 - {secure_renegotiate, boolean()}

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

The CA certificates specified for the connection will be used to construct the certificate chain validating the CRLs.

-

The CRLs will be fetched from a local or external cache +

The CRLs will be fetched from a local or external cache see ssl_crl_cache_api(3).

 @@ -455,6 +446,10 @@ fun(srp, Username :: string(), UserState :: term()) -> {reuse_sessions, boolean()}

Specifies if the client is to try to reuse sessions when possible.

 + + {cacerts, [public_key:der_encoded()]} +

The DER-encoded trusted certificates. If this option + is supplied it overrides option cacertfile.

 {cacertfile, path()}

Path to a file containing PEM-encoded CA certificates. The CA @@ -462,7 +457,7 @@ fun(srp, Username :: string(), UserState :: term()) -> client certificate chain.

 - {{alpn_advertised_protocols, [binary()]} + {alpn_advertised_protocols, [binary()]}

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()) -> {psk_identity, string()}

Specifies the identity the client presents to the server. - The matching secret is found by calling user_look_fun.

+ The matching secret is found by calling user_lookup_fun.

 {srp_identity, {Username :: string(), Password :: string()} @@ -508,14 +503,13 @@ fun(srp, Username :: string(), UserState :: term()) -> to the server.

{server_name_indication, hostname()} - - {server_name_indication, disable} - -

Can be specified when upgrading a TCP socket to a TLS - socket to use the TLS Server Name Indication extension.

+

Can be specified when upgrading a TCP socket to a TLS + socket to use the TLS Server Name Indication extension.

 + {server_name_indication, disable} +

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.

 {fallback, boolean()} @@ -523,7 +517,7 @@ fun(srp, Username :: string(), UserState :: term()) ->

Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired TLS version downgrade. Defaults to false

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

+ to implement new clients. But legacy clients that retries connections in the following manner

ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1', 'tlsv1', 'sslv3']}])

ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1', 'sslv3']}, {fallback, true}])

@@ -545,6 +539,10 @@ fun(srp, Username :: string(), UserState :: term()) -> meaning in the server than in the client:

+ + {cacerts, [public_key:der_encoded()]} +

The DER-encoded trusted certificates. If this option + is supplied it overrides option cacertfile.

 {cacertfile, path()}

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.

 - {dh, der_encoded()} + {dh, public_key:der_encoded()}

The DER-encoded Diffie-Hellman parameters. If specified, it overrides option dhfile.

 @@ -577,7 +575,7 @@ fun(srp, Username :: string(), UserState :: term()) -> If set to true, the server fails if the client does not have a certificate to send, that is, sends an empty certificate. If set to false, it fails only if the client sends an invalid - certificate (an empty certificate is considered valid).

+ certificate (an empty certificate is considered valid). Defaults to false.

 {reuse_sessions, boolean()} 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 @@

The environment parameters can be set on the command line, for example:

-

erl ... -ssl protocol_version '[sslv3, tlsv1]' ....

+

erl -ssl protocol_version "['tlsv1.2', 'tlsv1.1']"

- ]]>. + ssl:protocol() ]]>.

Protocol supported by started clients and servers. If this option is not set, it defaults to all protocols currently supported by the ssl application. @@ -91,7 +91,7 @@

ERROR LOGGER AND EVENT HANDLERS -

The ssl applications has no error logger or event handlers.

+

The ssl applications uses the default OTP error logger to log unexpected errors and TLS alerts. The logging of TLS alerts may be turned off with the log_alert option.

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 @@ - insert(CRLSrc) -> ok | {error, Reason} - insert(URI, CRLSrc) -> ok | {error, Reason} - - - CRLSrc = {file, string()} | {der, [ delete(Entries) -> ok | {error, Reason} + + + Entries = http_uri:uri() | {file, string()} | {der, [ public_key:der_encoded() ]} + Reason = term() + + + Delete CRLs from the ssl applications local cache. + + + + insert(CRLSrc) -> ok | {error, Reason} + insert(URI, CRLSrc) -> ok | {error, Reason} + + + CRLSrc = {file, string()} | {der, [ public_key:der_encoded() ]} - URI = http_uri:uri() - Reason = term() - - + URI = http_uri:uri() + Reason = term() + + Insert CRLs into the ssl applications local cache. - - - - - delete(Entries) -> ok | {error, Reason} - - - Entries = http_uri:uri() | {file, string()} | {der, [ public_key:der_encoded() ]} - Reason = term() - - - Delete CRLs from the ssl applications local cache. - - + + \ 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 @@
- 20032013 + 20032015 Ericsson AB. All Rights Reserved. @@ -105,9 +105,9 @@
- Authentication of Sender + Peer Authentication -

Authentication of the sender is done by public key path +

Authentication of the peer is done by public key path validation as defined in RFC 3280. This means basically the following:

@@ -115,7 +115,7 @@ previous one. The certificates attributes are valid. The root certificate is a trusted certificate that is present - in the trusted certificate database kept by the peer./ + in the trusted certificate database kept by the peer.

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 @@ ssl_session_cache_api.xml ssl_session_cache_api - 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. + TLS session cache API - + 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.

DATA TYPES -- cgit v1.2.3