From 1776467988178ff24376499747fed836b1765e1d Mon Sep 17 00:00:00 2001 From: xsipewe Date: Mon, 16 Mar 2015 14:18:41 +0100 Subject: ssl: Editorial updates --- lib/ssl/doc/src/refman.xml | 4 +- lib/ssl/doc/src/ssl.xml | 1019 +++++++++++++++-------------- lib/ssl/doc/src/ssl_app.xml | 85 ++- lib/ssl/doc/src/ssl_distribution.xml | 255 ++++---- lib/ssl/doc/src/ssl_introduction.xml | 54 ++ lib/ssl/doc/src/ssl_protocol.xml | 126 ++-- lib/ssl/doc/src/ssl_session_cache_api.xml | 115 ++-- lib/ssl/doc/src/usersguide.xml | 5 +- lib/ssl/doc/src/using_ssl.xml | 101 +-- 9 files changed, 957 insertions(+), 807 deletions(-) create mode 100644 lib/ssl/doc/src/ssl_introduction.xml (limited to 'lib/ssl/doc/src') diff --git a/lib/ssl/doc/src/refman.xml b/lib/ssl/doc/src/refman.xml index d5f2219af9..c6ebe5764a 100644 --- a/lib/ssl/doc/src/refman.xml +++ b/lib/ssl/doc/src/refman.xml @@ -1,7 +1,7 @@ - +
19992015 @@ -33,6 +33,6 @@ - + diff --git a/lib/ssl/doc/src/ssl.xml b/lib/ssl/doc/src/ssl.xml index 47b0dbc206..1e6981f7e5 100644 --- a/lib/ssl/doc/src/ssl.xml +++ b/lib/ssl/doc/src/ssl.xml @@ -21,245 +21,282 @@ ssl + + + + ssl.xml
ssl Interface Functions for Secure Socket Layer -

This module contains interface functions to the Secure Socket - Layer. -

+

This module contains interface functions for the SSL.
SSL - ssl requires the crypto and public_key applications. + ssl requires the crypto and public_key + applications. Supported SSL/TLS-versions are SSL-3.0, TLS-1.0, - TLS-1.1 and TLS-1.2. + TLS-1.1, and TLS-1.2. For security reasons SSL-2.0 is not supported. For security reasons SSL-3.0 is no longer supported by default, - but may be configured. - Ephemeral Diffie-Hellman cipher suites are supported + but can be configured. + Ephemeral Diffie-Hellman cipher suites are supported, but not Diffie Hellman Certificates cipher suites. - Elliptic Curve cipher suites are supported if crypto - supports it and named curves are used. + Elliptic Curve cipher suites are supported if the crypto + application supports it and named curves are used. Export cipher suites are not supported as the U.S. lifted its export restrictions in early 2000. IDEA cipher suites are not supported as they have - become deprecated by the latest TLS spec so there is not any - real motivation to implement them. + become deprecated by the latest TLS specification so it is not + motivated to implement them. CRL validation is supported. - Policy certificate extensions are not supported - yet. - Support for 'Server Name Indication' extension client side - (RFC 6066 section 3). + Policy certificate extensions are not supported. + 'Server Name Indication' extension client side + (RFC 6066, Section 3) is supported.
- COMMON DATA TYPES -

The following data types are used in the functions below: -

+ DATA TYPES +

The following data types are used in the functions for ssl:

-

boolean() = true | false

+ -

option() = socketoption() | ssloption() | transportoption()

+ boolean() +

= true | false

 -

socketoption() = proplists:property() - The default socket options are - [{mode,list},{packet, 0},{header, 0},{active, true}]. -

+ option() +

= socketoption() | ssloption() | transportoption()

+ -

For valid options - see inet(3) and - gen_tcp(3). -

- -

ssloption() = {verify, verify_type()} | - {verify_fun, {fun(), term()}} | - {fail_if_no_peer_cert, boolean()} - {depth, integer()} | - {cert, der_encoded()}| {certfile, path()} | - {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo', der_encoded()}} | - {keyfile, path()} | {password, string()} | - {cacerts, [der_encoded()]} | {cacertfile, path()} | - |{dh, 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()} - {alpn_advertised_protocols, [binary()]} | - {alpn_preferred_protocols, [binary()]} | - {next_protocols_advertised, [binary()]} | - {client_preferred_next_protocols, {client | server, [binary()]} | {client | server, [binary()], binary()}} | - {log_alert, boolean()} | {server_name_indication, hostname() | disable} -

- -

transportoption() = {cb_info, {CallbackModule :: atom(), DataTag :: atom(), ClosedTag :: atom(), ErrTag:atom()}} - - defaults to {gen_tcp, tcp, tcp_closed, tcp_error}. Can be used to customize - the transport layer. The callback module must implement a reliable transport - protocol and behave as gen_tcp and in addition have functions corresponding to - inet:setopts/2, inet:getopts/2, inet:peername/1, inet:sockname/1 and inet:port/1. - The callback gen_tcp is treated specially and will call inet directly. -

- -

      CallbackModule = - atom() -

      DataTag = - atom() - tag used in socket data message.

-

      ClosedTag = atom() - tag used in - socket close message.

- -

verify_type() = verify_none | verify_peer

- -

path() = string() - representing a file path.

+ socketoption() +

= proplists:property()

+

The default socket options are + [{mode,list},{packet, 0},{header, 0},{active, true}].

+

For valid options, see the + inet(3) and + gen_tcp(3) manual pages + in kernel.

 + + ssloption() +

= {verify, verify_type()}

+

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

+

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

+

| {cert, der_encoded()}

+

| {certfile, path()}

+

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

+

| {keyfile, path()}

+

| {password, string()}

+

| {cacerts, [der_encoded()]}

+

| {cacertfile, path()}

+

| {dh, 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, + [binary()]} | {client | server, [binary()], binary()}}

+

| {log_alert, boolean()}

+

| {server_name_indication, hostname() | disable}

 + + transportoption() +

= {cb_info, {CallbackModule::atom(), DataTag::atom(), + ClosedTag::atom(), ErrTag:atom()}}

+

Defaults to {gen_tcp, tcp, tcp_closed, tcp_error}. Can be used + to customize the transport layer. The callback module must implement a + reliable transport protocol, behave as gen_tcp, and have functions + corresponding to inet:setopts/2, inet:getopts/2, + inet:peername/1, inet:sockname/1, and inet:port/1. + The callback gen_tcp is treated specially and calls inet + directly.

+ + CallbackModule +

= atom()

 + DataTag +

= atom()

p> +

Used in socket data message.

 + ClosedTag +

= atom()

+

Used in socket close message.

 + + -

der_encoded() = binary() -Asn1 DER encoded entity as an erlang binary.

- -

host() = hostname() | ipaddress()

- -

hostname() = string()

- -

- ip_address() = {N1,N2,N3,N4} % IPv4 - | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6

+ verify_type() +

= verify_none | verify_peer

 -

sslsocket() - opaque to the user.

- -

protocol() = sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'

- -

ciphers() = [ciphersuite()] | string() (according to old API)

- -

ciphersuite() = - {key_exchange(), cipher(), hash()}

- -

key_exchange() = 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 -

+ path() +

= string()

+

Represents a file path.

 + + der_encoded() +

= binary()

+

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

 + + host() +

= hostname() | ipaddress()

 + + hostname() +

= string()

 + + ip_address() +

= {N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6 +

-

cipher() = rc4_128 | des_cbc | '3des_ede_cbc' - | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm

+ sslsocket() +

Opaque to the user.

 -

hash() = md5 | sha -

+ protocol() +

= sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'

 -

prf_random() = client_random | server_random -

+ ciphers() +

= [ciphersuite()] | string()

+

According to old API.

 -

srp_param_type() = srp_1024 | srp_1536 | srp_2048 | srp_3072 - | srp_4096 | srp_6144 | srp_8192

+ ciphersuite() +

= {key_exchange(), cipher(), hash()}

 + key_exchange() +

= 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

 + + cipher() +

= rc4_128 | des_cbc | '3des_ede_cbc' + | aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm

 + + hash() +

= md5 | sha

 + + prf_random() +

= client_random | server_random

 + + srp_param_type() +

= srp_1024 | srp_1536 | srp_2048 | srp_3072 + | srp_4096 | srp_6144 | srp_8192

 + +
SSL OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT -

Options described here are options that are have the same - meaning in the client and the server. -

+

The following options have the same meaning in the client and + the server:

- {cert, der_encoded()} - The DER encoded users certificate. If this option - is supplied it will override the certfile option. + {cert, der_encoded()} +

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

 - {certfile, path()} - Path to a file containing the user's PEM encoded certificate. + {certfile, path()} +

Path to a file containing the user certificate.

 - {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo', der_encoded()}} - The DER encoded users private key. If this option - is supplied it will override the keyfile option. + {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' + |'PrivateKeyInfo', der_encoded()}} +

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

 - {keyfile, path()} - Path to file containing user's - private PEM encoded key. As PEM-files may contain several - entries this option defaults to the same file as given by - certfile option. - - {password, string()} - 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 will override the cacertfile option. - - {ciphers, ciphers()} - The cipher suites that should be supported. The function + {keyfile, path()} +

