1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
|
<!--
%CopyrightBegin%
Copyright Ericsson AB 2023-2024. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
%CopyrightEnd%
-->
# SSL Application
The ssl application provides secure communication over sockets.
## Description
The ssl application is an implementation of the TLS (previously known as SSL) and DTLS protocols in
Erlang.
For current statement of standards compliance see the
[User's Guide](standards_compliance.md).
## Dependencies
The SSL application uses the `Public_Key`, `Asn1` 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.
## Configuration
The application environment configuration parameters in this section are defined
for the SSL application. For more information about configuration parameters,
see the `m:application` manual page in Kernel.
> #### Note {: .info }
All parameters including the wording 'session_ticket' are TLS-1.3 only configuration
and other session parameters are prior to TLS-1.3 only configuration. DTLS versions
are based on TLS versions see [standard compliance](standards_compliance.md) for mapping.
The environment parameters can be set on the command line, for example:
`erl -ssl protocol_version "['tlsv1.2', 'tlsv1.1']"`
- **`protocol_version = ` `t:ssl:tls_version/0` | [`t:ssl:tls_version/0`]
`<optional>`** - Protocol supported by started clients and servers. If this
option is not set, it defaults to all TLS protocols currently supported, more
might be configurable, by the SSL application. This option can be overridden
by the version option to `ssl:connect/2,3` and `ssl:listen/2`.
- **`dtls_protocol_version = ` `t:ssl:dtls_version/0` | [`t:ssl:dtls_version/0`]
`<optional>`** - Protocol supported by started clients and servers. If this
option is not set, it defaults to all DTLS protocols currently supported, more
might be configurable, by the SSL application. This option can be overridden
by the version option to `ssl:connect/2,3` and `ssl:listen/2`.
- **`session_lifetime = integer() <optional>`** - Maximum lifetime of the
session data in seconds. Defaults to 24 hours which is the maximum recommended
lifetime by [RFC 5246](http://www.ietf.org/rfc/5246rfc.txt). However sessions
may be invalidated earlier due to the maximum limitation of the session cache
table.
- **`session_cb = atom() <optional>`** - Deprecated Since OTP-23.3 replaced by
`client_session_cb` and `server_session_cb`
- **`client_session_cb = atom() <optional>`** - Since OTP-23.3 Name client of
the session cache callback module that implements the `ssl_session_cache_api`
behavior. Defaults to `ssl_client_session_cache_db`.
- **`server_session_cb = atom() <optional>`** - Since OTP-23.3 Name of the
server session cache callback module that implements the
`ssl_session_cache_api` behavior. Defaults to `ssl_server_session_cache_db`.
- **`session_cb_init_args = proplist:proplist() <optional>`** - Deprecated Since
OTP-23.3 replaced by `client_session_cb_init_args` and
`server_session_cb_init_args`
- **`client_session_cb_init_args = proplist:proplist() <optional>`** - List of
extra user-defined arguments to the `init` function in the session cache
callback module. Defaults to `[]`.
- **`server_session_cb_init_args = proplist:proplist() <optional>`** - List of
extra user-defined arguments to the `init` function in the session cache
callback module. Defaults to `[]`.
- **`session_cache_client_max = integer() <optional>`
**
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.
- **`session_cache_server_max = integer() <optional>`** - 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.
- **`ssl_pem_cache_clean = integer() <optional>`** - Number of milliseconds
between PEM cache validations. Defaults to 2 minutes.
Note: The cache can be reloaded by calling `ssl:clear_pem_cache/0`.
- **`bypass_pem_cache = boolean() <optional>`** - 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.
- **`alert_timeout = integer() <optional>`** - 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.
- **`internal_active_n = integer() <optional>`** - 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).
- **`server_session_tickets_amount = integer() <optional>`** - Number of session
tickets sent by the server. It must be greater than 0. Defaults to 3.
- **`server_session_ticket_lifetime = integer() <optional>`** - Lifetime of
session tickets sent by the server. Servers must not use any value greater
than 604800 seconds (7 days). Expired tickets are automatically removed.
Defaults to 7200 seconds (2 hours).
- **`server_session_ticket_store_size = integer() <optional>`** - Sets the
maximum size of the server session ticket store (stateful tickets). Defaults
to 1000. Size limit is enforced by dropping old tickets.
- **`server_session_ticket_max_early_data = integer() <optional>`** - Sets the
maximum size of the early data that the server accepts and also configures its
NewSessionTicket messages to include this same size limit in their
early_data_indication extension. Defaults to 16384. Size limit is enforced by
both client and server.
- **`client_session_ticket_lifetime = integer() <optional>`** - Lifetime of
session tickets in the client ticket store. Expired tickets are automatically
removed. Defaults to 7200 seconds (2 hours).
- **`client_session_ticket_store_size = integer() <optional>`** - Sets the
maximum size of the client session ticket store. Defaults to 1000. Size limit
is enforced by dropping old tickets.
## Error Logger and Event Handlers
The SSL application uses [OTP logger](`m:logger`). TLS/DTLS alerts are logged on
notice level. Unexpected errors are logged on error level. These log entries
will by default end up in the default Erlang log. The option `log_level` may be
used to in run-time to set the log level of a specific TLS connection, which is
handy when you want to use level debug to inspect the TLS handshake setup.
## See Also
`m:application`
|
