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() = sha2() | legacy_hash()
128 sha2() = sha256 | sha384 | sha512
130 legacy_hash() = sha224 | sha | 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 x25519 | x448 | secp256r1 | secp384r1 | secp521r1 |
156 ffdhe2048 | ffdhe3072 | 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 |
172 legacy_named_curve()
173 legacy_named_curve() =
175 sect239k1 | sect233k1 | sect233r1 | secp224k1 | secp224r1 |
176 sect193r1 | sect193r2 | secp192k1 | secp192r1 | sect163k1 |
177 sect163r1 | sect163r2 | secp160k1 | secp160r1 | secp160r2
178 psk_identity() = string()
180 srp_identity() = {Username :: string(), Password :: string()}
182 srp_param_type() =
184 srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 |
185 srp_6144 | srp_8192
186 app_level_protocol() = binary()
188 protocol_extensions() =
190 #{renegotiation_info => binary(),
191 signature_algs => signature_algs(),
192 alpn => app_level_protocol(),
193 srp => binary(),
194 next_protocol => app_level_protocol(),
195 max_frag_enum => 1..4,
196 ec_point_formats => [0..2],
197 elliptic_curves => [public_key:oid()],
198 sni => hostname()}
199 error_alert() =
201 {tls_alert, {tls_alert(), Description :: string()}}
202 tls_alert() =
204 close_notify | unexpected_message | bad_record_mac |
205 record_overflow | handshake_failure | bad_certificate |
206 unsupported_certificate | certificate_revoked |
207 certificate_expired | certificate_unknown |
208 illegal_parameter | unknown_ca | access_denied |
209 decode_error | decrypt_error | export_restriction |
210 protocol_version | insufficient_security | internal_error |
211 inappropriate_fallback | user_canceled | no_renegotiation |
212 unsupported_extension | certificate_unobtainable |
213 unrecognized_name | bad_certificate_status_response |
214 bad_certificate_hash_value | unknown_psk_identity |
215 no_application_protocol
216 reason() = any()
218 bloom_filter_window_size() = integer()
220 bloom_filter_hash_functions() = integer()
222 bloom_filter_bits() = integer()
224 client_session_tickets() = disabled | manual | auto
226 server_session_tickets() =
228 disabled | stateful | stateless | stateful_with_cert |
229 stateless_with_cert
230 TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT
232 common_option() =
233 {protocol, protocol()} |
234 {handshake, handshake_completion()} |
235 {cert, cert() | [cert()]} |
236 {certfile, cert_pem()} |
237 {key, key()} |
238 {keyfile, key_pem()} |
239 {password, key_pem_password()} |
240 {certs_keys, certs_keys()} |
241 {ciphers, cipher_suites()} |
242 {eccs, [named_curve()]} |
243 {signature_algs, signature_algs()} |
244 {signature_algs_cert, sign_schemes()} |
245 {supported_groups, supported_groups()} |
246 {secure_renegotiate, secure_renegotiation()} |
247 {keep_secrets, keep_secrets()} |
248 {depth, allowed_cert_chain_length()} |
249 {verify_fun, custom_verify()} |
250 {crl_check, crl_check()} |
251 {crl_cache, crl_cache_opts()} |
252 {max_handshake_size, handshake_size()} |
253 {partial_chain, root_fun()} |
254 {versions, protocol_versions()} |
255 {user_lookup_fun, custom_user_lookup()} |
256 {log_level, logging_level()} |
257 {log_alert, log_alert()} |
258 {hibernate_after, hibernate_after()} |
259 {padding_check, padding_check()} |
260 {beast_mitigation, beast_mitigation()} |
261 {ssl_imp, ssl_imp()} |
262 {session_tickets, session_tickets()} |
263 {key_update_at, key_update_at()} |
264 {receiver_spawn_opts, spawn_opts()} |
265 {sender_spawn_opts, spawn_opts()}
266 protocol() = tls | dtls
268 Choose TLS or DTLS protocol for the transport layer security.
270 Defaults to tls. For DTLS other transports than UDP are not yet
271 supported.
272 handshake_completion() = hello | full
274 Defaults to full. If hello is specified the handshake will pause
276 after the hello message and give the user a possibility make de‐
277 cisions based on hello extensions before continuing or aborting
278 the handshake by calling handshake_continue/3 or hand‐
279 shake_cancel/1
280 cert() = public_key:der_encoded()
282 The DER-encoded user certificate. Note that the cert option may
284 also be a list of DER-encoded certificates where the first one
285 is the user certificate, and the rest of the certificates con‐
286 stitutes the certificate chain. For maximum interoperability the
287 certificates in the chain should be in the correct order, the
288 chain will be sent as is to the peer. If chain certificates are
289 not provided, certificates from client_cacerts(), server_cac‐
290 erts(), or client_cafile(), server_cafile() are used to con‐
291 struct the chain. If this option is supplied, it overrides op‐
292 tion certfile.
293 cert_pem() = file:filename()
295 Path to a file containing the user certificate on PEM format or
297 possible several certificates where the first one is the user
298 certificate and the rest of the certificates constitutes the
299 certificate chain. For more details see cert(),
300 key() =
302 {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' |
303 'PrivateKeyInfo',
304 public_key:der_encoded()} |
305 #{algorithm := rsa | dss | ecdsa,
306 engine := crypto:engine_ref(),
307 key_id := crypto:key_id(),
308 password => crypto:password()}
309 The DER-encoded user's private key or a map referring to a
311 crypto engine and its key reference that optionally can be pass‐
312 word protected, see also crypto:engine_load/3 and Crypto's
313 Users Guide. If this option is supplied, it overrides option
314 keyfile.
315 key_pem() = file:filename()
317 Path to the file containing the user's private PEM-encoded key.
319 As PEM-files can contain several entries, this option defaults
320 to the same file as given by option certfile.
321 key_pem_password() = iodata() | fun(() -> iodata())
323 String containing the user's password or a function returning
325 same type. Only used if the private keyfile is password-pro‐
326 tected.
327 certs_keys() = [cert_key_conf()]
329 A list of a certificate (or possible a certificate and its
331 chain) and the associated key of the certificate, that may be
332 used to authenticate the client or the server. The certificate
333 key pair that is considered best and matches negotiated parame‐
334 ters for the connection will be selected. Different signature
335 algorithms are prioritized in the order eddsa, ecdsa,
336 rsa_pss_pss, rsa and dsa . If more than one key is supplied for
337 the same signing algorithm (which is probably an unusual use
338 case) they will prioritized by strength unless it is a so called
339 engine key that will be favoured over other keys. As engine keys
340 cannot be inspected, supplying more than one engine key will
341 make no sense. This offers flexibility to for instance configure
342 a newer certificate that is expected to be used in most cases
343 and an older but acceptable certificate that will only be used
344 to communicate with legacy systems. Note that there is a trade
345 off between the induced overhead and the flexibility so alterna‐
346 tives should be chosen for good reasons. If the certs_keys op‐
347 tion is specified it overrides all single certificate and key
348 options. For examples see the Users Guide
349 Note:
351 eddsa certificates are only supported by TLS-1.3 that does not
352 support dsa certificates. rsa_pss_pss (RSA certificates using
353 Probabilistic Signature Scheme) are supported in TLS-1.2 and
354 TLS-1.3, but some TLS-1.2 implementations may not support
355 rsa_pss_pss.
356 cert_key_conf() =
359 #{cert => cert(),
360 key => key(),
361 certfile => cert_pem(),
362 keyfile => key_pem(),
363 password => key_pem_password()}
364 A certificate (or possibly a certificate and its chain) and its
366 associated key on one of the possible formats. For the PEM file
367 format there may also be a password associated with the file
368 containg the key.
369 cipher_suites() = ciphers()
371 A list of cipher suites that should be supported
373 The function ssl:cipher_suites/2 can be used to find all ci‐
375 pher suites that are supported by default and all cipher suites
376 that may be configured.
377 If you compose your own cipher_suites() make sure they are fil‐
379 tered for cryptolib support ssl:filter_cipher_suites/2 Addi‐
380 tionally the functions ssl:append_cipher_suites/2 ,
381 ssl:prepend_cipher_suites/2, ssl:suite_to_str/1,
382 ssl:str_to_suite/1, and ssl:suite_to_openssl_str/1 also exist to
383 help creating customized cipher suite lists.
384 Note:
386 Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping
387 sets of cipher suites so to support both these versions cipher
388 suites from both versions need to be included. Also if the sup‐
389 plied list does not comply with the configured versions or cryp‐
390 tolib so that the list becomes empty, this option will fallback
391 on its appropriate default value for the configured versions.
392 Non-default cipher suites including anonymous cipher suites (PRE
395 TLS-1.3) are supported for interop/testing purposes and may be
396 used by adding them to your cipher suite list. Note that they
397 must also be supported/enabled by the peer to actually be used.
398 signature_algs() = [{hash(), sign_algo()} | sign_scheme()]
400 Explicitly list acceptable signature algorithms for certificates
402 and handshake messages in the preferred order. The client will
403 send its list as the client hello signature_algorithm extension
404 introduced in TLS-1.2, see Section 7.4.1.4.1 in RFC 5246. Previ‐
405 ously these algorithms where implicitly chosen and partly de‐
406 rived from the cipher suite.
407 In TLS-1.2 a somewhat more explicit negotiation is made possible
409 using a list of {hash(), sign_algo()} pairs.
410 In TLS-1.3 these algorithm pairs are replaced by so called sig‐
412 nature schemes sign_scheme() and completely decoupled from the
413 cipher suite.
414 Signature algorithms used for certificates may be overridden by
416 the signature schemes (algorithms) supplied by the signa‐
417 ture_algs_cert option.
418 TLS-1.2 default is Default_TLS_12_Alg_Pairs interleaved with
420 rsa_pss_schemes since ssl-11.0 (OTP-25) pss_pss is prefered over
421 pss_rsae that is prefered over rsa
422 Default_TLS_12_Alg_Pairs =
424 [
426 %% SHA2
427 {sha512, ecdsa},
428 {sha512, rsa},
429 {sha384, ecdsa},
430 {sha384, rsa},
431 {sha256, ecdsa},
432 {sha256, rsa}
433 ]
434 Support for {md5, rsa} was removed from the the TLS-1.2 default
436 in ssl-8.0 (OTP-22) and support for SHA1 {sha, _} and SHA224
437 {sha224, _} was removed in ssl-11.0 (OTP-26)
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 ]
457 Default_TLS_13_Schemes =
460 [
462 %% EDDSA
463 eddsa_ed25519,
464 eddsa_ed448
465 %% ECDSA
467 ecdsa_secp521r1_sha512,
468 ecdsa_secp384r1_sha384,
469 ecdsa_secp256r1_sha256] ++
470 %% RSASSA-PSS
472 rsa_pss_schemes()
473 EDDSA was made highest priority in ssl-10.8 (OTP-25)
476 TLS-1.3 default is
478 Default_TLS_13_Schemes
480 If both TLS-1.3 and TLS-1.2 are supported the default will be
482 Default_TLS_13_Schemes ++ TLS_13_Legacy_Schemes ++ Default_TLS_12_Alg_Pairs (not represented in TLS_13_Legacy_Schemes)
484 so appropriate algorithms can be chosen for the negotiated ver‐
486 sion.
487 Note:
489 TLS-1.2 algorithms will not be negotiated for TLS-1.3, but
490 TLS-1.3 RSASSA-PSS rsassa_pss_scheme() signature schemes may be
491 negotiated also for TLS-1.2 from 24.1 (fully working from
492 24.1.3). However if TLS-1.3 is negotiated when both TLS-1.3 and
493 TLS-1.2 is supported using defaults, the corresponding TLS-1.2
494 algorithms to the TLS-1.3 legacy signature schemes will be con‐
495 sidered as the legacy schemes and applied only to certificate
496 signatures.
497 sign_schemes() = [sign_scheme()]
500 Explicitly list acceptable signature schemes (algorithms) in the
502 preferred order. Overrides the algorithms supplied in signa‐
503 ture_algs option for certificates.
504 In addition to the signature_algorithms extension from TLS 1.2,
506 TLS 1.3 (RFC 5246 Section 4.2.3) adds the signature_algo‐
507 rithms_cert extension which enables having special requirements
508 on the signatures used in the certificates that differs from the
509 requirements on digital signatures as a whole. If this is not
510 required this extension is not need.
511 The client will send a signature_algorithms_cert extension (in
513 the client hello message), if TLS version 1.2 (back-ported to
514 TLS 1.2 in 24.1) or later is used, and the signature_algs_cert
515 option is explicitly specified. By default, only the signa‐
516 ture_algs extension is sent.
517 Note:
519 Note that supported signature schemes for TLS-1.2 are
520 sign_scheme_legacy() and rsassa_pss_scheme()
521 supported_groups() = [group()]
524 TLS 1.3 introduces the "supported_groups" extension that is used
526 for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
527 shake. Both client and server can specify a list of parameters
528 that they are willing to use.
529 If it is not specified it will use a default list ([x25519,
531 x448, secp256r1, secp384r1]) that is filtered based on the in‐
532 stalled crypto library version.
533 secure_renegotiation() = boolean()
535 Specifies if to reject renegotiation attempt that does not live
537 up to RFC 5746. By default secure_renegotiate is set to true,
538 that is, secure renegotiation is enforced. If set to false se‐
539 cure renegotiation will still be used if possible, but it falls
540 back to insecure renegotiation if the peer does not support RFC
541 5746.
542 allowed_cert_chain_length() = integer()
544 Maximum number of non-self-issued intermediate certificates that
546 can follow the peer certificate in a valid certification path.
547 So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
548 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
549 can be PEER, CA, CA, ROOT-CA, and so on. The default value is
550 10.
551 custom_verify() =
553 {Verifyfun :: function(), InitialUserState :: any()}
554 The verification fun is to be defined as follows:
556 fun(OtpCert :: #'OTPCertificate'{},
558 Event, InitialUserState :: term()) ->
559 {valid, UserState :: term()} |
560 {fail, Reason :: term()} | {unknown, UserState :: term()}.
561 fun(OtpCert :: #'OTPCertificate'{}, DerCert :: public_key:der_encoded(),
563 Event, InitialUserState :: term()) ->
564 {valid, UserState :: term()} |
565 {fail, Reason :: term()} | {unknown, UserState :: term()}.
566 Types:
568 Event = {bad_cert, Reason :: atom() |
569 {revoked, atom()}} |
570 {extension, #'Extension'{}} |
571 valid |
572 valid_peer
573 The verification fun is called during the X509-path validation
576 when an error or an extension unknown to the SSL application is
577 encountered. It is also called when a certificate is considered
578 valid by the path validation to allow access to each certificate
579 in the path to the user application. It differentiates between
580 the peer certificate and the CA certificates by using valid_peer
581 or valid as Event argument to the verification fun. See the pub‐
582 lic_key User's Guide for definition of #'OTPCertificate'{} and
583 #'Extension'{}.
584 * If the verify callback fun returns {fail, Reason}, the veri‐
586 fication process is immediately stopped, an alert is sent to
587 the peer, and the TLS/DTLS handshake terminates.
588 * If the verify callback fun returns {valid, UserState}, the
590 verification process continues.
591 * If the verify callback fun always returns {valid, User‐
593 State}, the TLS/DTLS handshake does not terminate regarding
594 verification failures and the connection is established.
595 * If called with an extension unknown to the user application,
597 return value {unknown, UserState} is to be used.
598 Note that if the fun returns unknown for an extension marked
600 as critical, validation will fail.
601 Default option verify_fun in verify_peer mode:
603 {fun(_,{bad_cert, _} = Reason, _) ->
605 {fail, Reason};
606 (_,{extension, _}, UserState) ->
607 {unknown, UserState};
608 (_, valid, UserState) ->
609 {valid, UserState};
610 (_, valid_peer, UserState) ->
611 {valid, UserState}
612 end, []}
613 Default option verify_fun in mode verify_none:
616 {fun(_,{bad_cert, _}, UserState) ->
618 {valid, UserState};
619 (_,{extension, #'Extension'{critical = true}}, UserState) ->
620 {valid, UserState};
621 (_,{extension, _}, UserState) ->
622 {unknown, UserState};
623 (_, valid, UserState) ->
624 {valid, UserState};
625 (_, valid_peer, UserState) ->
626 {valid, UserState}
627 end, []}
628 The possible path validation errors are given on form {bad_cert,
631 Reason} where Reason is:
632 unknown_ca:
634 No trusted CA was found in the trusted store. The trusted CA
635 is normally a so called ROOT CA, which is a self-signed cer‐
636 tificate. Trust can be claimed for an intermediate CA
637 (trusted anchor does not have to be self-signed according to
638 X-509) by using option partial_chain.
639 selfsigned_peer:
641 The chain consisted only of one self-signed certificate.
642 PKIX X-509-path validation error:
644 For possible reasons, see public_key:pkix_path_validation/3
645 crl_check() = boolean() | peer | best_effort
647 Perform CRL (Certificate Revocation List) verification (pub‐
649 lic_key:pkix_crls_validate/3) on all the certificates during the
650 path validation (public_key:pkix_path_validation/3) of the cer‐
651 tificate chain. Defaults to false.
652 peer:
654 check is only performed on the peer certificate.
655 best_effort:
657 if certificate revocation status cannot be determined it
658 will be accepted as valid.
659 The CA certificates specified for the connection will be used to
661 construct the certificate chain validating the CRLs.
662 The CRLs will be fetched from a local or external cache. See
664 ssl_crl_cache_api(3).
665 crl_cache_opts() =
667 {Module :: atom(),
668 {DbHandle :: internal | term(), Args :: list()}}
669 Specify how to perform lookup and caching of certificate revoca‐
671 tion lists. Module defaults to ssl_crl_cache with DbHandle be‐
672 ing internal and an empty argument list.
673 There are two implementations available:
675 ssl_crl_cache:
677 This module maintains a cache of CRLs. CRLs can be added to
678 the cache using the function ssl_crl_cache:insert/1, and op‐
679 tionally automatically fetched through HTTP if the following
680 argument is specified:
681 {http, timeout()}:
683 Enables fetching of CRLs specified as http URIs inX509
684 certificate extensions. Requires the OTP inets applica‐
685 tion.
686 ssl_crl_hash_dir:
688 This module makes use of a directory where CRLs are stored
689 in files named by the hash of the issuer name.
690 The file names consist of eight hexadecimal digits followed
692 by .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the
693 first version of the CRL, N starts at zero, and for each new
694 version, N is incremented by one. The OpenSSL utility c_re‐
695 hash creates symlinks according to this pattern.
696 For a given hash value, this module finds all consecutive
698 .r* files starting from zero, and those files taken together
699 make up the revocation list. CRL files whose nextUpdate
700 fields are in the past, or that are issued by a different CA
701 that happens to have the same name hash, are excluded.
702 The following argument is required:
704 {dir, string()}:
706 Specifies the directory in which the CRLs can be found.
707 root_fun() = function()
709 fun(Chain::[public_key:der_encoded()]) ->
711 {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca.
712 Claim an intermediate CA in the chain as trusted. TLS then per‐
715 forms public_key:pkix_path_validation/3 with the selected CA as
716 trusted anchor and the rest of the chain.
717 protocol_versions() = [protocol_version()]
719 TLS protocol versions supported by started clients and servers.
721 This option overrides the application environment option proto‐
722 col_version and dtls_protocol_version. If the environment option
723 is not set, it defaults to all versions, supported by the SSL
724 application. See also ssl(6).
725 custom_user_lookup() =
727 {Lookupfun :: function(), UserState :: any()}
728 The lookup fun is to defined as follows:
730 fun(psk, PSKIdentity :: binary(), UserState :: term()) ->
732 {ok, SharedSecret :: binary()} | error;
733 fun(srp, Username :: binary(), UserState :: term()) ->
734 {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
735 DerivedKey :: binary()}} | error.
736 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
739 by the client and server to determine the shared secret. When
740 called by the client, PSKIdentity is set to the hint presented
741 by the server or to undefined. When called by the server, PSKI‐
742 dentity is the identity presented by the client.
743 For Secure Remote Password (SRP), the fun is only used by the
745 server to obtain parameters that it uses to generate its session
746 keys. DerivedKey is to be derived according to RFC 2945 and
747 RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
748 word])])
749 session_id() = binary()
751 Identifies a TLS session.
753 log_alert() = boolean()
755 If set to false, TLS/DTLS Alert reports are not displayed. Dep‐
757 recated in OTP 22, use {log_level, logging_level()} instead.
758 logging_level() = logger:level() | none | all
760 Specifies the log level for a TLS/DTLS connection. Alerts are
762 logged on notice level, which is the default level. The level
763 debug triggers verbose logging of TLS/DTLS protocol messages.
764 See also ssl(6)
765 hibernate_after() = timeout()
767 When an integer-value is specified, TLS/DTLS-connection goes
769 into hibernation after the specified number of milliseconds of
770 inactivity, thus reducing its memory footprint. When undefined
771 is specified (this is the default), the process never goes into
772 hibernation.
773 handshake_size() = integer()
775 Integer (24 bits unsigned). Used to limit the size of valid TLS
777 handshake packets to avoid DoS attacks. Defaults to 256*1024.
778 padding_check() = boolean()
780 Affects TLS-1.0 connections only. If set to false, it disables
782 the block cipher padding check to be able to interoperate with
783 legacy software.
784 Warning:
786 Using {padding_check, boolean()} makes TLS vulnerable to the
787 Poodle attack.
788 beast_mitigation() = one_n_minus_one | zero_n | disabled
791 Affects TLS-1.0 connections only. Used to change the BEAST miti‐
793 gation strategy to interoperate with legacy software. Defaults
794 to one_n_minus_one.
795 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
797 zero_n - Perform 0/n BEAST mitigation.
799 disabled - Disable BEAST mitigation.
801 Warning:
803 Using {beast_mitigation, disabled} makes TLS-1.0 vulnerable to
804 the BEAST attack.
805 ssl_imp() = new | old
808 Deprecated since OTP-17, has no effect.
810 session_tickets() =
812 client_session_tickets() | server_session_tickets()
813 Configures the session ticket functionality in TLS 1.3 client
815 and server.
816 key_update_at() = integer() >= 1
818 Configures the maximum amount of bytes that can be sent on a TLS
820 1.3 connection before an automatic key update is performed.
821 There are cryptographic limits on the amount of plaintext which
823 can be safely encrypted under a given set of keys. The current
824 default ensures that data integrity will not be breached with
825 probability greater than 1/2^57. For more information see Limits
826 on Authenticated Encryption Use in TLS.
827 Warning:
829 The default value of this option shall provide the above men‐
830 tioned security guarantees and it shall be reasonable for most
831 applications (~353 TB).
832 middlebox_comp_mode() = boolean()
835 Configures the middlebox compatibility mode on a TLS 1.3 connec‐
837 tion.
838 A significant number of middleboxes misbehave when a TLS 1.3
840 connection is negotiated. Implementations can increase the
841 chance of making connections through those middleboxes by making
842 the TLS 1.3 handshake more like a TLS 1.2 handshake.
843 The middlebox compatibility mode is enabled (true) by default.
845 spawn_opts() = [erlang:spawn_opt_option()]
847 Configures spawn options of TLS sender and receiver processes.
849 Setting up garbage collection options can be helpful for trade-
851 offs between CPU usage and Memory usage. See erlang:spawn_opt/2.
852 For dist connections, default sender option is [...{priority,
854 max}], this priority option cannot be changed. For all connec‐
855 tions, ...link is added to receiver and cannot be changed.
856 keep_secrets() = boolean()
858 Configures a TLS 1.3 connection for keylogging
860 In order to retrieve keylog information on a TLS 1.3 connection,
862 it must be configured in advance to keep the client_random and
863 various handshake secrets.
864 The keep_secrets functionality is disabled (false) by default.
866 Added in OTP 23.2
868 TLS/DTLS OPTION DESCRIPTIONS - CLIENT
870 client_option() =
871 {verify, client_verify_type()} |
872 {reuse_session, client_reuse_session()} |
873 {reuse_sessions, client_reuse_sessions()} |
874 {cacerts, client_cacerts()} |
875 {cacertfile, client_cafile()} |
876 {alpn_advertised_protocols, client_alpn()} |
877 {client_preferred_next_protocols,
878 client_preferred_next_protocols()} |
879 {psk_identity, client_psk_identity()} |
880 {srp_identity, client_srp_identity()} |
881 {server_name_indication, sni()} |
882 {max_fragment_length, max_fragment_length()} |
883 {customize_hostname_check, customize_hostname_check()} |
884 {fallback, fallback()} |
885 {middlebox_comp_mode, middlebox_comp_mode()} |
886 {certificate_authorities, client_certificate_authorities()} |
887 {session_tickets, client_session_tickets()} |
888 {use_ticket, use_ticket()} |
889 {early_data, client_early_data()} |
890 {use_srtp, use_srtp()}
891 client_verify_type() = verify_type()
893 Defaults to verify_none as additional options are needed to be
895 able to perform the certificate verification. A warning will be
896 emitted unless verify_none is explicitly configured. Usually the
897 applications will want to configure verify_peer together with an
898 appropriate cacert or cacertfile option. For example an HTTPS
899 client would normally use the option {cacerts, public_key:cac‐
900 erts_get()} (available since OTP-25) to access the CA certifi‐
901 cates provided by the OS. Using verify_none means that all
902 x509-certificate path validation errors will be ignored. See
903 also option verify_fun.
904 client_reuse_session() =
906 session_id() | {session_id(), SessionData :: binary()}
907 Reuses a specific session. The session should be referred by its
909 session id if it is earlier saved with the option {reuse_ses‐
910 sions, save} since OTP-21.3 or explicitly specified by its ses‐
911 sion id and associated data since OTP-22.3. See also SSL's
912 Users Guide, Session Reuse pre TLS 1.3.
913 client_reuse_sessions() = boolean() | save
915 When save is specified a new connection will be negotiated and
917 saved for later reuse. The session ID can be fetched with con‐
918 nection_information/2 and used with the client option reuse_ses‐
919 sion The boolean value true specifies that if possible, auto‐
920 mated session reuse will be performed. If a new session is cre‐
921 ated, and is unique in regard to previous stored sessions, it
922 will be saved for possible later reuse. Since OTP-21.3.
923 client_certificate_authorities() = boolean()
925 If set to true, sends the certificate authorities extension in
927 TLS-1.3 client hello. The default is false. Note that setting it
928 to true may result in a big overhead if you have many trusted CA
929 certificates. Since OTP-24.3.
930 client_cacerts() =
932 [public_key:der_encoded()] | [public_key:combined_cert()]
933 The DER-encoded trusted certificates. If this option is supplied
935 it overrides option cacertfile.
936 client_cafile() = file:filename()
938 Path to a file containing PEM-encoded CA certificates. The CA
940 certificates are used during server authentication and when
941 building the client certificate chain.
942 Note:
944 When PEM caching is enabled, files provided with this option
945 will be checked for updates at fixed time intervals specified by
946 the ssl_pem_cache_clean environment parameter.
947 Note:
950 Alternatively, CA certificates can be provided as a DER-encoded
951 binary with client_cacerts option.
952 client_alpn() = [app_level_protocol()]
955 The list of protocols supported by the client to be sent to the
957 server to be used for an Application-Layer Protocol Negotiation
958 (ALPN). If the server supports ALPN then it will choose a proto‐
959 col from this list; otherwise it will fail the connection with a
960 "no_application_protocol" alert. A server that does not support
961 ALPN will ignore this value.
962 The list of protocols must not contain an empty binary.
964 The negotiated protocol can be retrieved using the negoti‐
966 ated_protocol/1 function.
967 client_preferred_next_protocols() =
969 {Precedence :: server | client,
970 ClientPrefs :: [app_level_protocol()]} |
971 {Precedence :: server | client,
972 ClientPrefs :: [app_level_protocol()],
973 Default :: app_level_protocol()}
974 Indicates that the client is to try to perform Next Protocol Ne‐
976 gotiation.
977 If precedence is server, the negotiated protocol is the first
979 protocol to be shown on the server advertised list, which is
980 also on the client preference list.
981 If precedence is client, the negotiated protocol is the first
983 protocol to be shown on the client preference list, which is
984 also on the server advertised list.
985 If the client does not support any of the server advertised pro‐
987 tocols or the server does not advertise any protocols, the
988 client falls back to the first protocol in its list or to the
989 default protocol (if a default is supplied). If the server does
990 not support Next Protocol Negotiation, the connection terminates
991 if no default protocol is supplied.
992 max_fragment_length() = undefined | 512 | 1024 | 2048 | 4096
994 Specifies the maximum fragment length the client is prepared to
996 accept from the server. See RFC 6066
997 client_psk_identity() = psk_identity()
999 Specifies the identity the client presents to the server. The
1001 matching secret is found by calling user_lookup_fun
1002 client_srp_identity() = srp_identity()
1004 Specifies the username and password to use to authenticate to
1006 the server.
1007 sni() = hostname() | disable
1009 Specify the hostname to be used in TLS Server Name Indication
1011 extension. If not specified it will default to the Host argument
1012 of connect/[3,4] unless it is of type inet:ipaddress().
1013 The HostName will also be used in the hostname verification of
1015 the peer certificate using public_key:pkix_verify_hostname/2.
1016 The special value disable prevents the Server Name Indication
1018 extension from being sent and disables the hostname verification
1019 check public_key:pkix_verify_hostname/2
1020 customize_hostname_check() = list()
1022 Customizes the hostname verification of the peer certificate, as
1024 different protocols that use TLS such as HTTP or LDAP may want
1025 to do it differently. For example the get standard HTTPS han‐
1026 dling provide the already implememnted fun from the public_key
1027 application for HTTPS. {customize_hostname_check, [{match_fun,
1028 public_key:pkix_verify_hostname_match_fun(https)}]} For futher
1029 description of customize options see public_key:pkix_ver‐
1030 ify_hostname/3
1031 fallback() = boolean()
1033 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired
1035 TLS version downgrade. Defaults to false
1036 Warning:
1038 Note this option is not needed in normal TLS usage and should
1039 not be used to implement new clients. But legacy clients that
1040 retries connections in the following manner
1041 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1',
1043 'tlsv1']}])
1044 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1']},
1046 {fallback, true}])
1047 ssl:connect(Host, Port, [...{versions, ['tlsv1']}, {fallback,
1049 true}])
1050 may use it to avoid undesired TLS version downgrade. Note that
1052 TLS_FALLBACK_SCSV must also be supported by the server for the
1053 prevention to work.
1054 client_session_tickets() = disabled | manual | auto
1057 Configures the session ticket functionality. Allowed values are
1059 disabled, manual and auto. If it is set to manual the client
1060 will send the ticket information to user process in a 3-tuple:
1061 {ssl, session_ticket, {SNI, TicketData}}
1063 where SNI is the ServerNameIndication and TicketData is the ex‐
1065 tended ticket data that can be used in subsequent session re‐
1066 sumptions.
1067 If it is set to auto, the client automatically handles received
1069 tickets and tries to use them when making new TLS connections
1070 (session resumption with pre-shared keys).
1071 Note:
1073 This option is supported by TLS 1.3 and above. See also SSL's
1074 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1075 use_ticket() = [binary()]
1078 Configures the session tickets to be used for session resump‐
1080 tion. It is a mandatory option in manual mode (session_tickets =
1081 manual).
1082 Note:
1084 Session tickets are only sent to user if option session_tickets
1085 is set to manual
1086 This option is supported by TLS 1.3 and above. See also SSL's
1088 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1089 client_early_data() = binary()
1092 Configures the early data to be sent by the client.
1094 In order to be able to verify that the server has the intention
1096 to process the early data, the following 3-tuple is sent to the
1097 user process:
1098 {ssl, SslSocket, {early_data, Result}}
1100 where Result is either accepted or rejected.
1102 Warning:
1104 It is the responsibility of the user to handle a rejected Early
1105 Data and to resend when it is appropriate.
1106 use_srtp() =
1109 #{protection_profiles := [binary()], mki => binary()}
1110 Configures the use_srtp DTLS hello extension.
1112 In order to negotiate the use of SRTP data protection, clients
1114 include an extension of type "use_srtp" in the DTLS extended
1115 client hello. This extension MUST only be used when the data be‐
1116 ing transported is RTP or RTCP.
1117 The value is a map with a mandatory protection_profiles and an
1119 optional mki parameters.
1120 protection_profiles configures the list of the client's accept‐
1122 able SRTP Protection Profiles. Each profile is a 2-byte binary.
1123 Example: #{protection_profiles => [<<0,2>>, <<0,5>>]}
1124 mki configures the SRTP Master Key Identifier chosen by the
1126 client.
1127 The srtp_mki field contains the value of the SRTP MKI which is
1129 associated with the SRTP master keys derived from this hand‐
1130 shake. Each SRTP session MUST have exactly one master key that
1131 is used to protect packets at any given time. The client MUST
1132 choose the MKI value so that it is distinct from the last MKI
1133 value that was used, and it SHOULD make these values unique for
1134 the duration of the TLS session.
1135 Note:
1137 This extension MUST only be used with DTLS, and not with TLS.
1138 Note:
1141 OTP does not handle SRTP, so an external implementations of SRTP
1142 encoder/decoder and a packet demultiplexer are needed to make
1143 use of the use_srtp extension. See also cb_info option.
1144 TLS/DTLS OPTION DESCRIPTIONS - SERVER
1147 server_option() =
1148 {cacerts, server_cacerts()} |
1149 {cacertfile, server_cafile()} |
1150 {dh, dh_der()} |
1151 {dhfile, dh_file()} |
1152 {verify, server_verify_type()} |
1153 {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
1154 {certificate_authorities, server_certificate_authorities()} |
1155 {reuse_sessions, server_reuse_sessions()} |
1156 {reuse_session, server_reuse_session()} |
1157 {alpn_preferred_protocols, server_alpn()} |
1158 {next_protocols_advertised, server_next_protocol()} |
1159 {psk_identity, server_psk_identity()} |
1160 {sni_hosts, sni_hosts()} |
1161 {sni_fun, sni_fun()} |
1162 {honor_cipher_order, honor_cipher_order()} |
1163 {honor_ecc_order, honor_ecc_order()} |
1164 {client_renegotiation, client_renegotiation()} |
1165 {session_tickets, server_session_tickets()} |
1166 {stateless_tickets_seed, stateless_tickets_seed()} |
1167 {anti_replay, anti_replay()} |
1168 {cookie, cookie()} |
1169 {early_data, server_early_data()} |
1170 {use_srtp, use_srtp()}
1171 server_cacerts() =
1173 [public_key:der_encoded()] | [public_key:combined_cert()]
1174 The DER-encoded trusted certificates. If this option is supplied
1176 it overrides option cacertfile.
1177 server_certificate_authorities() = boolean()
1179 Determines if a TLS-1.3 server should include the authorities
1181 extension in its certificate request message that will be sent
1182 if the option verify is set to verify_peer. Defaults to true.
1183 A reason to exclude the extension would be if the server wants
1185 to communicate with clients incapable of sending complete cer‐
1186 tificate chains that adhere to the extension, but the server
1187 still has the capability to recreate a chain that it can verify.
1188 server_cafile() = file:filename()
1190 Path to a file containing PEM-encoded CA certificates. The CA
1192 certificates are used to build the server certificate chain and
1193 for client authentication. The CAs are also used in the list of
1194 acceptable client CAs passed to the client when a certificate is
1195 requested. Can be omitted if there is no need to verify the
1196 client and if there are no intermediate CAs for the server cer‐
1197 tificate.
1198 Note:
1200 When PEM caching is enabled, files provided with this option
1201 will be checked for updates at fixed time intervals specified by
1202 the ssl_pem_cache_clean environment parameter.
1203 Note:
1206 Alternatively, CA certificates can be provided as a DER-encoded
1207 binary with server_cacerts option.
1208 dh_der() = binary()
1211 The DER-encoded Diffie-Hellman parameters. If specified, it
1213 overrides option dhfile.
1214 Warning:
1216 The dh_der option is not supported by TLS 1.3. Use the sup‐
1217 ported_groups option instead.
1218 dh_file() = file:filename()
1221 Path to a file containing PEM-encoded Diffie Hellman parameters
1223 to be used by the server if a cipher suite using Diffie Hellman
1224 key exchange is negotiated. If not specified, default parameters
1225 are used.
1226 Warning:
1228 The dh_file option is not supported by TLS 1.3. Use the sup‐
1229 ported_groups option instead.
1230 server_verify_type() = verify_type()
1233 Client certificates are an optional part of the TLS protocol. A
1235 server only does x509-certificate path validation in mode ver‐
1236 ify_peer. By default the server is in verify_none mode an hence
1237 will not send an certificate request to the client. When using
1238 verify_peer you may also want to specify the options
1239 fail_if_no_peer_cert and certificate_authorities.
1240 fail_if_no_peer_cert() = boolean()
1242 Used together with {verify, verify_peer} by an TLS/DTLS server.
1244 If set to true, the server fails if the client does not have a
1245 certificate to send, that is, sends an empty certificate. If set
1246 to false, it fails only if the client sends an invalid certifi‐
1247 cate (an empty certificate is considered valid). Defaults to
1248 false.
1249 server_reuse_sessions() = boolean()
1251 The boolean value true specifies that the server will agree to
1253 reuse sessions. Setting it to false will result in an empty ses‐
1254 sion table, that is no sessions will be reused. See also option
1255 reuse_session.
1256 server_reuse_session() = function()
1258 Enables the TLS/DTLS server to have a local policy for deciding
1260 if a session is to be reused or not. Meaningful only if re‐
1261 use_sessions is set to true. SuggestedSessionId is a binary(),
1262 PeerCert is a DER-encoded certificate, Compression is an enumer‐
1263 ation integer, and CipherSuite is of type ciphersuite().
1264 server_alpn() = [app_level_protocol()]
1266 Indicates the server will try to perform Application-Layer Pro‐
1268 tocol Negotiation (ALPN).
1269 The list of protocols is in order of preference. The protocol
1271 negotiated will be the first in the list that matches one of the
1272 protocols advertised by the client. If no protocol matches, the
1273 server will fail the connection with a "no_application_protocol"
1274 alert.
1275 The negotiated protocol can be retrieved using the negoti‐
1277 ated_protocol/1 function.
1278 server_next_protocol() = [app_level_protocol()]
1280 List of protocols to send to the client if the client indicates
1282 that it supports the Next Protocol extension. The client can se‐
1283 lect a protocol that is not on this list. The list of protocols
1284 must not contain an empty binary. If the server negotiates a
1285 Next Protocol, it can be accessed using the negotiated_next_pro‐
1286 tocol/1 method.
1287 server_psk_identity() = psk_identity()
1289 Specifies the server identity hint, which the server presents to
1291 the client.
1292 honor_cipher_order() = boolean()
1294 If set to true, use the server preference for cipher selection.
1296 If set to false (the default), use the client preference.
1297 sni_hosts() =
1299 [{hostname(), [server_option() | common_option()]}]
1300 If the server receives a SNI (Server Name Indication) from the
1302 client matching a host listed in the sni_hosts option, the spe‐
1303 cific options for that host will override previously specified
1304 options. The option sni_fun, and sni_hosts are mutually exclu‐
1305 sive.
1306 sni_fun() = fun((string()) -> [] | undefined)
1308 If the server receives a SNI (Server Name Indication) from the
1310 client, the given function will be called to retrieve
1311 [server_option()] for the indicated server. These options will
1312 be merged into predefined [server_option()] list. The function
1313 should be defined as: fun(ServerName :: string()) -> [server_op‐
1314 tion()] and can be specified as a fun or as named fun mod‐
1315 ule:function/1 The option sni_fun, and sni_hosts are mutually
1316 exclusive.
1317 client_renegotiation() = boolean()
1319 In protocols that support client-initiated renegotiation, the
1321 cost of resources of such an operation is higher for the server
1322 than the client. This can act as a vector for denial of service
1323 attacks. The SSL application already takes measures to counter-
1324 act such attempts, but client-initiated renegotiation can be
1325 strictly disabled by setting this option to false. The default
1326 value is true. Note that disabling renegotiation can result in
1327 long-lived connections becoming unusable due to limits on the
1328 number of messages the underlying cipher suite can encipher.
1329 honor_cipher_order() = boolean()
1331 If true, use the server's preference for cipher selection. If
1333 false (the default), use the client's preference.
1334 honor_ecc_order() = boolean()
1336 If true, use the server's preference for ECC curve selection. If
1338 false (the default), use the client's preference.
1339 server_session_tickets() =
1341 disabled | stateful | stateless | stateful_with_cert |
1342 stateless_with_cert
1343 Configures the session ticket functionality. Allowed values are
1345 disabled, stateful, stateless, stateful_with_cert, state‐
1346 less_with_cert.
1347 If it is not set to disabled, session resumption with pre-shared
1349 keys is enabled and the server will send stateful or stateless
1350 session tickets to the client after successful connections.
1351 Note:
1353 Pre-shared key session ticket resumption does not include any
1354 certificate exchange, hence the function ssl:peercert/1 will not
1355 be able to return the peer certificate as it is only communi‐
1356 cated in the initial handshake. The server options state‐
1357 ful_with_cert or stateless_with_cert may be used to make a
1358 server associate the client certificate from the original hand‐
1359 shake with the tickets it issues.
1360 A stateful session ticket is a database reference to internal
1363 state information. A stateless session ticket is a self-en‐
1364 crypted binary that contains both cryptographic keying material
1365 and state data.
1366 Warning:
1368 If it is set to stateful_with_cert the client certificate is
1369 stored with the internal state information, increasing memory
1370 consumption. If it is set to stateless_with_cert the client cer‐
1371 tificate is encoded in the self-encrypted binary that is sent to
1372 the client, increasing the payload size.
1373 Note:
1376 This option is supported by TLS 1.3 and above. See also SSL's
1377 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1378 stateless_tickets_seed() = binary()
1381 Configures the seed used for the encryption of stateless session
1383 tickets. Allowed values are any randomly generated binary(). If
1384 this option is not configured, an encryption seed will be ran‐
1385 domly generated.
1386 Warning:
1388 Reusing the ticket encryption seed between multiple server in‐
1389 stances enables stateless session tickets to work across multi‐
1390 ple server instances, but it breaks anti-replay protection
1391 across instances.
1392 Inaccurate time synchronization between server instances can
1394 also affect session ticket freshness checks, potentially causing
1395 false negatives as well as false positives.
1396 Note:
1399 This option is supported by TLS 1.3 and above and only with
1400 stateless session tickets.
1401 anti_replay() =
1404 '10k' | '100k' |
1405 {bloom_filter_window_size(),
1406 bloom_filter_hash_functions(),
1407 bloom_filter_bits()}
1408 Configures the server's built-in anti replay feature based on
1410 Bloom filters.
1411 Allowed values are the pre-defined '10k', '100k' or a custom
1413 3-tuple that defines the properties of the bloom filters: {Win‐
1414 dowSize, HashFunctions, Bits}. WindowSize is the number of sec‐
1415 onds after the current Bloom filter is rotated and also the win‐
1416 dow size used for freshness checks of ClientHello. HashFunctions
1417 is the number hash functions and Bits is the number of bits in
1418 the bit vector. '10k' and '100k' are simple defaults with the
1419 following properties:
1420 * '10k': Bloom filters can hold 10000 elements with 3% proba‐
1422 bility of false positives. WindowSize: 10, HashFunctions: 5,
1423 Bits: 72985 (8.91 KiB).
1424 * '100k': Bloom filters can hold 100000 elements with 3% prob‐
1426 ability of false positives. WindowSize: 10, HashFunctions:
1427 5, Bits: 729845 (89.09 KiB).
1428 Note:
1430 This option is supported by TLS 1.3 and above and only with
1431 stateless session tickets. Ticket lifetime, the number of tick‐
1432 ets sent by the server and the maximum number of tickets stored
1433 by the server in stateful mode are configured by application
1434 variables. See also SSL's Users Guide, Anti-Replay Protection
1435 in TLS 1.3
1436 cookie() = boolean()
1439 If true (default), the server sends a cookie extension in its
1441 HelloRetryRequest messages.
1442 Note:
1444 The cookie extension has two main purposes. It allows the server
1445 to force the client to demonstrate reachability at their appar‐
1446 ent network address (thus providing a measure of DoS protec‐
1447 tion). This is primarily useful for non-connection-oriented
1448 transports. It also allows to offload the server's state to the
1449 client. The cookie extension is enabled by default as it is a
1450 mandatory extension in RFC8446.
1451 server_early_data() = disabled | enabled
1454 Configures if the server accepts (enabled) or rejects (rejects)
1456 early data sent by a client. The default value is disabled.
1457 Warning:
1459 This option is a placeholder, early data is not yet implemented
1460 on the server side.
1461 use_srtp() =
1464 #{protection_profiles := [binary()], mki => binary()}
1465 Configures the use_srtp DTLS hello extension.
1467 Servers that receive an extended hello containing a "use_srtp"
1469 extension can agree to use SRTP by including an extension of
1470 type "use_srtp", with the chosen protection profile in the ex‐
1471 tended server hello. This extension MUST only be used when the
1472 data being transported is RTP or RTCP.
1473 The value is a map with a mandatory protection_profiles and an
1475 optional mki parameters.
1476 * protection_profiles configures the list of the server's cho‐
1478 sen SRTP Protection Profile as a list of a single 2-byte bi‐
1479 nary. Example: #{protection_profiles => [<<0,5>>]}
1480 * mki configures the server's SRTP Master Key Identifier.
1482 Upon receipt of a "use_srtp" extension containing a
1484 "srtp_mki" field, the server MUST either (assuming it ac‐
1485 cepts the extension at all):
1486 * include a matching "srtp_mki" value in its "use_srtp" ex‐
1488 tension to indicate that it will make use of the MKI, or
1489 * return an empty "srtp_mki" value to indicate that it can‐
1491 not make use of the MKI (default).
1492 Note:
1494 This extension MUST only be used with DTLS, and not with TLS.
1495 Note:
1498 OTP does not handle SRTP, so an external implementations of SRTP
1499 encoder/decoder and a packet demultiplexer are needed to make
1500 use of the use_srtp extension. See also cb_info option.
1501 connection_info() =
1504 [common_info() |
1505 curve_info() |
1506 ssl_options_info() |
1507 security_info()]
1508 common_info() =
1510 {protocol, protocol_version()} |
1511 {session_id, session_id()} |
1512 {session_resumption, boolean()} |
1513 {selected_cipher_suite, erl_cipher_suite()} |
1514 {sni_hostname, term()} |
1515 {srp_username, term()}
1516 curve_info() = {ecc, {named_curve, term()}}
1518 ssl_options_info() = tls_option()
1520 security_info() =
1522 {client_random, binary()} |
1523 {server_random, binary()} |
1524 {master_secret, binary()}
1525 connection_info_items() = [connection_info_item()]
1527 connection_info_item() =
1529 protocol | session_id | session_resumption |
1530 selected_cipher_suite | sni_hostname | srp_username | ecc |
1531 client_random | server_random | master_secret | keylog |
1532 tls_options_name()
1533 tls_options_name() = atom()
1535
1537 append_cipher_suites(Deferred, Suites) -> ciphers()
1538 Types:
1540 Deferred = ciphers() | cipher_filters()
1542 Suites = ciphers()
1543 Make Deferred suites become the least preferred suites, that is
1545 put them at the end of the cipher suite list Suites after remov‐
1546 ing them from Suites if present. Deferred may be a list of ci‐
1547 pher suites or a list of filters in which case the filters are
1548 use on Suites to extract the Deferred cipher list.
1549 cipher_suites(Description, Version) -> ciphers()
1551 Types:
1553 Description =
1555 default | all | exclusive | anonymous | exclusive_anony‐
1556 mous
1557 Version = protocol_version() | ssl_record:ssl_version()
1558 Lists all possible cipher suites corresponding to Description
1560 that are available. The exclusive and exclusive_anonymous option
1561 will exclusively list cipher suites first supported in Version
1562 whereas the other options are inclusive from the lowest possible
1563 version to Version. The all options includes all suites except
1564 the anonymous and no anonymous suites are supported by default.
1565 Note:
1567 TLS-1.3 has no overlapping cipher suites with previous TLS ver‐
1568 sions, that is the result of cipher_suites(all, 'tlsv1.3'). con‐
1569 tains a separate set of suites that can be used with TLS-1.3 an
1570 other set that can be used if a lower version is negotiated. PRE
1571 TLS-1.3 so called PSK and SRP suites need extra configuration to
1572 work see user lookup function. No anonymous suites are supported
1573 by TLS-1.3.
1574 Also note that the cipher suites returned by this function are
1576 the cipher suites that the OTP ssl application can support pro‐
1577 vided that they are supported by the cryptolib linked with the
1578 OTP crypto application. Use ssl:filter_cipher_suites(Suites,
1579 []). to filter the list for the current cryptolib. Note that ci‐
1580 pher suites may be filtered out because they are too old or too
1581 new depending on the cryptolib
1582 cipher_suites(Description, Version, StringType :: rfc | openssl) ->
1585 [string()]
1586 Types:
1588 Description = default | all | exclusive | anonymous
1590 Version = protocol_version() | ssl_record:ssl_version()
1591 Same as cipher_suites/2 but lists RFC or OpenSSL string names
1593 instead of erl_cipher_suite()
1594 eccs() -> NamedCurves
1596 eccs(Version) -> NamedCurves
1598 Types:
1600 Version = protocol_version()
1602 NamedCurves = [named_curve()]
1603 Returns a list of supported ECCs. eccs() is equivalent to call‐
1605 ing eccs(Protocol) with all supported protocols and then dedu‐
1606 plicating the output.
1607 clear_pem_cache() -> ok
1609 PEM files, used by ssl API-functions, are cached for performance
1611 reasons. The cache is automatically checked at regular intervals
1612 to see if any cache entries should be invalidated.
1613 This function provides a way to unconditionally clear the entire
1615 cache, thereby forcing a reload of previously cached PEM files.
1616 connect(TCPSocket, TLSOptions) ->
1618 {ok, sslsocket()} |
1619 {error, reason()} |
1620 {option_not_a_key_value_tuple, any()}
1621 connect(TCPSocket, TLSOptions, Timeout) ->
1623 {ok, sslsocket()} | {error, reason()}
1624 Types:
1626 TCPSocket = socket()
1628 TLSOptions = [tls_client_option()]
1629 Timeout = timeout()
1630 Upgrades a gen_tcp, or equivalent, connected socket to a TLS
1632 socket, that is, performs the client-side TLS handshake.
1633 Note:
1635 If the option verify is set to verify_peer the option
1636 server_name_indication shall also be specified, if it is not no
1637 Server Name Indication extension will be sent, and pub‐
1638 lic_key:pkix_verify_hostname/2 will be called with the IP-ad‐
1639 dress of the connection as ReferenceID, which is probably not
1640 what you want.
1641 If the option {handshake, hello} is used the handshake is paused
1644 after receiving the server hello message and the success re‐
1645 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1646 Thereafter the handshake is continued or canceled by calling
1647 handshake_continue/3 or handshake_cancel/1.
1648 If the option active is set to once, true or an integer value,
1650 the process owning the sslsocket will receive messages of type
1651 active_msgs()
1652 connect(Host, Port, TLSOptions) ->
1654 {ok, sslsocket()} |
1655 {ok, sslsocket(), Ext :: protocol_extensions()} |
1656 {error, reason()} |
1657 {option_not_a_key_value_tuple, any()}
1658 connect(Host, Port, TLSOptions, Timeout) ->
1660 {ok, sslsocket()} |
1661 {ok, sslsocket(), Ext :: protocol_extensions()} |
1662 {error, reason()} |
1663 {option_not_a_key_value_tuple, any()}
1664 Types:
1666 Host = host()
1668 Port = inet:port_number()
1669 TLSOptions = [tls_client_option()]
1670 Timeout = timeout()
1671 Opens a TLS/DTLS connection to Host, Port.
1673 When the option verify is set to verify_peer the check pub‐
1675 lic_key:pkix_verify_hostname/2 will be performed in addition to
1676 the usual x509-path validation checks. If the check fails the
1677 error {bad_cert, hostname_check_failed} will be propagated to
1678 the path validation fun verify_fun, where it is possible to do
1679 customized checks by using the full possibilities of the pub‐
1680 lic_key:pkix_verify_hostname/3 API. When the option
1681 server_name_indication is provided, its value (the DNS name)
1682 will be used as ReferenceID to public_key:pkix_verify_host‐
1683 name/2. When no server_name_indication option is given, the Host
1684 argument will be used as Server Name Indication extension. The
1685 Host argument will also be used for the public_key:pkix_ver‐
1686 ify_hostname/2 check and if the Host argument is an inet:ip_ad‐
1687 dress() the ReferenceID used for the check will be {ip, Host}
1688 otherwise dns_id will be assumed with a fallback to ip if that
1689 fails.
1690 Note:
1692 According to good practices certificates should not use IP-ad‐
1693 dresses as "server names". It would be very surprising if this
1694 happened outside a closed network.
1695 If the option {handshake, hello} is used the handshake is paused
1698 after receiving the server hello message and the success re‐
1699 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1700 Thereafter the handshake is continued or canceled by calling
1701 handshake_continue/3 or handshake_cancel/1.
1702 If the option active is set to once, true or an integer value,
1704 the process owning the sslsocket will receive messages of type
1705 active_msgs()
1706 close(SslSocket) -> ok | {error, Reason}
1708 Types:
1710 SslSocket = sslsocket()
1712 Reason = any()
1713 Closes a TLS/DTLS connection.
1715 close(SslSocket, How) ->
1717 ok | {ok, port()} | {ok, port(), Data} | {error, Reason}
1718 Types:
1720 SslSocket = sslsocket()
1722 How = timeout() | {NewController :: pid(), timeout()}
1723 Data = binary()
1724 Reason = any()
1725 Closes or downgrades a TLS connection. In the latter case the
1727 transport connection will be handed over to the NewController
1728 process after receiving the TLS close alert from the peer. The
1729 returned transport socket will have the following options set:
1730 [{active, false}, {packet, 0}, {mode, binary}].
1731 In case of downgrade, the close function might return some bi‐
1733 nary data that should be treated by the user as the first bytes
1734 received on the downgraded connection.
1735 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1737 Types:
1739 SslSocket = sslsocket()
1741 NewOwner = pid()
1742 Reason = any()
1743 Assigns a new controlling process to the SSL socket. A control‐
1745 ling process is the owner of an SSL socket, and receives all
1746 messages from the socket.
1747 connection_information(SslSocket) ->
1749 {ok, Result} | {error, reason()}
1750 Types:
1752 SslSocket = sslsocket()
1754 Result = connection_info()
1755 Returns the most relevant information about the connection, ssl
1757 options that are undefined will be filtered out. Note that val‐
1758 ues that affect the security of the connection will only be re‐
1759 turned if explicitly requested by connection_information/2.
1760 Note:
1762 The legacy Item = cipher_suite was removed in OTP-23. Previously
1763 it returned the cipher suite on its (undocumented) legacy for‐
1764 mat. It is replaced by selected_cipher_suite.
1765 connection_information(SslSocket, Items) ->
1768 {ok, Result} | {error, reason()}
1769 Types:
1771 SslSocket = sslsocket()
1773 Items = connection_info_items()
1774 Result = connection_info()
1775 Returns the requested information items about the connection, if
1777 they are defined.
1778 Note that client_random, server_random, master_secret and keylog
1780 are values that affect the security of connection. Meaningful
1781 atoms, not specified above, are the ssl option names.
1782 In order to retrieve keylog and other secret information from a
1784 TLS 1.3 connection, keep_secrets must be configured in advance
1785 and set to true.
1786 Note:
1788 If only undefined options are requested the resulting list can
1789 be empty.
1790 filter_cipher_suites(Suites, Filters) -> Ciphers
1793 Types:
1795 Suites = ciphers()
1797 Filters = cipher_filters()
1798 Ciphers = ciphers()
1799 Removes cipher suites if any of the filter functions returns
1801 false for any part of the cipher suite. If no filter function is
1802 supplied for some part the default behaviour regards it as if
1803 there was a filter function that returned true. For examples see
1804 Customizing cipher suites Additionally, this function also fil‐
1805 ters the cipher suites to exclude cipher suites not supported by
1806 the cryptolib used by the OTP crypto application. That is call‐
1807 ing ssl:filter_cipher_suites(Suites, []) will be equivalent to
1808 only applying the filters for cryptolib support.
1809 format_error(Reason :: Reason | {error, Reason}) -> string()
1811 Types:
1813 Reason = any()
1815 Presents the error returned by an SSL function as a printable
1817 string.
1818 getopts(SslSocket, OptionNames) ->
1820 {ok, [gen_tcp:option()]} | {error, reason()}
1821 Types:
1823 SslSocket = sslsocket()
1825 OptionNames = [gen_tcp:option_name()]
1826 Gets the values of the specified socket options.
1828 getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1830 getstat(SslSocket, Options) ->
1832 {ok, OptionValues} | {error, inet:posix()}
1833 Types:
1835 SslSocket = sslsocket()
1837 Options = [inet:stat_option()]
1838 OptionValues = [{inet:stat_option(), integer()}]
1839 Gets one or more statistic options for the underlying TCP
1841 socket.
1842 See inet:getstat/2 for statistic options description.
1844 handshake(HsSocket) ->
1846 {ok, SslSocket} |
1847 {ok, SslSocket, Ext} |
1848 {error, Reason}
1849 handshake(HsSocket, Timeout) ->
1851 {ok, SslSocket} |
1852 {ok, SslSocket, Ext} |
1853 {error, Reason}
1854 Types:
1856 HsSocket = sslsocket()
1858 Timeout = timeout()
1859 SslSocket = sslsocket()
1860 Ext = protocol_extensions()
1861 Reason = closed | timeout | error_alert()
1862 Performs the TLS/DTLS server-side handshake.
1864 Returns a new TLS/DTLS socket if the handshake is successful.
1866 If the option active is set to once, true or an integer value,
1868 the process owning the sslsocket will receive messages of type
1869 active_msgs()
1870 Warning:
1872 Not setting the timeout makes the server more vulnerable to DoS
1873 attacks.
1874 handshake(Socket, Options) ->
1877 {ok, SslSocket} |
1878 {ok, SslSocket, Ext} |
1879 {error, Reason}
1880 handshake(Socket, Options, Timeout) ->
1882 {ok, SslSocket} |
1883 {ok, SslSocket, Ext} |
1884 {error, Reason}
1885 Types:
1887 Socket = socket() | sslsocket()
1889 SslSocket = sslsocket()
1890 Options = [server_option()]
1891 Timeout = timeout()
1892 Ext = protocol_extensions()
1893 Reason = closed | timeout | {options, any()} | error_alert()
1894 If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1896 lent, socket to an SSL socket, that is, performs the TLS server-
1897 side handshake and returns a TLS socket.
1898 Warning:
1900 The ordinary Socket shall be in passive mode ({active, false})
1901 before calling this function, and before the client tries to
1902 connect with TLS, or else the behavior of this function is unde‐
1903 fined. The best way to ensure this is to create the ordinary
1904 listen socket in passive mode.
1905 If Socket is an sslsocket() : provides extra TLS/DTLS options
1908 to those specified in listen/2 and then performs the TLS/DTLS
1909 handshake. Returns a new TLS/DTLS socket if the handshake is
1910 successful.
1911 Warning:
1913 Not setting the timeout makes the server more vulnerable to DoS
1914 attacks.
1915 If option {handshake, hello} is specified the handshake is
1918 paused after receiving the client hello message and the success
1919 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1920 Thereafter the handshake is continued or canceled by calling
1921 handshake_continue/3 or handshake_cancel/1.
1922 If the option active is set to once, true or an integer value,
1924 the process owning the sslsocket will receive messages of type
1925 active_msgs()
1926 handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1928 Cancel the handshake with a fatal USER_CANCELED alert.
1930 handshake_continue(HsSocket, Options) ->
1932 {ok, SslSocket} | {error, Reason}
1933 handshake_continue(HsSocket, Options, Timeout) ->
1935 {ok, SslSocket} | {error, Reason}
1936 Types:
1938 HsSocket = sslsocket()
1940 Options = [tls_client_option() | tls_server_option()]
1941 Timeout = timeout()
1942 SslSocket = sslsocket()
1943 Reason = closed | timeout | error_alert()
1944 Continue the TLS handshake, possibly with new, additional or
1946 changed options.
1947 listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1949 Types:
1951 Port = inet:port_number()
1953 Options = [tls_server_option()]
1954 ListenSocket = sslsocket()
1955 Creates an SSL listen socket.
1957 negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1959 Types:
1961 SslSocket = sslsocket()
1963 Protocol = binary()
1964 Reason = protocol_not_negotiated | closed
1965 Returns the protocol negotiated through ALPN or NPN extensions.
1967 peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1969 Types:
1971 SslSocket = sslsocket()
1973 Cert = public_key:der_encoded()
1974 The peer certificate is returned as a DER-encoded binary. The
1976 certificate can be decoded with public_key:pkix_decode_cert/2
1977 Suggested further reading about certificates is public_key
1978 User's Guide and ssl User's Guide
1979 peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1981 Types:
1983 SslSocket = sslsocket()
1985 Address = inet:ip_address()
1986 Port = inet:port_number()
1987 Returns the address and port number of the peer.
1989 prepend_cipher_suites(Preferred, Suites) -> ciphers()
1991 Types:
1993 Preferred = ciphers() | cipher_filters()
1995 Suites = ciphers()
1996 Make Preferred suites become the most preferred suites that is
1998 put them at the head of the cipher suite list Suites after re‐
1999 moving them from Suites if present. Preferred may be a list of
2000 cipher suites or a list of filters in which case the filters are
2001 use on Suites to extract the preferred cipher list.
2002 prf(SslSocket, Secret, Label, Seed, WantedLength) ->
2004 {ok, binary()} | {error, reason()}
2005 Types:
2007 SslSocket = sslsocket()
2009 Secret = binary() | master_secret
2010 Label = binary()
2011 Seed = [binary() | prf_random()]
2012 WantedLength = integer() >= 0
2013 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
2015 ate extra key material. It either takes user-generated values
2016 for Secret and Seed or atoms directing it to use a specific
2017 value from the session security parameters.
2018 recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
2020 recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
2022 Types:
2024 SslSocket = sslsocket()
2026 Length = integer() >= 0
2027 Data = binary() | list() | HttpPacket
2028 Timeout = timeout()
2029 HttpPacket = any()
2030 See the description of HttpPacket in erlang:decode_packet/3
2031 in ERTS.
2032 Receives a packet from a socket in passive mode. A closed socket
2034 is indicated by return value {error, closed}.
2035 Argument Length is meaningful only when the socket is in mode
2037 raw and denotes the number of bytes to read. If Length = 0, all
2038 available bytes are returned. If Length > 0, exactly Length
2039 bytes are returned, or an error; possibly discarding less than
2040 Length bytes of data when the socket gets closed from the other
2041 side.
2042 Optional argument Timeout specifies a time-out in milliseconds.
2044 The default value is infinity.
2045 renegotiate(SslSocket) -> ok | {error, reason()}
2047 Types:
2049 SslSocket = sslsocket()
2051 Initiates a new handshake. A notable return value is {error,
2053 renegotiation_rejected} indicating that the peer refused to go
2054 through with the renegotiation, but the connection is still ac‐
2055 tive using the previously negotiated session.
2056 TLS-1.3 has removed the renegotiate feature of earlier TLS ver‐
2058 sions and instead adds a new feature called key update that re‐
2059 places the most important part of renegotiate, that is the re‐
2060 freshing of session keys. This is triggered automatically after
2061 reaching a plaintext limit and can be configured by option
2062 key_update_at.
2063 update_keys(SslSocket, Type) -> ok | {error, reason()}
2065 Types:
2067 SslSocket = sslsocket()
2069 Type = write | read_write
2070 There are cryptographic limits on the amount of plaintext which
2072 can be safely encrypted under a given set of keys. If the amount
2073 of data surpasses those limits, a key update is triggered and a
2074 new set of keys are installed. See also the option key_up‐
2075 date_at.
2076 This function can be used to explicitly start a key update on a
2078 TLS 1.3 connection. There are two types of the key update: if
2079 Type is set to write, only the writing key is updated; if Type
2080 is set to read_write, both the reading and writing keys are up‐
2081 dated.
2082 send(SslSocket, Data) -> ok | {error, reason()}
2084 Types:
2086 SslSocket = sslsocket()
2088 Data = iodata()
2089 Writes Data to SslSocket.
2091 A notable return value is {error, closed} indicating that the
2093 socket is closed.
2094 setopts(SslSocket, Options) -> ok | {error, reason()}
2096 Types:
2098 SslSocket = sslsocket()
2100 Options = [gen_tcp:option()]
2101 Sets options according to Options for socket SslSocket.
2103 shutdown(SslSocket, How) -> ok | {error, reason()}
2105 Types:
2107 SslSocket = sslsocket()
2109 How = read | write | read_write
2110 Immediately closes a socket in one or two directions.
2112 How == write means closing the socket for writing, reading from
2114 it is still possible.
2115 To be able to handle that the peer has done a shutdown on the
2117 write side, option {exit_on_close, false} is useful.
2118 signature_algs(Description, Version) -> [signature_algs()]
2120 Types:
2122 Description = default | all | exclusive
2124 Version = protocol_version()
2125 Lists all possible signature algorithms corresponding to De‐
2127 scription that are available. The exclusive option will exclu‐
2128 sively list algorithms/schemes for that protocol version,
2129 whereas the default and all options lists the combined list to
2130 support the range of protocols from (D)TLS-1.2, the first ver‐
2131 sion to support configuration of the signature algorithms, to
2132 Version.
2133 Example:
2135 1> ssl:signature_algs(default, 'tlsv1.3').
2137 [eddsa_ed25519,eddsa_ed448,ecdsa_secp521r1_sha512,
2138 ecdsa_secp384r1_sha384,ecdsa_secp256r1_sha256,
2139 rsa_pss_pss_sha512,rsa_pss_pss_sha384,rsa_pss_pss_sha256,
2140 rsa_pss_rsae_sha512,rsa_pss_rsae_sha384,rsa_pss_rsae_sha256,
2141 rsa_pkcs1_sha512,rsa_pkcs1_sha384,rsa_pkcs1_sha256,
2142 {sha512,ecdsa},
2143 {sha384,ecdsa},
2144 {sha256,ecdsa}]
2145 2>ssl:signature_algs(all, 'tlsv1.3').
2147 [eddsa_ed25519,eddsa_ed448,ecdsa_secp521r1_sha512,
2148 ecdsa_secp384r1_sha384,ecdsa_secp256r1_sha256,
2149 rsa_pss_pss_sha512,rsa_pss_pss_sha384,rsa_pss_pss_sha256,
2150 rsa_pss_rsae_sha512,rsa_pss_rsae_sha384,rsa_pss_rsae_sha256,
2151 rsa_pkcs1_sha512,rsa_pkcs1_sha384,rsa_pkcs1_sha256,
2152 {sha512,ecdsa},
2153 {sha384,ecdsa},
2154 {sha256,ecdsa},
2155 {sha224,ecdsa},
2156 {sha224,rsa},
2157 {sha,rsa},
2158 {sha,dsa}]
2159 3> ssl:signature_algs(exclusive, 'tlsv1.3').
2161 [eddsa_ed25519,eddsa_ed448,ecdsa_secp521r1_sha512,
2162 ecdsa_secp384r1_sha384,ecdsa_secp256r1_sha256,
2163 rsa_pss_pss_sha512,rsa_pss_pss_sha384,rsa_pss_pss_sha256,
2164 rsa_pss_rsae_sha512,rsa_pss_rsae_sha384,rsa_pss_rsae_sha256]
2165 Note:
2168 Some TLS-1-3 scheme names overlap with TLS-1.2 algorithm-tuple-
2169 pair-names and then TLS-1.3 names will be used, for example
2170 rsa_pkcs1_sha256 instead of {sha256, rsa} these are legacy algo‐
2171 rithms in TLS-1.3 that apply only to certificate signatures in
2172 this version of the protocol.
2173 sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
2176 Types:
2178 SslSocket = sslsocket()
2180 Address = inet:ip_address()
2181 Port = inet:port_number()
2182 Returns the local address and port number of socket SslSocket.
2184 start() -> ok | {error, reason()}
2186 start(Type :: permanent | transient | temporary) ->
2188 ok | {error, reason()}
2189 Starts the SSL application. Default type is temporary.
2191 stop() -> ok
2193 Stops the SSL application.
2195 str_to_suite(CipherSuiteName) ->
2197 erl_cipher_suite() |
2198 {error, {not_recognized, CipherSuiteName}}
2199 Types:
2201 CipherSuiteName = string()
2203 Converts an RFC or OpenSSL name string to an erl_cipher_suite()
2205 Returns an error if the cipher suite is not supported or the
2206 name is not a valid cipher suite name.
2207 suite_to_openssl_str(CipherSuite) -> string()
2209 Types:
2211 CipherSuite = erl_cipher_suite()
2213 Converts erl_cipher_suite() to OpenSSL name string.
2215 PRE TLS-1.3 these names differ for RFC names
2217 suite_to_str(CipherSuite) -> string()
2219 Types:
2221 CipherSuite = erl_cipher_suite()
2223 Converts erl_cipher_suite() to RFC name string.
2225 transport_accept(ListenSocket) ->
2227 {ok, SslSocket} | {error, reason()}
2228 transport_accept(ListenSocket, Timeout) ->
2230 {ok, SslSocket} | {error, reason()}
2231 Types:
2233 ListenSocket = sslsocket()
2235 Timeout = timeout()
2236 SslSocket = sslsocket()
2237 Accepts an incoming connection request on a listen socket. Lis‐
2239 tenSocket must be a socket returned from listen/2. The socket
2240 returned is to be passed to handshake/[2,3] to complete hand‐
2241 shaking, that is, establishing the TLS/DTLS connection.
2242 Warning:
2244 Most API functions require that the TLS/DTLS connection is es‐
2245 tablished to work as expected.
2246 The accepted socket inherits the options set for ListenSocket in
2249 listen/2.
2250 The default value for Timeout is infinity. If Timeout is speci‐
2252 fied and no connection is accepted within the given time, {er‐
2253 ror, timeout} is returned.
2254 versions() -> [VersionInfo]
2256 Types:
2258 VersionInfo =
2260 {ssl_app, string()} |
2261 {supported | available | implemented, [tls_version()]} |
2262 {supported_dtls | available_dtls | implemented_dtls,
2263 [dtls_version()]}
2264 Lists information, mainly concerning TLS/DTLS versions, in run‐
2266 time for debugging and testing purposes.
2267 app_vsn:
2269 The application version of the SSL application.
2270 supported:
2272 TLS versions supported with current application environment
2273 and crypto library configuration. Overridden by a version
2274 option on connect/[2,3,4], listen/2, and handshake/[2,3].
2275 For the negotiated TLS version, see connection_information/1
2276 .
2277 supported_dtls:
2279 DTLS versions supported with current application environment
2280 and crypto library configuration. Overridden by a version
2281 option on connect/[2,3,4], listen/2, and handshake/[2,3].
2282 For the negotiated DTLS version, see connection_informa‐
2283 tion/1 .
2284 available:
2286 All TLS versions supported with the linked crypto library.
2287 available_dtls:
2289 All DTLS versions supported with the linked crypto library.
2290 implemented:
2292 All TLS versions supported by the SSL application if linked
2293 with a crypto library with the necessary support.
2294 implemented_dtls:
2296 All DTLS versions supported by the SSL application if linked
2297 with a crypto library with the necessary support.
2298
2300 inet(3) and gen_tcp(3) gen_udp(3)
2301Ericsson AB ssl 11.0.3 ssl(3)