Path to the file containing the user's + private PEM-encoded key. As PEM-files can contain several + entries, this option defaults to the same file as given by + option certfile.

 + + {password, string()} +

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 - supported by default. cipher_suites(all) may be called - to find all available cipher suites. - Pre-Shared Key (RFC 4279 and + supported by default. cipher_suites(all) can be called + to find all available cipher suites. Pre-Shared Key + (RFC 4279 and RFC 5487), - Secure Remote Password (RFC 5054) + Secure Remote Password + (RFC 5054), and anonymous cipher suites only work if explicitly enabled by - this option and they are supported/enabled by the peer also. - Note that anonymous cipher suites are supported for testing purposes - only and should not be used when security matters. + 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 + RFC 5746. + By default secure_renegotiate is set to false, + that is, secure renegotiation is used if possible, + but it fallback to unsecure renegotiation if the peer + does not support + RFC 5746.

 - {ssl_imp, new | old} - No longer has any meaning as the old implementation has - been removed, it will be ignored. - - - {secure_renegotiate, boolean()} - Specifies if to reject renegotiation attempt that does - not live up to RFC 5746. By default secure_renegotiate is - set to false i.e. secure renegotiation will be used if possible - but it will fallback to unsecure renegotiation if the peer - does not support RFC 5746. - - - {depth, integer()} - - The depth is the maximum number of non-self-issued - intermediate certificates that may follow the peer certificate - in a valid certification path. So if depth is 0 the PEER must - be signed by the trusted ROOT-CA directly, if 1 the path can - be PEER, CA, ROOT-CA, if it is 2 PEER, CA, CA, ROOT-CA and so - on. The default value is 1. - + {depth, integer()} +

Maximum number of non-self-issued + intermediate certificates that can follow the peer certificate + in a valid certification path. So, if depth is 0 the PEER must + be signed by the trusted ROOT-CA directly; if 1 the path can + be PEER, CA, ROOT-CA; if 2 the path can be PEER, CA, CA, + ROOT-CA, and so on. The default value is 1.

 - {verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}} - -

The verification fun should be defined as:

+ {verify_fun, {Verifyfun :: fun(), InitialUserState :: + term()}} +

The verification fun is to be defined as follows:

-fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked, atom()}} | +fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked, +atom()}} | {extension, #'Extension'{}}, InitialUserState :: term()) -> {valid, UserState :: term()} | {valid_peer, UserState :: term()} | {fail, Reason :: term()} | {unknown, UserState :: term()}. -

The verify fun will be called during the X509-path - validation when an error or an extension unknown to the ssl - application is encountered. Additionally it will be called +

The verification fun is called during the X509-path + validation when an error or an extension unknown to the ssl + application is encountered. It is also called when a certificate is considered valid by the path validation to allow access to each certificate in the path to the user - application. Note that it will differentiate between the - peer certificate and CA certificates by using valid_peer or - valid as the second argument to the verify fun. See the public_key User's - Guide for definition of #'OTPCertificate'{} and - #'Extension'{}.

- -

If the verify callback fun returns {fail, Reason}, the - verification process is immediately stopped and an alert is - sent to the peer and the TLS/SSL handshake is terminated. If - the verify callback fun returns {valid, UserState}, the - verification process is continued. If the verify callback fun - always returns {valid, UserState}, the TLS/SSL handshake will - not be terminated with respect to verification failures and - the connection will be established. If called with an - extension unknown to the user application, the return value - {unknown, UserState} should be used.

- -

The default verify_fun option in verify_peer mode:

+ application. It differentiates between the peer + certificate and the CA certificates by using valid_peer or + valid as second argument to the verification fun. See the + public_key User's + Guide for definition of #'OTPCertificate'{} and + #'Extension'{}.

+ + +

If the verify callback fun returns {fail, Reason}, + the verification process is immediately stopped, an alert is + sent to the peer, and the TLS/SSL handshake terminates.

 +

If the verify callback fun returns {valid, UserState}, + the verification process continues.

 +

If the verify callback fun always returns + {valid, UserState}, the TLS/SSL handshake does not + terminate regarding verification failures and the connection is + established.

 +

If called with an extension unknown to the user application, + return value {unknown, UserState} is to be used.

 + + +

Default option verify_fun in verify_peer mode:

{fun(_,{bad_cert, _} = Reason, _) -> @@ -273,7 +310,7 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revo end, []} -

The default verify_fun option in verify_none mode:

+

Default option verify_fun in mode verify_none:

{fun(_,{bad_cert, _}, UserState) -> @@ -287,21 +324,24 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revo end, []} -

Possible path validation errors are given on the form {bad_cert, Reason} where Reason is:

+

The possible path validation errors are given on form + {bad_cert, Reason} where Reason is:

- unknown_ca - No trusted CA was found in the trusted store. The trusted CA is - normally a so called ROOT CA that is a self-signed cert. Trust may - be claimed for an intermediat CA (trusted anchor does not have to be self signed - according to X-509) by using the option partial_chain - - selfsigned_peer - The chain consisted only of one self-signed certificate. - - PKIX X-509-path validation error - Possible such reasons see public_key:pkix_path_validation/3 + unknown_ca +

No trusted CA was found in the trusted store. The trusted CA is + normally a so called ROOT CA, which is a self-signed certificate. Trust can + be claimed for an intermediat CA (trusted anchor does not have to be + self-signed according to X-509) by using option partial_chain.

+ + + selfsigned_peer +

The chain consisted only of one self-signed certificate.

 + + PKIX X-509-path validation error +

For possible reasons, see public_key:pkix_path_validation/3 +

@@ -341,32 +381,30 @@ fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revo - - {partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | unknown_ca - - - Claim an intermediat CA in the chain as trusted. TLS will then perform the public_key:pkix_path_validation/3 - with the selected CA as trusted anchor and the rest of the chain. - - {versions, [protocol()]} - TLS protocol versions that will be supported by started clients and servers. - This option overrides the application environment option protocol_version. If the - environment option is not set it defaults to all versions, except SSL-3.0, supported by the SSL application. See also - ssl(6) - + {partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | + unknown_ca } +

Claim an intermediate CA in the chain as trusted. TLS then + performs public_key:pkix_path_validation/3 + with the selected CA as trusted anchor and the rest of the chain.

 + + {versions, [protocol()]} +

TLS protocol versions supported by started clients and servers. + This option overrides the application environment option + protocol_version. If the environment option is not set, it defaults + to all versions, except SSL-3.0, supported by the ssl application. + See also ssl(6).

 + + {hibernate_after, integer()|undefined} +

When an integer-value is specified, ssl_connection + goes into hibernation after the specified number of milliseconds + of inactivity, thus reducing its memory footprint. When + undefined is specified (this is the default), the process + never goes into hibernation.

 + + {user_lookup_fun, {Lookupfun :: fun(), UserState :: term()}} +

The lookup fun is to defined as follows:

- {hibernate_after, integer()|undefined} - When an integer-value is specified, the ssl_connection - will go into hibernation after the specified number of milliseconds - of inactivity, thus reducing its memory footprint. When - undefined is specified (this is the default), the process - will never go into hibernation. - - - {user_lookup_fun, {Lookupfun :: fun(), UserState :: term()}} - -

The lookup fun should be defined as:

fun(psk, PSKIdentity ::string(), UserState :: term()) -> {ok, SharedSecret :: binary()} | error; @@ -374,59 +412,55 @@ fun(srp, Username :: string(), UserState :: term()) -> {ok, {SRPParams :: srp_param_type(), Salt :: binary(), DerivedKey :: binary()}} | error. -

For Pre-Shared Key (PSK) cipher suites, the lookup fun will - be called by the client and server to determine the shared - secret. When called by the client, PSKIdentity will be set to the - hint presented by the server or undefined. When called by the - server, PSKIdentity is the identity presented by the client. -

- -

For Secure Remote Password (SRP), the fun will only be used by the server to obtain - parameters that it will use to generate its session keys. DerivedKey should be - derived according to RFC 2945 and - RFC 5054: - crypto:sha([Salt, crypto:sha([Username, <<$:>>, Password])]) +

For Pre-Shared Key (PSK) cipher suites, the lookup fun is + called by the client and server to determine the shared + secret. When called by the client, PSKIdentity is set to the + hint presented by the server or to undefined. When called by the + server, PSKIdentity is the identity presented by the client.

+ +

For Secure Remote Password (SRP), the fun is only used by the server to + obtain parameters that it uses to generate its session keys. + DerivedKey is to be derived according to + RFC 2945 and + RFC 5054: + crypto:sha([Salt, crypto:sha([Username, <<$:>>, Password])])

- {padding_check, boolean()} - -

This option only affects TLS-1.0 connections. - If set to false it disables the block cipher padding check - to be able to interoperate with legacy software. -

- -

Using this option makes TLS vulnerable to - the Poodle attack

 - - - + {padding_check, boolean()} +

Affects TLS-1.0 connections only. + If set to false, it disables the block cipher padding check + to be able to interoperate with legacy software.

 + - + +

Using {padding_check, boolean()} makes TLS + vulnerable to the Poodle attack.

 +
SSL OPTION DESCRIPTIONS - CLIENT SIDE -

Options described here are client specific or has a slightly different - meaning in the client than in the server.

+

The following options are client-specific or have a slightly different + meaning in the client than in the server:

- {verify, verify_type()} - In verify_none mode the default behavior will be to - allow all x509-path validation errors. See also the verify_fun - option. - - {reuse_sessions, boolean()} - Specifies if client should try to reuse sessions - when possible. + + {verify, verify_type()} +

In mode verify_none the default behavior is to allow + all x509-path validation errors. See also option verify_fun.

 + + {reuse_sessions, boolean()} +

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

 - {cacertfile, path()} - The path to a file containing PEM encoded CA certificates. The CA + {cacertfile, path()} +

Path to a file containing PEM-encoded CA certificates. The CA certificates are used during server authentication and when building the - client certificate chain. - + client certificate chain.

+ {alpn_advertised_protocols, [binary()]} @@ -444,39 +478,44 @@ fun(srp, Username :: string(), UserState :: term()) -> {client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()]}} {client_preferred_next_protocols, {Precedence :: server | client, ClientPrefs :: [binary()], Default :: binary()}} -

