1ssl(7)                   Erlang Application Definition                  ssl(7)
2
3
4

NAME

6       ssl - The ssl application provides secure communication over
7         sockets.
8

DESCRIPTION

10       The  ssl application is an implementation of the SSL, TLS and DTLS pro‐
11       tocols in Erlang.
12
13       For current statement of standards compliance see the User's Guide.
14

DEPENDENCIES

16       The SSL application uses the public_key, asn1 and Crypto application to
17       handle  public  keys  and  encryption, hence these applications must be
18       loaded for the SSL application to work. In an embedded environment this
19       means  they must be started with application:start/[1,2] before the SSL
20       application is started.
21

CONFIGURATION

23       The application environment configuration parameters  in  this  section
24       are defined for the SSL application. For more information about config‐
25       uration parameters, see the application(3) manual page in Kernel.
26
27       The environment parameters can be set on the command line, for example:
28
29       erl -ssl protocol_version "['tlsv1.2', 'tlsv1.1']"
30
31         protocol_version  =  ssl:tls_version()  |  [ssl:tls_version()]   <op‐
32         tional>:
33           Protocol  supported  by started clients and servers. If this option
34           is not set, it defaults to all TLS protocols  currently  supported,
35           more might be configurable, by the SSL application. This option can
36           be overridden  by  the  version  option  to  ssl:connect/[2,3]  and
37           ssl:listen/2.
38
39         dtls_protocol_version  =  ssl:dtls_version()  |  [ssl:dtls_version()]
40         <optional>:
41           Protocol supported by started clients and servers. If  this  option
42           is  not set, it defaults to all DTLS protocols currently supported,
43           more might be configurable, by the SSL application. This option can
44           be  overridden  by  the  version  option  to  ssl:connect/[2,3] and
45           ssl:listen/2.
46
47         session_lifetime = integer() <optional>:
48           Maximum lifetime of the session data in  seconds.  Defaults  to  24
49           hours  which  is the maximum recommended lifetime by RFC 5246. How‐
50           ever sessions may be invalidated earlier due to the maximum limita‐
51           tion of the session cache table.
52
53         session_cb = atom() <optional>:
54           Deprecated   Since   OTP-23.3  replaced  by  client_session_cb  and
55           server_session_cb
56
57         client_session_cb = atom() <optional>:
58           Since OTP-23.3 Name client of the  session  cache  callback  module
59           that  implements  the  ssl_session_cache_api  behavior. Defaults to
60           ssl_client_session_cache_db.
61
62         server_session_cb = atom() <optional>:
63           Since OTP-23.3 Name of the server  session  cache  callback  module
64           that  implements  the  ssl_session_cache_api  behavior. Defaults to
65           ssl_server_session_cache_db.
66
67         session_cb_init_args = proplist:proplist() <optional>:
68           Deprecated Since OTP-23.3 replaced  by  client_session_cb_init_args
69           and server_session_cb_init_args
70
71         client_session_cb_init_args = proplist:proplist() <optional>:
72           List  of  extra  user-defined arguments to the init function in the
73           session cache callback module. Defaults to [].
74
75         server_session_cb_init_args = proplist:proplist() <optional>:
76           List of extra user-defined arguments to the init  function  in  the
77           session cache callback module. Defaults to [].
78
79         session_cache_client_max = integer() <optional>
80           :  Limits the growth of the clients session cache, that is how many
81           sessions towards servers that are cached to be used by  new  client
82           connections. If the maximum number of sessions is reached, the cur‐
83           rent cache entries will be invalidated regardless of their  remain‐
84           ing  lifetime. Defaults to 1000. Recommended ssl-8.2.1 or later for
85           this option to work as intended.
86
87         session_cache_server_max = integer() <optional>:
88           Limits the growth of the servers session cache, that  is  how  many
89           client  sessions are cached by the server. If the maximum number of
90           sessions is reached, the current cache entries will be  invalidated
91           regardless  of  their  remaining lifetime. Defaults to 1000. Recom‐
92           mended ssl-8.2.1 or later for this option to work as intended.
93
94         ssl_pem_cache_clean = integer() <optional>:
95           Number of milliseconds between PEM cache validations. Defaults to 2
96           minutes.ssl:clear_pem_cache/0
97
98         bypass_pem_cache = boolean() <optional>:
99           Introduced  in  ssl-8.0.2. Disables the PEM-cache. Can be used as a
100           workaround for the PEM-cache bottleneck before ssl-8.1.1.  Defaults
101           to false.
102
103         alert_timeout = integer() <optional>:
104           Number of milliseconds between sending of a fatal alert and closing
105           the connection. Waiting a little while improves the  peers  chances
106           to  properly receiving the alert so it may shutdown gracefully. De‐
107           faults to 5000 milliseconds.
108
109         internal_active_n = integer() <optional>:
110           For TLS connections this value  is  used  to  handle  the  internal
111           socket. As the implementation was changed from an active once to an
112           active N behavior (N = 100), for performance reasons,  this  option
113           exist  for  possible tweaking or restoring of the old behavior (in‐
114           ternal_active_n = 1) in unforeseen scenarios. The option  will  not
115           affect  erlang distribution over TLS that will always run in active
116           N mode. Added in ssl-9.1 (OTP-21.2).
117
118         server_session_tickets_amount = integer() <optional>:
119           Number of session tickets sent by the server. It  must  be  greater
120           than 0. Defaults to 3.
121
122         server_session_ticket_lifetime = integer() <optional>:
123           Lifetime  of  session  tickets sent by the server. Servers must not
124           use any value greater than 604800 seconds (7 days). Expired tickets
125           are automatically removed. Defaults to 7200 seconds (2 hours).
126
127         server_session_ticket_store_size = integer() <optional>:
128           Sets  the maximum size of the server session ticket store (stateful
129           tickets). Defaults to 1000. Size limit is enforced by dropping  old
130           tickets.
131
132         server_session_ticket_max_early_data = integer() <optional>:
133           Sets the maximum size of the early data that the server accepts and
134           also configures its NewSessionTicket messages to include this  same
135           size  limit  in  their early_data_indication extension. Defaults to
136           16384. Size limit is enforced by both client and server.
137
138         client_session_ticket_lifetime = integer() <optional>:
139           Lifetime of session tickets in the  client  ticket  store.  Expired
140           tickets  are  automatically  removed.  Defaults  to 7200 seconds (2
141           hours).
142
143         client_session_ticket_store_size = integer() <optional>:
144           Sets the maximum size of the client session ticket store.  Defaults
145           to 1000. Size limit is enforced by dropping old tickets.
146

ERROR LOGGER AND EVENT HANDLERS

148       The  SSL application uses OTP logger. TLS/DTLS alerts are logged on no‐
149       tice level. Unexpected errors are logged on error level. These log  en‐
150       tries  will  by  default  end  up in the default Erlang log. The option
151       log_level may be used to in run-time to set the log level of a specific
152       TLS  connection, which is handy when you want to use level debug to in‐
153       spect the TLS handshake setup.
154

SEE ALSO

156       application(3)
157
158
159
160Ericsson AB                       ssl 10.5.3                            ssl(7)
Impressum