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 exprimental.
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 users certificate. Note that the cert option may
277 also be a list of DER-encoded certificates where the first one
278 is the users 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 users
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 refering to a crypto
304 engine and its key reference that optionally can be password
305 protected, seealso crypto:engine_load/4 and Crypto's Users
306 Guide. If this option is supplied, it overrides option keyfile.
307 key_pem() = file:filename()
309 Path to the file containing the user's private PEM-encoded key.
311 As PEM-files can contain several entries, this option defaults
312 to the same file as given by option certfile.
313 key_password() = string()
315 String containing the user's password. Only used if the private
317 keyfile is password-protected.
318 cipher_suites() = ciphers()
320 A list of cipher suites that should be supported
322 The function ssl:cipher_suites/2 can be used to find all ci‐
324 pher suites that are supported by default and all cipher suites
325 that may be configured.
326 If you compose your own cipher_suites() make sure they are fil‐
328 tered for cryptolib support ssl:filter_cipher_suites/2 Addi‐
329 tionaly the functions ssl:append_cipher_suites/2 ,
330 ssl:prepend_cipher_suites/2, ssl:suite_to_str/1,
331 ssl:str_to_suite/1, and ssl:suite_to_openssl_str/1 also exist to
332 help creating customized cipher suite lists.
333 Note:
335 Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping
336 sets of cipher suites so to support both these versions cipher
337 suites from both versions need to be included. Also if the sup‐
338 plied list does not comply with the configured versions or cryp‐
339 tolib so that the list becomes empty, this option will fallback
340 on its appropriate default value for the configured versions.
341 Non-default cipher suites including anonymous cipher suites (PRE
344 TLS-1.3) are supported for interop/testing purposes and may be
345 used by adding them to your cipher suite list. Note that they
346 must also be supported/enabled by the peer to actually be used.
347 signature_algs() = [{hash(), sign_algo()} | sign_scheme()]
349 Explicitly list acceptable signature algorithms for certificates
351 and handshake messages in the preferred order. The client will
352 send its list as the client hello signature_algorithm extension
353 introduced in TLS-1.2, see Section 7.4.1.4.1 in RFC 5246. Previ‐
354 ously these algorithms where implicitly chosen and partly de‐
355 rived from the cipher suite.
356 In TLS-1.2 a somewhat more explicit negotiation is made possible
358 using a list of {hash(), sign_algo()} pairs.
359 In TLS-1.3 these algorithm pairs are replaced by so called sig‐
361 nature schemes sign_scheme() and completely decoupled from the
362 cipher suite.
363 Signature algorithms used for certificates may be overridden by
365 the signature schemes (algorithms) supplied by the signa‐
366 ture_algs_cert option.
367 TLS-1.2 default is
369 Default_TLS_12_Alg_Pairs =
371 [
373 %% SHA2
374 {sha512, ecdsa},
375 {sha512, rsa},
376 {sha384, ecdsa},
377 {sha384, rsa},
378 {sha256, ecdsa},
379 {sha256, rsa},
380 {sha224, ecdsa},
381 {sha224, rsa},
382 %% SHA
383 {sha, ecdsa},
384 {sha, rsa},
385 {sha, dsa}
386 ]
387 Support for {md5, rsa} was removed from the the TLS-1.2 default
390 in ssl-8.0 (OTP-22)
391 TLS_13 _Legacy_Schemes =
393 [
395 %% Legacy algorithms only applicable to certificate signatures
396 rsa_pkcs1_sha512, %% Corresponds to {sha512, rsa}
397 rsa_pkcs1_sha384, %% Corresponds to {sha384, rsa}
398 rsa_pkcs1_sha256, %% Corresponds to {sha256, rsa}
399 ecdsa_sha1, %% Corresponds to {sha, ecdsa}
400 rsa_pkcs1_sha1 %% Corresponds to {sha, rsa}
401 ]
402 Default_TLS_13_Schemes =
405 [
407 %% ECDSA
408 ecdsa_secp521r1_sha512,
409 ecdsa_secp384r1_sha384,
410 ecdsa_secp256r1_sha256,
411 %% RSASSA-PSS
412 rsa_pss_pss_sha512,
413 rsa_pss_pss_sha384,
414 rsa_pss_pss_sha256,
415 rsa_pss_rsae_sha512,
416 rsa_pss_rsae_sha384,
417 rsa_pss_rsae_sha256,
418 %% EDDSA
419 eddsa_ed25519,
420 eddsa_ed448]
421 TLS-1.3 default is
424 Default_TLS_13_Schemes ++ Legacy_TLS_13_Schemes
426 If both TLS-1.3 and TLS-1.2 are supported the default will be
428 Default_TLS_13_Schemes ++ Default_TLS_12_Alg_Pairs
430 so appropriate algorithms can be chosen for the negotiated ver‐
432 sion.
433 Note:
435 TLS-1.2 algorithms will not be negotiated for TLS-1.3, but
436 TLS-1.3 RSASSA-PSS rsassa_pss_scheme() signature schemes may be
437 negotiated also for TLS-1.2 from @OTP-16590@ However if TLS-1.3
438 is negotiated when both TLS-1.3 and TLS-1.2 is supported using
439 defaults, the corresponding TLS-1.2 algorithms to the TLS-1.3
440 legacy signature schemes will be considered as the legacy
441 schemes and applied only to certificate signatures.
442 sign_schemes() = [sign_scheme()]
445 Explicitly list acceptable signature schemes (algorithms), in
447 prefered ordered, for certificates, overrides the algorithms
448 supplied in signature_algs option for certificates.
449 In addition to the signature_algorithms extension from TLS 1.2,
451 TLS 1.3 (RFC 5246 Section 4.2.3) adds the signature_algo‐
452 rithms_cert extension which enables having special requirements
453 on the signatures used in the certificates that differs from the
454 requirements on digital signatures as a whole. If this is not
455 required this extension is not need.
456 The client will send a signature_algorithms_cert extension (in
458 the client hello message), if TLS version 1.2 (back-ported to
459 TLS 1.2 in @OTP-16590@) or later is used, and the signa‐
460 ture_algs_cert option is explicitly specified. By default, only
461 the signature_algs extension is sent.
462 Note:
464 Note that supported signature schemes for TLS-1.2 are
465 sign_scheme_legacy() and rsassa_pss_scheme()
466 supported_groups() = [group()]
469 TLS 1.3 introduces the "supported_groups" extension that is used
471 for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
472 shake. Both client and server can specify a list of parameters
473 that they are willing to use.
474 If it is not specified it will use a default list ([x25519,
476 x448, secp256r1, secp384r1]) that is filtered based on the in‐
477 stalled crypto library version.
478 secure_renegotiation() = boolean()
480 Specifies if to reject renegotiation attempt that does not live
482 up to RFC 5746. By default secure_renegotiate is set to true,
483 that is, secure renegotiation is enforced. If set to false se‐
484 cure renegotiation will still be used if possible, but it falls
485 back to insecure renegotiation if the peer does not support RFC
486 5746.
487 allowed_cert_chain_length() = integer()
489 Maximum number of non-self-issued intermediate certificates that
491 can follow the peer certificate in a valid certification path.
492 So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
493 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
494 can be PEER, CA, CA, ROOT-CA, and so on. The default value is
495 10.
496 custom_verify() =
498 {Verifyfun :: function(), InitialUserState :: any()}
499 The verification fun is to be defined as follows:
501 fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() |
503 {revoked, atom()}} |
504 {extension, #'Extension'{}} | valid | valid_peer, InitialUserState :: term()) ->
505 {valid, UserState :: term()} |
506 {fail, Reason :: term()} | {unknown, UserState :: term()}.
507 The verification fun is called during the X509-path validation
510 when an error or an extension unknown to the SSL application is
511 encountered. It is also called when a certificate is considered
512 valid by the path validation to allow access to each certificate
513 in the path to the user application. It differentiates between
514 the peer certificate and the CA certificates by using valid_peer
515 or valid as second argument to the verification fun. See the
516 public_key User's Guide for definition of #'OTPCertificate'{}
517 and #'Extension'{}.
518 * If the verify callback fun returns {fail, Reason}, the veri‐
520 fication process is immediately stopped, an alert is sent to
521 the peer, and the TLS/DTLS handshake terminates.
522 * If the verify callback fun returns {valid, UserState}, the
524 verification process continues.
525 * If the verify callback fun always returns {valid, User‐
527 State}, the TLS/DTLS handshake does not terminate regarding
528 verification failures and the connection is established.
529 * If called with an extension unknown to the user application,
531 return value {unknown, UserState} is to be used.
532 Note that if the fun returns unknown for an extension marked
534 as critical, validation will fail.
535 Default option verify_fun in verify_peer mode:
537 {fun(_,{bad_cert, _} = Reason, _) ->
539 {fail, Reason};
540 (_,{extension, _}, UserState) ->
541 {unknown, UserState};
542 (_, valid, UserState) ->
543 {valid, UserState};
544 (_, valid_peer, UserState) ->
545 {valid, UserState}
546 end, []}
547 Default option verify_fun in mode verify_none:
550 {fun(_,{bad_cert, _}, UserState) ->
552 {valid, UserState};
553 (_,{extension, #'Extension'{critical = true}}, UserState) ->
554 {valid, UserState};
555 (_,{extension, _}, UserState) ->
556 {unknown, UserState};
557 (_, valid, UserState) ->
558 {valid, UserState};
559 (_, valid_peer, UserState) ->
560 {valid, UserState}
561 end, []}
562 The possible path validation errors are given on form {bad_cert,
565 Reason} where Reason is:
566 unknown_ca:
568 No trusted CA was found in the trusted store. The trusted CA
569 is normally a so called ROOT CA, which is a self-signed cer‐
570 tificate. Trust can be claimed for an intermediate CA
571 (trusted anchor does not have to be self-signed according to
572 X-509) by using option partial_chain.
573 selfsigned_peer:
575 The chain consisted only of one self-signed certificate.
576 PKIX X-509-path validation error:
578 For possible reasons, see public_key:pkix_path_validation/3
579 crl_check() = boolean() | peer | best_effort
581 Perform CRL (Certificate Revocation List) verification (pub‐
583 lic_key:pkix_crls_validate/3) on all the certificates during the
584 path validation (public_key:pkix_path_validation/3) of the cer‐
585 tificate chain. Defaults to false.
586 peer:
588 check is only performed on the peer certificate.
589 best_effort:
591 if certificate revocation status cannot be determined it
592 will be accepted as valid.
593 The CA certificates specified for the connection will be used to
595 construct the certificate chain validating the CRLs.
596 The CRLs will be fetched from a local or external cache. See
598 ssl_crl_cache_api(3).
599 crl_cache_opts() =
601 {Module :: atom(),
602 {DbHandle :: internal | term(), Args :: list()}}
603 Specify how to perform lookup and caching of certificate revoca‐
605 tion lists. Module defaults to ssl_crl_cache with DbHandle be‐
606 ing internal and an empty argument list.
607 There are two implementations available:
609 ssl_crl_cache:
611 This module maintains a cache of CRLs. CRLs can be added to
612 the cache using the function ssl_crl_cache:insert/1, and op‐
613 tionally automatically fetched through HTTP if the following
614 argument is specified:
615 {http, timeout()}:
617 Enables fetching of CRLs specified as http URIs inX509
618 certificate extensions. Requires the OTP inets applica‐
619 tion.
620 ssl_crl_hash_dir:
622 This module makes use of a directory where CRLs are stored
623 in files named by the hash of the issuer name.
624 The file names consist of eight hexadecimal digits followed
626 by .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the
627 first version of the CRL, N starts at zero, and for each new
628 version, N is incremented by one. The OpenSSL utility c_re‐
629 hash creates symlinks according to this pattern.
630 For a given hash value, this module finds all consecutive
632 .r* files starting from zero, and those files taken together
633 make up the revocation list. CRL files whose nextUpdate
634 fields are in the past, or that are issued by a different CA
635 that happens to have the same name hash, are excluded.
636 The following argument is required:
638 {dir, string()}:
640 Specifies the directory in which the CRLs can be found.
641 root_fun() = function()
643 fun(Chain::[public_key:der_encoded()]) ->
645 {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
646 Claim an intermediate CA in the chain as trusted. TLS then per‐
649 forms public_key:pkix_path_validation/3 with the selected CA as
650 trusted anchor and the rest of the chain.
651 protocol_versions() = [protocol_version()]
653 TLS protocol versions supported by started clients and servers.
655 This option overrides the application environment option proto‐
656 col_version and dtls_protocol_version. If the environment option
657 is not set, it defaults to all versions, supported by the SSL
658 application. See also ssl(6).
659 custom_user_lookup() =
661 {Lookupfun :: function(), UserState :: any()}
662 The lookup fun is to defined as follows:
664 fun(psk, PSKIdentity :: binary(), UserState :: term()) ->
666 {ok, SharedSecret :: binary()} | error;
667 fun(srp, Username :: binary(), UserState :: term()) ->
668 {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
669 DerivedKey :: binary()}} | error.
670 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
673 by the client and server to determine the shared secret. When
674 called by the client, PSKIdentity is set to the hint presented
675 by the server or to undefined. When called by the server, PSKI‐
676 dentity is the identity presented by the client.
677 For Secure Remote Password (SRP), the fun is only used by the
679 server to obtain parameters that it uses to generate its session
680 keys. DerivedKey is to be derived according to RFC 2945 and
681 RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
682 word])])
683 session_id() = binary()
685 Identifies a TLS session.
687 log_alert() = boolean()
689 If set to false, TLS/DTLS Alert reports are not displayed. Dep‐
691 recated in OTP 22, use {log_level, logging_level()} instead.
692 logging_level() = logger:level() | none | all
694 Specifies the log level for a TLS/DTLS connection. Alerts are
696 logged on notice level, which is the default level. The level
697 debug triggers verbose logging of TLS/DTLS protocol messages.
698 See also ssl(6)
699 hibernate_after() = timeout()
701 When an integer-value is specified, TLS/DTLS-connection goes
703 into hibernation after the specified number of milliseconds of
704 inactivity, thus reducing its memory footprint. When undefined
705 is specified (this is the default), the process never goes into
706 hibernation.
707 handshake_size() = integer()
709 Integer (24 bits unsigned). Used to limit the size of valid TLS
711 handshake packets to avoid DoS attacks. Defaults to 256*1024.
712 padding_check() = boolean()
714 Affects TLS-1.0 connections only. If set to false, it disables
716 the block cipher padding check to be able to interoperate with
717 legacy software.
718 Warning:
720 Using {padding_check, boolean()} makes TLS vulnerable to the
721 Poodle attack.
722 beast_mitigation() = one_n_minus_one | zero_n | disabled
725 Affects TLS-1.0 connections only. Used to change the BEAST miti‐
727 gation strategy to interoperate with legacy software. Defaults
728 to one_n_minus_one.
729 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
731 zero_n - Perform 0/n BEAST mitigation.
733 disabled - Disable BEAST mitigation.
735 Warning:
737 Using {beast_mitigation, disabled} makes TLS-1.0 vulnerable to
738 the BEAST attack.
739 ssl_imp() = new | old
742 Deprecated since OTP-17, has no affect.
744 session_tickets() =
746 client_session_tickets() | server_session_tickets()
747 Configures the session ticket functionalty in TLS 1.3 client and
749 server.
750 key_update_at() = integer() >= 1
752 Configures the maximum amount of bytes that can be sent on a TLS
754 1.3 connection before an automatic key update is performed.
755 There are cryptographic limits on the amount of plaintext which
757 can be safely encrypted under a given set of keys. The current
758 default ensures that data integrity will not be breached with
759 probability greater than 1/2^57. For more information see Limits
760 on Authenticated Encryption Use in TLS.
761 Warning:
763 The default value of this option shall provide the above men‐
764 tioned security guarantees and it shall be reasonable for most
765 applications (~353 TB).
766 middlebox_comp_mode() = boolean()
769 Configures the middlebox compatibility mode on a TLS 1.3 connec‐
771 tion.
772 A significant number of middleboxes misbehave when a TLS 1.3
774 connection is negotiated. Implementations can increase the
775 chance of making connections through those middleboxes by making
776 the TLS 1.3 handshake more like a TLS 1.2 handshake.
777 The middlebox compatibility mode is enabled (true) by default.
779 keep_secrets() = boolean()
781 Configures a TLS 1.3 connection for keylogging
783 In order to retrieve keylog information on a TLS 1.3 connection,
785 it must be configured in advance to keep the client_random and
786 various handshake secrets.
787 The keep_secrets functionality is disabled (false) by default.
789 Added in OTP 23.2
791 TLS/DTLS OPTION DESCRIPTIONS - CLIENT
793 client_option() =
794 {verify, client_verify_type()} |
795 {reuse_session, client_reuse_session()} |
796 {reuse_sessions, client_reuse_sessions()} |
797 {cacerts, client_cacerts()} |
798 {cacertfile, client_cafile()} |
799 {alpn_advertised_protocols, client_alpn()} |
800 {client_preferred_next_protocols,
801 client_preferred_next_protocols()} |
802 {psk_identity, client_psk_identity()} |
803 {srp_identity, client_srp_identity()} |
804 {server_name_indication, sni()} |
805 {max_fragment_length, max_fragment_length()} |
806 {customize_hostname_check, customize_hostname_check()} |
807 {fallback, fallback()} |
808 {session_tickets, client_session_tickets()} |
809 {use_ticket, use_ticket()} |
810 {early_data, client_early_data()}
811 client_verify_type() = verify_type()
813 In mode verify_none the default behavior is to allow all
815 x509-path validation errors. See also option verify_fun.
816 client_reuse_session() =
818 session_id() | {session_id(), SessionData :: binary()}
819 Reuses a specific session. The session should be refered by its
821 session id if it is earlier saved with the option {reuse_ses‐
822 sions, save} since OTP-21.3 or explicitly specified by its ses‐
823 sion id and associated data since OTP-22.3. See also SSL's
824 Users Guide, Session Reuse pre TLS 1.3
825 client_reuse_sessions() = boolean() | save
827 When save is specified a new connection will be negotiated and
829 saved for later reuse. The session ID can be fetched with con‐
830 nection_information/2 and used with the client option reuse_ses‐
831 sion The boolean value true specifies that if possible, automa‐
832 tized session reuse will be performed. If a new session is cre‐
833 ated, and is unique in regard to previous stored sessions, it
834 will be saved for possible later reuse. Since OTP-21.3
835 client_cacerts() = [public_key:der_encoded()]
837 The DER-encoded trusted certificates. If this option is supplied
839 it overrides option cacertfile.
840 client_cafile() = file:filename()
842 Path to a file containing PEM-encoded CA certificates. The CA
844 certificates are used during server authentication and when
845 building the client certificate chain.
846 client_alpn() = [app_level_protocol()]
848 The list of protocols supported by the client to be sent to the
850 server to be used for an Application-Layer Protocol Negotiation
851 (ALPN). If the server supports ALPN then it will choose a proto‐
852 col from this list; otherwise it will fail the connection with a
853 "no_application_protocol" alert. A server that does not support
854 ALPN will ignore this value.
855 The list of protocols must not contain an empty binary.
857 The negotiated protocol can be retrieved using the negoti‐
859 ated_protocol/1 function.
860 client_preferred_next_protocols() =
862 {Precedence :: server | client,
863 ClientPrefs :: [app_level_protocol()]} |
864 {Precedence :: server | client,
865 ClientPrefs :: [app_level_protocol()],
866 Default :: app_level_protocol()}
867 Indicates that the client is to try to perform Next Protocol Ne‐
869 gotiation.
870 If precedence is server, the negotiated protocol is the first
872 protocol to be shown on the server advertised list, which is
873 also on the client preference list.
874 If precedence is client, the negotiated protocol is the first
876 protocol to be shown on the client preference list, which is
877 also on the server advertised list.
878 If the client does not support any of the server advertised pro‐
880 tocols or the server does not advertise any protocols, the
881 client falls back to the first protocol in its list or to the
882 default protocol (if a default is supplied). If the server does
883 not support Next Protocol Negotiation, the connection terminates
884 if no default protocol is supplied.
885 max_fragment_length() = undefined | 512 | 1024 | 2048 | 4096
887 Specifies the maximum fragment length the client is prepared to
889 accept from the server. See RFC 6066
890 client_psk_identity() = psk_identity()
892 Specifies the identity the client presents to the server. The
894 matching secret is found by calling user_lookup_fun
895 client_srp_identity() = srp_identity()
897 Specifies the username and password to use to authenticate to
899 the server.
900 sni() = hostname() | disable
902 Specify the hostname to be used in TLS Server Name Indication
904 extension. If not specified it will default to the Host argument
905 of connect/[3,4] unless it is of type inet:ipaddress().
906 The HostName will also be used in the hostname verification of
908 the peer certificate using public_key:pkix_verify_hostname/2.
909 The special value disable prevents the Server Name Indication
911 extension from being sent and disables the hostname verification
912 check public_key:pkix_verify_hostname/2
913 customize_hostname_check() = list()
915 Customizes the hostname verification of the peer certificate, as
917 different protocols that use TLS such as HTTP or LDAP may want
918 to do it differently, for possible options see pub‐
919 lic_key:pkix_verify_hostname/3
920 fallback() = boolean()
922 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired
924 TLS version downgrade. Defaults to false
925 Warning:
927 Note this option is not needed in normal TLS usage and should
928 not be used to implement new clients. But legacy clients that
929 retries connections in the following manner
930 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1',
932 'tlsv1']}])
933 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1']},
935 {fallback, true}])
936 ssl:connect(Host, Port, [...{versions, ['tlsv1']}, {fallback,
938 true}])
939 may use it to avoid undesired TLS version downgrade. Note that
941 TLS_FALLBACK_SCSV must also be supported by the server for the
942 prevention to work.
943 client_session_tickets() = disabled | manual | auto
946 Configures the session ticket functionality. Allowed values are
948 disabled, manual and auto. If it is set to manual the client
949 will send the ticket information to user process in a 3-tuple:
950 {ssl, session_ticket, {SNI, TicketData}}
952 where SNI is the ServerNameIndication and TicketData is the ex‐
954 tended ticket data that can be used in subsequent session re‐
955 sumptions.
956 If it is set to auto, the client automatically handles received
958 tickets and tries to use them when making new TLS connections
959 (session resumption with pre-shared keys).
960 Note:
962 This option is supported by TLS 1.3 and above. See also SSL's
963 Users Guide, Session Tickets and Session Resumption in TLS 1.3
964 use_ticket() = [binary()]
967 Configures the session tickets to be used for session resump‐
969 tion. It is a mandatory option in manual mode (session_tickets =
970 manual).
971 Note:
973 Session tickets are only sent to user if option session_tickets
974 is set to manual
975 This option is supported by TLS 1.3 and above. See also SSL's
977 Users Guide, Session Tickets and Session Resumption in TLS 1.3
978 client_early_data() = binary()
981 Configures the early data to be sent by the client.
983 In order to be able to verify that the server has the intention
985 to process the early data, the following 3-tuple is sent to the
986 user process:
987 {ssl, SslSocket, {early_data, Result}}
989 where Result is either accepted or rejected.
991 Warning:
993 It is the responsibility of the user to handle a rejected Early
994 Data and to resend when it is appropriate.
995 TLS/DTLS OPTION DESCRIPTIONS - SERVER
998 server_option() =
999 {cacerts, server_cacerts()} |
1000 {cacertfile, server_cafile()} |
1001 {dh, dh_der()} |
1002 {dhfile, dh_file()} |
1003 {verify, server_verify_type()} |
1004 {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
1005 {reuse_sessions, server_reuse_sessions()} |
1006 {reuse_session, server_reuse_session()} |
1007 {alpn_preferred_protocols, server_alpn()} |
1008 {next_protocols_advertised, server_next_protocol()} |
1009 {psk_identity, server_psk_identity()} |
1010 {sni_hosts, sni_hosts()} |
1011 {sni_fun, sni_fun()} |
1012 {honor_cipher_order, honor_cipher_order()} |
1013 {honor_ecc_order, honor_ecc_order()} |
1014 {client_renegotiation, client_renegotiation()} |
1015 {session_tickets, server_session_tickets()} |
1016 {anti_replay, anti_replay()} |
1017 {cookie, cookie()} |
1018 {early_data, server_early_data()}
1019 server_cacerts() = [public_key:der_encoded()]
1021 The DER-encoded trusted certificates. If this option is supplied
1023 it overrides option cacertfile.
1024 server_cafile() = file:filename()
1026 Path to a file containing PEM-encoded CA certificates. The CA
1028 certificates are used to build the server certificate chain and
1029 for client authentication. The CAs are also used in the list of
1030 acceptable client CAs passed to the client when a certificate is
1031 requested. Can be omitted if there is no need to verify the
1032 client and if there are no intermediate CAs for the server cer‐
1033 tificate.
1034 dh_der() = binary()
1036 The DER-encoded Diffie-Hellman parameters. If specified, it
1038 overrides option dhfile.
1039 Warning:
1041 The dh_der option is not supported by TLS 1.3. Use the sup‐
1042 ported_groups option instead.
1043 dh_file() = file:filename()
1046 Path to a file containing PEM-encoded Diffie Hellman parameters
1048 to be used by the server if a cipher suite using Diffie Hellman
1049 key exchange is negotiated. If not specified, default parameters
1050 are used.
1051 Warning:
1053 The dh_file option is not supported by TLS 1.3. Use the sup‐
1054 ported_groups option instead.
1055 server_verify_type() = verify_type()
1058 A server only does x509-path validation in mode verify_peer, as
1060 it then sends a certificate request to the client (this message
1061 is not sent if the verify option is verify_none). You can then
1062 also want to specify option fail_if_no_peer_cert.
1063 fail_if_no_peer_cert() = boolean()
1065 Used together with {verify, verify_peer} by an TLS/DTLS server.
1067 If set to true, the server fails if the client does not have a
1068 certificate to send, that is, sends an empty certificate. If set
1069 to false, it fails only if the client sends an invalid certifi‐
1070 cate (an empty certificate is considered valid). Defaults to
1071 false.
1072 server_reuse_sessions() = boolean()
1074 The boolean value true specifies that the server will agree to
1076 reuse sessions. Setting it to false will result in an empty ses‐
1077 sion table, that is no sessions will be reused. See also option
1078 reuse_session
1079 server_reuse_session() = function()
1081 Enables the TLS/DTLS server to have a local policy for deciding
1083 if a session is to be reused or not. Meaningful only if re‐
1084 use_sessions is set to true. SuggestedSessionId is a binary(),
1085 PeerCert is a DER-encoded certificate, Compression is an enumer‐
1086 ation integer, and CipherSuite is of type ciphersuite().
1087 server_alpn() = [app_level_protocol()]
1089 Indicates the server will try to perform Application-Layer Pro‐
1091 tocol Negotiation (ALPN).
1092 The list of protocols is in order of preference. The protocol
1094 negotiated will be the first in the list that matches one of the
1095 protocols advertised by the client. If no protocol matches, the
1096 server will fail the connection with a "no_application_protocol"
1097 alert.
1098 The negotiated protocol can be retrieved using the negoti‐
1100 ated_protocol/1 function.
1101 server_next_protocol() = [app_level_protocol()]
1103 List of protocols to send to the client if the client indicates
1105 that it supports the Next Protocol extension. The client can se‐
1106 lect a protocol that is not on this list. The list of protocols
1107 must not contain an empty binary. If the server negotiates a
1108 Next Protocol, it can be accessed using the negotiated_next_pro‐
1109 tocol/1 method.
1110 server_psk_identity() = psk_identity()
1112 Specifies the server identity hint, which the server presents to
1114 the client.
1115 honor_cipher_order() = boolean()
1117 If set to true, use the server preference for cipher selection.
1119 If set to false (the default), use the client preference.
1120 sni_hosts() =
1122 [{hostname(), [server_option() | common_option()]}]
1123 If the server receives a SNI (Server Name Indication) from the
1125 client matching a host listed in the sni_hosts option, the spe‐
1126 cific options for that host will override previously specified
1127 options. The option sni_fun, and sni_hosts are mutually exclu‐
1128 sive.
1129 sni_fun() = function()
1131 If the server receives a SNI (Server Name Indication) from the
1133 client, the given function will be called to retrieve
1134 [server_option()] for the indicated server. These options will
1135 be merged into predefined [server_option()] list. The function
1136 should be defined as: fun(ServerName :: string()) -> [server_op‐
1137 tion()] and can be specified as a fun or as named fun mod‐
1138 ule:function/1 The option sni_fun, and sni_hosts are mutually
1139 exclusive.
1140 client_renegotiation() = boolean()
1142 In protocols that support client-initiated renegotiation, the
1144 cost of resources of such an operation is higher for the server
1145 than the client. This can act as a vector for denial of service
1146 attacks. The SSL application already takes measures to counter-
1147 act such attempts, but client-initiated renegotiation can be
1148 strictly disabled by setting this option to false. The default
1149 value is true. Note that disabling renegotiation can result in
1150 long-lived connections becoming unusable due to limits on the
1151 number of messages the underlying cipher suite can encipher.
1152 honor_cipher_order() = boolean()
1154 If true, use the server's preference for cipher selection. If
1156 false (the default), use the client's preference.
1157 honor_ecc_order() = boolean()
1159 If true, use the server's preference for ECC curve selection. If
1161 false (the default), use the client's preference.
1162 server_session_tickets() = disabled | stateful | stateless
1164 Configures the session ticket functionality. Allowed values are
1166 disabled, stateful and stateless.
1167 If it is set to stateful or stateless, session resumption with
1169 pre-shared keys is enabled and the server will send stateful or
1170 stateless session tickets to the client after successful connec‐
1171 tions.
1172 A stateful session ticket is a database reference to internal
1174 state information. A stateless session ticket is a self-en‐
1175 crypted binary that contains both cryptographic keying material
1176 and state data.
1177 Note:
1179 This option is supported by TLS 1.3 and above. See also SSL's
1180 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1181 anti_replay() =
1184 '10k' | '100k' |
1185 {bloom_filter_window_size(),
1186 bloom_filter_hash_functions(),
1187 bloom_filter_bits()}
1188 Configures the server's built-in anti replay feature based on
1190 Bloom filters.
1191 Allowed values are the pre-defined '10k', '100k' or a custom
1193 3-tuple that defines the properties of the bloom filters: {Win‐
1194 dowSize, HashFunctions, Bits}. WindowSize is the number of sec‐
1195 onds after the current Bloom filter is rotated and also the win‐
1196 dow size used for freshness checks. HashFunctions is the number
1197 hash functions and Bits is the number of bits in the bit vector.
1198 '10k' and '100k' are simple defaults with the following proper‐
1199 ties:
1200 * '10k': Bloom filters can hold 10000 elements with 3% proba‐
1202 bility of false positives. WindowSize: 10, HashFunctions: 5,
1203 Bits: 72985 (8.91 KiB).
1204 * '100k': Bloom filters can hold 100000 elements with 3% prob‐
1206 ability of false positives. WindowSize: 10, HashFunctions:
1207 5, Bits: 729845 (89.09 KiB).
1208 Note:
1210 This option is supported by TLS 1.3 and above and only with
1211 stateless session tickets. Ticket lifetime, the number of tick‐
1212 ets sent by the server and the maximum number of tickets stored
1213 by the server in stateful mode are configured by application
1214 variables. See also SSL's Users Guide, Anti-Replay Protection
1215 in TLS 1.3
1216 cookie() = boolean()
1219 If true (default), the server sends a cookie extension in its
1221 HelloRetryRequest messages.
1222 Note:
1224 The cookie extension has two main purposes. It allows the server
1225 to force the client to demonstrate reachability at their appar‐
1226 ent network address (thus providing a measure of DoS protec‐
1227 tion). This is primarily useful for non-connection-oriented
1228 transports. It also allows to offload the server's state to the
1229 client. The cookie extension is enabled by default as it is a
1230 mandatory extension in RFC8446.
1231 server_early_data() = disabled | enabled
1234 Configures if the server accepts (enabled) or rejects (rejects)
1236 early data sent by a client. The default value is disabled.
1237 Warning:
1239 This option is a placeholder, early data is not yet implemented
1240 on the server side.
1241 connection_info() =
1244 [common_info() |
1245 curve_info() |
1246 ssl_options_info() |
1247 security_info()]
1248 common_info() =
1250 {protocol, protocol_version()} |
1251 {session_id, session_id()} |
1252 {session_resumption, boolean()} |
1253 {selected_cipher_suite, erl_cipher_suite()} |
1254 {sni_hostname, term()} |
1255 {srp_username, term()}
1256 curve_info() = {ecc, {named_curve, term()}}
1258 ssl_options_info() = tls_option()
1260 security_info() =
1262 {client_random, binary()} |
1263 {server_random, binary()} |
1264 {master_secret, binary()}
1265 connection_info_items() = [connection_info_item()]
1267 connection_info_item() =
1269 protocol | session_id | session_resumption |
1270 selected_cipher_suite | sni_hostname | srp_username | ecc |
1271 client_random | server_random | master_secret | keylog |
1272 tls_options_name()
1273 tls_options_name() = atom()
1275
1277 append_cipher_suites(Deferred, Suites) -> ciphers()
1278 Types:
1280 Deferred = ciphers() | cipher_filters()
1282 Suites = ciphers()
1283 Make Deferred suites become the least preferred suites, that is
1285 put them at the end of the cipher suite list Suites after remov‐
1286 ing them from Suites if present. Deferred may be a list of ci‐
1287 pher suites or a list of filters in which case the filters are
1288 use on Suites to extract the Deferred cipher list.
1289 cipher_suites(Description, Version) -> ciphers()
1291 Types:
1293 Description =
1295 default | all | exclusive | anonymous | exclusive_anony‐
1296 mous
1297 Version = protocol_version()
1298 Lists all possible cipher suites corresponding to Description
1300 that are available. The exclusive and exclusive_anonymous option
1301 will exclusively list cipher suites first supported in Version
1302 whereas the other options are inclusive from the lowest possible
1303 version to Version. The all options includes all suites except
1304 the anonymous and no anonymous suites are supported by default.
1305 Note:
1307 TLS-1.3 has no overlapping cipher suites with previous TLS ver‐
1308 sions, that is the result of cipher_suites(all, 'tlsv1.3'). con‐
1309 tains a separate set of suites that can be used with TLS-1.3 an
1310 other set that can be used if a lower version is negotiated. PRE
1311 TLS-1.3 so called PSK and SRP suites need extra configuration to
1312 work see user lookup function. No anonymous suites are supported
1313 by TLS-1.3.
1314 Also note that the cipher suites returned by this function are
1316 the cipher suites that the OTP ssl application can support pro‐
1317 vided that they are supported by the cryptolib linked with the
1318 OTP crypto application. Use ssl:filter_cipher_suites(Suites,
1319 []). to filter the list for the current cryptolib. Note that ci‐
1320 pher suites may be filtered out because they are too old or too
1321 new depending on the cryptolib
1322 cipher_suites(Description, Version, StringType :: rfc | openssl) ->
1325 [string()]
1326 Types:
1328 Description = default | all | exclusive | anonymous
1330 Version = protocol_version()
1331 Same as cipher_suites/2 but lists RFC or OpenSSL string names
1333 instead of erl_cipher_suite()
1334 eccs() -> NamedCurves
1336 eccs(Version) -> NamedCurves
1338 Types:
1340 Version = protocol_version()
1342 NamedCurves = [named_curve()]
1343 Returns a list of supported ECCs. eccs() is equivalent to call‐
1345 ing eccs(Protocol) with all supported protocols and then dedu‐
1346 plicating the output.
1347 clear_pem_cache() -> ok
1349 PEM files, used by ssl API-functions, are cached. The cache is
1351 regularly checked to see if any cache entries should be invali‐
1352 dated, however this function provides a way to unconditionally
1353 clear the whole cache.
1354 connect(TCPSocket, TLSOptions) ->
1356 {ok, sslsocket()} |
1357 {error, reason()} |
1358 {option_not_a_key_value_tuple, any()}
1359 connect(TCPSocket, TLSOptions, Timeout) ->
1361 {ok, sslsocket()} | {error, reason()}
1362 Types:
1364 TCPSocket = socket()
1366 TLSOptions = [tls_client_option()]
1367 Timeout = timeout()
1368 Upgrades a gen_tcp, or equivalent, connected socket to a TLS
1370 socket, that is, performs the client-side TLS handshake.
1371 Note:
1373 If the option verify is set to verify_peer the option
1374 server_name_indication shall also be specified, if it is not no
1375 Server Name Indication extension will be sent, and pub‐
1376 lic_key:pkix_verify_hostname/2 will be called with the IP-ad‐
1377 dress of the connection as ReferenceID, which is probably not
1378 what you want.
1379 If the option {handshake, hello} is used the handshake is paused
1382 after receiving the server hello message and the success re‐
1383 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1384 Thereafter the handshake is continued or canceled by calling
1385 handshake_continue/3 or handshake_cancel/1.
1386 If the option active is set to once, true or an integer value,
1388 the process owning the sslsocket will receive messages of type
1389 active_msgs()
1390 connect(Host, Port, TLSOptions) ->
1392 {ok, sslsocket()} |
1393 {ok, sslsocket(), Ext :: protocol_extensions()} |
1394 {error, reason()} |
1395 {option_not_a_key_value_tuple, any()}
1396 connect(Host, Port, TLSOptions, Timeout) ->
1398 {ok, sslsocket()} |
1399 {ok, sslsocket(), Ext :: protocol_extensions()} |
1400 {error, reason()} |
1401 {option_not_a_key_value_tuple, any()}
1402 Types:
1404 Host = host()
1406 Port = inet:port_number()
1407 TLSOptions = [tls_client_option()]
1408 Timeout = timeout()
1409 Opens a TLS/DTLS connection to Host, Port.
1411 When the option verify is set to verify_peer the check pub‐
1413 lic_key:pkix_verify_hostname/2 will be performed in addition to
1414 the usual x509-path validation checks. If the check fails the
1415 error {bad_cert, hostname_check_failed} will be propagated to
1416 the path validation fun verify_fun, where it is possible to do
1417 customized checks by using the full possibilities of the pub‐
1418 lic_key:pkix_verify_hostname/3 API. When the option
1419 server_name_indication is provided, its value (the DNS name)
1420 will be used as ReferenceID to public_key:pkix_verify_host‐
1421 name/2. When no server_name_indication option is given, the Host
1422 argument will be used as Server Name Indication extension. The
1423 Host argument will also be used for the public_key:pkix_ver‐
1424 ify_hostname/2 check and if the Host argument is an inet:ip_ad‐
1425 dress() the ReferenceID used for the check will be {ip, Host}
1426 otherwise dns_id will be assumed with a fallback to ip if that
1427 fails.
1428 Note:
1430 According to good practices certificates should not use IP-ad‐
1431 dresses as "server names". It would be very surprising if this
1432 happen outside a closed network.
1433 If the option {handshake, hello} is used the handshake is paused
1436 after receiving the server hello message and the success re‐
1437 sponse is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1438 Thereafter the handshake is continued or canceled by calling
1439 handshake_continue/3 or handshake_cancel/1.
1440 If the option active is set to once, true or an integer value,
1442 the process owning the sslsocket will receive messages of type
1443 active_msgs()
1444 close(SslSocket) -> ok | {error, Reason}
1446 Types:
1448 SslSocket = sslsocket()
1450 Reason = any()
1451 Closes a TLS/DTLS connection.
1453 close(SslSocket, How) ->
1455 ok | {ok, port()} | {ok, port(), Data} | {error, Reason}
1456 Types:
1458 SslSocket = sslsocket()
1460 How = timeout() | {NewController :: pid(), timeout()}
1461 Data = binary()
1462 Reason = any()
1463 Closes or downgrades a TLS connection. In the latter case the
1465 transport connection will be handed over to the NewController
1466 process after receiving the TLS close alert from the peer. The
1467 returned transport socket will have the following options set:
1468 [{active, false}, {packet, 0}, {mode, binary}].
1469 In case of downgrade, the close function might return some bi‐
1471 nary data that should be treated by the user as the first bytes
1472 received on the downgraded connection.
1473 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1475 Types:
1477 SslSocket = sslsocket()
1479 NewOwner = pid()
1480 Reason = any()
1481 Assigns a new controlling process to the SSL socket. A control‐
1483 ling process is the owner of an SSL socket, and receives all
1484 messages from the socket.
1485 connection_information(SslSocket) ->
1487 {ok, Result} | {error, reason()}
1488 Types:
1490 SslSocket = sslsocket()
1492 Result = connection_info()
1493 Returns the most relevant information about the connection, ssl
1495 options that are undefined will be filtered out. Note that val‐
1496 ues that affect the security of the connection will only be re‐
1497 turned if explicitly requested by connection_information/2.
1498 Note:
1500 The legacy Item = cipher_suite was removed in OTP-23. Previously
1501 it returned the cipher suite on its (undocumented) legacy for‐
1502 mat. It is replaced by selected_cipher_suite.
1503 connection_information(SslSocket, Items) ->
1506 {ok, Result} | {error, reason()}
1507 Types:
1509 SslSocket = sslsocket()
1511 Items = connection_info_items()
1512 Result = connection_info()
1513 Returns the requested information items about the connection, if
1515 they are defined.
1516 Note that client_random, server_random, master_secret and keylog
1518 are values that affect the security of connection. Meaningful
1519 atoms, not specified above, are the ssl option names.
1520 In order to retrieve keylog and other secret information from a
1522 TLS 1.3 connection, keep_secrets must be configured in advance
1523 and set to true.
1524 Note:
1526 If only undefined options are requested the resulting list can
1527 be empty.
1528 filter_cipher_suites(Suites, Filters) -> Ciphers
1531 Types:
1533 Suites = ciphers()
1535 Filters = cipher_filters()
1536 Ciphers = ciphers()
1537 Removes cipher suites if any of the filter functions returns
1539 false for any part of the cipher suite. If no filter function is
1540 supplied for some part the default behaviour regards it as if
1541 there was a filter function that returned true. For examples see
1542 Customizing cipher suites Additionaly this function also fil‐
1543 ters the cipher suites to exclude cipher suites not supported by
1544 the cryptolib used by the OTP crypto application. That is call‐
1545 ing ssl:filter_cipher_suites(Suites, []) will be equivalent to
1546 only applying the filters for cryptolib support.
1547 format_error(Reason :: {error, Reason}) -> string()
1549 Types:
1551 Reason = any()
1553 Presents the error returned by an SSL function as a printable
1555 string.
1556 getopts(SslSocket, OptionNames) ->
1558 {ok, [gen_tcp:option()]} | {error, reason()}
1559 Types:
1561 SslSocket = sslsocket()
1563 OptionNames = [gen_tcp:option_name()]
1564 Gets the values of the specified socket options.
1566 getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1568 getstat(SslSocket, Options) ->
1570 {ok, OptionValues} | {error, inet:posix()}
1571 Types:
1573 SslSocket = sslsocket()
1575 Options = [inet:stat_option()]
1576 OptionValues = [{inet:stat_option(), integer()}]
1577 Gets one or more statistic options for the underlying TCP
1579 socket.
1580 See inet:getstat/2 for statistic options description.
1582 handshake(HsSocket) ->
1584 {ok, SslSocket} |
1585 {ok, SslSocket, Ext} |
1586 {error, Reason}
1587 handshake(HsSocket, Timeout) ->
1589 {ok, SslSocket} |
1590 {ok, SslSocket, Ext} |
1591 {error, Reason}
1592 Types:
1594 HsSocket = sslsocket()
1596 Timeout = timeout()
1597 SslSocket = sslsocket()
1598 Ext = protocol_extensions()
1599 Reason = closed | timeout | error_alert()
1600 Performs the TLS/DTLS server-side handshake.
1602 Returns a new TLS/DTLS socket if the handshake is successful.
1604 If the option active is set to once, true or an integer value,
1606 the process owning the sslsocket will receive messages of type
1607 active_msgs()
1608 handshake(Socket, Options) ->
1610 {ok, SslSocket} |
1611 {ok, SslSocket, Ext} |
1612 {error, Reason}
1613 handshake(Socket, Options, Timeout) ->
1615 {ok, SslSocket} |
1616 {ok, SslSocket, Ext} |
1617 {error, Reason}
1618 Types:
1620 Socket = socket() | sslsocket()
1622 SslSocket = sslsocket()
1623 Options = [server_option()]
1624 Timeout = timeout()
1625 Ext = protocol_extensions()
1626 Reason = closed | timeout | {options, any()} | error_alert()
1627 If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1629 lent, socket to an SSL socket, that is, performs the TLS server-
1630 side handshake and returns a TLS socket.
1631 Warning:
1633 The Socket shall be in passive mode ({active, false}) before
1634 calling this function or else the behavior of this function is
1635 undefined.
1636 If Socket is an sslsocket() : provides extra TLS/DTLS options
1639 to those specified in listen/2 and then performs the TLS/DTLS
1640 handshake. Returns a new TLS/DTLS socket if the handshake is
1641 successful.
1642 If option {handshake, hello} is specified the handshake is
1644 paused after receiving the client hello message and the success
1645 response 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 handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1654 Cancel the handshake with a fatal USER_CANCELED alert.
1656 handshake_continue(HsSocket, Options) ->
1658 {ok, SslSocket} | {error, Reason}
1659 handshake_continue(HsSocket, Options, Timeout) ->
1661 {ok, SslSocket} | {error, Reason}
1662 Types:
1664 HsSocket = sslsocket()
1666 Options = [tls_client_option() | tls_server_option()]
1667 Timeout = timeout()
1668 SslSocket = sslsocket()
1669 Reason = closed | timeout | error_alert()
1670 Continue the TLS handshake possiby with new, additional or
1672 changed options.
1673 listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1675 Types:
1677 Port = inet:port_number()
1679 Options = [tls_server_option()]
1680 ListenSocket = sslsocket()
1681 Creates an SSL listen socket.
1683 negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1685 Types:
1687 SslSocket = sslsocket()
1689 Protocol = binary()
1690 Reason = protocol_not_negotiated
1691 Returns the protocol negotiated through ALPN or NPN extensions.
1693 peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1695 Types:
1697 SslSocket = sslsocket()
1699 Cert = public_key:der_encoded()
1700 The peer certificate is returned as a DER-encoded binary. The
1702 certificate can be decoded with public_key:pkix_decode_cert/2
1703 Suggested further reading about certificates is public_key
1704 User's Guide and ssl User's Guide
1705 peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1707 Types:
1709 SslSocket = sslsocket()
1711 Address = inet:ip_address()
1712 Port = inet:port_number()
1713 Returns the address and port number of the peer.
1715 prepend_cipher_suites(Preferred, Suites) -> ciphers()
1717 Types:
1719 Preferred = ciphers() | cipher_filters()
1721 Suites = ciphers()
1722 Make Preferred suites become the most preferred suites that is
1724 put them at the head of the cipher suite list Suites after re‐
1725 moving them from Suites if present. Preferred may be a list of
1726 cipher suites or a list of filters in which case the filters are
1727 use on Suites to extract the preferred cipher list.
1728 prf(SslSocket, Secret, Label, Seed, WantedLength) ->
1730 {ok, binary()} | {error, reason()}
1731 Types:
1733 SslSocket = sslsocket()
1735 Secret = binary() | master_secret
1736 Label = binary()
1737 Seed = [binary() | prf_random()]
1738 WantedLength = integer() >= 0
1739 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1741 ate extra key material. It either takes user-generated values
1742 for Secret and Seed or atoms directing it to use a specific
1743 value from the session security parameters.
1744 recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
1746 recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
1748 Types:
1750 SslSocket = sslsocket()
1752 Length = integer()
1753 Data = binary() | list() | HttpPacket
1754 Timeout = timeout()
1755 HttpPacket = any()
1756 See the description of HttpPacket in erlang:decode_packet/3
1757 in ERTS.
1758 Receives a packet from a socket in passive mode. A closed socket
1760 is indicated by return value {error, closed}.
1761 Argument Length is meaningful only when the socket is in mode
1763 raw and denotes the number of bytes to read. If Length = 0, all
1764 available bytes are returned. If Length > 0, exactly Length
1765 bytes are returned, or an error; possibly discarding less than
1766 Length bytes of data when the socket gets closed from the other
1767 side.
1768 Optional argument Timeout specifies a time-out in milliseconds.
1770 The default value is infinity.
1771 renegotiate(SslSocket) -> ok | {error, reason()}
1773 Types:
1775 SslSocket = sslsocket()
1777 Initiates a new handshake. A notable return value is {error,
1779 renegotiation_rejected} indicating that the peer refused to go
1780 through with the renegotiation, but the connection is still ac‐
1781 tive using the previously negotiated session.
1782 update_keys(SslSocket, Type) -> ok | {error, reason()}
1784 Types:
1786 SslSocket = sslsocket()
1788 Type = write | read_write
1789 There are cryptographic limits on the amount of plaintext which
1791 can be safely encrypted under a given set of keys. If the amount
1792 of data surpasses those limits, a key update is triggered and a
1793 new set of keys are installed. See also the option key_up‐
1794 date_at.
1795 This function can be used to explicitly start a key update on a
1797 TLS 1.3 connection. There are two types of the key update: if
1798 Type is set to write, only the writing key is updated; if Type
1799 is set to read_write, both the reading and writing keys are up‐
1800 dated.
1801 send(SslSocket, Data) -> ok | {error, reason()}
1803 Types:
1805 SslSocket = sslsocket()
1807 Data = iodata()
1808 Writes Data to SslSocket.
1810 A notable return value is {error, closed} indicating that the
1812 socket is closed.
1813 setopts(SslSocket, Options) -> ok | {error, reason()}
1815 Types:
1817 SslSocket = sslsocket()
1819 Options = [gen_tcp:option()]
1820 Sets options according to Options for socket SslSocket.
1822 shutdown(SslSocket, How) -> ok | {error, reason()}
1824 Types:
1826 SslSocket = sslsocket()
1828 How = read | write | read_write
1829 Immediately closes a socket in one or two directions.
1831 How == write means closing the socket for writing, reading from
1833 it is still possible.
1834 To be able to handle that the peer has done a shutdown on the
1836 write side, option {exit_on_close, false} is useful.
1837 sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1839 Types:
1841 SslSocket = sslsocket()
1843 Address = inet:ip_address()
1844 Port = inet:port_number()
1845 Returns the local address and port number of socket SslSocket.
1847 start() -> ok | {error, reason()}
1849 start(Type :: permanent | transient | temporary) ->
1851 ok | {error, reason()}
1852 Starts the SSL application. Default type is temporary.
1854 stop() -> ok
1856 Stops the SSL application.
1858 str_to_suite(CipherSuiteName) ->
1860 erl_cipher_suite() |
1861 {error, {not_recognized, CipherSuiteName}}
1862 Types:
1864 CipherSuiteName = string()
1866 Converts an RFC or OpenSSL name string to an erl_cipher_suite()
1868 Returns an error if the cipher suite is not supported or the
1869 name is not a valid cipher suite name.
1870 suite_to_openssl_str(CipherSuite) -> string()
1872 Types:
1874 CipherSuite = erl_cipher_suite()
1876 Converts erl_cipher_suite() to OpenSSL name string.
1878 PRE TLS-1.3 these names differ for RFC names
1880 suite_to_str(CipherSuite) -> string()
1882 Types:
1884 CipherSuite = erl_cipher_suite()
1886 Converts erl_cipher_suite() to RFC name string.
1888 transport_accept(ListenSocket) ->
1890 {ok, SslSocket} | {error, reason()}
1891 transport_accept(ListenSocket, Timeout) ->
1893 {ok, SslSocket} | {error, reason()}
1894 Types:
1896 ListenSocket = sslsocket()
1898 Timeout = timeout()
1899 SslSocket = sslsocket()
1900 Accepts an incoming connection request on a listen socket. Lis‐
1902 tenSocket must be a socket returned from listen/2. The socket
1903 returned is to be passed to handshake/[2,3] to complete hand‐
1904 shaking, that is, establishing the TLS/DTLS connection.
1905 Warning:
1907 Most API functions require that the TLS/DTLS connection is es‐
1908 tablished to work as expected.
1909 The accepted socket inherits the options set for ListenSocket in
1912 listen/2.
1913 The default value for Timeout is infinity. If Timeout is speci‐
1915 fied and no connection is accepted within the given time, {er‐
1916 ror, timeout} is returned.
1917 versions() -> [VersionInfo]
1919 Types:
1921 VersionInfo =
1923 {ssl_app, string()} |
1924 {supported | available | implemented, [tls_version()]} |
1925 {supported_dtls | available_dtls | implemented_dtls,
1926 [dtls_version()]}
1927 Lists information, mainly concerning TLS/DTLS versions, in run‐
1929 time for debugging and testing purposes.
1930 app_vsn:
1932 The application version of the SSL application.
1933 supported:
1935 TLS versions supported with current application environment
1936 and crypto library configuration. Overridden by a version
1937 option on connect/[2,3,4], listen/2, and handshake/[2,3].
1938 For the negotiated TLS version, see connection_information/1
1939 .
1940 supported_dtls:
1942 DTLS versions supported with current application environment
1943 and crypto library configuration. Overridden by a version
1944 option on connect/[2,3,4], listen/2, and handshake/[2,3].
1945 For the negotiated DTLS version, see connection_informa‐
1946 tion/1 .
1947 available:
1949 All TLS versions supported with the linked crypto library.
1950 available_dtls:
1952 All DTLS versions supported with the linked crypto library.
1953 implemented:
1955 All TLS versions supported by the SSL application if linked
1956 with a crypto library with the necessary support.
1957 implemented_dtls:
1959 All DTLS versions supported by the SSL application if linked
1960 with a crypto library with the necessary support.
1961
1963 inet(3) and gen_tcp(3) gen_udp(3)
1964Ericsson AB ssl 10.5.3 ssl(3)