Indicates the client will try to perform Next Protocol +

Indicates that the client is to try to perform Next Protocol Negotiation.

-

If precedence is server the negotiated protocol will be the - first protocol that appears on the server advertised list that is +

If precedence is server, the negotiated protocol is the + first protocol to be shown on the server advertised list, which is also on the client preference list.

-

If precedence is client the negotiated protocol will be the - first protocol that appears on the client preference list that is +

If precedence is client, the negotiated protocol is the + first protocol to be shown on the client preference list, which is also on the server advertised list.

If the client does not support any of the server advertised - protocols or the server does not advertise any protocols the - client will fallback to the first protocol in its list or if a - default is supplied it will fallback to that instead. If the - server does not support Next Protocol Negotiation the - connection will be aborted if no default protocol is supplied.

+ protocols or the server does not advertise any protocols, the + client falls back to the first protocol in its list or to the + default protocol (if a default is supplied). If the + server does not support Next Protocol Negotiation, the + connection terminates if no default protocol is supplied.

 - {psk_identity, string()} - Specifies the identity the client presents to the server. The matching secret is - found by calling the user_look_fun. - - {srp_identity, {Username :: string(), Password :: string()} - Specifies the Username and Password to use to authenticate to the server. + {psk_identity, string()} +

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

 - {server_name_indication, hostname()} - {server_name_indication, disable} + + {srp_identity, {Username :: string(), Password :: string()} + +

Specifies the username and password to use to authenticate + to the server.

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

This option can be specified when upgrading a TCP socket to a TLS +

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

-

When starting a TLS connection without upgrade the Server Name - Indication extension will be sent if possible, this option may also be + +

When starting a TLS connection without upgrade, the Server Name + Indication extension is sent if possible. This option can also be used to disable that behavior.

 {fallback, boolean()} @@ -502,63 +541,58 @@ fun(srp, Username :: string(), UserState :: term()) ->
SSL OPTION DESCRIPTIONS - SERVER SIDE -

Options described here are server specific or has a slightly different - meaning in the server than in the client.

+

The following options are server-specific or have a slightly different + meaning in the server than in the client:

- {cacertfile, path()} - The path to a file containing PEM encoded CA + {cacertfile, path()} +

Path to a file containing PEM-encoded CA certificates. The CA certificates are used to build the server - certificate chain, and for client authentication. Also the CAs - are used in the list of acceptable client CAs passed to the - client when a certificate is requested. May be omitted if there - is no need to verify the client and if there are not any - intermediate CAs for the server certificate. - + certificate chain and for client authentication. The CAs are + also used in the list of acceptable client CAs passed to the + client when a certificate is requested. Can be omitted if there + is no need to verify the client and if there are no + intermediate CAs for the server certificate.

 - {dh, der_encoded()} - The DER encoded Diffie Hellman parameters. If this option - is supplied it will override the dhfile option. - - - {dhfile, path()} - Path to file containing PEM encoded Diffie Hellman parameters, - for the server to use if a cipher suite using Diffie Hellman key exchange - is negotiated. If not specified default parameters will be used. - - - {verify, verify_type()} - Servers only do the x509-path validation in verify_peer - mode, as it then will send a certificate request to the client - (this message is not sent if the verify option is verify_none) - and you may then also want to specify the option - fail_if_no_peer_cert. + {dh, der_encoded()} +

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

 + + {dhfile, path()} +

Path to a file containing PEM-encoded Diffie Hellman parameters + to be used by the server if a cipher suite using Diffie Hellman key + exchange is negotiated. If not specified, default parameters are used. +

+ + {verify, verify_type()} +

A server only does x509-path validation in mode verify_peer, + as it then sends a certificate request to the client + (this message is not sent if the verify option is verify_none). + You can then also want to specify option fail_if_no_peer_cert. +

+ + {fail_if_no_peer_cert, boolean()} +

Used together with {verify, verify_peer} by an SSL server. + 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).

 - {fail_if_no_peer_cert, boolean()} - Used together with {verify, verify_peer} by an ssl server. - If set to true, the server will fail if the client does not have - a certificate to send, i.e. sends a empty certificate, if set to - false it will only fail if the client sends an invalid - certificate (an empty certificate is considered valid). - + {reuse_sessions, boolean()} +

Specifies if the server is to agree to reuse sessions + when requested by the clients. See also option reuse_session. +

- {reuse_sessions, boolean()} - Specifies if the server should agree to reuse sessions - when the clients request to do so. See also the reuse_session - option. - - - {reuse_session, fun(SuggestedSessionId, - PeerCert, Compression, CipherSuite) -> boolean()} - Enables the ssl server to have a local policy - for deciding if a session should be reused or not, - only meaningful if reuse_sessions is set to true. - SuggestedSessionId is a binary(), PeerCert is a DER encoded - certificate, Compression is an enumeration integer - and CipherSuite is of type ciphersuite(). - + {reuse_session, fun(SuggestedSessionId, + PeerCert, Compression, CipherSuite) -> boolean()} +

Enables the SSL server to have a local policy + for deciding if a session is to be reused or not. + Meaningful only if reuse_sessions is set to true. + SuggestedSessionId is a binary(), PeerCert is + a DER-encoded certificate, Compression is an enumeration integer, + and CipherSuite is of type ciphersuite().

 {alpn_preferred_protocols, [binary()]} @@ -573,65 +607,62 @@ fun(srp, Username :: string(), UserState :: term()) ->

The negotiated protocol can be retrieved using the negotiated_protocol/1 function.

 - {next_protocols_advertised, Protocols :: [binary()]} - The list of protocols to send to the client if the client indicates - it supports the Next Protocol extension. The client may select a protocol + {next_protocols_advertised, Protocols :: [binary()]} +

List of protocols to send to the client if the client indicates that + it supports the Next Protocol extension. The client can select a protocol that is not on this list. The list of protocols must not contain an empty - binary. If the server negotiates a Next Protocol it can be accessed - using negotiated_protocol/1 function. - + binary. If the server negotiates a Next Protocol, it can be accessed + using the negotiated_next_protocol/1 method.

 - {psk_identity, string()} - Specifies the server identity hint the server presents to the client. - - {log_alert, boolean()} - If false, error reports will not be displayed. - {honor_cipher_order, boolean()} - If true, use the server's preference for cipher selection. If false - (the default), use the client's preference. - + {psk_identity, string()} +

Specifies the server identity hint, which the server presents to + the client.

 + + {log_alert, boolean()} +

If set to false, error reports are not displayed.

 + + {honor_cipher_order, boolean()} +

If set to true, use the server preference for cipher + selection. If set to false (the default), use the client + preference.

 + +
General -

When an ssl socket is in active mode (the default), data from the +

When an SSL socket is in active mode (the default), data from the socket is delivered to the owner of the socket in the form of - messages: -

+ messages:

+ - {ssl, Socket, Data} - - {ssl_closed, Socket} - - - {ssl_error, Socket, Reason} - +

{ssl, Socket, Data}

 +

{ssl_closed, Socket}

 +

{ssl_error, Socket, Reason}

 - -

A Timeout argument specifies a timeout in milliseconds. The - default value for a Timeout argument is infinity. -

+ +

A Timeout argument specifies a time-out in milliseconds. The + default value for argument Timeout is infinity.

cipher_suites() -> cipher_suites(Type) -> ciphers() - Returns a list of supported cipher suites + Returns a list of supported cipher suites. Type = erlang | openssl | all -

Returns a list of supported cipher suites. - cipher_suites() is equivalent to cipher_suites(erlang). - Type openssl is provided for backwards compatibility with - old ssl that used openssl. cipher_suites(all) returns + cipher_suites() is equivalent to cipher_suites(erlang). + Type openssl is provided for backwards compatibility with the + old SSL, which used OpenSSL. cipher_suites(all) returns all available cipher suites. The cipher suites not present - in cipher_suites(erlang) but in included in cipher_suites(all) - will not be used unless explicitly configured by the user. -

+ in cipher_suites(erlang) but included in + cipher_suites(all) are not used unless explicitly configured + by the user.

 @@ -651,17 +682,17 @@ fun(srp, Username :: string(), UserState :: term()) -> connect(Socket, SslOptions) -> connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {error, Reason} - Upgrades a gen_tcp, or - equivalent, connected socket to an ssl socket. + Upgrades a gen_tcp, or + equivalent, connected socket to an SSL socket. - Socket = socket() - SslOptions = [ssloption()] + Socket = socket() + SslOptions = [ssloption()] Timeout = integer() | infinity SslSocket = sslsocket() Reason = term() -

Upgrades a gen_tcp, or equivalent, - connected socket to an ssl socket i.e. performs the +

Upgrades a gen_tcp, or equivalent, + connected socket to an SSL socket, that is, performs the client-side ssl handshake.

 @@ -670,7 +701,7 @@ fun(srp, Username :: string(), UserState :: term()) -> connect(Host, Port, Options) -> connect(Host, Port, Options, Timeout) -> {ok, SslSocket} | {error, Reason} - Opens an ssl connection to Host, Port. + Opens an SSL connection to Host, Port. Host = host() Port = integer() @@ -679,72 +710,70 @@ fun(srp, Username :: string(), UserState :: term()) -> SslSocket = sslsocket() Reason = term() -

Opens an ssl connection to Host, Port.

 +

Opens an SSL connection to Host, Port.

 close(SslSocket) -> ok | {error, Reason} - Close an ssl connection + Closes an SSL connection. SslSocket = sslsocket() Reason = term() -

Close an ssl connection.

+

Closes an SSL connection.

+ + + + + connection_info(SslSocket) -> + {ok, {ProtocolVersion, CipherSuite}} | {error, Reason} + Returns the Negotiated Protocol version and cipher suite. + + + CipherSuite = ciphersuite() + ProtocolVersion = protocol() + +

Returns the Negotiated Protocol version and cipher suite.

 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason} - Assigns a new controlling process to the - ssl-socket. - + SSL socket. SslSocket = sslsocket() NewOwner = pid() Reason = term() -

