.TH ssl 7 "ssl 9.1.2" "Ericsson AB" "Erlang Application Definition" .SH NAME ssl \- The ssl application provides secure communication over sockets. .SH DESCRIPTION .LP The ssl application is an implementation of the SSL/TLS/DTLS protocol in Erlang\&. .RS 2 .TP 2 * Supported SSL/TLS/DTLS-versions are SSL-3\&.0, TLS-1\&.0, TLS-1\&.1, TLS-1\&.2, DTLS-1\&.0 (based on TLS-1\&.1), DTLS-1\&.2 (based on TLS-1\&.2) .LP .TP 2 * For security reasons SSL-2\&.0 is not supported\&. Interoperability with SSL-2\&.0 enabled clients dropped\&. (OTP 21) .LP .TP 2 * For security reasons SSL-3\&.0 is no longer supported by default, but can be configured\&. (OTP 19) .LP .TP 2 * For security reasons RSA key exchange cipher suites are no longer supported by default, but can be configured\&. (OTP 21) .LP .TP 2 * For security reasons DES cipher suites are no longer supported by default, but can be configured\&. (OTP 20) .LP .TP 2 * For security reasons 3DES cipher suites are no longer supported by default, but can be configured\&. (OTP 21) .LP .TP 2 * Renegotiation Indication Extension RFC 5746 is supported .LP .TP 2 * Ephemeral Diffie-Hellman cipher suites are supported, but not Diffie Hellman Certificates cipher suites\&. .LP .TP 2 * Elliptic Curve cipher suites are supported if the Crypto application supports it and named curves are used\&. .LP .TP 2 * Export cipher suites are not supported as the U\&.S\&. lifted its export restrictions in early 2000\&. .LP .TP 2 * IDEA cipher suites are not supported as they have become deprecated by the latest TLS specification so it is not motivated to implement them\&. .LP .TP 2 * Compression is not supported\&. .LP .TP 2 * CRL validation is supported\&. .LP .TP 2 * Policy certificate extensions are not supported\&. .LP .TP 2 * \&'Server Name Indication\&' extension (RFC 6066) is supported\&. .LP .TP 2 * Application Layer Protocol Negotiation (ALPN) and its successor Next Protocol Negotiation (NPN) are supported\&. .LP .TP 2 * It is possible to use Pre-Shared Key (PSK) and Secure Remote Password (SRP) cipher suites, but they are not enabled by default\&. .LP .RE .SH "DEPENDENCIES" .LP The SSL application uses the \fIpublic_key\fR\&, \fIasn1\fR\& 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 \fIapplication:start/[1,2]\fR\& before the SSL application is started\&. .SH "CONFIGURATION" .LP The application environment configuration parameters in this section are defined for the SSL application\&. For more information about configuration parameters, see the \fBapplication(3erl)\fR\& manual page in Kernel\&. .LP The environment parameters can be set on the command line, for example: .LP \fIerl -ssl protocol_version "[\&'tlsv1\&.2\&', \&'tlsv1\&.1\&']"\fR\& .RS 2 .TP 2 .B \fIprotocol_version = \fR\&\fBssl:ssl_tls_protocol()\fR\&\fI\fR\&: Protocol supported by started clients and servers\&. If this option is not set, it defaults to all TLS protocols currently supported by the SSL application\&. This option can be overridden by the version option to \fIssl:connect/[2,3]\fR\& and \fIssl:listen/2\fR\&\&. .TP 2 .B \fIdtls_protocol_version = \fR\&\fBssl:dtls_protocol()\fR\&\fI\fR\&: Protocol supported by started clients and servers\&. If this option is not set, it defaults to all DTLS protocols currently supported by the SSL application\&. This option can be overridden by the version option to \fIssl:connect/[2,3]\fR\& and \fIssl:listen/2\fR\&\&. .TP 2 .B \fIsession_lifetime = integer() \fR\&: Maximum lifetime of the session data in seconds\&. Defaults to 24 hours which is the maximum recommended lifetime by RFC 5246\&. However sessions may be invalidated earlier due to the maximum limitation of the session cache table\&. .TP 2 .B \fIsession_cb = atom() \fR\&: Name of the session cache callback module that implements the \fIssl_session_cache_api\fR\& behavior\&. Defaults to \fIssl_session_cache\fR\&\&. .TP 2 .B \fIsession_cb_init_args = proplist:proplist() \fR\&: List of extra user-defined arguments to the \fIinit\fR\& function in the session cache callback module\&. Defaults to \fI[]\fR\&\&. .TP 2 .B \fIsession_cache_client_max = integer() \fR\& .br : Limits the growth of the clients session cache, that is how many sessions towards servers that are cached to be used by new client connections\&. If the maximum number of sessions is reached, the current cache entries will be invalidated regardless of their remaining lifetime\&. Defaults to 1000\&. Recommended ssl-8\&.2\&.1 or later for this option to work as intended\&. .TP 2 .B \fIsession_cache_server_max = integer() \fR\&: Limits the growth of the servers session cache, that is how many client sessions are cached by the server\&. If the maximum number of sessions is reached, the current cache entries will be invalidated regardless of their remaining lifetime\&. Defaults to 1000\&. Recommended ssl-8\&.2\&.1 or later for this option to work as intended\&. .TP 2 .B \fIssl_pem_cache_clean = integer() \fR\&: Number of milliseconds between PEM cache validations\&. Defaults to 2 minutes\&.\fBssl:clear_pem_cache/0\fR\& .TP 2 .B \fIbypass_pem_cache = boolean() \fR\&: Introduced in ssl-8\&.0\&.2\&. Disables the PEM-cache\&. Can be used as a workaround for the PEM-cache bottleneck before ssl-8\&.1\&.1\&. Defaults to false\&. .TP 2 .B \fIalert_timeout = integer() \fR\&: Number of milliseconds between sending of a fatal alert and closing the connection\&. Waiting a little while improves the peers chances to properly receiving the alert so it may shutdown gracefully\&. Defaults to 5000 milliseconds\&. .TP 2 .B \fIinternal_active_n = integer() \fR\&: For TLS connections this value is used to handle the internal socket\&. As the implementation was changed from an active once to an active N behavior (N = 100), for performance reasons, this option exist for possible tweaking or restoring of the old behavior (internal_active_n = 1) in unforeseen scenarios\&. The option will not affect erlang distribution over TLS that will always run in active N mode\&. Added in ssl-9\&.1 (OTP-21\&.2)\&. .RE .SH "ERROR LOGGER AND EVENT HANDLERS" .LP The SSL application uses the default \fBOTP error logger\fR\& to log unexpected errors and TLS/DTLS alerts\&. The logging of TLS/DTLS alerts may be turned off with the \fIlog_alert\fR\& option\&. .SH "SEE ALSO" .LP \fBapplication(3erl)\fR\&