1ssl(3) Erlang Module Definition ssl(3)
2
6 ssl - Interface Functions for Secure Socket Layer
7
9 This module contains interface functions for the TLS/DTLS protocol. For
10 detailed information about the supported standards see ssl(6).
11
13 Types used in TLS/DTLS
14 socket() = gen_tcp:socket()
15 sslsocket() = any()
17 An opaque reference to the TLS/DTLS connection, may be used for
19 equality matching.
20 tls_option() = tls_client_option() | tls_server_option()
22 tls_client_option() =
24 client_option() |
25 common_option() |
26 socket_option() |
27 transport_option()
28 tls_server_option() =
30 server_option() |
31 common_option() |
32 socket_option() |
33 transport_option()
34 socket_option() =
36 gen_tcp:connect_option() |
37 gen_tcp:listen_option() |
38 gen_udp:option()
39 The default socket options are [{mode,list},{packet, 0},{header,
41 0},{active, true}].
42 For valid options, see the inet(3), gen_tcp(3) and gen_udp(3)
44 manual pages in Kernel. Note that stream oriented options such
45 as packet are only relevant for TLS and not DTLS
46 active_msgs() =
48 {ssl, sslsocket(), Data :: binary() | list()} |
49 {ssl_closed, sslsocket()} |
50 {ssl_error, sslsocket(), Reason :: any()} |
51 {ssl_passive, sslsocket()}
52 When a TLS/DTLS socket is in active mode (the default), data
54 from the socket is delivered to the owner of the socket in the
55 form of messages as described above.
56 The ssl_passive message is sent only when the socket is in {ac‐
58 tive, N} mode and the counter dropped to 0. It indicates that
59 the socket has transitioned to passive ({active, false}) mode.
60 transport_option() =
62 {cb_info,
63 {CallbackModule :: atom(),
64 DataTag :: atom(),
65 ClosedTag :: atom(),
66 ErrTag :: atom()}} |
67 {cb_info,
68 {CallbackModule :: atom(),
69 DataTag :: atom(),
70 ClosedTag :: atom(),
71 ErrTag :: atom(),
72 PassiveTag :: atom()}}
73 Defaults to {gen_tcp, tcp, tcp_closed, tcp_error, tcp_passive}
75 for TLS (for backward compatibility a four tuple will be con‐
76 verted to a five tuple with the last element "second_ele‐
77 ment"_passive) and {gen_udp, udp, udp_closed, udp_error} for
78 DTLS (might also be changed to five tuple in the future). Can be
79 used to customize the transport layer. The tag values should be
80 the values used by the underlying transport in its active mode
81 messages. For TLS the callback module must implement a reliable
82 transport protocol, behave as gen_tcp, and have functions corre‐
83 sponding to inet:setopts/2, inet:getopts/2, inet:peername/1,
84 inet:sockname/1, and inet:port/1. The callback gen_tcp is
85 treated specially and calls inet directly. For DTLS this feature
86 must be considered experimental.
87 host() = hostname() | ip_address()
89 hostname() = string()
91 ip_address() = inet:ip_address()
93 protocol_version() = tls_version() | dtls_version()
95 tls_version() = 'tlsv1.2' | 'tlsv1.3' | tls_legacy_version()
97 dtls_version() = 'dtlsv1.2' | dtls_legacy_version()
99 tls_legacy_version() = tlsv1 | 'tlsv1.1'
101 dtls_legacy_version() = dtlsv1
103 prf_random() = client_random | server_random
105 verify_type() = verify_none | verify_peer
107 ciphers() = [erl_cipher_suite()] | string()
109 erl_cipher_suite() =
111 #{key_exchange := kex_algo(),
112 cipher := cipher(),
113 mac := hash() | aead,
114 prf := hash() | default_prf}
115 cipher() =
117 aes_128_cbc | aes_256_cbc | aes_128_gcm | aes_256_gcm |
118 aes_128_ccm | aes_256_ccm | aes_128_ccm_8 | aes_256_ccm_8 |
119 chacha20_poly1305 |
120 legacy_cipher()
121 legacy_cipher() = rc4_128 | des_cbc | '3des_ede_cbc'
123 cipher_filters() =
125 [{key_exchange | cipher | mac | prf, algo_filter()}]
126 hash() = sha | sha2() | legacy_hash()
128 sha2() = sha224 | sha256 | sha384 | sha512
130 legacy_hash() = md5
132 old_cipher_suite() =
134 {kex_algo(), cipher(), hash()} |
135 {kex_algo(), cipher(), hash() | aead, hash()}
136 sign_algo() = rsa | dsa | ecdsa | eddsa
138 sign_scheme() =
140 eddsa_ed25519 | eddsa_ed448 | ecdsa_secp256r1_sha256 |
141 ecdsa_secp384r1_sha384 | ecdsa_secp521r1_sha512 |
142 rsassa_pss_scheme() |
143 sign_scheme_legacy()
144 rsassa_pss_scheme() =
146 rsa_pss_rsae_sha256 | rsa_pss_rsae_sha384 |
147 rsa_pss_rsae_sha512 | rsa_pss_pss_sha256 |
148 rsa_pss_pss_sha384 | rsa_pss_pss_sha512
149 sign_scheme_legacy() =
151 rsa_pkcs1_sha256 | rsa_pkcs1_sha384 | rsa_pkcs1_sha512 |
152 rsa_pkcs1_sha1 | ecdsa_sha1
153 group() =
155 secp256r1 | secp384r1 | secp521r1 | ffdhe2048 | ffdhe3072 |
156 ffdhe4096 | ffdhe6144 | ffdhe8192
157 kex_algo() =
159 rsa | dhe_rsa | dhe_dss | ecdhe_ecdsa | ecdh_ecdsa |
160 ecdh_rsa | srp_rsa | srp_dss | psk | dhe_psk | rsa_psk |
161 dh_anon | ecdh_anon | srp_anon | any
162 algo_filter() =
164 fun((kex_algo() | cipher() | hash() | aead | default_prf) ->
165 true | false)
166 named_curve() =
168 sect571r1 | sect571k1 | secp521r1 | brainpoolP512r1 |
169 sect409k1 | sect409r1 | brainpoolP384r1 | secp384r1 |
170 sect283k1 | sect283r1 | brainpoolP256r1 | secp256k1 |
171 secp256r1 | sect239k1 | sect233k1 | sect233r1 | secp224k1 |
172 secp224r1 | sect193r1 | sect193r2 | secp192k1 | secp192r1 |
173 sect163k1 | sect163r1 | sect163r2 | secp160k1 | secp160r1 |
174 secp160r2
175 psk_identity() = string()
177 srp_identity() = {Username :: string(), Password :: string()}
179 srp_param_type() =
181 srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 |
182 srp_6144 | srp_8192
183 app_level_protocol() = binary()
185 protocol_extensions() =
187 #{renegotiation_info => binary(),
188 signature_algs => signature_algs(),
189 alpn => app_level_protocol(),
190 srp => binary(),
191 next_protocol => app_level_protocol(),
192 max_frag_enum => 1..4,
193 ec_point_formats => [0..2],
194 elliptic_curves => [public_key:oid()],
195 sni => hostname()}
196 error_alert() =
198 {tls_alert, {tls_alert(), Description :: string()}}
199 tls_alert() =
201 close_notify | unexpected_message | bad_record_mac |
202 record_overflow | handshake_failure | bad_certificate |
203 unsupported_certificate | certificate_revoked |
204 certificate_expired | certificate_unknown |
205 illegal_parameter | unknown_ca | access_denied |
206 decode_error | decrypt_error | export_restriction |
207 protocol_version | insufficient_security | internal_error |
208 inappropriate_fallback | user_canceled | no_renegotiation |
209 unsupported_extension | certificate_unobtainable |
210 unrecognized_name | bad_certificate_status_response |
211 bad_certificate_hash_value | unknown_psk_identity |
212 no_application_protocol
213 reason() = any()
215 bloom_filter_window_size() = integer()
217 bloom_filter_hash_functions() = integer()
219 bloom_filter_bits() = integer()
221 client_session_tickets() = disabled | manual | auto
223 server_session_tickets() = disabled | stateful | stateless
225 TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT
227 common_option() =
228 {protocol, protocol()} |
229 {handshake, handshake_completion()} |
230 {cert, cert() | [cert()]} |
231 {certfile, cert_pem()} |
232 {key, key()} |
233 {keyfile, key_pem()} |
234 {password, key_pem_password()} |
235 {certs_keys, certs_keys()} |
236 {ciphers, cipher_suites()} |
237 {eccs, [named_curve()]} |
238 {signature_algs, signature_algs()} |
239 {signature_algs_cert, sign_schemes()} |
240 {supported_groups, supported_groups()} |
241 {secure_renegotiate, secure_renegotiation()} |
242 {keep_secrets, keep_secrets()} |
243 {depth, allowed_cert_chain_length()} |
244 {verify_fun, custom_verify()} |
245 {crl_check, crl_check()} |
246 {crl_cache, crl_cache_opts()} |
247 {max_handshake_size, handshake_size()} |
248 {partial_chain, root_fun()} |
249 {versions, protocol_versions()} |
250 {user_lookup_fun, custom_user_lookup()} |
251 {log_level, logging_level()} |
252 {log_alert, log_alert()} |
253 {hibernate_after, hibernate_after()} |
254 {padding_check, padding_check()} |
255 {beast_mitigation, beast_mitigation()} |
256 {ssl_imp, ssl_imp()} |
257 {session_tickets, session_tickets()} |
258 {key_update_at, key_update_at()} |
259 {receiver_spawn_opts, spawn_opts()} |
260 {sender_spawn_opts, spawn_opts()}
261 protocol() = tls | dtls
263 Choose TLS or DTLS protocol for the transport layer security.
265 Defaults to tls. For DTLS other transports than UDP are not yet
266 supported.
267 handshake_completion() = hello | full
269 Defaults to full. If hello is specified the handshake will pause
271 after the hello message and give the user a possibility make de‐
272 cisions based on hello extensions before continuing or aborting
273 the handshake by calling handshake_continue/3 or hand‐
274 shake_cancel/1
275 cert() = public_key:der_encoded()
277 The DER-encoded user certificate. Note that the cert option may
279 also be a list of DER-encoded certificates where the first one
280 is the user certificate, and the rest of the certificates con‐
281 stitutes the certificate chain. For maximum interoperability the
282 certificates in the chain should be in the correct order, the
283 chain will be sent as is to the peer. If chain certificates are
284 not provided, certificates from client_cacerts(), server_cac‐
285 erts(), or client_cafile(), server_cafile() are used to con‐
286 struct the chain. If this option is supplied, it overrides op‐
287 tion certfile.
288 cert_pem() = file:filename()
290 Path to a file containing the user certificate on PEM format or
292 possible several certificates where the first one is the user
293 certificate and the rest of the certificates constitutes the
294 certificate chain. For more details see cert(),
295 key() =
297 {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' |
298 'PrivateKeyInfo',
299 public_key:der_encoded()} |
300 #{algorithm := rsa | dss | ecdsa,
301 engine := crypto:engine_ref(),
302 key_id := crypto:key_id(),
303 password => crypto:password()}
304 The DER-encoded user's private key or a map referring to a
306 crypto engine and its key reference that optionally can be pass‐
307 word protected, see also crypto:engine_load/3 and Crypto's
308 Users Guide. If this option is supplied, it overrides option
309 keyfile.
310 key_pem() = file:filename()
312 Path to the file containing the user's private PEM-encoded key.
314 As PEM-files can contain several entries, this option defaults
315 to the same file as given by option certfile.
316 key_pem_password() = iodata() | fun(() -> iodata())
318 String containing the user's password or a function returning
320 same type. Only used if the private keyfile is password-pro‐
321 tected.
322 certs_keys() = [cert_key_conf()]
324 A list of a certificate (or possible a certificate and its
326 chain) and the associated key of the certificate, that may be
327 used to authenticate the client or the server. The certificate
328 key pair that is considered best and matches negotiated parame‐
329 ters for the connection will be selected. Different signature
330 algorithms are prioritized in the order eddsa, ecdsa,
331 rsa_pss_pss, rsa and dsa . If more than one key is supplied for
332 the same signing algorithm (which is probably an unusual use
333 case) they will prioritized by strength unless it is a so called
334 engine key that will be favoured over other keys. As engine keys
335 cannot be inspected, supplying more than one engine key will
336 make no sense. This offers flexibility to for instance configure
337 a newer certificate that is expected to be used in most cases
338 and an older but acceptable certificate that will only be used
339 to communicate with legacy systems. Note that there is a trade
340 off between the induced overhead and the flexibility so alterna‐
341 tives should be chosen for good reasons. If the certs_keys op‐
342 tion is specified it overrides all single certificate and key
343 options. For examples see the Users Guide
344 Note:
346 eddsa certificates are only supported by TLS-1.3 that does not
347 support dsa certificates. rsa_pss_pss (RSA certificates using
348 Probabilistic Signature Scheme) are supported in TLS-1.2 and
349 TLS-1.3, but some TLS-1.2 implementations may not support
350 rsa_pss_pss.
351 cert_key_conf() =
354 #{cert => cert(),
355 key => key(),
356 certfile => cert_pem(),
357 keyfile => key_pem(),
358 password => key_pem_password()}
359 A certificate (or possibly a certificate and its chain) and its
361 associated key on one of the possible formats. For the PEM file
362 format there may also be a password associated with the file
363 containg the key.
364 cipher_suites() = ciphers()
366 A list of cipher suites that should be supported
368 The function ssl:cipher_suites/2 can be used to find all ci‐
370 pher suites that are supported by default and all cipher suites
371 that may be configured.
372 If you compose your own cipher_suites() make sure they are fil‐
374 tered for cryptolib support ssl:filter_cipher_suites/2 Addi‐
375 tionally the functions ssl:append_cipher_suites/2 ,
376 ssl:prepend_cipher_suites/2, ssl:suite_to_str/1,
377 ssl:str_to_suite/1, and ssl:suite_to_openssl_str/1 also exist to
378 help creating customized cipher suite lists.
379 Note:
381 Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping
382 sets of cipher suites so to support both these versions cipher
383 suites from both versions need to be included. Also if the sup‐
384 plied list does not comply with the configured versions or cryp‐
385 tolib so that the list becomes empty, this option will fallback
386 on its appropriate default value for the configured versions.
387 Non-default cipher suites including anonymous cipher suites (PRE
390 TLS-1.3) are supported for interop/testing purposes and may be
391 used by adding them to your cipher suite list. Note that they
392 must also be supported/enabled by the peer to actually be used.
393 signature_algs() = [{hash(), sign_algo()} | sign_scheme()]
395 Explicitly list acceptable signature algorithms for certificates
397 and handshake messages in the preferred order. The client will
398 send its list as the client hello signature_algorithm extension
399 introduced in TLS-1.2, see Section 7.4.1.4.1 in RFC 5246. Previ‐
400 ously these algorithms where implicitly chosen and partly de‐
401 rived from the cipher suite.
402 In TLS-1.2 a somewhat more explicit negotiation is made possible
404 using a list of {hash(), sign_algo()} pairs.
405 In TLS-1.3 these algorithm pairs are replaced by so called sig‐
407 nature schemes sign_scheme() and completely decoupled from the
408 cipher suite.
409 Signature algorithms used for certificates may be overridden by
411 the signature schemes (algorithms) supplied by the signa‐
412 ture_algs_cert option.
413 TLS-1.2 default is Default_TLS_12_Alg_Pairs interleaved with
415 rsa_pss_schemes since ssl-11.0 (OTP-25) pss_pss is prefered over
416 pss_rsae that is prefered over rsa
417 Default_TLS_12_Alg_Pairs =
419 [
421 %% SHA2
422 {sha512, ecdsa},
423 {sha512, rsa},
424 {sha384, ecdsa},
425 {sha384, rsa},
426 {sha256, ecdsa},
427 {sha256, rsa},
428 {sha224, ecdsa},
429 {sha224, rsa},
430 %% SHA
431 {sha, ecdsa},
432 {sha, rsa},
433 {sha, dsa}
434 ]
435 Support for {md5, rsa} was removed from the the TLS-1.2 default
437 in ssl-8.0 (OTP-22)
438 rsa_pss_schemes =
440 [rsa_pss_pss_sha512,
442 rsa_pss_pss_sha384,
443 rsa_pss_pss_sha256,
444 rsa_pss_rsae_sha512,
445 rsa_pss_rsae_sha384,
446 rsa_pss_rsae_sha256]
447 TLS_13_Legacy_Schemes =
450 [
452 %% Legacy algorithms only applicable to certificate signatures
453 rsa_pkcs1_sha512, %% Corresponds to {sha512, rsa}
454 rsa_pkcs1_sha384, %% Corresponds to {sha384, rsa}
455 rsa_pkcs1_sha256, %% Corresponds to {sha256, rsa}
456 ecdsa_sha1, %% Corresponds to {sha, ecdsa}
457 rsa_pkcs1_sha1 %% Corresponds to {sha, rsa}
458 ]
459 Default_TLS_13_Schemes =
462 [
464 %% EDDSA
465 eddsa_ed25519,
466 eddsa_ed448
467 %% ECDSA
469 ecdsa_secp521r1_sha512,
470 ecdsa_secp384r1_sha384,
471 ecdsa_secp256r1_sha256] ++
472 %% RSASSA-PSS
474 rsa_pss_schemes()
475 EDDSA was made highest priority in ssl-11.0 (OTP-25)
478 TLS-1.3 default is
480 Default_TLS_13_Schemes ++ Legacy_TLS_13_Schemes
482 If both TLS-1.3 and TLS-1.2 are supported the default will be
484 Default_TLS_13_Schemes ++ Default_TLS_12_Alg_Pairs
486 so appropriate algorithms can be chosen for the negotiated ver‐
488 sion.
489 Note:
491 TLS-1.2 algorithms will not be negotiated for TLS-1.3, but
492 TLS-1.3 RSASSA-PSS rsassa_pss_scheme() signature schemes may be
493 negotiated also for TLS-1.2 from 24.1 (fully working from
494 24.1.3). However if TLS-1.3 is negotiated when both TLS-1.3 and
495 TLS-1.2 is supported using defaults, the corresponding TLS-1.2
496 algorithms to the TLS-1.3 legacy signature schemes will be con‐
497 sidered as the legacy schemes and applied only to certificate
498 signatures.
499 sign_schemes() = [sign_scheme()]
502 Explicitly list acceptable signature schemes (algorithms) in the
504 preferred order. Overrides the algorithms supplied in signa‐
505 ture_algs option for certificates.
506 In addition to the signature_algorithms extension from TLS 1.2,
508 TLS 1.3 (RFC 5246 Section 4.2.3) adds the signature_algo‐
509 rithms_cert extension which enables having special requirements
510 on the signatures used in the certificates that differs from the
511 requirements on digital signatures as a whole. If this is not
512 required this extension is not need.
513 The client will send a signature_algorithms_cert extension (in
515 the client hello message), if TLS version 1.2 (back-ported to
516 TLS 1.2 in 24.1) or later is used, and the signature_algs_cert
517 option is explicitly specified. By default, only the signa‐
518 ture_algs extension is sent.
519 Note:
521 Note that supported signature schemes for TLS-1.2 are
522 sign_scheme_legacy() and rsassa_pss_scheme()
523 supported_groups() = [group()]
526 TLS 1.3 introduces the "supported_groups" extension that is used
528 for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
529 shake. Both client and server can specify a list of parameters
530 that they are willing to use.
531 If it is not specified it will use a default list ([x25519,
533 x448, secp256r1, secp384r1]) that is filtered based on the in‐
534 stalled crypto library version.
535 secure_renegotiation() = boolean()
537 Specifies if to reject renegotiation attempt that does not live
539 up to RFC 5746. By default secure_renegotiate is set to true,
540 that is, secure renegotiation is enforced. If set to false se‐
541 cure renegotiation will still be used if possible, but it falls
542 back to insecure renegotiation if the peer does not support RFC
543 5746.
544 allowed_cert_chain_length() = integer()
546 Maximum number of non-self-issued intermediate certificates that
548 can follow the peer certificate in a valid certification path.
549 So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
550 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
551 can be PEER, CA, CA, ROOT-CA, and so on. The default value is
552 10.
553 custom_verify() =
555 {Verifyfun :: function(), InitialUserState :: any()}
556 The verification fun is to be defined as follows:
558 fun(OtpCert :: #'OTPCertificate'{},
560 Event, InitialUserState :: term()) ->
561 {valid, UserState :: term()} |
562 {fail, Reason :: term()} | {unknown, UserState :: term()}.
563 fun(OtpCert :: #'OTPCertificate'{}, DerCert :: public_key:der_encoded(),
565 Event, InitialUserState :: term()) ->
566 {valid, UserState :: term()} |
567 {fail, Reason :: term()} | {unknown, UserState :: term()}.
568 Types:
570 Event = {bad_cert, Reason :: atom() |
571 {revoked, atom()}} |
572 {extension, #'Extension'{}} |
573 valid |
574 valid_peer
575 The verification fun is called during the X509-path validation
578 when an error or an extension unknown to the SSL application is
579 encountered. It is also called when a certificate is considered
580 valid by the path validation to allow access to each certificate
581 in the path to the user application. It differentiates between
582 the peer certificate and the CA certificates by using valid_peer
583 or valid as Event argument to the verification fun. See the pub‐
584 lic_key User's Guide for definition of #'OTPCertificate'{} and
585 #'Extension'{}.
586 * If the verify callback fun returns {fail, Reason}, the veri‐
588 fication process is immediately stopped, an alert is sent to
589 the peer, and the TLS/DTLS handshake terminates.
590 * If the verify callback fun returns {valid, UserState}, the
592 verification process continues.
593 * If the verify callback fun always returns {valid, User‐
595 State}, the TLS/DTLS handshake does not terminate regarding
596 verification failures and the connection is established.
597 * If called with an extension unknown to the user application,
599 return value {unknown, UserState} is to be used.
600 Note that if the fun returns unknown for an extension marked
602 as critical, validation will fail.
603 Default option verify_fun in verify_peer mode:
605 {fun(_,{bad_cert, _} = Reason, _) ->
607 {fail, Reason};
608 (_,{extension, _}, UserState) ->
609 {unknown, UserState};
610 (_, valid, UserState) ->
611 {valid, UserState};
612 (_, valid_peer, UserState) ->
613 {valid, UserState}
614 end, []}
615 Default option verify_fun in mode verify_none:
618 {fun(_,{bad_cert, _}, UserState) ->
620 {valid, UserState};
621 (_,{extension, #'Extension'{critical = true}}, UserState) ->
622 {valid, UserState};
623 (_,{extension, _}, UserState) ->
624 {unknown, UserState};
625 (_, valid, UserState) ->
626 {valid, UserState};
627 (_, valid_peer, UserState) ->
628 {valid, UserState}
629 end, []}
630 The possible path validation errors are given on form {bad_cert,
633 Reason} where Reason is:
634 unknown_ca:
636 No trusted CA was found in the trusted store. The trusted CA
637 is normally a so called ROOT CA, which is a self-signed cer‐
638 tificate. Trust can be claimed for an intermediate CA
639 (trusted anchor does not have to be self-signed according to
640 X-509) by using option partial_chain.
641 selfsigned_peer:
643 The chain consisted only of one self-signed certificate.
644 PKIX X-509-path validation error:
646 For possible reasons, see public_key:pkix_path_validation/3
647 crl_check() = boolean() | peer | best_effort
649 Perform CRL (Certificate Revocation List) verification (pub‐
651 lic_key:pkix_crls_validate/3) on all the certificates during the
652 path validation (public_key:pkix_path_validation/3) of the cer‐
653 tificate chain. Defaults to false.
654 peer:
656 check is only performed on the peer certificate.
657 best_effort:
659 if certificate revocation status cannot be determined it
660 will be accepted as valid.
661 The CA certificates specified for the connection will be used to
663 construct the certificate chain validating the CRLs.
664 The CRLs will be fetched from a local or external cache. See
666 ssl_crl_cache_api(3).
667 crl_cache_opts() =
669 {Module :: atom(),
670 {DbHandle :: internal | term(), Args :: list()}}
671 Specify how to perform lookup and caching of certificate revoca‐
673 tion lists. Module defaults to ssl_crl_cache with DbHandle be‐
674 ing internal and an empty argument list.
675 There are two implementations available:
677 ssl_crl_cache:
679 This module maintains a cache of CRLs. CRLs can be added to
680 the cache using the function ssl_crl_cache:insert/1, and op‐
681 tionally automatically fetched through HTTP if the following
682 argument is specified:
683 {http, timeout()}:
685 Enables fetching of CRLs specified as http URIs inX509
686 certificate extensions. Requires the OTP inets applica‐
687 tion.
688 ssl_crl_hash_dir:
690 This module makes use of a directory where CRLs are stored
691 in files named by the hash of the issuer name.
692 The file names consist of eight hexadecimal digits followed
694 by .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the
695 first version of the CRL, N starts at zero, and for each new
696 version, N is incremented by one. The OpenSSL utility c_re‐
697 hash creates symlinks according to this pattern.
698 For a given hash value, this module finds all consecutive
700 .r* files starting from zero, and those files taken together
701 make up the revocation list. CRL files whose nextUpdate
702 fields are in the past, or that are issued by a different CA
703 that happens to have the same name hash, are excluded.
704 The following argument is required:
706 {dir, string()}:
708 Specifies the directory in which the CRLs can be found.
709 root_fun() = function()
711 fun(Chain::[public_key:der_encoded()]) ->
713 {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
714 Claim an intermediate CA in the chain as trusted. TLS then per‐
717 forms public_key:pkix_path_validation/3 with the selected CA as
718 trusted anchor and the rest of the chain.
719 protocol_versions() = [protocol_version()]
721 TLS protocol versions supported by started clients and servers.
723 This option overrides the application environment option proto‐
724 col_version and dtls_protocol_version. If the environment option
725 is not set, it defaults to all versions, supported by the SSL
726 application. See also ssl(6).
727 custom_user_lookup() =
729 {Lookupfun :: function(), UserState :: any()}
730 The lookup fun is to defined as follows:
732 fun(psk, PSKIdentity :: binary(), UserState :: term()) ->
734 {ok, SharedSecret :: binary()} | error;
735 fun(srp, Username :: binary(), UserState :: term()) ->
736 {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
737 DerivedKey :: binary()}} | error.
738 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
741 by the client and server to determine the shared secret. When
742 called by the client, PSKIdentity is set to the hint presented
743 by the server or to undefined. When called by the server, PSKI‐
744 dentity is the identity presented by the client.
745 For Secure Remote Password (SRP), the fun is only used by the
747 server to obtain parameters that it uses to generate its session
748 keys. DerivedKey is to be derived according to RFC 2945 and
749 RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
750 word])])
751 session_id() = binary()
753 Identifies a TLS session.
755 log_alert() = boolean()
757 If set to false, TLS/DTLS Alert reports are not displayed. Dep‐
759 recated in OTP 22, use {log_level, logging_level()} instead.
760 logging_level() = logger:level() | none | all
762 Specifies the log level for a TLS/DTLS connection. Alerts are
764 logged on notice level, which is the default level. The level
765 debug triggers verbose logging of TLS/DTLS protocol messages.
766 See also ssl(6)
767 hibernate_after() = timeout()
769 When an integer-value is specified, TLS/DTLS-connection goes
771 into hibernation after the specified number of milliseconds of
772 inactivity, thus reducing its memory footprint. When undefined
773 is specified (this is the default), the process never goes into
774 hibernation.
775 handshake_size() = integer()
777 Integer (24 bits unsigned). Used to limit the size of valid TLS
779 handshake packets to avoid DoS attacks. Defaults to 256*1024.
780 padding_check() = boolean()
782 Affects TLS-1.0 connections only. If set to false, it disables
784 the block cipher padding check to be able to interoperate with
785 legacy software.
786 Warning:
788 Using {padding_check, boolean()} makes TLS vulnerable to the
789 Poodle attack.
790 beast_mitigation() = one_n_minus_one | zero_n | disabled
793 Affects TLS-1.0 connections only. Used to change the BEAST miti‐
795 gation strategy to interoperate with legacy software. Defaults
796 to one_n_minus_one.
797 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
799 zero_n - Perform 0/n BEAST mitigation.
801 disabled - Disable BEAST mitigation.
803 Warning:
805 Using {beast_mitigation, disabled} makes TLS-1.0 vulnerable to
806 the BEAST attack.
807 ssl_imp() = new | old
810 Deprecated since OTP-17, has no effect.
812 session_tickets() =
814 client_session_tickets() | server_session_tickets()
815 Configures the session ticket functionality in TLS 1.3 client
817 and server.
818 key_update_at() = integer() >= 1
820 Configures the maximum amount of bytes that can be sent on a TLS
822 1.3 connection before an automatic key update is performed.
823 There are cryptographic limits on the amount of plaintext which
825 can be safely encrypted under a given set of keys. The current
826 default ensures that data integrity will not be breached with
827 probability greater than 1/2^57. For more information see Limits
828 on Authenticated Encryption Use in TLS.
829 Warning:
831 The default value of this option shall provide the above men‐
832 tioned security guarantees and it shall be reasonable for most
833 applications (~353 TB).
834 middlebox_comp_mode() = boolean()
837 Configures the middlebox compatibility mode on a TLS 1.3 connec‐
839 tion.
840 A significant number of middleboxes misbehave when a TLS 1.3
842 connection is negotiated. Implementations can increase the
843 chance of making connections through those middleboxes by making
844 the TLS 1.3 handshake more like a TLS 1.2 handshake.
845 The middlebox compatibility mode is enabled (true) by default.
847 spawn_opts() = [erlang:spawn_opt_option()]
849 Configures spawn options of TLS sender and receiver processes.
851 Setting up garbage collection options can be helpful for trade-
853 offs between CPU usage and Memory usage. See erlang:spawn_opt/2.
854 For dist connections, default sender option is [...{priority,
856 max}], this priority option cannot be changed. For all connec‐
857 tions, ...link is added to receiver and cannot be changed.
858 keep_secrets() = boolean()
860 Configures a TLS 1.3 connection for keylogging
862 In order to retrieve keylog information on a TLS 1.3 connection,
864 it must be configured in advance to keep the client_random and
865 various handshake secrets.
866 The keep_secrets functionality is disabled (false) by default.
868 Added in OTP 23.2
870 TLS/DTLS OPTION DESCRIPTIONS - CLIENT
872 client_option() =
873 {verify, client_verify_type()} |
874 {reuse_session, client_reuse_session()} |
875 {reuse_sessions, client_reuse_sessions()} |
876 {cacerts, client_cacerts()} |
877 {cacertfile, client_cafile()} |
878 {alpn_advertised_protocols, client_alpn()} |
879 {client_preferred_next_protocols,
880 client_preferred_next_protocols()} |
881 {psk_identity, client_psk_identity()} |
882 {srp_identity, client_srp_identity()} |
883 {server_name_indication, sni()} |
884 {max_fragment_length, max_fragment_length()} |
885 {customize_hostname_check, customize_hostname_check()} |
886 {fallback, fallback()} |
887 {middlebox_comp_mode, middlebox_comp_mode()} |
888 {certificate_authorities, client_certificate_authorities()} |
889 {session_tickets, client_session_tickets()} |
890 {use_ticket, use_ticket()} |
891 {early_data, client_early_data()}
892 client_verify_type() = verify_type()
894 Defaults to verify_none as additional options are needed to be
896 able to perform the certificate verification. A warning will be
897 emitted unless verify_none is explicitly configured. Usually the
898 applications will want to configure verify_peer together with an
899 appropriate cacert or cacertfile option. For example an HTTPS
900 client would normally use the option {cacerts, public_key:cac‐
901 erts_get()} (available since OTP-25) to access the CA certifi‐
902 cates provided by the OS. Using verify_none means that all
903 x509-certificate path validation errors will be ignored. See
904 also option verify_fun.
905 client_reuse_session() =
907 session_id() | {session_id(), SessionData :: binary()}
908 Reuses a specific session. The session should be referred by its
910 session id if it is earlier saved with the option {reuse_ses‐
911 sions, save} since OTP-21.3 or explicitly specified by its ses‐
912 sion id and associated data since OTP-22.3. See also SSL's
913 Users Guide, Session Reuse pre TLS 1.3.
914 client_reuse_sessions() = boolean() | save
916 When save is specified a new connection will be negotiated and
918 saved for later reuse. The session ID can be fetched with con‐
919 nection_information/2 and used with the client option reuse_ses‐
920 sion The boolean value true specifies that if possible, auto‐
921 mated session reuse will be performed. If a new session is cre‐
922 ated, and is unique in regard to previous stored sessions, it
923 will be saved for possible later reuse. Since OTP-21.3.
924 client_certificate_authorities() = boolean()
926 If set to true, sends the certificate authorities extension in
928 TLS-1.3 client hello. The default is false. Note that setting it
929 to true may result in a big overhead if you have many trusted CA
930 certificates. Since OTP-24.3.
931 client_cacerts() =
933 [public_key:der_encoded()] | [public_key:combined_cert()]
934 The DER-encoded trusted certificates. If this option is supplied
936 it overrides option cacertfile.
937 client_cafile() = file:filename()
939 Path to a file containing PEM-encoded CA certificates. The CA
941 certificates are used during server authentication and when
942 building the client certificate chain.
943 Note:
945 When PEM caching is enabled, files provided with this option
946 will be checked for updates at fixed time intervals specified by
947 the ssl_pem_cache_clean environment parameter.
948 Note:
951 Alternatively, CA certificates can be provided as a DER-encoded
952 binary with client_cacerts option.
953 client_alpn() = [app_level_protocol()]
956 The list of protocols supported by the client to be sent to the
958 server to be used for an Application-Layer Protocol Negotiation
959 (ALPN). If the server supports ALPN then it will choose a proto‐
960 col from this list; otherwise it will fail the connection with a
961 "no_application_protocol" alert. A server that does not support
962 ALPN will ignore this value.
963 The list of protocols must not contain an empty binary.
965 The negotiated protocol can be retrieved using the negoti‐
967 ated_protocol/1 function.
968 client_preferred_next_protocols() =
970 {Precedence :: server | client,
971 ClientPrefs :: [app_level_protocol()]} |
972 {Precedence :: server | client,
973 ClientPrefs :: [app_level_protocol()],
974 Default :: app_level_protocol()}
975 Indicates that the client is to try to perform Next Protocol Ne‐
977 gotiation.
978 If precedence is server, the negotiated protocol is the first
980 protocol to be shown on the server advertised list, which is
981 also on the client preference list.
982 If precedence is client, the negotiated protocol is the first
984 protocol to be shown on the client preference list, which is
985 also on the server advertised list.
986 If the client does not support any of the server advertised pro‐
988 tocols or the server does not advertise any protocols, the
989 client falls back to the first protocol in its list or to the
990 default protocol (if a default is supplied). If the server does
991 not support Next Protocol Negotiation, the connection terminates
992 if no default protocol is supplied.
993 max_fragment_length() = undefined | 512 | 1024 | 2048 | 4096
995 Specifies the maximum fragment length the client is prepared to
997 accept from the server. See RFC 6066
998 client_psk_identity() = psk_identity()
1000 Specifies the identity the client presents to the server. The
1002 matching secret is found by calling user_lookup_fun
1003 client_srp_identity() = srp_identity()
1005 Specifies the username and password to use to authenticate to
1007 the server.
1008 sni() = hostname() | disable
1010 Specify the hostname to be used in TLS Server Name Indication
1012 extension. If not specified it will default to the Host argument
1013 of connect/[3,4] unless it is of type inet:ipaddress().
1014 The HostName will also be used in the hostname verification of
1016 the peer certificate using public_key:pkix_verify_hostname/2.
1017 The special value disable prevents the Server Name Indication
1019 extension from being sent and disables the hostname verification
1020 check public_key:pkix_verify_hostname/2
1021 customize_hostname_check() = list()
1023 Customizes the hostname verification of the peer certificate, as
1025 different protocols that use TLS such as HTTP or LDAP may want
1026 to do it differently, for possible options see pub‐
1027 lic_key:pkix_verify_hostname/3
1028 fallback() = boolean()
1030 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired
1032 TLS version downgrade. Defaults to false
1033 Warning:
1035 Note this option is not needed in normal TLS usage and should
1036 not be used to implement new clients. But legacy clients that
1037 retries connections in the following manner
1038 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1',
1040 'tlsv1']}])
1041 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1']},
1043 {fallback, true}])
1044 ssl:connect(Host, Port, [...{versions, ['tlsv1']}, {fallback,
1046 true}])
1047 may use it to avoid undesired TLS version downgrade. Note that
1049 TLS_FALLBACK_SCSV must also be supported by the server for the
1050 prevention to work.
1051 client_session_tickets() = disabled | manual | auto
1054 Configures the session ticket functionality. Allowed values are
1056 disabled, manual and auto. If it is set to manual the client
1057 will send the ticket information to user process in a 3-tuple:
1058 {ssl, session_ticket, {SNI, TicketData}}
1060 where SNI is the ServerNameIndication and TicketData is the ex‐
1062 tended ticket data that can be used in subsequent session re‐
1063 sumptions.
1064 If it is set to auto, the client automatically handles received
1066 tickets and tries to use them when making new TLS connections
1067 (session resumption with pre-shared keys).
1068 Note:
1070 This option is supported by TLS 1.3 and above. See also SSL's
1071 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1072 use_ticket() = [binary()]
1075 Configures the session tickets to be used for session resump‐
1077 tion. It is a mandatory option in manual mode (session_tickets =
1078 manual).
1079 Note:
1081 Session tickets are only sent to user if option session_tickets
1082 is set to manual
1083 This option is supported by TLS 1.3 and above. See also SSL's
1085 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1086 client_early_data() = binary()
1089 Configures the early data to be sent by the client.
1091 In order to be able to verify that the server has the intention
1093 to process the early data, the following 3-tuple is sent to the
1094 user process:
1095 {ssl, SslSocket, {early_data, Result}}
1097 where Result is either accepted or rejected.
1099 Warning:
1101 It is the responsibility of the user to handle a rejected Early
1102 Data and to resend when it is appropriate.
1103 TLS/DTLS OPTION DESCRIPTIONS - SERVER
1106 server_option() =
1107 {cacerts, server_cacerts()} |
1108 {cacertfile, server_cafile()} |
1109 {dh, dh_der()} |
1110 {dhfile, dh_file()} |
1111 {verify, server_verify_type()} |
1112 {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
1113 {certificate_authorities, server_certificate_authorities()} |
1114 {reuse_sessions, server_reuse_sessions()} |
1115 {reuse_session, server_reuse_session()} |
1116 {alpn_preferred_protocols, server_alpn()} |
1117 {next_protocols_advertised, server_next_protocol()} |
1118 {psk_identity, server_psk_identity()} |
1119 {sni_hosts, sni_hosts()} |
1120 {sni_fun, sni_fun()} |
1121 {honor_cipher_order, honor_cipher_order()} |
1122 {honor_ecc_order, honor_ecc_order()} |
1123 {client_renegotiation, client_renegotiation()} |
1124 {session_tickets, server_session_tickets()} |
1125 {anti_replay, anti_replay()} |
1126 {cookie, cookie()} |
1127 {early_data, server_early_data()}
1128 server_cacerts() =
1130 [public_key:der_encoded()] | [public_key:combined_cert()]
1131 The DER-encoded trusted certificates. If this option is supplied
1133 it overrides option cacertfile.
1134 server_certificate_authorities() = boolean()
1136 Determines if a TLS-1.3 server should include the authorities
1138 extension in its certificate request message that will be sent
1139 if the option verify is set to verify_peer. Defaults to true.
1140 A reason to exclude the extension would be if the server wants
1142 to communicate with clients incapable of sending complete cer‐
1143 tificate chains that adhere to the extension, but the server
1144 still has the capability to recreate a chain that it can verify.
1145 server_cafile() = file:filename()
1147 Path to a file containing PEM-encoded CA certificates. The CA
1149 certificates are used to build the server certificate chain and
1150 for client authentication. The CAs are also used in the list of
1151 acceptable client CAs passed to the client when a certificate is
1152 requested. Can be omitted if there is no need to verify the
1153 client and if there are no intermediate CAs for the server cer‐
1154 tificate.
1155 Note:
1157 When PEM caching is enabled, files provided with this option
1158 will be checked for updates at fixed time intervals specified by
1159 the ssl_pem_cache_clean environment parameter.
1160 Note:
1163 Alternatively, CA certificates can be provided as a DER-encoded
1164 binary with server_cacerts option.
1165 dh_der() = binary()
1168 The DER-encoded Diffie-Hellman parameters. If specified, it
1170 overrides option dhfile.
1171 Warning:
1173 The dh_der option is not supported by TLS 1.3. Use the sup‐
1174 ported_groups option instead.
1175 dh_file() = file:filename()
1178 Path to a file containing PEM-encoded Diffie Hellman parameters
1180 to be used by the server if a cipher suite using Diffie Hellman
1181 key exchange is negotiated. If not specified, default parameters
1182 are used.
1183 Warning:
1185 The dh_file option is not supported by TLS 1.3. Use the sup‐
1186 ported_groups option instead.
1187 server_verify_type() = verify_type()
1190 Client certificates are an optional part of the TLS protocol. A
1192 server only does x509-certificate path validation in mode ver‐
1193 ify_peer. By default the server is in verify_none mode an hence
1194 will not send an certificate request to the client. When using
1195 verify_peer you may also want to specify the options
1196 fail_if_no_peer_cert and certificate_authorities.
1197 fail_if_no_peer_cert() = boolean()
1199 Used together with {verify, verify_peer} by an TLS/DTLS server.
1201 If set to true, the server fails if the client does not have a
1202 certificate to send, that is, sends an empty certificate. If set
1203 to false, it fails only if the client sends an invalid certifi‐
1204 cate (an empty certificate is considered valid). Defaults to
1205 false.
1206 server_reuse_sessions() = boolean()
1208 The boolean value true specifies that the server will agree to
1210 reuse sessions. Setting it to false will result in an empty ses‐
1211 sion table, that is no sessions will be reused. See also option
1212 reuse_session.
1213 server_reuse_session() = function()
1215 Enables the TLS/DTLS server to have a local policy for deciding
1217 if a session is to be reused or not. Meaningful only if re‐
1218 use_sessions is set to true. SuggestedSessionId is a binary(),
1219 PeerCert is a DER-encoded certificate, Compression is an enumer‐
1220 ation integer, and CipherSuite is of type ciphersuite().
1221 server_alpn() = [app_level_protocol()]
1223 Indicates the server will try to perform Application-Layer Pro‐
1225 tocol Negotiation (ALPN).
1226 The list of protocols is in order of preference. The protocol
1228 negotiated will be the first in the list that matches one of the
1229 protocols advertised by the client. If no protocol matches, the
1230 server will fail the connection with a "no_application_protocol"
1231 alert.
1232 The negotiated protocol can be retrieved using the negoti‐
1234 ated_protocol/1 function.
1235 server_next_protocol() = [app_level_protocol()]
1237 List of protocols to send to the client if the client indicates
1239 that it supports the Next Protocol extension. The client can se‐
1240 lect a protocol that is not on this list. The list of protocols
1241 must not contain an empty binary. If the server negotiates a
1242 Next Protocol, it can be accessed using the negotiated_next_pro‐
1243 tocol/1 method.
1244 server_psk_identity() = psk_identity()
1246 Specifies the server identity hint, which the server presents to
1248 the client.
1249 honor_cipher_order() = boolean()
1251 If set to true, use the server preference for cipher selection.
1253 If set to false (the default), use the client preference.
1254 sni_hosts() =
1256 [{hostname(), [server_option() | common_option()]}]
1257 If the server receives a SNI (Server Name Indication) from the
1259 client matching a host listed in the sni_hosts option, the spe‐
1260 cific options for that host will override previously specified
1261 options. The option sni_fun, and sni_hosts are mutually exclu‐
1262 sive.
1263 sni_fun() = function()
1265 If the server receives a SNI (Server Name Indication) from the
1267 client, the given function will be called to retrieve
1268 [server_option()] for the indicated server. These options will
1269 be merged into predefined [server_option()] list. The function
1270 should be defined as: fun(ServerName :: string()) -> [server_op‐
1271 tion()] and can be specified as a fun or as named fun mod‐
1272 ule:function/1 The option sni_fun, and sni_hosts are mutually
1273 exclusive.
1274 client_renegotiation() = boolean()
1276 In protocols that support client-initiated renegotiation, the
1278 cost of resources of such an operation is higher for the server
1279 than the client. This can act as a vector for denial of service
1280 attacks. The SSL application already takes measures to counter-
1281 act such attempts, but client-initiated renegotiation can be
1282 strictly disabled by setting this option to false. The default
1283 value is true. Note that disabling renegotiation can result in
1284 long-lived connections becoming unusable due to limits on the
1285 number of messages the underlying cipher suite can encipher.
1286 honor_cipher_order() = boolean()
1288 If true, use the server's preference for cipher selection. If
1290 false (the default), use the client's preference.
1291 honor_ecc_order() = boolean()
1293 If true, use the server's preference for ECC curve selection. If
1295 false (the default), use the client's preference.
1296 server_session_tickets() = disabled | stateful | stateless
1298 Configures the session ticket functionality. Allowed values are
1300 disabled, stateful and stateless.
1301 If it is set to stateful or stateless, session resumption with
1303 pre-shared keys is enabled and the server will send stateful or
1304 stateless session tickets to the client after successful connec‐
1305 tions.
1306 A stateful session ticket is a database reference to internal
1308 state information. A stateless session ticket is a self-en‐
1309 crypted binary that contains both cryptographic keying material
1310 and state data.
1311 Note:
1313 This option is supported by TLS 1.3 and above. See also SSL's
1314 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1315 anti_replay() =
1318 '10k' | '100k' |
1319 {bloom_filter_window_size(),
1320 bloom_filter_hash_functions(),
1321 bloom_filter_bits()}
1322 Configures the server's built-in anti replay feature based on
1324 Bloom filters.
1325 Allowed values are the pre-defined '10k', '100k' or a custom
1327 3-tuple that defines the properties of the bloom filters: {Win‐
1328 dowSize, HashFunctions, Bits}. WindowSize is the number of sec‐
1329 onds after the current Bloom filter is rotated and also the win‐
1330 dow size used for freshness checks. HashFunctions is the number
1331 hash functions and Bits is the number of bits in the bit vector.
1332 '10k' and '100k' are simple defaults with the following proper‐
1333 ties:
1334 * '10k': Bloom filters can hold 10000 elements with 3% proba‐
1336 bility of false positives. WindowSize: 10, HashFunctions: 5,
1337 Bits: 72985 (8.91 KiB).
1338 * '100k': Bloom filters can hold 100000 elements with 3% prob‐
1340 ability of false positives. WindowSize: 10, HashFunctions:
1341 5, Bits: 729845 (89.09 KiB).
1342 Note:
1344 This option is supported by TLS 1.3 and above and only with
1345 stateless session tickets. Ticket lifetime, the number of tick‐
1346 ets sent by the server and the maximum number of tickets stored
1347 by the server in stateful mode are configured by application
1348 variables. See also SSL's Users Guide, Anti-Replay Protection
1349 in TLS 1.3
1350 cookie() = boolean()
1353 If true (default), the server sends a cookie extension in its
1355 HelloRetryRequest messages.
1356 Note:
1358 The cookie extension has two main purposes. It allows the server
1359 to force the client to demonstrate reachability at their appar‐
1360 ent network address (thus providing a measure of DoS protec‐
1361 tion). This is primarily useful for non-connection-oriented
1362 transports. It also allows to offload the server's state to the
1363 client. The cookie extension is enabled by default as it is a
1364 mandatory extension in RFC8446.
1365 server_early_data() = disabled | enabled
1368 Configures if the server accepts (enabled) or rejects (rejects)
1370 early data sent by a client. The default value is disabled.
1371 Warning:
1373 This option is a placeholder, early data is not yet implemented
1374 on the server side.
1375 connection_info() =
1378 [common_info() |
1379 curve_info() |
1380 ssl_options_info() |
1381 security_info()]
1382 common_info() =
1384 {protocol, protocol_version()} |
1385 {session_id, session_id()} |
1386 {session_resumption, boolean()} |
1387 {selected_cipher_suite, erl_cipher_suite()} |
1388 {sni_hostname, term()} |
1389 {srp_username, term()}
1390 curve_info() = {ecc, {named_curve, term()}}
1392 ssl_options_info() = tls_option()
1394 security_info() =
1396 {client_random, binary()} |
1397 {server_random, binary()} |
1398 {master_secret, binary()}
1399 connection_info_items() = [connection_info_item()]
1401 connection_info_item() =
1403 protocol | session_id | session_resumption |
1404 selected_cipher_suite | sni_hostname | srp_username | ecc |
1405 client_random | server_random | master_secret | keylog |
1406 tls_options_name()
1407 tls_options_name() = atom()
1409
1411 append_cipher_suites(Deferred, Suites) -> ciphers()
1412 Types:
1414 Deferred = ciphers() | cipher_filters()
1416 Suites = ciphers()
1417 Make Deferred suites become the least preferred suites, that is
1419 put them at the end of the cipher suite list Suites after remov‐
1420 ing them from Suites if present. Deferred may be a list of ci‐
1421 pher suites or a list of filters in which case the filters are
1422 use on Suites to extract the Deferred cipher list.
1423 cipher_suites(Description, Version) -> ciphers()
1425 Types:
1427 Description =
1429 default | all | exclusive | anonymous | exclusive_anony‐
1430 mous
1431 Version = protocol_version()
1432 Lists all possible cipher suites corresponding to Description
1434 that are available. The exclusive and exclusive_anonymous option
1435 will exclusively list cipher suites first supported in Version
1436 whereas the other options are inclusive from the lowest possible
1437 version to Version. The all options includes all suites except
1438 the anonymous and no anonymous suites are supported by default.
1439 Note:
1441 TLS-1.3 has no overlapping cipher suites with previous TLS ver‐
1442 sions, that is the result of cipher_suites(all, 'tlsv1.3'). con‐
1443 tains a separate set of suites that can be used with TLS-1.3 an
1444 other set that can be used if a lower version is negotiated. PRE
1445 TLS-1.3 so called PSK and SRP suites need extra configuration to
1446 work see user lookup function. No anonymous suites are supported
1447 by TLS-1.3.
1448 Also note that the cipher suites returned by this function are
1450 the cipher suites that the OTP ssl application can support pro‐
1451 vided that they are supported by the cryptolib linked with the
1452 OTP crypto application. Use ssl:filter_cipher_suites(Suites,
1453 []). to filter the list for the current cryptolib. Note that ci‐
1454 pher suites may be filtered out because they are too old or too
1455 new depending on the cryptolib
1456 cipher_suites(Description, Version, StringType :: rfc | openssl) ->
1459 [string()]
1460 Types:
1462 Description = default | all | exclusive | anonymous
1464 Version = protocol_version()
1465 Same as cipher_suites/2 but lists RFC or OpenSSL string names
1467 instead of erl_cipher_suite()
1468 eccs() -> NamedCurves
1470 eccs(Version) -> NamedCurves
1472 Types:
1474 Version = protocol_version()
1476 NamedCurves = [named_curve()]
1477 Returns a list of supported ECCs. eccs() is equivalent to call‐
1479 ing eccs(Protocol) with all supported protocols and then dedu‐
1480 plicating the output.
1481 clear_pem_cache() -> ok
1483 PEM files, used by ssl API-functions, are cached for performance
1485 reasons. The cache is automatically checked at regular intervals
1486 to see if any cache entries should be invalidated.
1487 This function provides a way to unconditionally clear the entire
1489 cache, thereby forcing a reload of previously cached PEM files.
1490 connect(TCPSocket, TLSOptions) ->
1492 {ok, sslsocket()} |
1493 {error, reason()} |
1494 {option_not_a_key_value_tuple, any()}
1495 connect(TCPSocket, TLSOptions, Timeout) ->
1497 {ok, sslsocket()} | {error, reason()}
1498 Types:
1500 TCPSocket = socket()
1502 TLSOptions = [tls_client_option()]
1503 Timeout = timeout()
1504 Upgrades a gen_tcp, or equivalent, connected socket to a TLS
1506 socket, that is, performs the client-side TLS handshake.
1507 Note:
1509 If the option verify is set to verify_peer the option
1510 server_name_indication shall also be specified, if it is not no
1511 Server Name Indication extension will be sent, and pub‐
1512 lic_key:pkix_verify_hostname/2 will be called with the IP-ad‐
1513 dress of the connection as ReferenceID, which is probably not
1514 what you want.
1515 If the option {handshake, hello} is used the handshake is paused
1518 after receiving the server hello message and the success re‐
1519 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1520 Thereafter the handshake is continued or canceled by calling
1521 handshake_continue/3 or handshake_cancel/1.
1522 If the option active is set to once, true or an integer value,
1524 the process owning the sslsocket will receive messages of type
1525 active_msgs()
1526 connect(Host, Port, TLSOptions) ->
1528 {ok, sslsocket()} |
1529 {ok, sslsocket(), Ext :: protocol_extensions()} |
1530 {error, reason()} |
1531 {option_not_a_key_value_tuple, any()}
1532 connect(Host, Port, TLSOptions, Timeout) ->
1534 {ok, sslsocket()} |
1535 {ok, sslsocket(), Ext :: protocol_extensions()} |
1536 {error, reason()} |
1537 {option_not_a_key_value_tuple, any()}
1538 Types:
1540 Host = host()
1542 Port = inet:port_number()
1543 TLSOptions = [tls_client_option()]
1544 Timeout = timeout()
1545 Opens a TLS/DTLS connection to Host, Port.
1547 When the option verify is set to verify_peer the check pub‐
1549 lic_key:pkix_verify_hostname/2 will be performed in addition to
1550 the usual x509-path validation checks. If the check fails the
1551 error {bad_cert, hostname_check_failed} will be propagated to
1552 the path validation fun verify_fun, where it is possible to do
1553 customized checks by using the full possibilities of the pub‐
1554 lic_key:pkix_verify_hostname/3 API. When the option
1555 server_name_indication is provided, its value (the DNS name)
1556 will be used as ReferenceID to public_key:pkix_verify_host‐
1557 name/2. When no server_name_indication option is given, the Host
1558 argument will be used as Server Name Indication extension. The
1559 Host argument will also be used for the public_key:pkix_ver‐
1560 ify_hostname/2 check and if the Host argument is an inet:ip_ad‐
1561 dress() the ReferenceID used for the check will be {ip, Host}
1562 otherwise dns_id will be assumed with a fallback to ip if that
1563 fails.
1564 Note:
1566 According to good practices certificates should not use IP-ad‐
1567 dresses as "server names". It would be very surprising if this
1568 happened outside a closed network.
1569 If the option {handshake, hello} is used the handshake is paused
1572 after receiving the server hello message and the success re‐
1573 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1574 Thereafter the handshake is continued or canceled by calling
1575 handshake_continue/3 or handshake_cancel/1.
1576 If the option active is set to once, true or an integer value,
1578 the process owning the sslsocket will receive messages of type
1579 active_msgs()
1580 close(SslSocket) -> ok | {error, Reason}
1582 Types:
1584 SslSocket = sslsocket()
1586 Reason = any()
1587 Closes a TLS/DTLS connection.
1589 close(SslSocket, How) ->
1591 ok | {ok, port()} | {ok, port(), Data} | {error, Reason}
1592 Types:
1594 SslSocket = sslsocket()
1596 How = timeout() | {NewController :: pid(), timeout()}
1597 Data = binary()
1598 Reason = any()
1599 Closes or downgrades a TLS connection. In the latter case the
1601 transport connection will be handed over to the NewController
1602 process after receiving the TLS close alert from the peer. The
1603 returned transport socket will have the following options set:
1604 [{active, false}, {packet, 0}, {mode, binary}].
1605 In case of downgrade, the close function might return some bi‐
1607 nary data that should be treated by the user as the first bytes
1608 received on the downgraded connection.
1609 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1611 Types:
1613 SslSocket = sslsocket()
1615 NewOwner = pid()
1616 Reason = any()
1617 Assigns a new controlling process to the SSL socket. A control‐
1619 ling process is the owner of an SSL socket, and receives all
1620 messages from the socket.
1621 connection_information(SslSocket) ->
1623 {ok, Result} | {error, reason()}
1624 Types:
1626 SslSocket = sslsocket()
1628 Result = connection_info()
1629 Returns the most relevant information about the connection, ssl
1631 options that are undefined will be filtered out. Note that val‐
1632 ues that affect the security of the connection will only be re‐
1633 turned if explicitly requested by connection_information/2.
1634 Note:
1636 The legacy Item = cipher_suite was removed in OTP-23. Previously
1637 it returned the cipher suite on its (undocumented) legacy for‐
1638 mat. It is replaced by selected_cipher_suite.
1639 connection_information(SslSocket, Items) ->
1642 {ok, Result} | {error, reason()}
1643 Types:
1645 SslSocket = sslsocket()
1647 Items = connection_info_items()
1648 Result = connection_info()
1649 Returns the requested information items about the connection, if
1651 they are defined.
1652 Note that client_random, server_random, master_secret and keylog
1654 are values that affect the security of connection. Meaningful
1655 atoms, not specified above, are the ssl option names.
1656 In order to retrieve keylog and other secret information from a
1658 TLS 1.3 connection, keep_secrets must be configured in advance
1659 and set to true.
1660 Note:
1662 If only undefined options are requested the resulting list can
1663 be empty.
1664 filter_cipher_suites(Suites, Filters) -> Ciphers
1667 Types:
1669 Suites = ciphers()
1671 Filters = cipher_filters()
1672 Ciphers = ciphers()
1673 Removes cipher suites if any of the filter functions returns
1675 false for any part of the cipher suite. If no filter function is
1676 supplied for some part the default behaviour regards it as if
1677 there was a filter function that returned true. For examples see
1678 Customizing cipher suites Additionally, this function also fil‐
1679 ters the cipher suites to exclude cipher suites not supported by
1680 the cryptolib used by the OTP crypto application. That is call‐
1681 ing ssl:filter_cipher_suites(Suites, []) will be equivalent to
1682 only applying the filters for cryptolib support.
1683 format_error(Reason :: {error, Reason}) -> string()
1685 Types:
1687 Reason = any()
1689 Presents the error returned by an SSL function as a printable
1691 string.
1692 getopts(SslSocket, OptionNames) ->
1694 {ok, [gen_tcp:option()]} | {error, reason()}
1695 Types:
1697 SslSocket = sslsocket()
1699 OptionNames = [gen_tcp:option_name()]
1700 Gets the values of the specified socket options.
1702 getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1704 getstat(SslSocket, Options) ->
1706 {ok, OptionValues} | {error, inet:posix()}
1707 Types:
1709 SslSocket = sslsocket()
1711 Options = [inet:stat_option()]
1712 OptionValues = [{inet:stat_option(), integer()}]
1713 Gets one or more statistic options for the underlying TCP
1715 socket.
1716 See inet:getstat/2 for statistic options description.
1718 handshake(HsSocket) ->
1720 {ok, SslSocket} |
1721 {ok, SslSocket, Ext} |
1722 {error, Reason}
1723 handshake(HsSocket, Timeout) ->
1725 {ok, SslSocket} |
1726 {ok, SslSocket, Ext} |
1727 {error, Reason}
1728 Types:
1730 HsSocket = sslsocket()
1732 Timeout = timeout()
1733 SslSocket = sslsocket()
1734 Ext = protocol_extensions()
1735 Reason = closed | timeout | error_alert()
1736 Performs the TLS/DTLS server-side handshake.
1738 Returns a new TLS/DTLS socket if the handshake is successful.
1740 If the option active is set to once, true or an integer value,
1742 the process owning the sslsocket will receive messages of type
1743 active_msgs()
1744 Warning:
1746 Not setting the timeout makes the server more vulnerable to DoS
1747 attacks.
1748 handshake(Socket, Options) ->
1751 {ok, SslSocket} |
1752 {ok, SslSocket, Ext} |
1753 {error, Reason}
1754 handshake(Socket, Options, Timeout) ->
1756 {ok, SslSocket} |
1757 {ok, SslSocket, Ext} |
1758 {error, Reason}
1759 Types:
1761 Socket = socket() | sslsocket()
1763 SslSocket = sslsocket()
1764 Options = [server_option()]
1765 Timeout = timeout()
1766 Ext = protocol_extensions()
1767 Reason = closed | timeout | {options, any()} | error_alert()
1768 If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1770 lent, socket to an SSL socket, that is, performs the TLS server-
1771 side handshake and returns a TLS socket.
1772 Warning:
1774 The ordinary Socket shall be in passive mode ({active, false})
1775 before calling this function, and before the client tries to
1776 connect with TLS, or else the behavior of this function is unde‐
1777 fined. The best way to ensure this is to create the ordinary
1778 listen socket in passive mode.
1779 If Socket is an sslsocket() : provides extra TLS/DTLS options
1782 to those specified in listen/2 and then performs the TLS/DTLS
1783 handshake. Returns a new TLS/DTLS socket if the handshake is
1784 successful.
1785 Warning:
1787 Not setting the timeout makes the server more vulnerable to DoS
1788 attacks.
1789 If option {handshake, hello} is specified the handshake is
1792 paused after receiving the client hello message and the success
1793 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1794 Thereafter the handshake is continued or canceled by calling
1795 handshake_continue/3 or handshake_cancel/1.
1796 If the option active is set to once, true or an integer value,
1798 the process owning the sslsocket will receive messages of type
1799 active_msgs()
1800 handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1802 Cancel the handshake with a fatal USER_CANCELED alert.
1804 handshake_continue(HsSocket, Options) ->
1806 {ok, SslSocket} | {error, Reason}
1807 handshake_continue(HsSocket, Options, Timeout) ->
1809 {ok, SslSocket} | {error, Reason}
1810 Types:
1812 HsSocket = sslsocket()
1814 Options = [tls_client_option() | tls_server_option()]
1815 Timeout = timeout()
1816 SslSocket = sslsocket()
1817 Reason = closed | timeout | error_alert()
1818 Continue the TLS handshake, possibly with new, additional or
1820 changed options.
1821 listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1823 Types:
1825 Port = inet:port_number()
1827 Options = [tls_server_option()]
1828 ListenSocket = sslsocket()
1829 Creates an SSL listen socket.
1831 negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1833 Types:
1835 SslSocket = sslsocket()
1837 Protocol = binary()
1838 Reason = protocol_not_negotiated
1839 Returns the protocol negotiated through ALPN or NPN extensions.
1841 peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1843 Types:
1845 SslSocket = sslsocket()
1847 Cert = public_key:der_encoded()
1848 The peer certificate is returned as a DER-encoded binary. The
1850 certificate can be decoded with public_key:pkix_decode_cert/2
1851 Suggested further reading about certificates is public_key
1852 User's Guide and ssl User's Guide
1853 peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1855 Types:
1857 SslSocket = sslsocket()
1859 Address = inet:ip_address()
1860 Port = inet:port_number()
1861 Returns the address and port number of the peer.
1863 prepend_cipher_suites(Preferred, Suites) -> ciphers()
1865 Types:
1867 Preferred = ciphers() | cipher_filters()
1869 Suites = ciphers()
1870 Make Preferred suites become the most preferred suites that is
1872 put them at the head of the cipher suite list Suites after re‐
1873 moving them from Suites if present. Preferred may be a list of
1874 cipher suites or a list of filters in which case the filters are
1875 use on Suites to extract the preferred cipher list.
1876 prf(SslSocket, Secret, Label, Seed, WantedLength) ->
1878 {ok, binary()} | {error, reason()}
1879 Types:
1881 SslSocket = sslsocket()
1883 Secret = binary() | master_secret
1884 Label = binary()
1885 Seed = [binary() | prf_random()]
1886 WantedLength = integer() >= 0
1887 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1889 ate extra key material. It either takes user-generated values
1890 for Secret and Seed or atoms directing it to use a specific
1891 value from the session security parameters.
1892 recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
1894 recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
1896 Types:
1898 SslSocket = sslsocket()
1900 Length = integer()
1901 Data = binary() | list() | HttpPacket
1902 Timeout = timeout()
1903 HttpPacket = any()
1904 See the description of HttpPacket in erlang:decode_packet/3
1905 in ERTS.
1906 Receives a packet from a socket in passive mode. A closed socket
1908 is indicated by return value {error, closed}.
1909 Argument Length is meaningful only when the socket is in mode
1911 raw and denotes the number of bytes to read. If Length = 0, all
1912 available bytes are returned. If Length > 0, exactly Length
1913 bytes are returned, or an error; possibly discarding less than
1914 Length bytes of data when the socket gets closed from the other
1915 side.
1916 Optional argument Timeout specifies a time-out in milliseconds.
1918 The default value is infinity.
1919 renegotiate(SslSocket) -> ok | {error, reason()}
1921 Types:
1923 SslSocket = sslsocket()
1925 Initiates a new handshake. A notable return value is {error,
1927 renegotiation_rejected} indicating that the peer refused to go
1928 through with the renegotiation, but the connection is still ac‐
1929 tive using the previously negotiated session.
1930 update_keys(SslSocket, Type) -> ok | {error, reason()}
1932 Types:
1934 SslSocket = sslsocket()
1936 Type = write | read_write
1937 There are cryptographic limits on the amount of plaintext which
1939 can be safely encrypted under a given set of keys. If the amount
1940 of data surpasses those limits, a key update is triggered and a
1941 new set of keys are installed. See also the option key_up‐
1942 date_at.
1943 This function can be used to explicitly start a key update on a
1945 TLS 1.3 connection. There are two types of the key update: if
1946 Type is set to write, only the writing key is updated; if Type
1947 is set to read_write, both the reading and writing keys are up‐
1948 dated.
1949 send(SslSocket, Data) -> ok | {error, reason()}
1951 Types:
1953 SslSocket = sslsocket()
1955 Data = iodata()
1956 Writes Data to SslSocket.
1958 A notable return value is {error, closed} indicating that the
1960 socket is closed.
1961 setopts(SslSocket, Options) -> ok | {error, reason()}
1963 Types:
1965 SslSocket = sslsocket()
1967 Options = [gen_tcp:option()]
1968 Sets options according to Options for socket SslSocket.
1970 shutdown(SslSocket, How) -> ok | {error, reason()}
1972 Types:
1974 SslSocket = sslsocket()
1976 How = read | write | read_write
1977 Immediately closes a socket in one or two directions.
1979 How == write means closing the socket for writing, reading from
1981 it is still possible.
1982 To be able to handle that the peer has done a shutdown on the
1984 write side, option {exit_on_close, false} is useful.
1985 sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1987 Types:
1989 SslSocket = sslsocket()
1991 Address = inet:ip_address()
1992 Port = inet:port_number()
1993 Returns the local address and port number of socket SslSocket.
1995 start() -> ok | {error, reason()}
1997 start(Type :: permanent | transient | temporary) ->
1999 ok | {error, reason()}
2000 Starts the SSL application. Default type is temporary.
2002 stop() -> ok
2004 Stops the SSL application.
2006 str_to_suite(CipherSuiteName) ->
2008 erl_cipher_suite() |
2009 {error, {not_recognized, CipherSuiteName}}
2010 Types:
2012 CipherSuiteName = string()
2014 Converts an RFC or OpenSSL name string to an erl_cipher_suite()
2016 Returns an error if the cipher suite is not supported or the
2017 name is not a valid cipher suite name.
2018 suite_to_openssl_str(CipherSuite) -> string()
2020 Types:
2022 CipherSuite = erl_cipher_suite()
2024 Converts erl_cipher_suite() to OpenSSL name string.
2026 PRE TLS-1.3 these names differ for RFC names
2028 suite_to_str(CipherSuite) -> string()
2030 Types:
2032 CipherSuite = erl_cipher_suite()
2034 Converts erl_cipher_suite() to RFC name string.
2036 transport_accept(ListenSocket) ->
2038 {ok, SslSocket} | {error, reason()}
2039 transport_accept(ListenSocket, Timeout) ->
2041 {ok, SslSocket} | {error, reason()}
2042 Types:
2044 ListenSocket = sslsocket()
2046 Timeout = timeout()
2047 SslSocket = sslsocket()
2048 Accepts an incoming connection request on a listen socket. Lis‐
2050 tenSocket must be a socket returned from listen/2. The socket
2051 returned is to be passed to handshake/[2,3] to complete hand‐
2052 shaking, that is, establishing the TLS/DTLS connection.
2053 Warning:
2055 Most API functions require that the TLS/DTLS connection is es‐
2056 tablished to work as expected.
2057 The accepted socket inherits the options set for ListenSocket in
2060 listen/2.
2061 The default value for Timeout is infinity. If Timeout is speci‐
2063 fied and no connection is accepted within the given time, {er‐
2064 ror, timeout} is returned.
2065 versions() -> [VersionInfo]
2067 Types:
2069 VersionInfo =
2071 {ssl_app, string()} |
2072 {supported | available | implemented, [tls_version()]} |
2073 {supported_dtls | available_dtls | implemented_dtls,
2074 [dtls_version()]}
2075 Lists information, mainly concerning TLS/DTLS versions, in run‐
2077 time for debugging and testing purposes.
2078 app_vsn:
2080 The application version of the SSL application.
2081 supported:
2083 TLS versions supported with current application environment
2084 and crypto library configuration. Overridden by a version
2085 option on connect/[2,3,4], listen/2, and handshake/[2,3].
2086 For the negotiated TLS version, see connection_information/1
2087 .
2088 supported_dtls:
2090 DTLS versions supported with current application environment
2091 and crypto library configuration. Overridden by a version
2092 option on connect/[2,3,4], listen/2, and handshake/[2,3].
2093 For the negotiated DTLS version, see connection_informa‐
2094 tion/1 .
2095 available:
2097 All TLS versions supported with the linked crypto library.
2098 available_dtls:
2100 All DTLS versions supported with the linked crypto library.
2101 implemented:
2103 All TLS versions supported by the SSL application if linked
2104 with a crypto library with the necessary support.
2105 implemented_dtls:
2107 All DTLS versions supported by the SSL application if linked
2108 with a crypto library with the necessary support.
2109
2111 inet(3) and gen_tcp(3) gen_udp(3)
2112Ericsson AB ssl 10.8.6 ssl(3)