Assigns a new controlling process to the ssl-socket. A - controlling process is the owner of an ssl-socket, and receives - all messages from the socket.

+

Assigns a new controlling process to the SSL socket. A + controlling process is the owner of an SSL socket, and receives + all messages from the socket.

 - connection_info(SslSocket) -> - {ok, {ProtocolVersion, CipherSuite}} | {error, Reason} - Returns the negotiated protocol version and cipher suite. - - - CipherSuite = ciphersuite() - ProtocolVersion = protocol() - -

Returns the negotiated protocol version and cipher suite.

- - - - format_error(Reason) -> string() - Return an error string. + Returns an error string. Reason = term() -

Presents the error returned by an ssl function as a printable string.

+

Presents the error returned by an SSL function as a printable string.

 getopts(Socket, OptionNames) -> {ok, [socketoption()]} | {error, Reason} - Get the value of the specified options. + Gets the values of the specified options. Socket = sslsocket() OptionNames = [atom()] -

Get the value of the specified socket options. +

Gets the values of the specified socket options.

@@ -752,34 +781,47 @@ fun(srp, Username :: string(), UserState :: term()) -> listen(Port, Options) -> {ok, ListenSocket} | {error, Reason} - Creates an ssl listen socket. + Creates an SSL listen socket. Port = integer() Options = options() ListenSocket = sslsocket() -

Creates an ssl listen socket.

+

Creates an SSL listen socket.

+ + + + + negotiated_next_protocol(Socket) -> {ok, Protocol} | {error, next_protocol_not_negotiated} + Returns the Next Protocol negotiated. + + Socket = sslsocket() + Protocol = binary() + + +

Returns the Next Protocol negotiated.

 peercert(Socket) -> {ok, Cert} | {error, Reason} - Return the peer certificate. + Returns the peer certificate. Socket = sslsocket() Cert = binary() -

The peer certificate is returned as a DER encoded binary. - The certificate can be decoded with public_key:pkix_decode_cert/2. -

+

The peer certificate is returned as a DER-encoded binary. + The certificate can be decoded with + public_key:pkix_decode_cert/2.

 + peername(Socket) -> {ok, {Address, Port}} | {error, Reason} - Return peer address and port. + Returns the peer address and port. Socket = sslsocket() Address = ipaddress() @@ -789,12 +831,32 @@ fun(srp, Username :: string(), UserState :: term()) ->

Returns the address and port number of the peer.

 + + + prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()} + Uses a session Pseudo-Random Function to generate key material. + + Socket = sslsocket() + Secret = binary() | master_secret + Label = binary() + Seed = [binary() | prf_random()] + WantedLength = non_neg_integer() + + +

Uses the Pseudo-Random Function (PRF) of a TLS session to generate + extra key material. It either takes user-generated values for + Secret and Seed or atoms directing it to use a specific + value from the session security parameters.

+

Can only be used with TLS connections; {error, undefined} + is returned for SSLv3 connections.

+ + recv(Socket, Length) -> recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason} - Receive data on a socket. + Receives data on a socket. Socket = sslsocket() Length = integer() @@ -802,63 +864,43 @@ fun(srp, Username :: string(), UserState :: term()) -> Data = [char()] | binary() -

This function receives a packet from a socket in passive - mode. A closed socket is indicated by a return value +

Receives a packet from a socket in passive + mode. A closed socket is indicated by return value {error, closed}.

-

The Length argument is only meaningful when - the socket is in raw mode and denotes the number of +

Argument Length is meaningful only when + the socket is in mode raw and denotes the number of bytes to read. If Length = 0, all available bytes are returned. If Length > 0, exactly Length bytes are returned, or an error; possibly discarding less than Length bytes of data when the socket gets closed from the other side.

-

The optional Timeout parameter specifies a timeout in +

Optional argument Timeout specifies a time-out in milliseconds. The default value is infinity.

 - - prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()} - Use a sessions pseudo random function to generate key material. - - Socket = sslsocket() - Secret = binary() | master_secret - Label = binary() - Seed = [binary() | prf_random()] - WantedLength = non_neg_integer() - - -

Use the pseudo random function (PRF) of a TLS session to generate - additional key material. It either takes user generated values for - Secret and Seed or atoms directing it use a specific - value from the session security parameters.

-

This function can only be used with TLS connections, {error, undefined} - is returned for SSLv3 connections.

- - - renegotiate(Socket) -> ok | {error, Reason} - Initiates a new handshake. + Initiates a new handshake. Socket = sslsocket()

Initiates a new handshake. A notable return value is {error, renegotiation_rejected} indicating that the peer - refused to go through with the renegotiation but the connection + refused to go through with the renegotiation, but the connection is still active using the previously negotiated session.

 send(Socket, Data) -> ok | {error, Reason} - Write data to a socket. + Writes data to a socket. Socket = sslsocket() Data = iodata() -

Writes Data to Socket.

+

Writes Data to Socket.

A notable return value is {error, closed} indicating that the socket is closed.

 @@ -866,31 +908,31 @@ fun(srp, Username :: string(), UserState :: term()) -> setopts(Socket, Options) -> ok | {error, Reason} - Set socket options. + Sets socket options. Socket = sslsocket() Options = [socketoption]() -

Sets options according to Options for the socket - Socket.

+

Sets options according to Options for socket + Socket.

 shutdown(Socket, How) -> ok | {error, Reason} - Immediately close a socket + Immediately closes a socket. Socket = sslsocket() How = read | write | read_write Reason = reason() -

Immediately close a socket in one or two directions.

+

Immediately closes a socket in one or two directions.

How == write means closing the socket for writing, reading from it is still possible.

To be able to handle that the peer has done a shutdown on - the write side, the {exit_on_close, false} option + the write side, option {exit_on_close, false} is useful.

 @@ -898,16 +940,16 @@ fun(srp, Username :: string(), UserState :: term()) -> ssl_accept(Socket) -> ssl_accept(Socket, Timeout) -> ok | {error, Reason} - Perform server-side SSL/TLS handshake + Performs server-side SSL/TLS handshake. Socket = sslsocket() Timeout = integer() Reason = term() -

Performs the SSL/TLS server-side handshake Socket is a socket as returned - by ssl:transport_accept/[1,2] +

Performs the SSL/TLS server-side handshake.

+

Socket is a socket as returned by + ssl:transport_accept/[1,2]

