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_password()} |
235 {ciphers, cipher_suites()} |
236 {eccs, [named_curve()]} |
237 {signature_algs, signature_algs()} |
238 {signature_algs_cert, sign_schemes()} |
239 {supported_groups, supported_groups()} |
240 {secure_renegotiate, secure_renegotiation()} |
241 {keep_secrets, keep_secrets()} |
242 {depth, allowed_cert_chain_length()} |
243 {verify_fun, custom_verify()} |
244 {crl_check, crl_check()} |
245 {crl_cache, crl_cache_opts()} |
246 {max_handshake_size, handshake_size()} |
247 {partial_chain, root_fun()} |
248 {versions, protocol_versions()} |
249 {user_lookup_fun, custom_user_lookup()} |
250 {log_level, logging_level()} |
251 {log_alert, log_alert()} |
252 {hibernate_after, hibernate_after()} |
253 {padding_check, padding_check()} |
254 {beast_mitigation, beast_mitigation()} |
255 {ssl_imp, ssl_imp()} |
256 {session_tickets, session_tickets()} |
257 {key_update_at, key_update_at()} |
258 {middlebox_comp_mode, middlebox_comp_mode()}
259 protocol() = tls | dtls
261 Choose TLS or DTLS protocol for the transport layer security.
263 Defaults to tls. For DTLS other transports than UDP are not yet
264 supported.
265 handshake_completion() = hello | full
267 Defaults to full. If hello is specified the handshake will pause
269 after the hello message and give the user a possibility make de‐
270 cisions based on hello extensions before continuing or aborting
271 the handshake by calling handshake_continue/3 or hand‐
272 shake_cancel/1
273 cert() = public_key:der_encoded()
275 The DER-encoded user certificate. Note that the cert option may
277 also be a list of DER-encoded certificates where the first one
278 is the user certificate, and the rest of the certificates con‐
279 stitutes the certificate chain. For maximum interoperability the
280 certificates in the chain should be in the correct order, the
281 chain will be sent as is to the peer. If chain certificates are
282 not provided, certificates from client_cacerts(), server_cac‐
283 erts(), or client_cafile(), server_cafile() are used to con‐
284 struct the chain. If this option is supplied, it overrides op‐
285 tion certfile.
286 cert_pem() = file:filename()
288 Path to a file containing the user certificate on PEM format or
290 possible several certificates where the first one is the user
291 certificate and the rest of the certificates constitutes the
292 certificate chain. For more details see cert(),
293 key() =
295 {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' |
296 'PrivateKeyInfo',
297 public_key:der_encoded()} |
298 #{algorithm := rsa | dss | ecdsa,
299 engine := crypto:engine_ref(),
300 key_id := crypto:key_id(),
301 password => crypto:password()}
302 The DER-encoded user's private key or a map referring to a
304 crypto engine and its key reference that optionally can be pass‐
305 word protected, see also crypto:engine_load/4 and Crypto's
306 Users Guide. If this option is supplied, it overrides option
307 keyfile.
308 key_pem() = file:filename()
310 Path to the file containing the user's private PEM-encoded key.
312 As PEM-files can contain several entries, this option defaults
313 to the same file as given by option certfile.
314 key_password() = string() | fun(() -> string())
316 String containing the user's password or a function returning
318 same type. Only used if the private keyfile is password-pro‐
319 tected.
320 cipher_suites() = ciphers()
322 A list of cipher suites that should be supported
324 The function ssl:cipher_suites/2 can be used to find all ci‐
326 pher suites that are supported by default and all cipher suites
327 that may be configured.
328 If you compose your own cipher_suites() make sure they are fil‐
330 tered for cryptolib support ssl:filter_cipher_suites/2 Addi‐
331 tionally the functions ssl:append_cipher_suites/2 ,
332 ssl:prepend_cipher_suites/2, ssl:suite_to_str/1,
333 ssl:str_to_suite/1, and ssl:suite_to_openssl_str/1 also exist to
334 help creating customized cipher suite lists.
335 Note:
337 Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping
338 sets of cipher suites so to support both these versions cipher
339 suites from both versions need to be included. Also if the sup‐
340 plied list does not comply with the configured versions or cryp‐
341 tolib so that the list becomes empty, this option will fallback
342 on its appropriate default value for the configured versions.
343 Non-default cipher suites including anonymous cipher suites (PRE
346 TLS-1.3) are supported for interop/testing purposes and may be
347 used by adding them to your cipher suite list. Note that they
348 must also be supported/enabled by the peer to actually be used.
349 signature_algs() = [{hash(), sign_algo()} | sign_scheme()]
351 Explicitly list acceptable signature algorithms for certificates
353 and handshake messages in the preferred order. The client will
354 send its list as the client hello signature_algorithm extension
355 introduced in TLS-1.2, see Section 7.4.1.4.1 in RFC 5246. Previ‐
356 ously these algorithms where implicitly chosen and partly de‐
357 rived from the cipher suite.
358 In TLS-1.2 a somewhat more explicit negotiation is made possible
360 using a list of {hash(), sign_algo()} pairs.
361 In TLS-1.3 these algorithm pairs are replaced by so called sig‐
363 nature schemes sign_scheme() and completely decoupled from the
364 cipher suite.
365 Signature algorithms used for certificates may be overridden by
367 the signature schemes (algorithms) supplied by the signa‐
368 ture_algs_cert option.
369 TLS-1.2 default is
371 Default_TLS_12_Alg_Pairs =
373 [
375 %% SHA2
376 {sha512, ecdsa},
377 {sha512, rsa},
378 {sha384, ecdsa},
379 {sha384, rsa},
380 {sha256, ecdsa},
381 {sha256, rsa},
382 {sha224, ecdsa},
383 {sha224, rsa},
384 %% SHA
385 {sha, ecdsa},
386 {sha, rsa},
387 {sha, dsa}
388 ]
389 Support for {md5, rsa} was removed from the the TLS-1.2 default
392 in ssl-8.0 (OTP-22)
393 TLS_13 _Legacy_Schemes =
395 [
397 %% Legacy algorithms only applicable to certificate signatures
398 rsa_pkcs1_sha512, %% Corresponds to {sha512, rsa}
399 rsa_pkcs1_sha384, %% Corresponds to {sha384, rsa}
400 rsa_pkcs1_sha256, %% Corresponds to {sha256, rsa}
401 ecdsa_sha1, %% Corresponds to {sha, ecdsa}
402 rsa_pkcs1_sha1 %% Corresponds to {sha, rsa}
403 ]
404 Default_TLS_13_Schemes =
407 [
409 %% ECDSA
410 ecdsa_secp521r1_sha512,
411 ecdsa_secp384r1_sha384,
412 ecdsa_secp256r1_sha256,
413 %% RSASSA-PSS
414 rsa_pss_pss_sha512,
415 rsa_pss_pss_sha384,
416 rsa_pss_pss_sha256,
417 rsa_pss_rsae_sha512,
418 rsa_pss_rsae_sha384,
419 rsa_pss_rsae_sha256,
420 %% EDDSA
421 eddsa_ed25519,
422 eddsa_ed448]
423 TLS-1.3 default is
426 Default_TLS_13_Schemes ++ Legacy_TLS_13_Schemes
428 If both TLS-1.3 and TLS-1.2 are supported the default will be
430 Default_TLS_13_Schemes ++ Default_TLS_12_Alg_Pairs
432 so appropriate algorithms can be chosen for the negotiated ver‐
434 sion.
435 Note:
437 TLS-1.2 algorithms will not be negotiated for TLS-1.3, but
438 TLS-1.3 RSASSA-PSS rsassa_pss_scheme() signature schemes may be
439 negotiated also for TLS-1.2 from 24.1 (fully working from
440 24.1.3). However if TLS-1.3 is negotiated when both TLS-1.3 and
441 TLS-1.2 is supported using defaults, the corresponding TLS-1.2
442 algorithms to the TLS-1.3 legacy signature schemes will be con‐
443 sidered as the legacy schemes and applied only to certificate
444 signatures.
445 sign_schemes() = [sign_scheme()]
448 Explicitly list acceptable signature schemes (algorithms) in the
450 preferred order. Overrides the algorithms supplied in signa‐
451 ture_algs option for certificates.
452 In addition to the signature_algorithms extension from TLS 1.2,
454 TLS 1.3 (RFC 5246 Section 4.2.3) adds the signature_algo‐
455 rithms_cert extension which enables having special requirements
456 on the signatures used in the certificates that differs from the
457 requirements on digital signatures as a whole. If this is not
458 required this extension is not need.
459 The client will send a signature_algorithms_cert extension (in
461 the client hello message), if TLS version 1.2 (back-ported to
462 TLS 1.2 in 24.1) or later is used, and the signature_algs_cert
463 option is explicitly specified. By default, only the signa‐
464 ture_algs extension is sent.
465 Note:
467 Note that supported signature schemes for TLS-1.2 are
468 sign_scheme_legacy() and rsassa_pss_scheme()
469 supported_groups() = [group()]
472 TLS 1.3 introduces the "supported_groups" extension that is used
474 for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
475 shake. Both client and server can specify a list of parameters
476 that they are willing to use.
477 If it is not specified it will use a default list ([x25519,
479 x448, secp256r1, secp384r1]) that is filtered based on the in‐
480 stalled crypto library version.
481 secure_renegotiation() = boolean()
483 Specifies if to reject renegotiation attempt that does not live
485 up to RFC 5746. By default secure_renegotiate is set to true,
486 that is, secure renegotiation is enforced. If set to false se‐
487 cure renegotiation will still be used if possible, but it falls
488 back to insecure renegotiation if the peer does not support RFC
489 5746.
490 allowed_cert_chain_length() = integer()
492 Maximum number of non-self-issued intermediate certificates that
494 can follow the peer certificate in a valid certification path.
495 So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
496 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
497 can be PEER, CA, CA, ROOT-CA, and so on. The default value is
498 10.
499 custom_verify() =
501 {Verifyfun :: function(), InitialUserState :: any()}
502 The verification fun is to be defined as follows:
504 fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() |
506 {revoked, atom()}} |
507 {extension, #'Extension'{}} | valid | valid_peer, InitialUserState :: term()) ->
508 {valid, UserState :: term()} |
509 {fail, Reason :: term()} | {unknown, UserState :: term()}.
510 The verification fun is called during the X509-path validation
513 when an error or an extension unknown to the SSL application is
514 encountered. It is also called when a certificate is considered
515 valid by the path validation to allow access to each certificate
516 in the path to the user application. It differentiates between
517 the peer certificate and the CA certificates by using valid_peer
518 or valid as second argument to the verification fun. See the
519 public_key User's Guide for definition of #'OTPCertificate'{}
520 and #'Extension'{}.
521 * If the verify callback fun returns {fail, Reason}, the veri‐
523 fication process is immediately stopped, an alert is sent to
524 the peer, and the TLS/DTLS handshake terminates.
525 * If the verify callback fun returns {valid, UserState}, the
527 verification process continues.
528 * If the verify callback fun always returns {valid, User‐
530 State}, the TLS/DTLS handshake does not terminate regarding
531 verification failures and the connection is established.
532 * If called with an extension unknown to the user application,
534 return value {unknown, UserState} is to be used.
535 Note that if the fun returns unknown for an extension marked
537 as critical, validation will fail.
538 Default option verify_fun in verify_peer mode:
540 {fun(_,{bad_cert, _} = Reason, _) ->
542 {fail, Reason};
543 (_,{extension, _}, UserState) ->
544 {unknown, UserState};
545 (_, valid, UserState) ->
546 {valid, UserState};
547 (_, valid_peer, UserState) ->
548 {valid, UserState}
549 end, []}
550 Default option verify_fun in mode verify_none:
553 {fun(_,{bad_cert, _}, UserState) ->
555 {valid, UserState};
556 (_,{extension, #'Extension'{critical = true}}, UserState) ->
557 {valid, UserState};
558 (_,{extension, _}, UserState) ->
559 {unknown, UserState};
560 (_, valid, UserState) ->
561 {valid, UserState};
562 (_, valid_peer, UserState) ->
563 {valid, UserState}
564 end, []}
565 The possible path validation errors are given on form {bad_cert,
568 Reason} where Reason is:
569 unknown_ca:
571 No trusted CA was found in the trusted store. The trusted CA
572 is normally a so called ROOT CA, which is a self-signed cer‐
573 tificate. Trust can be claimed for an intermediate CA
574 (trusted anchor does not have to be self-signed according to
575 X-509) by using option partial_chain.
576 selfsigned_peer:
578 The chain consisted only of one self-signed certificate.
579 PKIX X-509-path validation error:
581 For possible reasons, see public_key:pkix_path_validation/3
582 crl_check() = boolean() | peer | best_effort
584 Perform CRL (Certificate Revocation List) verification (pub‐
586 lic_key:pkix_crls_validate/3) on all the certificates during the
587 path validation (public_key:pkix_path_validation/3) of the cer‐
588 tificate chain. Defaults to false.
589 peer:
591 check is only performed on the peer certificate.
592 best_effort:
594 if certificate revocation status cannot be determined it
595 will be accepted as valid.
596 The CA certificates specified for the connection will be used to
598 construct the certificate chain validating the CRLs.
599 The CRLs will be fetched from a local or external cache. See
601 ssl_crl_cache_api(3).
602 crl_cache_opts() =
604 {Module :: atom(),
605 {DbHandle :: internal | term(), Args :: list()}}
606 Specify how to perform lookup and caching of certificate revoca‐
608 tion lists. Module defaults to ssl_crl_cache with DbHandle be‐
609 ing internal and an empty argument list.
610 There are two implementations available:
612 ssl_crl_cache:
614 This module maintains a cache of CRLs. CRLs can be added to
615 the cache using the function ssl_crl_cache:insert/1, and op‐
616 tionally automatically fetched through HTTP if the following
617 argument is specified:
618 {http, timeout()}:
620 Enables fetching of CRLs specified as http URIs inX509
621 certificate extensions. Requires the OTP inets applica‐
622 tion.
623 ssl_crl_hash_dir:
625 This module makes use of a directory where CRLs are stored
626 in files named by the hash of the issuer name.
627 The file names consist of eight hexadecimal digits followed
629 by .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the
630 first version of the CRL, N starts at zero, and for each new
631 version, N is incremented by one. The OpenSSL utility c_re‐
632 hash creates symlinks according to this pattern.
633 For a given hash value, this module finds all consecutive
635 .r* files starting from zero, and those files taken together
636 make up the revocation list. CRL files whose nextUpdate
637 fields are in the past, or that are issued by a different CA
638 that happens to have the same name hash, are excluded.
639 The following argument is required:
641 {dir, string()}:
643 Specifies the directory in which the CRLs can be found.
644 root_fun() = function()
646 fun(Chain::[public_key:der_encoded()]) ->
648 {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
649 Claim an intermediate CA in the chain as trusted. TLS then per‐
652 forms public_key:pkix_path_validation/3 with the selected CA as
653 trusted anchor and the rest of the chain.
654 protocol_versions() = [protocol_version()]
656 TLS protocol versions supported by started clients and servers.
658 This option overrides the application environment option proto‐
659 col_version and dtls_protocol_version. If the environment option
660 is not set, it defaults to all versions, supported by the SSL
661 application. See also ssl(6).
662 custom_user_lookup() =
664 {Lookupfun :: function(), UserState :: any()}
665 The lookup fun is to defined as follows:
667 fun(psk, PSKIdentity :: binary(), UserState :: term()) ->
669 {ok, SharedSecret :: binary()} | error;
670 fun(srp, Username :: binary(), UserState :: term()) ->
671 {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
672 DerivedKey :: binary()}} | error.
673 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
676 by the client and server to determine the shared secret. When
677 called by the client, PSKIdentity is set to the hint presented
678 by the server or to undefined. When called by the server, PSKI‐
679 dentity is the identity presented by the client.
680 For Secure Remote Password (SRP), the fun is only used by the
682 server to obtain parameters that it uses to generate its session
683 keys. DerivedKey is to be derived according to RFC 2945 and
684 RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
685 word])])
686 session_id() = binary()
688 Identifies a TLS session.
690 log_alert() = boolean()
692 If set to false, TLS/DTLS Alert reports are not displayed. Dep‐
694 recated in OTP 22, use {log_level, logging_level()} instead.
695 logging_level() = logger:level() | none | all
697 Specifies the log level for a TLS/DTLS connection. Alerts are
699 logged on notice level, which is the default level. The level
700 debug triggers verbose logging of TLS/DTLS protocol messages.
701 See also ssl(6)
702 hibernate_after() = timeout()
704 When an integer-value is specified, TLS/DTLS-connection goes
706 into hibernation after the specified number of milliseconds of
707 inactivity, thus reducing its memory footprint. When undefined
708 is specified (this is the default), the process never goes into
709 hibernation.
710 handshake_size() = integer()
712 Integer (24 bits unsigned). Used to limit the size of valid TLS
714 handshake packets to avoid DoS attacks. Defaults to 256*1024.
715 padding_check() = boolean()
717 Affects TLS-1.0 connections only. If set to false, it disables
719 the block cipher padding check to be able to interoperate with
720 legacy software.
721 Warning:
723 Using {padding_check, boolean()} makes TLS vulnerable to the
724 Poodle attack.
725 beast_mitigation() = one_n_minus_one | zero_n | disabled
728 Affects TLS-1.0 connections only. Used to change the BEAST miti‐
730 gation strategy to interoperate with legacy software. Defaults
731 to one_n_minus_one.
732 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
734 zero_n - Perform 0/n BEAST mitigation.
736 disabled - Disable BEAST mitigation.
738 Warning:
740 Using {beast_mitigation, disabled} makes TLS-1.0 vulnerable to
741 the BEAST attack.
742 ssl_imp() = new | old
745 Deprecated since OTP-17, has no effect.
747 session_tickets() =
749 client_session_tickets() | server_session_tickets()
750 Configures the session ticket functionality in TLS 1.3 client
752 and server.
753 key_update_at() = integer() >= 1
755 Configures the maximum amount of bytes that can be sent on a TLS
757 1.3 connection before an automatic key update is performed.
758 There are cryptographic limits on the amount of plaintext which
760 can be safely encrypted under a given set of keys. The current
761 default ensures that data integrity will not be breached with
762 probability greater than 1/2^57. For more information see Limits
763 on Authenticated Encryption Use in TLS.
764 Warning:
766 The default value of this option shall provide the above men‐
767 tioned security guarantees and it shall be reasonable for most
768 applications (~353 TB).
769 middlebox_comp_mode() = boolean()
772 Configures the middlebox compatibility mode on a TLS 1.3 connec‐
774 tion.
775 A significant number of middleboxes misbehave when a TLS 1.3
777 connection is negotiated. Implementations can increase the
778 chance of making connections through those middleboxes by making
779 the TLS 1.3 handshake more like a TLS 1.2 handshake.
780 The middlebox compatibility mode is enabled (true) by default.
782 keep_secrets() = boolean()
784 Configures a TLS 1.3 connection for keylogging
786 In order to retrieve keylog information on a TLS 1.3 connection,
788 it must be configured in advance to keep the client_random and
789 various handshake secrets.
790 The keep_secrets functionality is disabled (false) by default.
792 Added in OTP 23.2
794 TLS/DTLS OPTION DESCRIPTIONS - CLIENT
796 client_option() =
797 {verify, client_verify_type()} |
798 {reuse_session, client_reuse_session()} |
799 {reuse_sessions, client_reuse_sessions()} |
800 {cacerts, client_cacerts()} |
801 {cacertfile, client_cafile()} |
802 {alpn_advertised_protocols, client_alpn()} |
803 {client_preferred_next_protocols,
804 client_preferred_next_protocols()} |
805 {psk_identity, client_psk_identity()} |
806 {srp_identity, client_srp_identity()} |
807 {server_name_indication, sni()} |
808 {max_fragment_length, max_fragment_length()} |
809 {customize_hostname_check, customize_hostname_check()} |
810 {fallback, fallback()} |
811 {certificate_authorities, certificate_authorities()} |
812 {session_tickets, client_session_tickets()} |
813 {use_ticket, use_ticket()} |
814 {early_data, client_early_data()}
815 client_verify_type() = verify_type()
817 In mode verify_none the default behavior is to allow all
819 x509-path validation errors. See also option verify_fun.
820 client_reuse_session() =
822 session_id() | {session_id(), SessionData :: binary()}
823 Reuses a specific session. The session should be referred by its
825 session id if it is earlier saved with the option {reuse_ses‐
826 sions, save} since OTP-21.3 or explicitly specified by its ses‐
827 sion id and associated data since OTP-22.3. See also SSL's
828 Users Guide, Session Reuse pre TLS 1.3
829 client_reuse_sessions() = boolean() | save
831 When save is specified a new connection will be negotiated and
833 saved for later reuse. The session ID can be fetched with con‐
834 nection_information/2 and used with the client option reuse_ses‐
835 sion The boolean value true specifies that if possible, auto‐
836 mated session reuse will be performed. If a new session is cre‐
837 ated, and is unique in regard to previous stored sessions, it
838 will be saved for possible later reuse. Since OTP-21.3
839 certificate_authorities() = boolean()
841 If set to true, sends the certificate authorities extension in
843 TLS-1.3 client hello. The default is false. Note that setting it
844 to true may result in a big overhead if you have many trusted CA
845 certificates. Since OTP-24.3
846 client_cacerts() = [public_key:der_encoded()]
848 The DER-encoded trusted certificates. If this option is supplied
850 it overrides option cacertfile.
851 client_cafile() = file:filename()
853 Path to a file containing PEM-encoded CA certificates. The CA
855 certificates are used during server authentication and when
856 building the client certificate chain.
857 client_alpn() = [app_level_protocol()]
859 The list of protocols supported by the client to be sent to the
861 server to be used for an Application-Layer Protocol Negotiation
862 (ALPN). If the server supports ALPN then it will choose a proto‐
863 col from this list; otherwise it will fail the connection with a
864 "no_application_protocol" alert. A server that does not support
865 ALPN will ignore this value.
866 The list of protocols must not contain an empty binary.
868 The negotiated protocol can be retrieved using the negoti‐
870 ated_protocol/1 function.
871 client_preferred_next_protocols() =
873 {Precedence :: server | client,
874 ClientPrefs :: [app_level_protocol()]} |
875 {Precedence :: server | client,
876 ClientPrefs :: [app_level_protocol()],
877 Default :: app_level_protocol()}
878 Indicates that the client is to try to perform Next Protocol Ne‐
880 gotiation.
881 If precedence is server, the negotiated protocol is the first
883 protocol to be shown on the server advertised list, which is
884 also on the client preference list.
885 If precedence is client, the negotiated protocol is the first
887 protocol to be shown on the client preference list, which is
888 also on the server advertised list.
889 If the client does not support any of the server advertised pro‐
891 tocols or the server does not advertise any protocols, the
892 client falls back to the first protocol in its list or to the
893 default protocol (if a default is supplied). If the server does
894 not support Next Protocol Negotiation, the connection terminates
895 if no default protocol is supplied.
896 max_fragment_length() = undefined | 512 | 1024 | 2048 | 4096
898 Specifies the maximum fragment length the client is prepared to
900 accept from the server. See RFC 6066
901 client_psk_identity() = psk_identity()
903 Specifies the identity the client presents to the server. The
905 matching secret is found by calling user_lookup_fun
906 client_srp_identity() = srp_identity()
908 Specifies the username and password to use to authenticate to
910 the server.
911 sni() = hostname() | disable
913 Specify the hostname to be used in TLS Server Name Indication
915 extension. If not specified it will default to the Host argument
916 of connect/[3,4] unless it is of type inet:ipaddress().
917 The HostName will also be used in the hostname verification of
919 the peer certificate using public_key:pkix_verify_hostname/2.
920 The special value disable prevents the Server Name Indication
922 extension from being sent and disables the hostname verification
923 check public_key:pkix_verify_hostname/2
924 customize_hostname_check() = list()
926 Customizes the hostname verification of the peer certificate, as
928 different protocols that use TLS such as HTTP or LDAP may want
929 to do it differently, for possible options see pub‐
930 lic_key:pkix_verify_hostname/3
931 fallback() = boolean()
933 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired
935 TLS version downgrade. Defaults to false
936 Warning:
938 Note this option is not needed in normal TLS usage and should
939 not be used to implement new clients. But legacy clients that
940 retries connections in the following manner
941 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1',
943 'tlsv1']}])
944 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1']},
946 {fallback, true}])
947 ssl:connect(Host, Port, [...{versions, ['tlsv1']}, {fallback,
949 true}])
950 may use it to avoid undesired TLS version downgrade. Note that
952 TLS_FALLBACK_SCSV must also be supported by the server for the
953 prevention to work.
954 client_session_tickets() = disabled | manual | auto
957 Configures the session ticket functionality. Allowed values are
959 disabled, manual and auto. If it is set to manual the client
960 will send the ticket information to user process in a 3-tuple:
961 {ssl, session_ticket, {SNI, TicketData}}
963 where SNI is the ServerNameIndication and TicketData is the ex‐
965 tended ticket data that can be used in subsequent session re‐
966 sumptions.
967 If it is set to auto, the client automatically handles received
969 tickets and tries to use them when making new TLS connections
970 (session resumption with pre-shared keys).
971 Note:
973 This option is supported by TLS 1.3 and above. See also SSL's
974 Users Guide, Session Tickets and Session Resumption in TLS 1.3
975 use_ticket() = [binary()]
978 Configures the session tickets to be used for session resump‐
980 tion. It is a mandatory option in manual mode (session_tickets =
981 manual).
982 Note:
984 Session tickets are only sent to user if option session_tickets
985 is set to manual
986 This option is supported by TLS 1.3 and above. See also SSL's
988 Users Guide, Session Tickets and Session Resumption in TLS 1.3
989 client_early_data() = binary()
992 Configures the early data to be sent by the client.
994 In order to be able to verify that the server has the intention
996 to process the early data, the following 3-tuple is sent to the
997 user process:
998 {ssl, SslSocket, {early_data, Result}}
1000 where Result is either accepted or rejected.
1002 Warning:
1004 It is the responsibility of the user to handle a rejected Early
1005 Data and to resend when it is appropriate.
1006 TLS/DTLS OPTION DESCRIPTIONS - SERVER
1009 server_option() =
1010 {cacerts, server_cacerts()} |
1011 {cacertfile, server_cafile()} |
1012 {dh, dh_der()} |
1013 {dhfile, dh_file()} |
1014 {verify, server_verify_type()} |
1015 {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
1016 {reuse_sessions, server_reuse_sessions()} |
1017 {reuse_session, server_reuse_session()} |
1018 {alpn_preferred_protocols, server_alpn()} |
1019 {next_protocols_advertised, server_next_protocol()} |
1020 {psk_identity, server_psk_identity()} |
1021 {sni_hosts, sni_hosts()} |
1022 {sni_fun, sni_fun()} |
1023 {honor_cipher_order, honor_cipher_order()} |
1024 {honor_ecc_order, honor_ecc_order()} |
1025 {client_renegotiation, client_renegotiation()} |
1026 {session_tickets, server_session_tickets()} |
1027 {anti_replay, anti_replay()} |
1028 {cookie, cookie()} |
1029 {early_data, server_early_data()}
1030 server_cacerts() = [public_key:der_encoded()]
1032 The DER-encoded trusted certificates. If this option is supplied
1034 it overrides option cacertfile.
1035 server_cafile() = file:filename()
1037 Path to a file containing PEM-encoded CA certificates. The CA
1039 certificates are used to build the server certificate chain and
1040 for client authentication. The CAs are also used in the list of
1041 acceptable client CAs passed to the client when a certificate is
1042 requested. Can be omitted if there is no need to verify the
1043 client and if there are no intermediate CAs for the server cer‐
1044 tificate.
1045 dh_der() = binary()
1047 The DER-encoded Diffie-Hellman parameters. If specified, it
1049 overrides option dhfile.
1050 Warning:
1052 The dh_der option is not supported by TLS 1.3. Use the sup‐
1053 ported_groups option instead.
1054 dh_file() = file:filename()
1057 Path to a file containing PEM-encoded Diffie Hellman parameters
1059 to be used by the server if a cipher suite using Diffie Hellman
1060 key exchange is negotiated. If not specified, default parameters
1061 are used.
1062 Warning:
1064 The dh_file option is not supported by TLS 1.3. Use the sup‐
1065 ported_groups option instead.
1066 server_verify_type() = verify_type()
1069 A server only does x509-path validation in mode verify_peer, as
1071 it then sends a certificate request to the client (this message
1072 is not sent if the verify option is verify_none). You can then
1073 also want to specify option fail_if_no_peer_cert.
1074 fail_if_no_peer_cert() = boolean()
1076 Used together with {verify, verify_peer} by an TLS/DTLS server.
1078 If set to true, the server fails if the client does not have a
1079 certificate to send, that is, sends an empty certificate. If set
1080 to false, it fails only if the client sends an invalid certifi‐
1081 cate (an empty certificate is considered valid). Defaults to
1082 false.
1083 server_reuse_sessions() = boolean()
1085 The boolean value true specifies that the server will agree to
1087 reuse sessions. Setting it to false will result in an empty ses‐
1088 sion table, that is no sessions will be reused. See also option
1089 reuse_session
1090 server_reuse_session() = function()
1092 Enables the TLS/DTLS server to have a local policy for deciding
1094 if a session is to be reused or not. Meaningful only if re‐
1095 use_sessions is set to true. SuggestedSessionId is a binary(),
1096 PeerCert is a DER-encoded certificate, Compression is an enumer‐
1097 ation integer, and CipherSuite is of type ciphersuite().
1098 server_alpn() = [app_level_protocol()]
1100 Indicates the server will try to perform Application-Layer Pro‐
1102 tocol Negotiation (ALPN).
1103 The list of protocols is in order of preference. The protocol
1105 negotiated will be the first in the list that matches one of the
1106 protocols advertised by the client. If no protocol matches, the
1107 server will fail the connection with a "no_application_protocol"
1108 alert.
1109 The negotiated protocol can be retrieved using the negoti‐
1111 ated_protocol/1 function.
1112 server_next_protocol() = [app_level_protocol()]
1114 List of protocols to send to the client if the client indicates
1116 that it supports the Next Protocol extension. The client can se‐
1117 lect a protocol that is not on this list. The list of protocols
1118 must not contain an empty binary. If the server negotiates a
1119 Next Protocol, it can be accessed using the negotiated_next_pro‐
1120 tocol/1 method.
1121 server_psk_identity() = psk_identity()
1123 Specifies the server identity hint, which the server presents to
1125 the client.
1126 honor_cipher_order() = boolean()
1128 If set to true, use the server preference for cipher selection.
1130 If set to false (the default), use the client preference.
1131 sni_hosts() =
1133 [{hostname(), [server_option() | common_option()]}]
1134 If the server receives a SNI (Server Name Indication) from the
1136 client matching a host listed in the sni_hosts option, the spe‐
1137 cific options for that host will override previously specified
1138 options. The option sni_fun, and sni_hosts are mutually exclu‐
1139 sive.
1140 sni_fun() = function()
1142 If the server receives a SNI (Server Name Indication) from the
1144 client, the given function will be called to retrieve
1145 [server_option()] for the indicated server. These options will
1146 be merged into predefined [server_option()] list. The function
1147 should be defined as: fun(ServerName :: string()) -> [server_op‐
1148 tion()] and can be specified as a fun or as named fun mod‐
1149 ule:function/1 The option sni_fun, and sni_hosts are mutually
1150 exclusive.
1151 client_renegotiation() = boolean()
1153 In protocols that support client-initiated renegotiation, the
1155 cost of resources of such an operation is higher for the server
1156 than the client. This can act as a vector for denial of service
1157 attacks. The SSL application already takes measures to counter-
1158 act such attempts, but client-initiated renegotiation can be
1159 strictly disabled by setting this option to false. The default
1160 value is true. Note that disabling renegotiation can result in
1161 long-lived connections becoming unusable due to limits on the
1162 number of messages the underlying cipher suite can encipher.
1163 honor_cipher_order() = boolean()
1165 If true, use the server's preference for cipher selection. If
1167 false (the default), use the client's preference.
1168 honor_ecc_order() = boolean()
1170 If true, use the server's preference for ECC curve selection. If
1172 false (the default), use the client's preference.
1173 server_session_tickets() = disabled | stateful | stateless
1175 Configures the session ticket functionality. Allowed values are
1177 disabled, stateful and stateless.
1178 If it is set to stateful or stateless, session resumption with
1180 pre-shared keys is enabled and the server will send stateful or
1181 stateless session tickets to the client after successful connec‐
1182 tions.
1183 A stateful session ticket is a database reference to internal
1185 state information. A stateless session ticket is a self-en‐
1186 crypted binary that contains both cryptographic keying material
1187 and state data.
1188 Note:
1190 This option is supported by TLS 1.3 and above. See also SSL's
1191 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1192 anti_replay() =
1195 '10k' | '100k' |
1196 {bloom_filter_window_size(),
1197 bloom_filter_hash_functions(),
1198 bloom_filter_bits()}
1199 Configures the server's built-in anti replay feature based on
1201 Bloom filters.
1202 Allowed values are the pre-defined '10k', '100k' or a custom
1204 3-tuple that defines the properties of the bloom filters: {Win‐
1205 dowSize, HashFunctions, Bits}. WindowSize is the number of sec‐
1206 onds after the current Bloom filter is rotated and also the win‐
1207 dow size used for freshness checks. HashFunctions is the number
1208 hash functions and Bits is the number of bits in the bit vector.
1209 '10k' and '100k' are simple defaults with the following proper‐
1210 ties:
1211 * '10k': Bloom filters can hold 10000 elements with 3% proba‐
1213 bility of false positives. WindowSize: 10, HashFunctions: 5,
1214 Bits: 72985 (8.91 KiB).
1215 * '100k': Bloom filters can hold 100000 elements with 3% prob‐
1217 ability of false positives. WindowSize: 10, HashFunctions:
1218 5, Bits: 729845 (89.09 KiB).
1219 Note:
1221 This option is supported by TLS 1.3 and above and only with
1222 stateless session tickets. Ticket lifetime, the number of tick‐
1223 ets sent by the server and the maximum number of tickets stored
1224 by the server in stateful mode are configured by application
1225 variables. See also SSL's Users Guide, Anti-Replay Protection
1226 in TLS 1.3
1227 cookie() = boolean()
1230 If true (default), the server sends a cookie extension in its
1232 HelloRetryRequest messages.
1233 Note:
1235 The cookie extension has two main purposes. It allows the server
1236 to force the client to demonstrate reachability at their appar‐
1237 ent network address (thus providing a measure of DoS protec‐
1238 tion). This is primarily useful for non-connection-oriented
1239 transports. It also allows to offload the server's state to the
1240 client. The cookie extension is enabled by default as it is a
1241 mandatory extension in RFC8446.
1242 server_early_data() = disabled | enabled
1245 Configures if the server accepts (enabled) or rejects (rejects)
1247 early data sent by a client. The default value is disabled.
1248 Warning:
1250 This option is a placeholder, early data is not yet implemented
1251 on the server side.
1252 connection_info() =
1255 [common_info() |
1256 curve_info() |
1257 ssl_options_info() |
1258 security_info()]
1259 common_info() =
1261 {protocol, protocol_version()} |
1262 {session_id, session_id()} |
1263 {session_resumption, boolean()} |
1264 {selected_cipher_suite, erl_cipher_suite()} |
1265 {sni_hostname, term()} |
1266 {srp_username, term()}
1267 curve_info() = {ecc, {named_curve, term()}}
1269 ssl_options_info() = tls_option()
1271 security_info() =
1273 {client_random, binary()} |
1274 {server_random, binary()} |
1275 {master_secret, binary()}
1276 connection_info_items() = [connection_info_item()]
1278 connection_info_item() =
1280 protocol | session_id | session_resumption |
1281 selected_cipher_suite | sni_hostname | srp_username | ecc |
1282 client_random | server_random | master_secret | keylog |
1283 tls_options_name()
1284 tls_options_name() = atom()
1286
1288 append_cipher_suites(Deferred, Suites) -> ciphers()
1289 Types:
1291 Deferred = ciphers() | cipher_filters()
1293 Suites = ciphers()
1294 Make Deferred suites become the least preferred suites, that is
1296 put them at the end of the cipher suite list Suites after remov‐
1297 ing them from Suites if present. Deferred may be a list of ci‐
1298 pher suites or a list of filters in which case the filters are
1299 use on Suites to extract the Deferred cipher list.
1300 cipher_suites(Description, Version) -> ciphers()
1302 Types:
1304 Description =
1306 default | all | exclusive | anonymous | exclusive_anony‐
1307 mous
1308 Version = protocol_version()
1309 Lists all possible cipher suites corresponding to Description
1311 that are available. The exclusive and exclusive_anonymous option
1312 will exclusively list cipher suites first supported in Version
1313 whereas the other options are inclusive from the lowest possible
1314 version to Version. The all options includes all suites except
1315 the anonymous and no anonymous suites are supported by default.
1316 Note:
1318 TLS-1.3 has no overlapping cipher suites with previous TLS ver‐
1319 sions, that is the result of cipher_suites(all, 'tlsv1.3'). con‐
1320 tains a separate set of suites that can be used with TLS-1.3 an
1321 other set that can be used if a lower version is negotiated. PRE
1322 TLS-1.3 so called PSK and SRP suites need extra configuration to
1323 work see user lookup function. No anonymous suites are supported
1324 by TLS-1.3.
1325 Also note that the cipher suites returned by this function are
1327 the cipher suites that the OTP ssl application can support pro‐
1328 vided that they are supported by the cryptolib linked with the
1329 OTP crypto application. Use ssl:filter_cipher_suites(Suites,
1330 []). to filter the list for the current cryptolib. Note that ci‐
1331 pher suites may be filtered out because they are too old or too
1332 new depending on the cryptolib
1333 cipher_suites(Description, Version, StringType :: rfc | openssl) ->
1336 [string()]
1337 Types:
1339 Description = default | all | exclusive | anonymous
1341 Version = protocol_version()
1342 Same as cipher_suites/2 but lists RFC or OpenSSL string names
1344 instead of erl_cipher_suite()
1345 eccs() -> NamedCurves
1347 eccs(Version) -> NamedCurves
1349 Types:
1351 Version = protocol_version()
1353 NamedCurves = [named_curve()]
1354 Returns a list of supported ECCs. eccs() is equivalent to call‐
1356 ing eccs(Protocol) with all supported protocols and then dedu‐
1357 plicating the output.
1358 clear_pem_cache() -> ok
1360 PEM files, used by ssl API-functions, are cached. The cache is
1362 regularly checked to see if any cache entries should be invali‐
1363 dated, however this function provides a way to unconditionally
1364 clear the whole cache.
1365 connect(TCPSocket, TLSOptions) ->
1367 {ok, sslsocket()} |
1368 {error, reason()} |
1369 {option_not_a_key_value_tuple, any()}
1370 connect(TCPSocket, TLSOptions, Timeout) ->
1372 {ok, sslsocket()} | {error, reason()}
1373 Types:
1375 TCPSocket = socket()
1377 TLSOptions = [tls_client_option()]
1378 Timeout = timeout()
1379 Upgrades a gen_tcp, or equivalent, connected socket to a TLS
1381 socket, that is, performs the client-side TLS handshake.
1382 Note:
1384 If the option verify is set to verify_peer the option
1385 server_name_indication shall also be specified, if it is not no
1386 Server Name Indication extension will be sent, and pub‐
1387 lic_key:pkix_verify_hostname/2 will be called with the IP-ad‐
1388 dress of the connection as ReferenceID, which is probably not
1389 what you want.
1390 If the option {handshake, hello} is used the handshake is paused
1393 after receiving the server hello message and the success re‐
1394 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1395 Thereafter the handshake is continued or canceled by calling
1396 handshake_continue/3 or handshake_cancel/1.
1397 If the option active is set to once, true or an integer value,
1399 the process owning the sslsocket will receive messages of type
1400 active_msgs()
1401 connect(Host, Port, TLSOptions) ->
1403 {ok, sslsocket()} |
1404 {ok, sslsocket(), Ext :: protocol_extensions()} |
1405 {error, reason()} |
1406 {option_not_a_key_value_tuple, any()}
1407 connect(Host, Port, TLSOptions, Timeout) ->
1409 {ok, sslsocket()} |
1410 {ok, sslsocket(), Ext :: protocol_extensions()} |
1411 {error, reason()} |
1412 {option_not_a_key_value_tuple, any()}
1413 Types:
1415 Host = host()
1417 Port = inet:port_number()
1418 TLSOptions = [tls_client_option()]
1419 Timeout = timeout()
1420 Opens a TLS/DTLS connection to Host, Port.
1422 When the option verify is set to verify_peer the check pub‐
1424 lic_key:pkix_verify_hostname/2 will be performed in addition to
1425 the usual x509-path validation checks. If the check fails the
1426 error {bad_cert, hostname_check_failed} will be propagated to
1427 the path validation fun verify_fun, where it is possible to do
1428 customized checks by using the full possibilities of the pub‐
1429 lic_key:pkix_verify_hostname/3 API. When the option
1430 server_name_indication is provided, its value (the DNS name)
1431 will be used as ReferenceID to public_key:pkix_verify_host‐
1432 name/2. When no server_name_indication option is given, the Host
1433 argument will be used as Server Name Indication extension. The
1434 Host argument will also be used for the public_key:pkix_ver‐
1435 ify_hostname/2 check and if the Host argument is an inet:ip_ad‐
1436 dress() the ReferenceID used for the check will be {ip, Host}
1437 otherwise dns_id will be assumed with a fallback to ip if that
1438 fails.
1439 Note:
1441 According to good practices certificates should not use IP-ad‐
1442 dresses as "server names". It would be very surprising if this
1443 happened outside a closed network.
1444 If the option {handshake, hello} is used the handshake is paused
1447 after receiving the server hello message and the success re‐
1448 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1449 Thereafter the handshake is continued or canceled by calling
1450 handshake_continue/3 or handshake_cancel/1.
1451 If the option active is set to once, true or an integer value,
1453 the process owning the sslsocket will receive messages of type
1454 active_msgs()
1455 close(SslSocket) -> ok | {error, Reason}
1457 Types:
1459 SslSocket = sslsocket()
1461 Reason = any()
1462 Closes a TLS/DTLS connection.
1464 close(SslSocket, How) ->
1466 ok | {ok, port()} | {ok, port(), Data} | {error, Reason}
1467 Types:
1469 SslSocket = sslsocket()
1471 How = timeout() | {NewController :: pid(), timeout()}
1472 Data = binary()
1473 Reason = any()
1474 Closes or downgrades a TLS connection. In the latter case the
1476 transport connection will be handed over to the NewController
1477 process after receiving the TLS close alert from the peer. The
1478 returned transport socket will have the following options set:
1479 [{active, false}, {packet, 0}, {mode, binary}].
1480 In case of downgrade, the close function might return some bi‐
1482 nary data that should be treated by the user as the first bytes
1483 received on the downgraded connection.
1484 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1486 Types:
1488 SslSocket = sslsocket()
1490 NewOwner = pid()
1491 Reason = any()
1492 Assigns a new controlling process to the SSL socket. A control‐
1494 ling process is the owner of an SSL socket, and receives all
1495 messages from the socket.
1496 connection_information(SslSocket) ->
1498 {ok, Result} | {error, reason()}
1499 Types:
1501 SslSocket = sslsocket()
1503 Result = connection_info()
1504 Returns the most relevant information about the connection, ssl
1506 options that are undefined will be filtered out. Note that val‐
1507 ues that affect the security of the connection will only be re‐
1508 turned if explicitly requested by connection_information/2.
1509 Note:
1511 The legacy Item = cipher_suite was removed in OTP-23. Previously
1512 it returned the cipher suite on its (undocumented) legacy for‐
1513 mat. It is replaced by selected_cipher_suite.
1514 connection_information(SslSocket, Items) ->
1517 {ok, Result} | {error, reason()}
1518 Types:
1520 SslSocket = sslsocket()
1522 Items = connection_info_items()
1523 Result = connection_info()
1524 Returns the requested information items about the connection, if
1526 they are defined.
1527 Note that client_random, server_random, master_secret and keylog
1529 are values that affect the security of connection. Meaningful
1530 atoms, not specified above, are the ssl option names.
1531 In order to retrieve keylog and other secret information from a
1533 TLS 1.3 connection, keep_secrets must be configured in advance
1534 and set to true.
1535 Note:
1537 If only undefined options are requested the resulting list can
1538 be empty.
1539 filter_cipher_suites(Suites, Filters) -> Ciphers
1542 Types:
1544 Suites = ciphers()
1546 Filters = cipher_filters()
1547 Ciphers = ciphers()
1548 Removes cipher suites if any of the filter functions returns
1550 false for any part of the cipher suite. If no filter function is
1551 supplied for some part the default behaviour regards it as if
1552 there was a filter function that returned true. For examples see
1553 Customizing cipher suites Additionally, this function also fil‐
1554 ters the cipher suites to exclude cipher suites not supported by
1555 the cryptolib used by the OTP crypto application. That is call‐
1556 ing ssl:filter_cipher_suites(Suites, []) will be equivalent to
1557 only applying the filters for cryptolib support.
1558 format_error(Reason :: {error, Reason}) -> string()
1560 Types:
1562 Reason = any()
1564 Presents the error returned by an SSL function as a printable
1566 string.
1567 getopts(SslSocket, OptionNames) ->
1569 {ok, [gen_tcp:option()]} | {error, reason()}
1570 Types:
1572 SslSocket = sslsocket()
1574 OptionNames = [gen_tcp:option_name()]
1575 Gets the values of the specified socket options.
1577 getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1579 getstat(SslSocket, Options) ->
1581 {ok, OptionValues} | {error, inet:posix()}
1582 Types:
1584 SslSocket = sslsocket()
1586 Options = [inet:stat_option()]
1587 OptionValues = [{inet:stat_option(), integer()}]
1588 Gets one or more statistic options for the underlying TCP
1590 socket.
1591 See inet:getstat/2 for statistic options description.
1593 handshake(HsSocket) ->
1595 {ok, SslSocket} |
1596 {ok, SslSocket, Ext} |
1597 {error, Reason}
1598 handshake(HsSocket, Timeout) ->
1600 {ok, SslSocket} |
1601 {ok, SslSocket, Ext} |
1602 {error, Reason}
1603 Types:
1605 HsSocket = sslsocket()
1607 Timeout = timeout()
1608 SslSocket = sslsocket()
1609 Ext = protocol_extensions()
1610 Reason = closed | timeout | error_alert()
1611 Performs the TLS/DTLS server-side handshake.
1613 Returns a new TLS/DTLS socket if the handshake is successful.
1615 If the option active is set to once, true or an integer value,
1617 the process owning the sslsocket will receive messages of type
1618 active_msgs()
1619 Warning:
1621 Not setting the timeout makes the server more vulnerable to DoS
1622 attacks.
1623 handshake(Socket, Options) ->
1626 {ok, SslSocket} |
1627 {ok, SslSocket, Ext} |
1628 {error, Reason}
1629 handshake(Socket, Options, Timeout) ->
1631 {ok, SslSocket} |
1632 {ok, SslSocket, Ext} |
1633 {error, Reason}
1634 Types:
1636 Socket = socket() | sslsocket()
1638 SslSocket = sslsocket()
1639 Options = [server_option()]
1640 Timeout = timeout()
1641 Ext = protocol_extensions()
1642 Reason = closed | timeout | {options, any()} | error_alert()
1643 If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1645 lent, socket to an SSL socket, that is, performs the TLS server-
1646 side handshake and returns a TLS socket.
1647 Warning:
1649 The ordinary Socket shall be in passive mode ({active, false})
1650 before calling this function, and before the client tries to
1651 connect with TLS, or else the behavior of this function is unde‐
1652 fined. The best way to ensure this is to create the ordinary
1653 listen socket in passive mode.
1654 If Socket is an sslsocket() : provides extra TLS/DTLS options
1657 to those specified in listen/2 and then performs the TLS/DTLS
1658 handshake. Returns a new TLS/DTLS socket if the handshake is
1659 successful.
1660 Warning:
1662 Not setting the timeout makes the server more vulnerable to DoS
1663 attacks.
1664 If option {handshake, hello} is specified the handshake is
1667 paused after receiving the client hello message and the success
1668 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1669 Thereafter the handshake is continued or canceled by calling
1670 handshake_continue/3 or handshake_cancel/1.
1671 If the option active is set to once, true or an integer value,
1673 the process owning the sslsocket will receive messages of type
1674 active_msgs()
1675 handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1677 Cancel the handshake with a fatal USER_CANCELED alert.
1679 handshake_continue(HsSocket, Options) ->
1681 {ok, SslSocket} | {error, Reason}
1682 handshake_continue(HsSocket, Options, Timeout) ->
1684 {ok, SslSocket} | {error, Reason}
1685 Types:
1687 HsSocket = sslsocket()
1689 Options = [tls_client_option() | tls_server_option()]
1690 Timeout = timeout()
1691 SslSocket = sslsocket()
1692 Reason = closed | timeout | error_alert()
1693 Continue the TLS handshake, possibly with new, additional or
1695 changed options.
1696 listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1698 Types:
1700 Port = inet:port_number()
1702 Options = [tls_server_option()]
1703 ListenSocket = sslsocket()
1704 Creates an SSL listen socket.
1706 negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1708 Types:
1710 SslSocket = sslsocket()
1712 Protocol = binary()
1713 Reason = protocol_not_negotiated
1714 Returns the protocol negotiated through ALPN or NPN extensions.
1716 peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1718 Types:
1720 SslSocket = sslsocket()
1722 Cert = public_key:der_encoded()
1723 The peer certificate is returned as a DER-encoded binary. The
1725 certificate can be decoded with public_key:pkix_decode_cert/2
1726 Suggested further reading about certificates is public_key
1727 User's Guide and ssl User's Guide
1728 peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1730 Types:
1732 SslSocket = sslsocket()
1734 Address = inet:ip_address()
1735 Port = inet:port_number()
1736 Returns the address and port number of the peer.
1738 prepend_cipher_suites(Preferred, Suites) -> ciphers()
1740 Types:
1742 Preferred = ciphers() | cipher_filters()
1744 Suites = ciphers()
1745 Make Preferred suites become the most preferred suites that is
1747 put them at the head of the cipher suite list Suites after re‐
1748 moving them from Suites if present. Preferred may be a list of
1749 cipher suites or a list of filters in which case the filters are
1750 use on Suites to extract the preferred cipher list.
1751 prf(SslSocket, Secret, Label, Seed, WantedLength) ->
1753 {ok, binary()} | {error, reason()}
1754 Types:
1756 SslSocket = sslsocket()
1758 Secret = binary() | master_secret
1759 Label = binary()
1760 Seed = [binary() | prf_random()]
1761 WantedLength = integer() >= 0
1762 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1764 ate extra key material. It either takes user-generated values
1765 for Secret and Seed or atoms directing it to use a specific
1766 value from the session security parameters.
1767 recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
1769 recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
1771 Types:
1773 SslSocket = sslsocket()
1775 Length = integer()
1776 Data = binary() | list() | HttpPacket
1777 Timeout = timeout()
1778 HttpPacket = any()
1779 See the description of HttpPacket in erlang:decode_packet/3
1780 in ERTS.
1781 Receives a packet from a socket in passive mode. A closed socket
1783 is indicated by return value {error, closed}.
1784 Argument Length is meaningful only when the socket is in mode
1786 raw and denotes the number of bytes to read. If Length = 0, all
1787 available bytes are returned. If Length > 0, exactly Length
1788 bytes are returned, or an error; possibly discarding less than
1789 Length bytes of data when the socket gets closed from the other
1790 side.
1791 Optional argument Timeout specifies a time-out in milliseconds.
1793 The default value is infinity.
1794 renegotiate(SslSocket) -> ok | {error, reason()}
1796 Types:
1798 SslSocket = sslsocket()
1800 Initiates a new handshake. A notable return value is {error,
1802 renegotiation_rejected} indicating that the peer refused to go
1803 through with the renegotiation, but the connection is still ac‐
1804 tive using the previously negotiated session.
1805 update_keys(SslSocket, Type) -> ok | {error, reason()}
1807 Types:
1809 SslSocket = sslsocket()
1811 Type = write | read_write
1812 There are cryptographic limits on the amount of plaintext which
1814 can be safely encrypted under a given set of keys. If the amount
1815 of data surpasses those limits, a key update is triggered and a
1816 new set of keys are installed. See also the option key_up‐
1817 date_at.
1818 This function can be used to explicitly start a key update on a
1820 TLS 1.3 connection. There are two types of the key update: if
1821 Type is set to write, only the writing key is updated; if Type
1822 is set to read_write, both the reading and writing keys are up‐
1823 dated.
1824 send(SslSocket, Data) -> ok | {error, reason()}
1826 Types:
1828 SslSocket = sslsocket()
1830 Data = iodata()
1831 Writes Data to SslSocket.
1833 A notable return value is {error, closed} indicating that the
1835 socket is closed.
1836 setopts(SslSocket, Options) -> ok | {error, reason()}
1838 Types:
1840 SslSocket = sslsocket()
1842 Options = [gen_tcp:option()]
1843 Sets options according to Options for socket SslSocket.
1845 shutdown(SslSocket, How) -> ok | {error, reason()}
1847 Types:
1849 SslSocket = sslsocket()
1851 How = read | write | read_write
1852 Immediately closes a socket in one or two directions.
1854 How == write means closing the socket for writing, reading from
1856 it is still possible.
1857 To be able to handle that the peer has done a shutdown on the
1859 write side, option {exit_on_close, false} is useful.
1860 sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1862 Types:
1864 SslSocket = sslsocket()
1866 Address = inet:ip_address()
1867 Port = inet:port_number()
1868 Returns the local address and port number of socket SslSocket.
1870 start() -> ok | {error, reason()}
1872 start(Type :: permanent | transient | temporary) ->
1874 ok | {error, reason()}
1875 Starts the SSL application. Default type is temporary.
1877 stop() -> ok
1879 Stops the SSL application.
1881 str_to_suite(CipherSuiteName) ->
1883 erl_cipher_suite() |
1884 {error, {not_recognized, CipherSuiteName}}
1885 Types:
1887 CipherSuiteName = string()
1889 Converts an RFC or OpenSSL name string to an erl_cipher_suite()
1891 Returns an error if the cipher suite is not supported or the
1892 name is not a valid cipher suite name.
1893 suite_to_openssl_str(CipherSuite) -> string()
1895 Types:
1897 CipherSuite = erl_cipher_suite()
1899 Converts erl_cipher_suite() to OpenSSL name string.
1901 PRE TLS-1.3 these names differ for RFC names
1903 suite_to_str(CipherSuite) -> string()
1905 Types:
1907 CipherSuite = erl_cipher_suite()
1909 Converts erl_cipher_suite() to RFC name string.
1911 transport_accept(ListenSocket) ->
1913 {ok, SslSocket} | {error, reason()}
1914 transport_accept(ListenSocket, Timeout) ->
1916 {ok, SslSocket} | {error, reason()}
1917 Types:
1919 ListenSocket = sslsocket()
1921 Timeout = timeout()
1922 SslSocket = sslsocket()
1923 Accepts an incoming connection request on a listen socket. Lis‐
1925 tenSocket must be a socket returned from listen/2. The socket
1926 returned is to be passed to handshake/[2,3] to complete hand‐
1927 shaking, that is, establishing the TLS/DTLS connection.
1928 Warning:
1930 Most API functions require that the TLS/DTLS connection is es‐
1931 tablished to work as expected.
1932 The accepted socket inherits the options set for ListenSocket in
1935 listen/2.
1936 The default value for Timeout is infinity. If Timeout is speci‐
1938 fied and no connection is accepted within the given time, {er‐
1939 ror, timeout} is returned.
1940 versions() -> [VersionInfo]
1942 Types:
1944 VersionInfo =
1946 {ssl_app, string()} |
1947 {supported | available | implemented, [tls_version()]} |
1948 {supported_dtls | available_dtls | implemented_dtls,
1949 [dtls_version()]}
1950 Lists information, mainly concerning TLS/DTLS versions, in run‐
1952 time for debugging and testing purposes.
1953 app_vsn:
1955 The application version of the SSL application.
1956 supported:
1958 TLS versions supported with current application environment
1959 and crypto library configuration. Overridden by a version
1960 option on connect/[2,3,4], listen/2, and handshake/[2,3].
1961 For the negotiated TLS version, see connection_information/1
1962 .
1963 supported_dtls:
1965 DTLS versions supported with current application environment
1966 and crypto library configuration. Overridden by a version
1967 option on connect/[2,3,4], listen/2, and handshake/[2,3].
1968 For the negotiated DTLS version, see connection_informa‐
1969 tion/1 .
1970 available:
1972 All TLS versions supported with the linked crypto library.
1973 available_dtls:
1975 All DTLS versions supported with the linked crypto library.
1976 implemented:
1978 All TLS versions supported by the SSL application if linked
1979 with a crypto library with the necessary support.
1980 implemented_dtls:
1982 All DTLS versions supported by the SSL application if linked
1983 with a crypto library with the necessary support.
1984
1986 inet(3) and gen_tcp(3) gen_udp(3)
1987Ericsson AB ssl 10.7.3.1 ssl(3)