Debian Codegraph @

doc/src/manual/ranch_ssl.asciidoc

raw
1 = ranch_ssl(3)
2
3 == Name
4
5 ranch_ssl - SSL transport
6
7 == Description
8
9 The module `ranch_ssl` implements an SSL Ranch transport.
10
11 == Exports
12
13 The module `ranch_ssl` implements the interface defined
14 by link:man:ranch_transport(3)[ranch_transport(3)].
15
16 == Types
17
18 === opt()
19
20 [source,erlang]
21 ----
22 opt() :: ranch_tcp:opt() | ssl_opt()
23 ----
24
25 Listen options.
26
27 The TCP options are defined in link:man:ranch_tcp(3)[ranch_tcp(3)].
28
29 === opts()
30
31 [source,erlang]
32 ----
33 opts() :: [opt()]
34 ----
35
36 List of listen options.
37
38 === ssl_opt()
39
40 [source,erlang]
41 ----
42 ssl_opt() = {alpn_preferred_protocols, [binary()]}
43 | {anti_replay, '10k' | '100k' | {integer(), integer(), integer()}}
44 | {beast_mitigation, one_n_minus_one | zero_n | disabled}
45 | {cacertfile, file:filename()}
46 | {cacerts, [public_key:der_encoded()]}
47 | {cert, public_key:der_encoded()}
48 | {certs_keys, [#{cert => public_key:der_encoded(),
49 key => ssl:key(),
50 certfile => file:filename(),
51 keyfile => file:filename(),
52 key_pem_password => iodata() | fun(() -> iodata())}]}
53 | {certfile, file:filename()}
54 | {ciphers, ssl:ciphers()}
55 | {client_renegotiation, boolean()}
56 | {crl_cache, [any()]}
57 | {crl_check, boolean() | peer | best_effort}
58 | {depth, integer()}
59 | {dh, binary()}
60 | {dhfile, file:filename()}
61 | {eccs, [ssl:named_curve()]}
62 | {fail_if_no_peer_cert, boolean()}
63 | {handshake, hello | full}
64 | {hibernate_after, timeout()}
65 | {honor_cipher_order, boolean()}
66 | {honor_ecc_order, boolean()}
67 | {key, ssl:key()}
68 | {key_update_at, pos_integer()}
69 | {keyfile, file:filename()}
70 | {log_alert, boolean()}
71 | {log_level, logger:level()}
72 | {max_handshake_size, integer()}
73 | {middlebox_comp_mode, boolean()}
74 | {next_protocols_advertised, [binary()]}
75 | {padding_check, boolean()}
76 | {partial_chain, fun()}
77 | {password, string()}
78 | {protocol, tls | dtls}
79 | {psk_identity, string()}
80 | {reuse_session, fun()}
81 | {reuse_sessions, boolean()}
82 | {secure_renegotiate, boolean()}
83 | {session_tickets, disabled | stateful | stateless}
84 | {signature_algs, [{ssl:hash(), ssl:sign_algo()}]}
85 | {signature_algs_cert, [ssl:sign_scheme()]}
86 | {sni_fun, fun()}
87 | {sni_hosts, [{string(), ssl_opt()}]}
88 | {supported_groups, [ssl:group()]}
89 | {user_lookup_fun, {fun(), any()}}
90 | {verify, verify_none | verify_peer}
91 | {verify_fun, {fun(), any()}}
92 | {versions, [ssl:protocol_version()]}
93 ----
94
95 SSL-specific listen options.
96
97 Specifying a certificate is mandatory, either through the `cert`
98 or `certfile` option, or by configuring SNI. None of the other
99 options are required.
100
101 The default value is given next to the option name:
102
103 alpn_preferred_protocols::
104
105 Perform Application-Layer Protocol Negotiation
106 with the given list of preferred protocols.
107
108 anti_replay::
109
110 Configures the server's built-in anti replay feature based on
111 Bloom filters.
112
113 beast_mitigation (one_n_minus_one)::
114
115 Change the BEAST mitigation strategy for SSL-3.0 and TLS-1.0
116 to interoperate with legacy software.
117
118 cacertfile::
119
120 Path to PEM encoded trusted certificates file used to verify
121 peer certificates.
122
123 cacerts::
124
125 List of DER encoded trusted certificates.
126
127 cert::
128
129 DER encoded user certificate.
130
131 certs_keys::
132
133 A list of a certificate (or possible a certificate and its chain)
134 and the associated key of the certificate, that may be used to
135 authenticate the client or the server.
136
137 certfile::
138
139 Path to the PEM encoded user certificate file. May also
140 contain the private key.
141
142 ciphers::
143
144 List of ciphers that clients are allowed to use.
145
146 client_renegotiation (true)::
147
148 Whether to allow client-initiated renegotiation.
149
150 crl_cache ({ssl_crl_cache, {internal, []}})::
151
152 Customize the module used to cache Certificate Revocation Lists.
153
154 crl_check (false)::
155
156 Whether to perform CRL check on all certificates in the chain
157 during validation.
158
159 depth (1)::
160
161 Maximum of intermediate certificates allowed in the
162 certification path.
163
164 dh::
165
166 DER encoded Diffie-Hellman parameters.
167
168 dhfile::
169
170 Path to the PEM encoded Diffie-Hellman parameters file.
171
172 eccs::
173
174 List of named ECC curves.
175
176 fail_if_no_peer_cert (false)::
177
178 Whether to refuse the connection if the client sends an
179 empty certificate.
180
181 handshake (full)::
182
183 If `hello` is specified for this option, the handshake is
184 paused after receiving the client hello message. The handshake
185 can then be resumed via `handshake_continue/3`, or cancelled
186 via `handshake_cancel/1`.
187 +
188 This option cannot be given to `ranch:handshake/1,2`.
189
190 hibernate_after (undefined)::
191
192 Time in ms after which SSL socket processes go into
193 hibernation to reduce memory usage.
194
195 honor_cipher_order (false)::
196
197 If true, use the server's preference for cipher selection.
198 If false, use the client's preference.
199
200 honor_ecc_order (false)::
201
202 If true, use the server's preference for ECC curve selection.
203 If false, use the client's preference.
204
205 key::
206
207 DER encoded user private key.
208
209 key_update_at::
210
211 Configures the maximum amount of bytes that can be sent on a
212 TLS 1.3 connection before an automatic key update is performed.
213
214 keyfile::
215
216 Path to the PEM encoded private key file, if different from
217 the certfile.
218
219 log_alert (true)::
220
221 If false, error reports will not be displayed.
222
223 log_level::
224
225 Specifies the log level for TLS/DTLS.
226
227 max_handshake_size (256*1024)::
228
229 Used to limit the size of valid TLS handshake packets to
230 avoid DoS attacks.
231
232 middlebox_comp_mode (true)::
233
234 Configures the middlebox compatibility mode on a TLS 1.3
235 connection.
236
237 next_protocols_advertised::
238
239 List of protocols to send to the client if it supports the
240 Next Protocol extension.
241
242 padding_check::
243
244 Allow disabling the block cipher padding check for TLS-1.0
245 to be able to interoperate with legacy software.
246
247 partial_chain::
248
249 Claim an intermediate CA in the chain as trusted.
250
251 password::
252
253 Password to the private key file, if password protected.
254
255 protocol (tls)::
256
257 Choose TLS or DTLS protocol for the transport layer security.
258
259 psk_identity::
260
261 Provide the given PSK identity hint to the client during the
262 handshake.
263
264 reuse_session::
265
266 Custom policy to decide whether a session should be reused.
267
268 reuse_sessions (false)::
269
270 Whether to allow session reuse.
271
272 secure_renegotiate (false)::
273
274 Whether to reject renegotiation attempts that do not conform
275 to RFC5746.
276
277 session_tickets::
278
279 Configures the session ticket functionality.
280
281 signature_algs::
282
283 The TLS signature algorithm extension may be used, from TLS 1.2,
284 to negotiate which signature algorithm to use during the TLS
285 handshake.
286
287 signature_algs_cert::
288
289 List of signature schemes for the signature_algs_cert extension
290 introduced in TLS 1.3, in order to make special requirements
291 on signatures used in certificates.
292
293 sni_fun::
294
295 Function called when the client requests a host using Server
296 Name Indication. Returns options to apply.
297
298 sni_hosts::
299
300 Options to apply for the host that matches what the client
301 requested with Server Name Indication.
302
303 supported_groups([x25519, x448, secp256r1, secp384r1])::
304
305 TLS 1.3 introduces the `supported_groups` extension that is
306 used for negotiating the Diffie-Hellman parameters in a
307 TLS 1.3 handshake. Both client and server can specify a list
308 of parameters that they are willing to use.
309
310 user_lookup_fun::
311
312 Function called to determine the shared secret when using PSK,
313 or provide parameters when using SRP.
314
315 verify (verify_none)::
316
317 Use `verify_peer` to request a certificate from the client.
318
319 verify_fun::
320
321 Custom policy to decide whether a client certificate is valid.
322
323 versions::
324
325 TLS protocol versions that will be supported.
326
327 Note that the client will not send a certificate unless the
328 value for the `verify` option is set to `verify_peer`. This
329 means that `fail_if_no_peer_cert` only applies when combined
330 with the `verify` option. The `verify_fun` option allows
331 greater control over the client certificate validation.
332
333 The options `sni_fun` and `sni_hosts` are mutually exclusive.
334
335 == Changelog
336
337 * *2.0*: The `ssl_opt()` type was updated for OTP-23.0.
338
339 == See also
340
341 link:man:ranch(7)[ranch(7)],
342 link:man:ranch_transport(3)[ranch_transport(3)],
343 link:man:ranch_tcp(3)[ranch_tcp(3)],
344 ssl(3)