@@ -915,7 +957,7 @@ fun(srp, Username :: string(), UserState :: term()) -> ssl_accept(Socket, SslOptions) -> ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason} - Perform server-side SSL/TLS handshake + Performs server-side SSL/TLS handshake. Socket = socket() | sslsocket() SslOptions = ssloptions() @@ -923,17 +965,19 @@ fun(srp, Username :: string(), UserState :: term()) -> Reason = term() -

If Socket is a socket() - upgrades a gen_tcp, or equivalent, socket to an ssl socket - i.e. performs the SSL/TLS server-side handshake and returns the ssl socket. -

+

If Socket is a socket(): upgrades a gen_tcp, + or equivalent, socket to an SSL socket, that is, performs + the SSL/TLS server-side handshake and returns the SSL socket.

-

Note that the listen socket should be in {active, false} mode +

The listen socket is to be in mode {active, false} before telling the client that the server is ready to upgrade - by calling this function, otherwise the upgrade may - or may not succeed depending on timing.

 + by calling this function, else the upgrade succeeds or does not + succeed depending on timing.

-

If Socket is an sslsocket() - provides additional SSL/TLS options to those specified in ssl:listen/2 and then performs the SSL/TLS handshake. +

If Socket is an sslsocket(): provides extra SSL/TLS + options to those specified in + ssl:listen/2 and then performs + the SSL/TLS handshake.

@@ -941,14 +985,14 @@ fun(srp, Username :: string(), UserState :: term()) -> sockname(Socket) -> {ok, {Address, Port}} | {error, Reason} - Return the local address and port. + Returns the local address and port. Socket = sslsocket() Address = ipaddress() Port = integer() -

Returns the local address and port number of the socket +

Returns the local address and port number of socket Socket.

 @@ -956,22 +1000,21 @@ fun(srp, Username :: string(), UserState :: term()) -> start() -> start(Type) -> ok | {error, Reason} - Starts the Ssl application. + Starts the sslapplication. - Type = permanent | transient | temporary + Type = permanent | transient | temporary -

Starts the Ssl application. Default type - is temporary. - application(3)

+

Starts the ssl application. Default type + is temporary.

 + stop() -> ok - Stops the Ssl application. + Stops the ssl application. -

Stops the Ssl application. - application(3)

+

Stops the ssl application.

 @@ -979,8 +1022,8 @@ fun(srp, Username :: string(), UserState :: term()) -> transport_accept(ListenSocket) -> transport_accept(ListenSocket, Timeout) -> {ok, NewSocket} | {error, Reason} - Accept an incoming connection and - prepare for ssl_accept + Accepts an incoming connection and + prepares for ssl_accept. ListenSocket = NewSocket = sslsocket() Timeout = integer() @@ -989,23 +1032,22 @@ fun(srp, Username :: string(), UserState :: term()) ->

Accepts an incoming connection request on a listen socket. ListenSocket must be a socket returned from - ssl:listen/2. - The socket returned should be passed to + ssl:listen/2. + The socket returned is to be passed to ssl:ssl_accept[2,3] - to complete handshaking i.e + to complete handshaking, that is, establishing the SSL/TLS connection.

The socket returned can only be used with - ssl:ssl_accept[2,3] - no traffic can be sent or received before that call.

+ ssl:ssl_accept[2,3]. + No traffic can be sent or received before that call.

The accepted socket inherits the options set for - ListenSocket in ssl:listen/2.

+ ListenSocket in + ssl:listen/2.

The default value for Timeout is infinity. If - Timeout is specified, and no connection is accepted + Timeout is specified and no connection is accepted within the given time, {error, timeout} is returned.

 @@ -1014,34 +1056,31 @@ fun(srp, Username :: string(), UserState :: term()) -> versions() -> [versions_info()] Returns version information relevant for the - ssl application. + ssl application. versions_info() = {app_vsn, string()} | {supported | available, [protocol()] -

- Returns version information relevant for the - ssl application. -

+

Returns version information relevant for the ssl + application.

app_vsn - The application version of the OTP ssl application. + The application version of the ssl application. supported - TLS/SSL versions supported by default. - Overridden by a versions option on - connect/[2,3,4], listen/2 and ssl_accept/[1,2,3]. For the - negotiated TLS/SSL version see connect/[2,3,4], + listen/2, and ssl_accept/[1,2,3]. + For the negotiated TLS/SSL version, see ssl:connection_info/1 - - + . + available - All TLS/SSL versions that the Erlang ssl application - can support. Note that TLS 1.2 requires sufficient support - from the crypto application. + All TLS/SSL versions supported by the ssl application. + TLS 1.2 requires sufficient support from the crypto + application. @@ -1063,8 +1102,8 @@ fun(srp, Username :: string(), UserState :: term()) ->
SEE ALSO -

inet(3) and - gen_tcp(3) +

inet(3) and + gen_tcp(3)

diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml index e3a3fc27f2..2b2d08124f 100644 --- a/lib/ssl/doc/src/ssl_app.xml +++ b/lib/ssl/doc/src/ssl_app.xml @@ -22,66 +22,60 @@ ssl + + + + ssl_app.sgml ssl - The SSL application provides secure communication over + The ssl application provides secure communication over sockets. +
DEPENDENCIES -

The ssl application uses the Erlang applications public_key and - crypto to handle public keys and encryption, hence these - applications needs to be loaded for the ssl application to work. In - an embedded environment that means they need to be started with - application:start/[1,2] before the ssl application is started. -

+

The ssl application uses the public_key and + crypto application to handle public keys and encryption, hence + these applications must be loaded for the ssl application to work. + In an embedded environment this means they must be started with + application:start/[1,2] before the ssl application is + started.

- ENVIRONMENT -

The following application environment configuration parameters - are defined for the SSL application. See application(3)for more - information about configuration parameters. -

-

Note that the environment parameters can be set on the command line, - for instance,

-

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

+ CONFIGURATION +

The application environment configuration parameters in this section + are defined for the ssl application. For more information + about configuration parameters, see the + application(3) + manual page in kernel.

+ +

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

+ +

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

+ ]]>. - -

Protocol that will be supported by started clients and - servers. If this option is not set it will default to all - protocols currently supported by the erlang ssl application. - Note that this option may be overridden by the version option - to ssl:connect/[2,3] and ssl:listen/2. -

- +

Protocol supported by started clients and + servers. If this option is not set, it defaults to all + protocols currently supported by the ssl application. + This option can be overridden by the version option + to ssl:connect/[2,3] and ssl:listen/2.

 ]]> - -

The lifetime of session data in seconds. -

- +

Lifetime of the session data in seconds.

 - ]]> - -

- Name of session cache callback module that implements - the ssl_session_cache_api behavior, defaults to - ssl_session_cache.erl. -

- + ]]> +

Name of the session cache callback module that implements + the ssl_session_cache_api behavior. Defaults to + ssl_session_cache.erl.

 ]]> - -

- List of additional user defined arguments to the init function in session cache - callback module, defaults to []. -

- + +

List of extra user-defined arguments to the init function + in the session cache callback module. Defaults to [].

 ]]> @@ -95,6 +89,11 @@
+
+ ERROR LOGGER AND EVENT HANDLERS +

The ssl applications has no error logger or event handlers.

+
+
SEE ALSO

application(3)

diff --git a/lib/ssl/doc/src/ssl_distribution.xml b/lib/ssl/doc/src/ssl_distribution.xml index 4b4d042f70..6d1a2f9ccc 100644 --- a/lib/ssl/doc/src/ssl_distribution.xml +++ b/lib/ssl/doc/src/ssl_distribution.xml @@ -31,23 +31,20 @@ B ssl_distribution.xml -

This chapter describes how the Erlang distribution can use - SSL to get additional verification and security. -

+

This section describes how the Erlang distribution can use + SSL to get extra verification and security.

-
- Introduction -

The Erlang distribution can in theory use almost any connection - based protocol as bearer. A module that implements the protocol - specific parts of the connection setup is however needed. The - default distribution module is inet_tcp_dist which is - included in the Kernel application. When starting an +

The Erlang distribution can in theory use almost any + connection-based protocol as bearer. However, a module that + implements the protocol-specific parts of the connection setup is + needed. The default distribution module is inet_tcp_dist + in the kernel application. When starting an Erlang node distributed, net_kernel uses this module to - setup listen ports and connections.

+ set up listen ports and connections.

-

In the SSL application there is an additional distribution - module, inet_tls_dist which can be used as an - alternative. All distribution connections will be using SSL and +

In the ssl application, an exra distribution + module, inet_tls_dist, can be used as an + alternative. All distribution connections will use SSL and all participating Erlang nodes in a distributed system must use this distribution module.

@@ -55,35 +52,45 @@ SSL connection setup. Erlang node cookies are however always used, as they can be used to differentiate between two different Erlang networks.

-

Setting up Erlang distribution over SSL involves some simple but - necessary steps:

+ +

To set up Erlang distribution over SSL:

- Building boot scripts including the SSL application - Specifying the distribution module for net_kernel - Specifying security options and other SSL options + Step 1: Build boot scripts including the + ssl application. + Step 2: Specify the distribution module for + net_kernel. + Step 3: Specify the security options and other + SSL options. + Step 4: Set up the environment to always use SSL. -

The rest of this chapter describes the above mentioned steps in - more detail.

-
+ +

The following sections describe these steps.

- Building boot scripts including the SSL application + Building Boot Scripts Including the ssl Application

Boot scripts are built using the systools utility in the - SASL application. Refer to the SASL documentations - for more information on systools. This is only an example of + sasl application. For more information on systools, + see the sasl documentation. This is only an example of what can be done.

-

The simplest boot script possible includes only the Kernel - and STDLIB applications. Such a script is located in the - Erlang distributions bin directory. The source for the script - can be found under the Erlang installation top directory under - /start_clean.rel]]>. Copy that - script to another location (and preferably another name) - and add the applications crypto, public_key and SSL with their current version numbers - after the STDLIB application.

-

An example .rel file with SSL added may look like this:

+

The simplest boot script possible includes only the kernel + and stdlib applications. Such a script is located in the + bin directory of the Erlang distribution. The source for the + script is found under the Erlang installation top directory under + /start_clean.rel]]>.

+ +

Do the following:

+ +

Copy that script to another location (and preferably another + name).

 +

Add the applications crypto, public_key, and + ssl with their current version numbers after the + stdlibapplication.

 + +

The following shows an example .rel file with ssl + added:

{release, {"OTP APN 181 01","R15A"}, {erts, "5.9"}, [{kernel,"2.15"}, @@ -94,23 +101,29 @@ ]}. -

Note that the version numbers surely will differ in your system. - Whenever one of the applications included in the script is - upgraded, the script has to be changed.

-

Assuming the above .rel file is stored in a file - start_ssl.rel in the current directory, a boot script - can be built like this:

+

The version numbers differ in your system. Whenever one of the + applications included in the script is upgraded, change the script.

+

Do the following:

+ +

Build the boot script.

+

Assuming the .rel file is stored in a file + start_ssl.rel in the current directory, a boot script + can be built as follows:

 + 1> systools:make_script("start_ssl",[]). -

There will now be a file start_ssl.boot in the current - directory. To test the boot script, start Erlang with the - -boot command line parameter specifying this boot script - (with its full path but without the .boot suffix), in - Unix it could look like this:

-

+

There is now a start_ssl.boot file in the current + directory.

+

Do the following:

+ +

Test the boot script. To do this, start Erlang with the + -boot command-line parameter specifying this boot script + (with its full path, but without the .boot suffix). In + UNIX it can look as follows:

 + whereis(ssl_manager). <0.41.0> ]]> -

The whereis function call verifies that the SSL - application is really started.

- -

As an alternative to building a bootscript, one can explicitly - add the path to the SSL ebin directory on the command - line. This is done with the command line option -pa. This - works as the SSL application does not need to be started for the - distribution to come up, as a clone of the SSL application is - hooked into the kernel application, so as long as the - SSL applications code can be reached, the distribution will - start. The -pa method is only recommended for testing - purposes.

- -

Note that the clone of the SSL application is necessary to + +

The whereis function-call verifies that the ssl + application is started.

+ +

As an alternative to building a bootscript, you can explicitly + add the path to the ssl ebin directory on the command + line. This is done with command-line option -pa. This + works as the ssl application does not need to be started for the + distribution to come up, as a clone of the ssl application is + hooked into the kernel application. So, as long as the + ssl application code can be reached, the distribution starts. + The -pa method is only recommended for testing purposes.

+ +

The clone of the ssl application must enable the use of the SSL code in such an early bootstage as - needed to setup the distribution, however this will make it - impossible to soft upgrade the SSL application.

 + needed to set up the distribution. However, this makes it + impossible to soft upgrade the ssl application.
- Specifying distribution module for net_kernel -

The distribution module for SSL is named inet_tls_dist - and is specified on the command line with the -proto_dist - option. The argument to -proto_dist should be the module - name without the _dist suffix, so this distribution + Specifying Distribution Module for net_kernel +

The distribution module for ssl is named inet_tls_dist + and is specified on the command line with option -proto_dist. + The argument to -proto_dist is to be the module + name without suffix _dist. So, this distribution module is specified with -proto_dist inet_tls on the command line.

-

-

Extending the command line from above gives us the following:

+

Extending the command line gives the following:

$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls -

For the distribution to actually be started, we need to give -the emulator a name as well:

+

For the distribution to be started, give the emulator a name as well:

$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls -sname ssl_test Erlang (BEAM) emulator version 5.0 [source] Eshell V5.0 (abort with ^G) (ssl_test@myhost)1> -

Note however that a node started in this way will refuse to talk - to other nodes, as no ssl parameters are supplied - (see below).

+ +

However, a node started in this way refuses to talk + to other nodes, as no ssl parameters are supplied + (see the next section).

- Specifying SSL options

For SSL to work, at least - a public key and certificate needs to be specified for the server - side. In the following example the PEM-files consists of two - entries the servers certificate and its private key.

- -

On the erl command line one can specify options that the - SSL distribution will add when creating a socket.

- -

One can specify the simpler SSL options certfile, keyfile, - password, cacertfile, verify, reuse_sessions, - secure_renegotiate, depth, hibernate_after and ciphers (use old - string format) by adding the prefix server_ or client_ to the - option name. The server can also take the options dhfile and - fail_if_no_peer_cert (also prefixed). - client_-prfixed options are used when the distribution initiates a - connection to another node and the server_-prefixed options are used - when accepting a connection from a remote node.

- -

More complex options such as verify_fun are not available at - the moment but a mechanism to handle such options may be added in - a future release.

- -

Raw socket options such as packet and size must not be specified on - the command line

. - -

The command line argument for specifying the SSL options is named - -ssl_dist_opt and should be followed by pairs of - SSL options and their values. The -ssl_dist_opt argument can + Specifying SSL Options +

For SSL to work, at least + a public key and a certificate must be specified for the server + side. In the following example, the PEM-files consist of two + entries, the server certificate and its private key.

+ +

On the erl command line you can specify options that the + SSL distribution adds when creating a socket.

+ +

The simplest SSL options in the following list can be specified + by adding the + prefix server_ or client_ to the option name:

+ + certfile + keyfile + password + cacertfile + verify + reuse_sessions + secure_renegotiate + depth + hibernate_after + ciphers (use old string format) + + +

The server can also take the options dhfile and + fail_if_no_peer_cert (also prefixed).

+ +

client_-prefixed options are used when the distribution + initiates a connection to another node. server_-prefixed + options are used when accepting a connection from a remote node.

+ +

More complex options, such as verify_func>, are currently not + available, but a mechanism to handle such options may be added in + a future release.

+ +

Raw socket options, such as packet and size must not + be specified on the command line.

+ +

The command-line argument for specifying the SSL options is named + -ssl_dist_opt and is to be followed by pairs of + SSL options and their values. Argument -ssl_dist_opt can be repeated any number of times.

-

An example command line would now look something like this +

An example command line can now look as follows (line breaks in the command are for readability, - they should not be there when typed):

+ and are not be there when typed):

$ erl -boot /home/me/ssl/start_ssl -proto_dist inet_tls -ssl_dist_opt server_certfile "/home/me/ssl/erlserver.pem" @@ -207,20 +233,20 @@ Erlang (BEAM) emulator version 5.0 [source] Eshell V5.0 (abort with ^G) (ssl_test@myhost)1> -

A node started in this way will be fully functional, using SSL +

A node started in this way is fully functional, using SSL as the distribution protocol.

- Setting up environment to always use SSL -

A convenient way to specify arguments to Erlang is to use the - ERL_FLAGS environment variable. All the flags needed to - use SSL distribution can be specified in that variable and will - then be interpreted as command line arguments for all + Setting up Environment to Always Use SSL +

A convenient way to specify arguments to Erlang is to use environment + variable ERL_FLAGS. All the flags needed to + use the SSL distribution can be specified in that variable and are + then interpreted as command-line arguments for all subsequent invocations of Erlang.

-

-

In a Unix (Bourne) shell it could look like this (line breaks for - readability, they should not be there when typed):

+ +

In a Unix (Bourne) shell, it can look as follows (line breaks are for + readability, they are not to be there when typed):

$ ERL_FLAGS="-boot /home/me/ssl/start_ssl -proto_dist inet_tls -ssl_dist_opt server_certfile /home/me/ssl/erlserver.pem @@ -240,7 +266,8 @@ Eshell V5.0 (abort with ^G) {ssl_dist_opt,["server_secure_renegotiate","true", "client_secure_renegotiate","true"] {home,["/home/me"]}] +

The init:get_arguments() call verifies that the correct - arguments are supplied to the emulator.

+ arguments are supplied to the emulator.

diff --git a/lib/ssl/doc/src/ssl_introduction.xml b/lib/ssl/doc/src/ssl_introduction.xml new file mode 100644 index 0000000000..6138749b79 --- /dev/null +++ b/lib/ssl/doc/src/ssl_introduction.xml @@ -0,0 +1,54 @@ + + + + +
+ + 2015 + 2015 + Ericsson AB, All Rights Reserved + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + Introduction + OTP team + + 2015-03-05 + A + ssl_introduction.xml +
+ +
+ Purpose +

Transport Layer Security (TLS) and its predecessor, the Secure + Sockets Layer (SSL) are cryptographic protocols designed to + provide communications security over a computer network. They + use x.509 certificates and hence asymmetric cryptography to + authenticate the counterparty with whom they are communicating, + and to exchange a symmetric key. This session key is then used + to encrypt data flowing between the parties. This allows for + data/message confidentiality, and message authentication codes + for message integrity.

+
+ +
+ Prerequisites +

It is assumed that the reader is familiar with the Erlang + programming language, the concepts of OTP, and has a basic + understanding of SSL/TSP.

+
+ + diff --git a/lib/ssl/doc/src/ssl_protocol.xml b/lib/ssl/doc/src/ssl_protocol.xml index 80d9cc4ee8..79162389ae 100644 --- a/lib/ssl/doc/src/ssl_protocol.xml +++ b/lib/ssl/doc/src/ssl_protocol.xml @@ -21,33 +21,42 @@ - Transport Layer Security (TLS) and its predecessor, Secure Socket Layer (SSL) + TLS and its Predecessor, SSL + + + + + + + ssl_protocol.xml -

The erlang SSL application currently implements the protocol SSL/TLS - for currently supported versions see ssl(3) +

The Erlang ssl application implements the SSL/TLS protocol + for the currently supported versions, see the + ssl(3) manual page.

-

By default erlang SSL is run over the TCP/IP protocol even - though you could plug in any other reliable transport protocol - with the same API as gen_tcp.

+

By default ssl is run over the TCP/IP protocol even + though you can plug in any other reliable transport protocol + with the same Application Programming Interface (API) as the + gen_tcp module in kernel.

-

If a client and server wants to use an upgrade mechanism, such as - defined by RFC2817, to upgrade a regular TCP/IP connection to an SSL - connection the erlang SSL API supports this. This can be useful for - things such as supporting HTTP and HTTPS on the same port and +

If a client and a server wants to use an upgrade mechanism, such as + defined by RFC 2817, to upgrade a regular TCP/IP connection to an SSL + connection, this is supported by the Erlang ssl API. This can be + useful for, for example, supporting HTTP and HTTPS on the same port and implementing virtual hosting.

- Security overview + Security Overview -

To achieve authentication and privacy the client and server will - perform a TLS Handshake procedure before transmitting or receiving - any data. During the handshake they agree on a protocol version and - cryptographic algorithms, they generate shared secrets using public - key cryptographics and optionally authenticate each other with +

To achieve authentication and privacy, the client and server + perform a TLS handshake procedure before transmitting or receiving + any data. During the handshake, they agree on a protocol version and + cryptographic algorithms, generate shared secrets using public + key cryptographies, and optionally authenticate each other with digital certificates.

@@ -55,20 +64,21 @@ Data Privacy and Integrity

A symmetric key algorithm has one key only. The key is - used for both encryption and decryption. These algorithms are fast - compared to public key algorithms (using two keys, a public and a - private one) and are therefore typically used for encrypting bulk + used for both encryption and decryption. These algorithms are fast, + compared to public key algorithms (using two keys, one public and one + private) and are therefore typically used for encrypting bulk data.

The keys for the symmetric encryption are generated uniquely for each connection and are based on a secret negotiated - in the TLS handshake.

+ in the TLS handshake.

-

The TLS handshake protocol and data transfer is run on top of - the TLS Record Protocol that uses a keyed-hash MAC (Message - Authenticity Code), or HMAC, to protect the message's data - integrity. From the TLS RFC "A Message Authentication Code is a +

The TLS handshake protocol and data transfer is run on top of + the TLS Record Protocol, which uses a keyed-hash Message + Authenticity Code (MAC), or a Hash-based MAC (HMAC), + to protect the message data + integrity. From the TLS RFC: "A Message Authentication Code is a one-way hash computed from a message and some secret data. It is difficult to forge without knowing the secret data. Its purpose is to detect if the message has been altered." @@ -82,15 +92,14 @@ passport. The holder of the certificate is called the subject. The certificate is signed with the private key of the issuer of the certificate. A chain - of trust is build by having the issuer in its turn being - certified by another certificate and so on until you reach the - so called root certificate that is self signed i.e. issued + of trust is built by having the issuer in its turn being + certified by another certificate, and so on, until you reach the + so called root certificate, which is self-signed, that is, issued by itself.

-

Certificates are issued by certification - authorities (CAs) only. There are a handful of - top CAs in the world that issue root certificates. You can - examine the certificates of several of them by clicking +

Certificates are issued by Certification Authorities (CAs) only. + A handful of top CAs in the world issue root certificates. You can + examine several of these certificates by clicking through the menus of your web browser.

@@ -99,23 +108,27 @@ Authentication of Sender

Authentication of the sender is done by public key path - validation as defined in RFC 3280. Simplified that means that - each certificate in the certificate chain is issued by the one - before, the certificates attributes are valid ones, and the - root cert is a trusted cert that is present in the trusted - certs database kept by the peer.

+ validation as defined in RFC 3280. This means basically + the following:

+ + Each certificate in the certificate chain is issued by the + 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./ + -

The server will always send a certificate chain as part of - the TLS handshake, but the client will only send one if - the server requests it. If the client does not have - an appropriate certificate it may send an "empty" certificate +

The server always sends a certificate chain as part of + the TLS handshake, but the client only sends one if requested + by the server. If the client does not have + an appropriate certificate, it can send an "empty" certificate to the server.

-

The client may choose to accept some path evaluation errors - for instance a web browser may ask the user if they want to - accept an unknown CA root certificate. The server, if it request - a certificate, will on the other hand not accept any path validation - errors. It is configurable if the server should accept +

The client can choose to accept some path evaluation errors, + for example, a web browser can ask the user whether to + accept an unknown CA root certificate. The server, if it requests + a certificate, does however not accept any path validation + errors. It is configurable if the server is to accept or reject an "empty" certificate as response to a certificate request.

@@ -123,25 +136,24 @@
TLS Sessions -

From the TLS RFC "A TLS session is an association between a - client and a server. Sessions are created by the handshake +

From the TLS RFC: "A TLS session is an association between a + client and a server. Sessions are created by the handshake protocol. Sessions define a set of cryptographic security parameters, which can be shared among multiple connections. Sessions are used to avoid the expensive negotiation of new security parameters for each connection."

-

Session data is by default kept by the SSL application in a - memory storage hence session data will be lost at application - restart or takeover. Users may define their own callback module +

Session data is by default kept by the ssl application in a + memory storage, hence session data is lost at application + restart or takeover. Users can define their own callback module to handle session data storage if persistent data storage is - required. Session data will also be invalidated after 24 hours - from it was saved, for security reasons. It is of course - possible to configure the amount of time the session data should be - saved.

+ required. Session data is also invalidated after 24 hours + from it was saved, for security reasons. The amount of time the + session data is to be saved can be configured.

-

SSL clients will by default try to reuse an available session, - SSL servers will by default agree to reuse sessions when clients - ask to do so.

+

By default the SSL clients try to reuse an available session and + by default the SSL servers agree to reuse sessions when clients + ask for it.

diff --git a/lib/ssl/doc/src/ssl_session_cache_api.xml b/lib/ssl/doc/src/ssl_session_cache_api.xml index 9f87d31e90..39db03c91c 100644 --- a/lib/ssl/doc/src/ssl_session_cache_api.xml +++ b/lib/ssl/doc/src/ssl_session_cache_api.xml @@ -21,6 +21,10 @@ ssl + + + + ssl_session_cache_api.xml ssl_session_cache_api @@ -28,35 +32,43 @@ that the data storage scheme can be replaced by defining a new callback module implementing this API. +
- Common Data Types + DATA TYPES -

The following data types are used in the functions below: -

+

The following data types are used in the functions for + ssl_session_cache_api:

-

cache_ref() = opaque()

- -

key() = {partialkey(), session_id()}

- -

partialkey() = opaque()

- -

session_id() = binary()

+ + cache_ref() +

= opaque()

 + + key() +

= {partialkey(), session_id()}

 + + partialkey() +

= opaque()

 + + session_id() +

= binary()

 + + session() +

= opaque()

 + -

session() = opaque()

-
delete(Cache, Key) -> _ - + Deletes a cache entry. - Cache = cache_ref() - Key = key() + Cache = cache_ref() + Key = key() -

Deletes a cache entry. Will only be called from the cache +

Deletes a cache entry. Is only called from the cache handling process.

@@ -69,49 +81,50 @@ -

Calls Fun(Elem, AccIn) on successive elements of the - cache, starting with AccIn == Acc0. Fun/2 must return a new - accumulator which is passed to the next call. The function returns - the final value of the accumulator. Acc0 is returned if the cache is - empty. +

Calls Fun(Elem, AccIn) on successive elements of the + cache, starting with AccIn == Acc0. Fun/2 must + return a new accumulator, which is passed to the next call. + The function returns the final value of the accumulator. + Acc0 is returned if the cache is empty.

init(Args) -> opaque() - Return cache reference + Returns cache reference. Args = proplists:proplist() - Will always include the property {role, client | server}. Currently this - is the only predefined property, there may also be user defined properties. - See also application environment variable - session_cb_init_args - +

Includes property {role, client | server}. + Currently this is the only predefined property, + there can also be user-defined properties. See also + application environment variable + session_cb_init_args. +

Performs possible initializations of the cache and returns - a reference to it that will be used as parameter to the other - API functions. Will be called by the cache handling processes - init function, hence putting the same requirements on it as a - normal process init function. Note that this function will be - called twice when starting the ssl application, once with the - role client and once with the role server, as the ssl application - must be prepared to take on both roles. + a reference to it that is used as parameter to the other + API functions. Is called by the cache handling processes + init function, hence putting the same requirements on it + as a normal process init function. This function is + called twice when starting the ssl application, once with + the role client and once with the role server, as the ssl + application must be prepared to take on both roles.

lookup(Cache, Key) -> Entry - Looks up a cache entry. + Looks up a cache entry. - Cache = cache_ref() - Key = key() - Entry = session() | undefined + Cache = cache_ref() + Key = key() + Entry = session() | undefined -

Looks up a cache entry. Should be callable from any +

Looks up a cache entry. Is to be callable from any process.

@@ -119,14 +132,14 @@ select_session(Cache, PartialKey) -> [session()] - Selects a sessions that could be reused. + Selects sessions that can be reused. - Cache = cache_ref() - PartialKey = partialkey() - Session = session() + Cache = cache_ref() + PartialKey = partialkey() + Session = session() -

Selects a sessions that could be reused. Should be callable +

Selects sessions that can be reused. Is to be callable from any process.

@@ -137,7 +150,7 @@ Called by the process that handles the cache when it is about to terminate. - Cache = term() - as returned by init/0 + Cache = term() - as returned by init/0

Takes care of possible cleanup that is needed when the @@ -148,15 +161,15 @@ update(Cache, Key, Session) -> _ - Caches a new session or updates a already cached one. + Caches a new session or updates an already cached one. - Cache = cache_ref() - Key = key() - Session = session() + Cache = cache_ref() + Key = key() + Session = session() -

Caches a new session or updates a already cached one. Will - only be called from the cache handling process. +

Caches a new session or updates an already cached one. Is + only called from the cache handling process.

diff --git a/lib/ssl/doc/src/usersguide.xml b/lib/ssl/doc/src/usersguide.xml index b1c7190085..6fce022507 100644 --- a/lib/ssl/doc/src/usersguide.xml +++ b/lib/ssl/doc/src/usersguide.xml @@ -23,14 +23,17 @@ SSL User's Guide OTP Team + 2003-05-26 + usersguide.sgml -

The SSL application provides secure communication over +

The Secure Socket Layer (SSL) application provides secure communication over sockets.

+ diff --git a/lib/ssl/doc/src/using_ssl.xml b/lib/ssl/doc/src/using_ssl.xml index cce388d02a..e3ebca9410 100644 --- a/lib/ssl/doc/src/using_ssl.xml +++ b/lib/ssl/doc/src/using_ssl.xml @@ -21,126 +21,129 @@ - Using the SSL API + Using SSL API + + + + + + + using_ssl.xml - -
- General information -

To see relevant version information for ssl you can - call ssl:versions/0

+

To see relevant version information for ssl, call ssl:versions/0.

-

To see all supported cipher suites - call ssl:cipher_suites/0. Note that available cipher suites - for a connection will depend on your certificate. It is also - possible to specify a specific cipher suite(s) that you - want your connection to use. Default is to use the strongest - available.

- -
+

To see all supported cipher suites, call ssl:cipher_suites/0. + The available cipher suites for a connection depend on your certificate. + Specific cipher suites that you want your connection to use can also be + specified. Default is to use the strongest available.

- Setting up connections + Setting up Connections -

Here follows some small example of how to set up client/server connections - using the erlang shell. The returned value of the sslsocket has been abbreviated with - [...] as it can be fairly large and is opaque.

+

This section shows a small example of how to set up client/server connections + using the Erlang shell. The returned value of the sslsocket is abbreviated + with [...] as it can be fairly large and is opaque.

- Minmal example + Minimal Example -

The minimal setup is not the most secure setup of ssl.

+

The minimal setup is not the most secure setup of SSL.

 - -

Start server side

+ +

To set up client/server connections:

+ +

Step 1: Start the server side:

1 server> ssl:start(). ok -

Create an ssl listen socket

+

Step 2: Create an SSL listen socket:

2 server> {ok, ListenSocket} = ssl:listen(9999, [{certfile, "cert.pem"}, {keyfile, "key.pem"},{reuseaddr, true}]). {ok,{sslsocket, [...]}} -

Do a transport accept on the ssl listen socket

+

Step 3: Do a transport accept on the SSL listen socket:

3 server> {ok, Socket} = ssl:transport_accept(ListenSocket). {ok,{sslsocket, [...]}} -

Start client side

+

Step 4: Start the client side:

1 client> ssl:start(). ok 2 client> {ok, Socket} = ssl:connect("localhost", 9999, [], infinity). {ok,{sslsocket, [...]}} -

Do the ssl handshake

+

Step 5: Do the SSL handshake:

4 server> ok = ssl:ssl_accept(Socket). ok -

Send a messag over ssl

+

Step 6: Send a message over SSL:

5 server> ssl:send(Socket, "foo"). ok -

Flush the shell message queue to see that we got the message - sent on the server side

+

Step 7: Flush the shell message queue to see that the message + was sent on the server side:

3 client> flush(). Shell got {ssl,{sslsocket,[...]},"foo"} ok
- Upgrade example + Upgrade Example -

To upgrade a TCP/IP connection to an ssl connection the - client and server have to aggre to do so. Agreement - may be accompliced by using a protocol such the one used by HTTP - specified in RFC 2817.

 +

To upgrade a TCP/IP connection to an SSL connection, the + client and server must agree to do so. The agreement + can be accomplished by using a protocol, for example, the one used by HTTP + specified in RFC 2817.

 + +

To upgrade to an SSL connection:

-

Start server side

+

Step 1: Start the server side:

1 server> ssl:start(). ok -

Create a normal tcp listen socket

+

Step 2: Create a normal TCP listen socket:

2 server> {ok, ListenSocket} = gen_tcp:listen(9999, [{reuseaddr, true}]). {ok, #Port<0.475>} -

Accept client connection

+

Step 3: Accept client connection:

3 server> {ok, Socket} = gen_tcp:accept(ListenSocket). {ok, #Port<0.476>} -

Start client side

+

Step 4: Start the client side:

1 client> ssl:start(). ok 2 client> {ok, Socket} = gen_tcp:connect("localhost", 9999, [], infinity). -

Make sure active is set to false before trying - to upgrade a connection to an ssl connection, otherwhise - ssl handshake messages may be deliverd to the wrong process.

+

Step 5: Ensure active is set to false before trying + to upgrade a connection to an SSL connection, otherwise + SSL handshake messages can be delivered to the wrong process:

4 server> inet:setopts(Socket, [{active, false}]). ok -

Do the ssl handshake.

+

Step 6: Do the SSL handshake:

5 server> {ok, SSLSocket} = ssl:ssl_accept(Socket, [{cacertfile, "cacerts.pem"}, {certfile, "cert.pem"}, {keyfile, "key.pem"}]). {ok,{sslsocket,[...]}} -

Upgrade to an ssl connection. Note that the client and server - must agree upon the upgrade and the server must call - ssl:accept/2 before the client calls ssl:connect/3.

+

Step 7: Upgrade to an SSL connection. The client and server + must agree upon the upgrade. The server must call + ssl:accept/2 before the client calls ssl:connect/3.

3 client>{ok, SSLSocket} = ssl:connect(Socket, [{cacertfile, "cacerts.pem"}, {certfile, "cert.pem"}, {keyfile, "key.pem"}], infinity). {ok,{sslsocket,[...]}} -

Send a messag over ssl

+

Step 8: Send a message over SSL:

4 client> ssl:send(SSLSocket, "foo"). ok -

Set active true on the ssl socket

+

Step 9: Set active true on the SSL socket:

4 server> ssl:setopts(SSLSocket, [{active, true}]). ok -

Flush the shell message queue to see that we got the message - sent on the client side

+

Step 10: Flush the shell message queue to see that the message + was sent on the client side:

5 server> flush(). Shell got {ssl,{sslsocket,[...]},"foo"} ok -- cgit v1.2.3