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
58 {active, 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 signature_algs() = [{hash(), sign_algo()}]
138 sign_algo() = rsa | dsa | ecdsa
140 sign_scheme() =
142 rsa_pkcs1_sha256 | rsa_pkcs1_sha384 | rsa_pkcs1_sha512 |
143 ecdsa_secp256r1_sha256 | ecdsa_secp384r1_sha384 |
144 ecdsa_secp521r1_sha512 | rsa_pss_rsae_sha256 |
145 rsa_pss_rsae_sha384 | rsa_pss_rsae_sha512 |
146 rsa_pss_pss_sha256 | rsa_pss_pss_sha384 | rsa_pss_pss_sha512 |
147 rsa_pkcs1_sha1 | ecdsa_sha1
148 group() =
150 secp256r1 | secp384r1 | secp521r1 | ffdhe2048 | ffdhe3072 |
151 ffdhe4096 | ffdhe6144 | ffdhe8192
152 kex_algo() =
154 rsa | dhe_rsa | dhe_dss | ecdhe_ecdsa | ecdh_ecdsa |
155 ecdh_rsa | srp_rsa | srp_dss | psk | dhe_psk | rsa_psk |
156 dh_anon | ecdh_anon | srp_anon | any
157 algo_filter() =
159 fun((kex_algo() | cipher() | hash() | aead | default_prf) ->
160 true | false)
161 named_curve() =
163 sect571r1 | sect571k1 | secp521r1 | brainpoolP512r1 |
164 sect409k1 | sect409r1 | brainpoolP384r1 | secp384r1 |
165 sect283k1 | sect283r1 | brainpoolP256r1 | secp256k1 |
166 secp256r1 | sect239k1 | sect233k1 | sect233r1 | secp224k1 |
167 secp224r1 | sect193r1 | sect193r2 | secp192k1 | secp192r1 |
168 sect163k1 | sect163r1 | sect163r2 | secp160k1 | secp160r1 |
169 secp160r2
170 psk_identity() = string()
172 srp_identity() = {Username :: string(), Password :: string()}
174 srp_param_type() =
176 srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 |
177 srp_6144 | srp_8192
178 app_level_protocol() = binary()
180 protocol_extensions() =
182 #{renegotiation_info => binary(),
183 signature_algs => signature_algs(),
184 alpn => app_level_protocol(),
185 srp => binary(),
186 next_protocol => app_level_protocol(),
187 max_frag_enum => 1..4,
188 ec_point_formats => [0..2],
189 elliptic_curves => [public_key:oid()],
190 sni => hostname()}
191 error_alert() =
193 {tls_alert, {tls_alert(), Description :: string()}}
194 tls_alert() =
196 close_notify | unexpected_message | bad_record_mac |
197 record_overflow | handshake_failure | bad_certificate |
198 unsupported_certificate | certificate_revoked |
199 certificate_expired | certificate_unknown |
200 illegal_parameter | unknown_ca | access_denied |
201 decode_error | decrypt_error | export_restriction |
202 protocol_version | insufficient_security | internal_error |
203 inappropriate_fallback | user_canceled | no_renegotiation |
204 unsupported_extension | certificate_unobtainable |
205 unrecognized_name | bad_certificate_status_response |
206 bad_certificate_hash_value | unknown_psk_identity |
207 no_application_protocol
208 reason() = any()
210 bloom_filter_window_size() = integer()
212 bloom_filter_hash_functions() = integer()
214 bloom_filter_bits() = integer()
216 client_session_tickets() = disabled | manual | auto
218 server_session_tickets() = disabled | stateful | stateless
220 TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT
222 common_option() =
223 {protocol, protocol()} |
224 {handshake, handshake_completion()} |
225 {cert, cert() | [cert()]} |
226 {certfile, cert_pem()} |
227 {key, key()} |
228 {keyfile, key_pem()} |
229 {password, key_password()} |
230 {ciphers, cipher_suites()} |
231 {eccs, [named_curve()]} |
232 {signature_algs_cert, signature_schemes()} |
233 {supported_groups, supported_groups()} |
234 {secure_renegotiate, secure_renegotiation()} |
235 {keep_secrets, keep_secrets()} |
236 {depth, allowed_cert_chain_length()} |
237 {verify_fun, custom_verify()} |
238 {crl_check, crl_check()} |
239 {crl_cache, crl_cache_opts()} |
240 {max_handshake_size, handshake_size()} |
241 {partial_chain, root_fun()} |
242 {versions, protocol_versions()} |
243 {user_lookup_fun, custom_user_lookup()} |
244 {log_level, logging_level()} |
245 {log_alert, log_alert()} |
246 {hibernate_after, hibernate_after()} |
247 {padding_check, padding_check()} |
248 {beast_mitigation, beast_mitigation()} |
249 {ssl_imp, ssl_imp()} |
250 {session_tickets, session_tickets()} |
251 {key_update_at, key_update_at()} |
252 {middlebox_comp_mode, middlebox_comp_mode()}
253 protocol() = tls | dtls
255 Choose TLS or DTLS protocol for the transport layer security.
257 Defaults to tls. For DTLS other transports than UDP are not yet
258 supported.
259 handshake_completion() = hello | full
261 Defaults to full. If hello is specified the handshake will pause
263 after the hello message and give the user a possibility make
264 decisions based on hello extensions before continuing or abort‐
265 ing the handshake by calling handshake_continue/3 or hand‐
266 shake_cancel/1
267 cert() = public_key:der_encoded()
269 The DER-encoded users certificate. Note that the cert option may
271 also be a list of DER-encoded certificates where the first one
272 is the users certificate and the rest of the certificates con‐
273 stitutes the certificate chain. For maximum interoperability the
274 certificates in the chain should be in the correct order, the
275 chain will be sent as is to the peer. If chain certificates are
276 not provided, certificates from client_cacerts(), server_cac‐
277 erts(), or client_cafile(), server_cafile() are used to con‐
278 struct the chain. If this option is supplied, it overrides
279 option certfile.
280 cert_pem() = file:filename()
282 Path to a file containing the user certificate on PEM format or
284 possible several certificates where the first one is the users
285 certificate and the rest of the certificates constitutes the
286 certificate chain. For more details see cert(),
287 key() =
289 {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' |
290 'PrivateKeyInfo',
291 public_key:der_encoded()} |
292 #{algorithm := rsa | dss | ecdsa,
293 engine := crypto:engine_ref(),
294 key_id := crypto:key_id(),
295 password => crypto:password()}
296 The DER-encoded user's private key or a map refering to a crypto
298 engine and its key reference that optionally can be password
299 protected, seealso crypto:engine_load/4 and Crypto's Users
300 Guide. If this option is supplied, it overrides option keyfile.
301 key_pem() = file:filename()
303 Path to the file containing the user's private PEM-encoded key.
305 As PEM-files can contain several entries, this option defaults
306 to the same file as given by option certfile.
307 key_password() = string()
309 String containing the user's password. Only used if the private
311 keyfile is password-protected.
312 cipher_suites() = ciphers()
314 A list of cipher suites that should be supported
316 The function ssl:cipher_suites/2 can be used to find all
318 cipher suites that are supported by default and all cipher
319 suites that may be configured.
320 If you compose your own cipher_suites() make sure they are fil‐
322 tered for cryptolib support ssl:filter_cipher_suites/2 Addi‐
323 tionaly the functions ssl:append_cipher_suites/2 ,
324 ssl:prepend_cipher_suites/2, ssl:suite_to_str/1,
325 ssl:str_to_suite/1, and ssl:suite_to_openssl_str/1 also exist to
326 help creating customized cipher suite lists.
327 Note:
329 Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping
330 sets of cipher suites so to support both these versions cipher
331 suites from both versions need to be included. If supporting
332 TLS-1.3 versions prior to TLS-1.2 can not be supported.
333 Non-default cipher suites including anonymous cipher suites (PRE
336 TLS-1.3) are supported for interop/testing purposes and may be
337 used by adding them to your cipher suite list. Note that they
338 must also be supported/enabled by the peer to actually be used.
339 signature_schemes() = [sign_scheme()]
341 In addition to the signature_algorithms extension from TLS 1.2,
343 TLS 1.3 (RFC 5246 Section 4.2.3)adds the signature_algo‐
344 rithms_cert extension which enables having special requirements
345 on the signatures used in the certificates that differs from the
346 requirements on digital signatures as a whole. If this is not
347 required this extension is not needed.
348 The client will send a signature_algorithms_cert extension
350 (ClientHello), if TLS version 1.3 or later is used, and the sig‐
351 nature_algs_cert option is explicitly specified. By default,
352 only the signature_algs extension is sent.
353 The signature schemes shall be ordered according to the client's
355 preference (favorite choice first).
356 supported_groups() = [group()]
358 TLS 1.3 introduces the "supported_groups" extension that is used
360 for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
361 shake. Both client and server can specify a list of parameters
362 that they are willing to use.
363 If it is not specified it will use a default list ([x25519,
365 x448, secp256r1, secp384r1]) that is filtered based on the
366 installed crypto library version.
367 secure_renegotiation() = boolean()
369 Specifies if to reject renegotiation attempt that does not live
371 up to RFC 5746. By default secure_renegotiate is set to true,
372 that is, secure renegotiation is enforced. If set to false
373 secure renegotiation will still be used if possible, but it
374 falls back to insecure renegotiation if the peer does not sup‐
375 port RFC 5746.
376 allowed_cert_chain_length() = integer()
378 Maximum number of non-self-issued intermediate certificates that
380 can follow the peer certificate in a valid certification path.
381 So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
382 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
383 can be PEER, CA, CA, ROOT-CA, and so on. The default value is
384 10.
385 custom_verify() =
387 {Verifyfun :: function(), InitialUserState :: any()}
388 The verification fun is to be defined as follows:
390 fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() |
392 {revoked, atom()}} |
393 {extension, #'Extension'{}} | valid | valid_peer, InitialUserState :: term()) ->
394 {valid, UserState :: term()} |
395 {fail, Reason :: term()} | {unknown, UserState :: term()}.
396 The verification fun is called during the X509-path validation
399 when an error or an extension unknown to the SSL application is
400 encountered. It is also called when a certificate is considered
401 valid by the path validation to allow access to each certificate
402 in the path to the user application. It differentiates between
403 the peer certificate and the CA certificates by using valid_peer
404 or valid as second argument to the verification fun. See the
405 public_key User's Guide for definition of #'OTPCertificate'{}
406 and #'Extension'{}.
407 * If the verify callback fun returns {fail, Reason}, the veri‐
409 fication process is immediately stopped, an alert is sent to
410 the peer, and the TLS/DTLS handshake terminates.
411 * If the verify callback fun returns {valid, UserState}, the
413 verification process continues.
414 * If the verify callback fun always returns {valid, User‐
416 State}, the TLS/DTLS handshake does not terminate regarding
417 verification failures and the connection is established.
418 * If called with an extension unknown to the user application,
420 return value {unknown, UserState} is to be used.
421 Note that if the fun returns unknown for an extension marked
423 as critical, validation will fail.
424 Default option verify_fun in verify_peer mode:
426 {fun(_,{bad_cert, _} = Reason, _) ->
428 {fail, Reason};
429 (_,{extension, _}, UserState) ->
430 {unknown, UserState};
431 (_, valid, UserState) ->
432 {valid, UserState};
433 (_, valid_peer, UserState) ->
434 {valid, UserState}
435 end, []}
436 Default option verify_fun in mode verify_none:
439 {fun(_,{bad_cert, _}, UserState) ->
441 {valid, UserState};
442 (_,{extension, #'Extension'{critical = true}}, UserState) ->
443 {valid, UserState};
444 (_,{extension, _}, UserState) ->
445 {unknown, UserState};
446 (_, valid, UserState) ->
447 {valid, UserState};
448 (_, valid_peer, UserState) ->
449 {valid, UserState}
450 end, []}
451 The possible path validation errors are given on form {bad_cert,
454 Reason} where Reason is:
455 unknown_ca:
457 No trusted CA was found in the trusted store. The trusted CA
458 is normally a so called ROOT CA, which is a self-signed cer‐
459 tificate. Trust can be claimed for an intermediate CA
460 (trusted anchor does not have to be self-signed according to
461 X-509) by using option partial_chain.
462 selfsigned_peer:
464 The chain consisted only of one self-signed certificate.
465 PKIX X-509-path validation error:
467 For possible reasons, see public_key:pkix_path_validation/3
468 crl_check() = boolean() | peer | best_effort
470 Perform CRL (Certificate Revocation List) verification (pub‐
472 lic_key:pkix_crls_validate/3) on all the certificates during the
473 path validation (public_key:pkix_path_validation/3) of the cer‐
474 tificate chain. Defaults to false.
475 peer:
477 check is only performed on the peer certificate.
478 best_effort:
480 if certificate revocation status cannot be determined it
481 will be accepted as valid.
482 The CA certificates specified for the connection will be used to
484 construct the certificate chain validating the CRLs.
485 The CRLs will be fetched from a local or external cache. See
487 ssl_crl_cache_api(3).
488 crl_cache_opts() =
490 {Module :: atom(),
491 {DbHandle :: internal | term(), Args :: list()}}
492 Specify how to perform lookup and caching of certificate revoca‐
494 tion lists. Module defaults to ssl_crl_cache with DbHandle
495 being internal and an empty argument list.
496 There are two implementations available:
498 ssl_crl_cache:
500 This module maintains a cache of CRLs. CRLs can be added to
501 the cache using the function ssl_crl_cache:insert/1, and
502 optionally automatically fetched through HTTP if the follow‐
503 ing argument is specified:
504 {http, timeout()}:
506 Enables fetching of CRLs specified as http URIs inX509
507 certificate extensions. Requires the OTP inets applica‐
508 tion.
509 ssl_crl_hash_dir:
511 This module makes use of a directory where CRLs are stored
512 in files named by the hash of the issuer name.
513 The file names consist of eight hexadecimal digits followed
515 by .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the
516 first version of the CRL, N starts at zero, and for each new
517 version, N is incremented by one. The OpenSSL utility
518 c_rehash creates symlinks according to this pattern.
519 For a given hash value, this module finds all consecutive
521 .r* files starting from zero, and those files taken together
522 make up the revocation list. CRL files whose nextUpdate
523 fields are in the past, or that are issued by a different CA
524 that happens to have the same name hash, are excluded.
525 The following argument is required:
527 {dir, string()}:
529 Specifies the directory in which the CRLs can be found.
530 root_fun() = function()
532 fun(Chain::[public_key:der_encoded()]) ->
534 {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
535 Claim an intermediate CA in the chain as trusted. TLS then per‐
538 forms public_key:pkix_path_validation/3 with the selected CA as
539 trusted anchor and the rest of the chain.
540 protocol_versions() = [protocol_version()]
542 TLS protocol versions supported by started clients and servers.
544 This option overrides the application environment option proto‐
545 col_version and dtls_protocol_version. If the environment option
546 is not set, it defaults to all versions, supported by the SSL
547 application. See also ssl(6).
548 custom_user_lookup() =
550 {Lookupfun :: function(), UserState :: any()}
551 The lookup fun is to defined as follows:
553 fun(psk, PSKIdentity :: binary(), UserState :: term()) ->
555 {ok, SharedSecret :: binary()} | error;
556 fun(srp, Username :: binary(), UserState :: term()) ->
557 {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
558 DerivedKey :: binary()}} | error.
559 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
562 by the client and server to determine the shared secret. When
563 called by the client, PSKIdentity is set to the hint presented
564 by the server or to undefined. When called by the server, PSKI‐
565 dentity is the identity presented by the client.
566 For Secure Remote Password (SRP), the fun is only used by the
568 server to obtain parameters that it uses to generate its session
569 keys. DerivedKey is to be derived according to RFC 2945 and
570 RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
571 word])])
572 session_id() = binary()
574 Identifies a TLS session.
576 log_alert() = boolean()
578 If set to false, TLS/DTLS Alert reports are not displayed. Dep‐
580 recated in OTP 22, use {log_level, logging_level()} instead.
581 logging_level() = logger:level() | none | all
583 Specifies the log level for a TLS/DTLS connection. Alerts are
585 logged on notice level, which is the default level. The level
586 debug triggers verbose logging of TLS/DTLS protocol messages.
587 See also ssl(6)
588 hibernate_after() = timeout()
590 When an integer-value is specified, TLS/DTLS-connection goes
592 into hibernation after the specified number of milliseconds of
593 inactivity, thus reducing its memory footprint. When undefined
594 is specified (this is the default), the process never goes into
595 hibernation.
596 handshake_size() = integer()
598 Integer (24 bits unsigned). Used to limit the size of valid TLS
600 handshake packets to avoid DoS attacks. Defaults to 256*1024.
601 padding_check() = boolean()
603 Affects TLS-1.0 connections only. If set to false, it disables
605 the block cipher padding check to be able to interoperate with
606 legacy software.
607 Warning:
609 Using {padding_check, boolean()} makes TLS vulnerable to the
610 Poodle attack.
611 beast_mitigation() = one_n_minus_one | zero_n | disabled
614 Affects TLS-1.0 connections only. Used to change the BEAST miti‐
616 gation strategy to interoperate with legacy software. Defaults
617 to one_n_minus_one.
618 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
620 zero_n - Perform 0/n BEAST mitigation.
622 disabled - Disable BEAST mitigation.
624 Warning:
626 Using {beast_mitigation, disabled} makes TLS-1.0 vulnerable to
627 the BEAST attack.
628 ssl_imp() = new | old
631 Deprecated since OTP-17, has no affect.
633 session_tickets() =
635 client_session_tickets() | server_session_tickets()
636 Configures the session ticket functionalty in TLS 1.3 client and
638 server.
639 key_update_at() = integer() >= 1
641 Configures the maximum amount of bytes that can be sent on a TLS
643 1.3 connection before an automatic key update is performed.
644 There are cryptographic limits on the amount of plaintext which
646 can be safely encrypted under a given set of keys. The current
647 default ensures that data integrity will not be breached with
648 probability greater than 1/2^57. For more information see Limits
649 on Authenticated Encryption Use in TLS.
650 Warning:
652 The default value of this option shall provide the above men‐
653 tioned security guarantees and it shall be reasonable for most
654 applications (~353 TB).
655 middlebox_comp_mode() = boolean()
658 Configures the middlebox compatibility mode on a TLS 1.3 connec‐
660 tion.
661 A significant number of middleboxes misbehave when a TLS 1.3
663 connection is negotiated. Implementations can increase the
664 chance of making connections through those middleboxes by making
665 the TLS 1.3 handshake more like a TLS 1.2 handshake.
666 The middlebox compatibility mode is enabled (true) by default.
668 keep_secrets() = boolean()
670 Configures a TLS 1.3 connection for keylogging
672 In order to retrieve keylog information on a TLS 1.3 connection,
674 it must be configured in advance to keep the client_random and
675 various handshake secrets.
676 The keep_secrets functionality is disabled (false) by default.
678 Added in OTP 23.2
680 TLS/DTLS OPTION DESCRIPTIONS - CLIENT
682 client_option() =
683 {verify, client_verify_type()} |
684 {reuse_session, client_reuse_session()} |
685 {reuse_sessions, client_reuse_sessions()} |
686 {cacerts, client_cacerts()} |
687 {cacertfile, client_cafile()} |
688 {alpn_advertised_protocols, client_alpn()} |
689 {client_preferred_next_protocols,
690 client_preferred_next_protocols()} |
691 {psk_identity, client_psk_identity()} |
692 {srp_identity, client_srp_identity()} |
693 {server_name_indication, sni()} |
694 {max_fragment_length, max_fragment_length()} |
695 {customize_hostname_check, customize_hostname_check()} |
696 {signature_algs, client_signature_algs()} |
697 {fallback, fallback()} |
698 {session_tickets, client_session_tickets()} |
699 {use_ticket, use_ticket()} |
700 {early_data, client_early_data()}
701 client_verify_type() = verify_type()
703 In mode verify_none the default behavior is to allow all
705 x509-path validation errors. See also option verify_fun.
706 client_reuse_session() =
708 session_id() | {session_id(), SessionData :: binary()}
709 Reuses a specific session. The session should be refered by its
711 session id if it is earlier saved with the option {reuse_ses‐
712 sions, save} since OTP-21.3 or explicitly specified by its ses‐
713 sion id and associated data since OTP-22.3. See also SSL's
714 Users Guide, Session Reuse pre TLS 1.3
715 client_reuse_sessions() = boolean() | save
717 When save is specified a new connection will be negotiated and
719 saved for later reuse. The session ID can be fetched with con‐
720 nection_information/2 and used with the client option reuse_ses‐
721 sion The boolean value true specifies that if possible, automa‐
722 tized session reuse will be performed. If a new session is cre‐
723 ated, and is unique in regard to previous stored sessions, it
724 will be saved for possible later reuse. Since OTP-21.3
725 client_cacerts() = [public_key:der_encoded()]
727 The DER-encoded trusted certificates. If this option is supplied
729 it overrides option cacertfile.
730 client_cafile() = file:filename()
732 Path to a file containing PEM-encoded CA certificates. The CA
734 certificates are used during server authentication and when
735 building the client certificate chain.
736 client_alpn() = [app_level_protocol()]
738 The list of protocols supported by the client to be sent to the
740 server to be used for an Application-Layer Protocol Negotiation
741 (ALPN). If the server supports ALPN then it will choose a proto‐
742 col from this list; otherwise it will fail the connection with a
743 "no_application_protocol" alert. A server that does not support
744 ALPN will ignore this value.
745 The list of protocols must not contain an empty binary.
747 The negotiated protocol can be retrieved using the negoti‐
749 ated_protocol/1 function.
750 client_preferred_next_protocols() =
752 {Precedence :: server | client,
753 ClientPrefs :: [app_level_protocol()]} |
754 {Precedence :: server | client,
755 ClientPrefs :: [app_level_protocol()],
756 Default :: app_level_protocol()}
757 Indicates that the client is to try to perform Next Protocol
759 Negotiation.
760 If precedence is server, the negotiated protocol is the first
762 protocol to be shown on the server advertised list, which is
763 also on the client preference list.
764 If precedence is client, the negotiated protocol is the first
766 protocol to be shown on the client preference list, which is
767 also on the server advertised list.
768 If the client does not support any of the server advertised pro‐
770 tocols or the server does not advertise any protocols, the
771 client falls back to the first protocol in its list or to the
772 default protocol (if a default is supplied). If the server does
773 not support Next Protocol Negotiation, the connection terminates
774 if no default protocol is supplied.
775 max_fragment_length() = undefined | 512 | 1024 | 2048 | 4096
777 Specifies the maximum fragment length the client is prepared to
779 accept from the server. See RFC 6066
780 client_psk_identity() = psk_identity()
782 Specifies the identity the client presents to the server. The
784 matching secret is found by calling user_lookup_fun
785 client_srp_identity() = srp_identity()
787 Specifies the username and password to use to authenticate to
789 the server.
790 sni() = hostname() | disable
792 Specify the hostname to be used in TLS Server Name Indication
794 extension. If not specified it will default to the Host argument
795 of connect/[3,4] unless it is of type inet:ipaddress().
796 The HostName will also be used in the hostname verification of
798 the peer certificate using public_key:pkix_verify_hostname/2.
799 The special value disable prevents the Server Name Indication
801 extension from being sent and disables the hostname verification
802 check public_key:pkix_verify_hostname/2
803 customize_hostname_check() = list()
805 Customizes the hostname verification of the peer certificate, as
807 different protocols that use TLS such as HTTP or LDAP may want
808 to do it differently, for possible options see pub‐
809 lic_key:pkix_verify_hostname/3
810 fallback() = boolean()
812 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired
814 TLS version downgrade. Defaults to false
815 Warning:
817 Note this option is not needed in normal TLS usage and should
818 not be used to implement new clients. But legacy clients that
819 retries connections in the following manner
820 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1',
822 'tlsv1']}])
823 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1']},
825 {fallback, true}])
826 ssl:connect(Host, Port, [...{versions, ['tlsv1']}, {fallback,
828 true}])
829 may use it to avoid undesired TLS version downgrade. Note that
831 TLS_FALLBACK_SCSV must also be supported by the server for the
832 prevention to work.
833 client_signature_algs() = signature_algs()
836 In addition to the algorithms negotiated by the cipher suite
838 used for key exchange, payload encryption, message authentica‐
839 tion and pseudo random calculation, the TLS signature algorithm
840 extension Section 7.4.1.4.1 in RFC 5246 may be used, from TLS
841 1.2, to negotiate which signature algorithm to use during the
842 TLS handshake. If no lower TLS versions than 1.2 are supported,
843 the client will send a TLS signature algorithm extension with
844 the algorithms specified by this option. Defaults to
845 [
847 %% SHA2
848 {sha512, ecdsa},
849 {sha512, rsa},
850 {sha384, ecdsa},
851 {sha384, rsa},
852 {sha256, ecdsa},
853 {sha256, rsa},
854 {sha224, ecdsa},
855 {sha224, rsa},
856 %% SHA
857 {sha, ecdsa},
858 {sha, rsa},
859 {sha, dsa},
860 ]
861 The algorithms should be in the preferred order. Selected signa‐
863 ture algorithm can restrict which hash functions that may be
864 selected. Default support for {md5, rsa} removed in ssl-8.0
865 client_session_tickets() = disabled | manual | auto
867 Configures the session ticket functionality. Allowed values are
869 disabled, manual and auto. If it is set to manual the client
870 will send the ticket information to user process in a 3-tuple:
871 {ssl, session_ticket, {SNI, TicketData}}
873 where SNI is the ServerNameIndication and TicketData is the
875 extended ticket data that can be used in subsequent session
876 resumptions.
877 If it is set to auto, the client automatically handles received
879 tickets and tries to use them when making new TLS connections
880 (session resumption with pre-shared keys).
881 Note:
883 This option is supported by TLS 1.3 and above. See also SSL's
884 Users Guide, Session Tickets and Session Resumption in TLS 1.3
885 use_ticket() = [binary()]
888 Configures the session tickets to be used for session resump‐
890 tion. It is a mandatory option in manual mode (session_tickets =
891 manual).
892 Note:
894 Session tickets are only sent to user if option session_tickets
895 is set to manual
896 This option is supported by TLS 1.3 and above. See also SSL's
898 Users Guide, Session Tickets and Session Resumption in TLS 1.3
899 client_early_data() = binary()
902 Configures the early data to be sent by the client.
904 In order to be able to verify that the server has the intention
906 to process the early data, the following 3-tuple is sent to the
907 user process:
908 {ssl, SslSocket, {early_data, Result}}
910 where Result is either accepted or rejected.
912 Warning:
914 It is the responsibility of the user to handle a rejected Early
915 Data and to resend when it is appropriate.
916 TLS/DTLS OPTION DESCRIPTIONS - SERVER
919 server_option() =
920 {cacerts, server_cacerts()} |
921 {cacertfile, server_cafile()} |
922 {dh, dh_der()} |
923 {dhfile, dh_file()} |
924 {verify, server_verify_type()} |
925 {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
926 {reuse_sessions, server_reuse_sessions()} |
927 {reuse_session, server_reuse_session()} |
928 {alpn_preferred_protocols, server_alpn()} |
929 {next_protocols_advertised, server_next_protocol()} |
930 {psk_identity, server_psk_identity()} |
931 {honor_cipher_order, boolean()} |
932 {sni_hosts, sni_hosts()} |
933 {sni_fun, sni_fun()} |
934 {honor_cipher_order, honor_cipher_order()} |
935 {honor_ecc_order, honor_ecc_order()} |
936 {client_renegotiation, client_renegotiation()} |
937 {signature_algs, server_signature_algs()} |
938 {session_tickets, server_session_tickets()} |
939 {anti_replay, anti_replay()} |
940 {cookie, cookie()} |
941 {early_data, server_early_data()}
942 server_cacerts() = [public_key:der_encoded()]
944 The DER-encoded trusted certificates. If this option is supplied
946 it overrides option cacertfile.
947 server_cafile() = file:filename()
949 Path to a file containing PEM-encoded CA certificates. The CA
951 certificates are used to build the server certificate chain and
952 for client authentication. The CAs are also used in the list of
953 acceptable client CAs passed to the client when a certificate is
954 requested. Can be omitted if there is no need to verify the
955 client and if there are no intermediate CAs for the server cer‐
956 tificate.
957 dh_der() = binary()
959 The DER-encoded Diffie-Hellman parameters. If specified, it
961 overrides option dhfile.
962 Warning:
964 The dh_der option is not supported by TLS 1.3. Use the sup‐
965 ported_groups option instead.
966 dh_file() = file:filename()
969 Path to a file containing PEM-encoded Diffie Hellman parameters
971 to be used by the server if a cipher suite using Diffie Hellman
972 key exchange is negotiated. If not specified, default parameters
973 are used.
974 Warning:
976 The dh_file option is not supported by TLS 1.3. Use the sup‐
977 ported_groups option instead.
978 server_verify_type() = verify_type()
981 A server only does x509-path validation in mode verify_peer, as
983 it then sends a certificate request to the client (this message
984 is not sent if the verify option is verify_none). You can then
985 also want to specify option fail_if_no_peer_cert.
986 fail_if_no_peer_cert() = boolean()
988 Used together with {verify, verify_peer} by an TLS/DTLS server.
990 If set to true, the server fails if the client does not have a
991 certificate to send, that is, sends an empty certificate. If set
992 to false, it fails only if the client sends an invalid certifi‐
993 cate (an empty certificate is considered valid). Defaults to
994 false.
995 server_reuse_sessions() = boolean()
997 The boolean value true specifies that the server will agree to
999 reuse sessions. Setting it to false will result in an empty ses‐
1000 sion table, that is no sessions will be reused. See also option
1001 reuse_session
1002 server_reuse_session() = function()
1004 Enables the TLS/DTLS server to have a local policy for deciding
1006 if a session is to be reused or not. Meaningful only if re‐
1007 use_sessions is set to true. SuggestedSessionId is a binary(),
1008 PeerCert is a DER-encoded certificate, Compression is an enumer‐
1009 ation integer, and CipherSuite is of type ciphersuite().
1010 server_alpn() = [app_level_protocol()]
1012 Indicates the server will try to perform Application-Layer Pro‐
1014 tocol Negotiation (ALPN).
1015 The list of protocols is in order of preference. The protocol
1017 negotiated will be the first in the list that matches one of the
1018 protocols advertised by the client. If no protocol matches, the
1019 server will fail the connection with a "no_application_protocol"
1020 alert.
1021 The negotiated protocol can be retrieved using the negoti‐
1023 ated_protocol/1 function.
1024 server_next_protocol() = [app_level_protocol()]
1026 List of protocols to send to the client if the client indicates
1028 that it supports the Next Protocol extension. The client can
1029 select a protocol that is not on this list. The list of proto‐
1030 cols must not contain an empty binary. If the server negotiates
1031 a Next Protocol, it can be accessed using the negoti‐
1032 ated_next_protocol/1 method.
1033 server_psk_identity() = psk_identity()
1035 Specifies the server identity hint, which the server presents to
1037 the client.
1038 honor_cipher_order() = boolean()
1040 If set to true, use the server preference for cipher selection.
1042 If set to false (the default), use the client preference.
1043 sni_hosts() =
1045 [{hostname(), [server_option() | common_option()]}]
1046 If the server receives a SNI (Server Name Indication) from the
1048 client matching a host listed in the sni_hosts option, the spe‐
1049 cific options for that host will override previously specified
1050 options. The option sni_fun, and sni_hosts are mutually exclu‐
1051 sive.
1052 sni_fun() = function()
1054 If the server receives a SNI (Server Name Indication) from the
1056 client, the given function will be called to retrieve
1057 [server_option()] for the indicated server. These options will
1058 be merged into predefined [server_option()] list. The function
1059 should be defined as: fun(ServerName :: string()) ->
1060 [server_option()] and can be specified as a fun or as named fun
1061 module:function/1 The option sni_fun, and sni_hosts are mutually
1062 exclusive.
1063 client_renegotiation() = boolean()
1065 In protocols that support client-initiated renegotiation, the
1067 cost of resources of such an operation is higher for the server
1068 than the client. This can act as a vector for denial of service
1069 attacks. The SSL application already takes measures to counter-
1070 act such attempts, but client-initiated renegotiation can be
1071 strictly disabled by setting this option to false. The default
1072 value is true. Note that disabling renegotiation can result in
1073 long-lived connections becoming unusable due to limits on the
1074 number of messages the underlying cipher suite can encipher.
1075 honor_cipher_order() = boolean()
1077 If true, use the server's preference for cipher selection. If
1079 false (the default), use the client's preference.
1080 honor_ecc_order() = boolean()
1082 If true, use the server's preference for ECC curve selection. If
1084 false (the default), use the client's preference.
1085 server_signature_algs() = signature_algs()
1087 The algorithms specified by this option will be the ones
1089 accepted by the server in a signature algorithm negotiation,
1090 introduced in TLS-1.2. The algorithms will also be offered to
1091 the client if a client certificate is requested. For more
1092 details see the corresponding client option.
1093 server_session_tickets() = disabled | stateful | stateless
1095 Configures the session ticket functionality. Allowed values are
1097 disabled, stateful and stateless.
1098 If it is set to stateful or stateless, session resumption with
1100 pre-shared keys is enabled and the server will send stateful or
1101 stateless session tickets to the client after successful connec‐
1102 tions.
1103 A stateful session ticket is a database reference to internal
1105 state information. A stateless session ticket is a self-
1106 encrypted binary that contains both cryptographic keying mate‐
1107 rial and state data.
1108 Note:
1110 This option is supported by TLS 1.3 and above. See also SSL's
1111 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1112 anti_replay() =
1115 '10k' | '100k' |
1116 {bloom_filter_window_size(),
1117 bloom_filter_hash_functions(),
1118 bloom_filter_bits()}
1119 Configures the server's built-in anti replay feature based on
1121 Bloom filters.
1122 Allowed values are the pre-defined '10k', '100k' or a custom
1124 3-tuple that defines the properties of the bloom filters: {Win‐
1125 dowSize, HashFunctions, Bits}. WindowSize is the number of sec‐
1126 onds after the current Bloom filter is rotated and also the win‐
1127 dow size used for freshness checks. HashFunctions is the number
1128 hash functions and Bits is the number of bits in the bit vector.
1129 '10k' and '100k' are simple defaults with the following proper‐
1130 ties:
1131 * '10k': Bloom filters can hold 10000 elements with 3% proba‐
1133 bility of false positives. WindowSize: 10, HashFunctions: 5,
1134 Bits: 72985 (8.91 KiB).
1135 * '100k': Bloom filters can hold 100000 elements with 3% prob‐
1137 ability of false positives. WindowSize: 10, HashFunctions:
1138 5, Bits: 729845 (89.09 KiB).
1139 Note:
1141 This option is supported by TLS 1.3 and above and only with
1142 stateless session tickets. Ticket lifetime, the number of tick‐
1143 ets sent by the server and the maximum number of tickets stored
1144 by the server in stateful mode are configured by application
1145 variables. See also SSL's Users Guide, Anti-Replay Protection
1146 in TLS 1.3
1147 cookie() = boolean()
1150 If true (default), the server sends a cookie extension in its
1152 HelloRetryRequest messages.
1153 Note:
1155 The cookie extension has two main purposes. It allows the server
1156 to force the client to demonstrate reachability at their appar‐
1157 ent network address (thus providing a measure of DoS protec‐
1158 tion). This is primarily useful for non-connection-oriented
1159 transports. It also allows to offload the server's state to the
1160 client. The cookie extension is enabled by default as it is a
1161 mandatory extension in RFC8446.
1162 server_early_data() = disabled | enabled
1165 Configures if the server accepts (enabled) or rejects (rejects)
1167 early data sent by a client. The default value is disabled.
1168 Warning:
1170 This option is a placeholder, early data is not yet implemented
1171 on the server side.
1172 connection_info() =
1175 [common_info() |
1176 curve_info() |
1177 ssl_options_info() |
1178 security_info()]
1179 common_info() =
1181 {protocol, protocol_version()} |
1182 {session_id, session_id()} |
1183 {session_resumption, boolean()} |
1184 {selected_cipher_suite, erl_cipher_suite()} |
1185 {sni_hostname, term()} |
1186 {srp_username, term()}
1187 curve_info() = {ecc, {named_curve, term()}}
1189 ssl_options_info() = tls_option()
1191 security_info() =
1193 {client_random, binary()} |
1194 {server_random, binary()} |
1195 {master_secret, binary()}
1196 connection_info_items() = [connection_info_item()]
1198 connection_info_item() =
1200 protocol | session_id | session_resumption |
1201 selected_cipher_suite | sni_hostname | srp_username | ecc |
1202 client_random | server_random | master_secret | keylog |
1203 tls_options_name()
1204 tls_options_name() = atom()
1206
1208 append_cipher_suites(Deferred, Suites) -> ciphers()
1209 Types:
1211 Deferred = ciphers() | cipher_filters()
1213 Suites = ciphers()
1214 Make Deferred suites become the least preferred suites, that is
1216 put them at the end of the cipher suite list Suites after remov‐
1217 ing them from Suites if present. Deferred may be a list of
1218 cipher suites or a list of filters in which case the filters are
1219 use on Suites to extract the Deferred cipher list.
1220 cipher_suites() -> [old_cipher_suite()] | [string()]
1222 cipher_suites(Type) -> [old_cipher_suite() | string()]
1224 Types:
1226 Type = erlang | openssl | all
1228 Deprecated in OTP 21, use cipher_suites/2 instead.
1230 cipher_suites(Description, Version) -> ciphers()
1232 Types:
1234 Description = default | all | exclusive | anonymous
1236 Version = protocol_version()
1237 Lists all possible cipher suites corresponding to Description
1239 that are available. The exclusive option will exclusively list
1240 cipher suites introduced in Version whereas the other options
1241 are inclusive from the lowest possible version to Version. The
1242 all options includes all suites except the anonymous.
1243 Note:
1245 TLS-1.3 has no overlapping cipher suites with previous TLS ver‐
1246 sions, that is the result of cipher_suites(all, 'tlsv1.3'). con‐
1247 tains a separate set of suites that can be used with TLS-1.3 an
1248 other set that can be used if a lower version is negotiated. No
1249 anonymous suites are supported by TLS-1.3.
1250 Also note that the cipher suites returned by this function are
1252 the cipher suites that the OTP ssl application can support pro‐
1253 vided that they are supported by the cryptolib linked with the
1254 OTP crypto application. Use ssl:filter_cipher_suites(Suites,
1255 []). to filter the list for the current cryptolib. Note that
1256 cipher suites may be filtered out because they are too old or
1257 too new depending on the cryptolib
1258 cipher_suites(Description, Version, StringType :: rfc | openssl) ->
1261 [string()]
1262 Types:
1264 Description = default | all | exclusive | anonymous
1266 Version = protocol_version()
1267 Same as cipher_suites/2 but lists RFC or OpenSSL string names
1269 instead of erl_cipher_suite()
1270 eccs() -> NamedCurves
1272 eccs(Version) -> NamedCurves
1274 Types:
1276 Version = protocol_version()
1278 NamedCurves = [named_curve()]
1279 Returns a list of supported ECCs. eccs() is equivalent to call‐
1281 ing eccs(Protocol) with all supported protocols and then dedu‐
1282 plicating the output.
1283 clear_pem_cache() -> ok
1285 PEM files, used by ssl API-functions, are cached. The cache is
1287 regularly checked to see if any cache entries should be invali‐
1288 dated, however this function provides a way to unconditionally
1289 clear the whole cache.
1290 connect(TCPSocket, TLSOptions) ->
1292 {ok, sslsocket()} |
1293 {error, reason()} |
1294 {option_not_a_key_value_tuple, any()}
1295 connect(TCPSocket, TLSOptions, Timeout) ->
1297 {ok, sslsocket()} | {error, reason()}
1298 Types:
1300 TCPSocket = socket()
1302 TLSOptions = [tls_client_option()]
1303 Timeout = timeout()
1304 Upgrades a gen_tcp, or equivalent, connected socket to a TLS
1306 socket, that is, performs the client-side TLS handshake.
1307 Note:
1309 If the option verify is set to verify_peer the option
1310 server_name_indication shall also be specified, if it is not no
1311 Server Name Indication extension will be sent, and pub‐
1312 lic_key:pkix_verify_hostname/2 will be called with the IP-
1313 address of the connection as ReferenceID, which is probably not
1314 what you want.
1315 If the option {handshake, hello} is used the handshake is paused
1318 after receiving the server hello message and the success
1319 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1320 Thereafter the handshake is continued or canceled by calling
1321 handshake_continue/3 or handshake_cancel/1.
1322 If the option active is set to once, true or an integer value,
1324 the process owning the sslsocket will receive messages of type
1325 active_msgs()
1326 connect(Host, Port, TLSOptions) ->
1328 {ok, sslsocket()} |
1329 {ok, sslsocket(), Ext :: protocol_extensions()} |
1330 {error, reason()} |
1331 {option_not_a_key_value_tuple, any()}
1332 connect(Host, Port, TLSOptions, Timeout) ->
1334 {ok, sslsocket()} |
1335 {ok, sslsocket(), Ext :: protocol_extensions()} |
1336 {error, reason()} |
1337 {option_not_a_key_value_tuple, any()}
1338 Types:
1340 Host = host()
1342 Port = inet:port_number()
1343 TLSOptions = [tls_client_option()]
1344 Timeout = timeout()
1345 Opens a TLS/DTLS connection to Host, Port.
1347 When the option verify is set to verify_peer the check pub‐
1349 lic_key:pkix_verify_hostname/2 will be performed in addition to
1350 the usual x509-path validation checks. If the check fails the
1351 error {bad_cert, hostname_check_failed} will be propagated to
1352 the path validation fun verify_fun, where it is possible to do
1353 customized checks by using the full possibilities of the pub‐
1354 lic_key:pkix_verify_hostname/3 API. When the option
1355 server_name_indication is provided, its value (the DNS name)
1356 will be used as ReferenceID to public_key:pkix_verify_host‐
1357 name/2. When no server_name_indication option is given, the Host
1358 argument will be used as Server Name Indication extension. The
1359 Host argument will also be used for the public_key:pkix_ver‐
1360 ify_hostname/2 check and if the Host argument is an
1361 inet:ip_address() the ReferenceID used for the check will be
1362 {ip, Host} otherwise dns_id will be assumed with a fallback to
1363 ip if that fails.
1364 Note:
1366 According to good practices certificates should not use IP-
1367 addresses as "server names". It would be very surprising if this
1368 happen outside a closed network.
1369 If the option {handshake, hello} is used the handshake is paused
1372 after receiving the server hello message and the success
1373 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1374 Thereafter the handshake is continued or canceled by calling
1375 handshake_continue/3 or handshake_cancel/1.
1376 If the option active is set to once, true or an integer value,
1378 the process owning the sslsocket will receive messages of type
1379 active_msgs()
1380 close(SslSocket) -> ok | {error, Reason}
1382 Types:
1384 SslSocket = sslsocket()
1386 Reason = any()
1387 Closes a TLS/DTLS connection.
1389 close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}
1391 Types:
1393 SslSocket = sslsocket()
1395 How = timeout() | {NewController :: pid(), timeout()}
1396 Reason = any()
1397 Closes or downgrades a TLS connection. In the latter case the
1399 transport connection will be handed over to the NewController
1400 process after receiving the TLS close alert from the peer. The
1401 returned transport socket will have the following options set:
1402 [{active, false}, {packet, 0}, {mode, binary}]
1403 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1405 Types:
1407 SslSocket = sslsocket()
1409 NewOwner = pid()
1410 Reason = any()
1411 Assigns a new controlling process to the SSL socket. A control‐
1413 ling process is the owner of an SSL socket, and receives all
1414 messages from the socket.
1415 connection_information(SslSocket) ->
1417 {ok, Result} | {error, reason()}
1418 Types:
1420 SslSocket = sslsocket()
1422 Result = connection_info()
1423 Returns the most relevant information about the connection, ssl
1425 options that are undefined will be filtered out. Note that val‐
1426 ues that affect the security of the connection will only be
1427 returned if explicitly requested by connection_information/2.
1428 Note:
1430 The legacy Item = cipher_suite was removed in OTP-23. Previously
1431 it returned the cipher suite on its (undocumented) legacy for‐
1432 mat. It is replaced by selected_cipher_suite.
1433 connection_information(SslSocket, Items) ->
1436 {ok, Result} | {error, reason()}
1437 Types:
1439 SslSocket = sslsocket()
1441 Items = connection_info_items()
1442 Result = connection_info()
1443 Returns the requested information items about the connection, if
1445 they are defined.
1446 Note that client_random, server_random, master_secret and keylog
1448 are values that affect the security of connection. Meaningful
1449 atoms, not specified above, are the ssl option names.
1450 Note:
1452 If only undefined options are requested the resulting list can
1453 be empty.
1454 filter_cipher_suites(Suites, Filters) -> Ciphers
1457 Types:
1459 Suites = ciphers()
1461 Filters = cipher_filters()
1462 Ciphers = ciphers()
1463 Removes cipher suites if any of the filter functions returns
1465 false for any part of the cipher suite. If no filter function is
1466 supplied for some part the default behaviour regards it as if
1467 there was a filter function that returned true. For examples see
1468 Customizing cipher suites Additionaly this function also fil‐
1469 ters the cipher suites to exclude cipher suites not supported by
1470 the cryptolib used by the OTP crypto application. That is call‐
1471 ing ssl:filter_cipher_suites(Suites, []) will be equivalent to
1472 only applying the filters for cryptolib support.
1473 format_error(Reason :: {error, Reason}) -> string()
1475 Types:
1477 Reason = any()
1479 Presents the error returned by an SSL function as a printable
1481 string.
1482 getopts(SslSocket, OptionNames) ->
1484 {ok, [gen_tcp:option()]} | {error, reason()}
1485 Types:
1487 SslSocket = sslsocket()
1489 OptionNames = [gen_tcp:option_name()]
1490 Gets the values of the specified socket options.
1492 getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1494 getstat(SslSocket, Options) ->
1496 {ok, OptionValues} | {error, inet:posix()}
1497 Types:
1499 SslSocket = sslsocket()
1501 Options = [inet:stat_option()]
1502 OptionValues = [{inet:stat_option(), integer()}]
1503 Gets one or more statistic options for the underlying TCP
1505 socket.
1506 See inet:getstat/2 for statistic options description.
1508 handshake(HsSocket) ->
1510 {ok, SslSocket} |
1511 {ok, SslSocket, Ext} |
1512 {error, Reason}
1513 handshake(HsSocket, Timeout) ->
1515 {ok, SslSocket} |
1516 {ok, SslSocket, Ext} |
1517 {error, Reason}
1518 Types:
1520 HsSocket = sslsocket()
1522 Timeout = timeout()
1523 SslSocket = sslsocket()
1524 Ext = protocol_extensions()
1525 Reason = closed | timeout | error_alert()
1526 Performs the TLS/DTLS server-side handshake.
1528 Returns a new TLS/DTLS socket if the handshake is successful.
1530 If the option active is set to once, true or an integer value,
1532 the process owning the sslsocket will receive messages of type
1533 active_msgs()
1534 handshake(Socket, Options) ->
1536 {ok, SslSocket} |
1537 {ok, SslSocket, Ext} |
1538 {error, Reason}
1539 handshake(Socket, Options, Timeout) ->
1541 {ok, SslSocket} |
1542 {ok, SslSocket, Ext} |
1543 {error, Reason}
1544 Types:
1546 Socket = socket() | sslsocket()
1548 SslSocket = sslsocket()
1549 Options = [server_option()]
1550 Timeout = timeout()
1551 Ext = protocol_extensions()
1552 Reason = closed | timeout | {options, any()} | error_alert()
1553 If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1555 lent, socket to an SSL socket, that is, performs the TLS server-
1556 side handshake and returns a TLS socket.
1557 Warning:
1559 The Socket shall be in passive mode ({active, false}) before
1560 calling this function or else the behavior of this function is
1561 undefined.
1562 If Socket is an sslsocket() : provides extra TLS/DTLS options
1565 to those specified in listen/2 and then performs the TLS/DTLS
1566 handshake. Returns a new TLS/DTLS socket if the handshake is
1567 successful.
1568 If option {handshake, hello} is specified the handshake is
1570 paused after receiving the client hello message and the success
1571 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1572 Thereafter the handshake is continued or canceled by calling
1573 handshake_continue/3 or handshake_cancel/1.
1574 If the option active is set to once, true or an integer value,
1576 the process owning the sslsocket will receive messages of type
1577 active_msgs()
1578 handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1580 Cancel the handshake with a fatal USER_CANCELED alert.
1582 handshake_continue(HsSocket, Options) ->
1584 {ok, SslSocket} | {error, Reason}
1585 handshake_continue(HsSocket, Options, Timeout) ->
1587 {ok, SslSocket} | {error, Reason}
1588 Types:
1590 HsSocket = sslsocket()
1592 Options = [tls_client_option() | tls_server_option()]
1593 Timeout = timeout()
1594 SslSocket = sslsocket()
1595 Reason = closed | timeout | error_alert()
1596 Continue the TLS handshake possiby with new, additional or
1598 changed options.
1599 listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1601 Types:
1603 Port = inet:port_number()
1605 Options = [tls_server_option()]
1606 ListenSocket = sslsocket()
1607 Creates an SSL listen socket.
1609 negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1611 Types:
1613 SslSocket = sslsocket()
1615 Protocol = binary()
1616 Reason = protocol_not_negotiated
1617 Returns the protocol negotiated through ALPN or NPN extensions.
1619 peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1621 Types:
1623 SslSocket = sslsocket()
1625 Cert = binary()
1626 The peer certificate is returned as a DER-encoded binary. The
1628 certificate can be decoded with public_key:pkix_decode_cert/2
1629 peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1631 Types:
1633 SslSocket = sslsocket()
1635 Address = inet:ip_address()
1636 Port = inet:port_number()
1637 Returns the address and port number of the peer.
1639 prepend_cipher_suites(Preferred, Suites) -> ciphers()
1641 Types:
1643 Preferred = ciphers() | cipher_filters()
1645 Suites = ciphers()
1646 Make Preferred suites become the most preferred suites that is
1648 put them at the head of the cipher suite list Suites after
1649 removing them from Suites if present. Preferred may be a list of
1650 cipher suites or a list of filters in which case the filters are
1651 use on Suites to extract the preferred cipher list.
1652 prf(SslSocket, Secret, Label, Seed, WantedLength) ->
1654 {ok, binary()} | {error, reason()}
1655 Types:
1657 SslSocket = sslsocket()
1659 Secret = binary() | master_secret
1660 Label = binary()
1661 Seed = [binary() | prf_random()]
1662 WantedLength = integer() >= 0
1663 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1665 ate extra key material. It either takes user-generated values
1666 for Secret and Seed or atoms directing it to use a specific
1667 value from the session security parameters.
1668 recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
1670 recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
1672 Types:
1674 SslSocket = sslsocket()
1676 Length = integer()
1677 Data = binary() | list() | HttpPacket
1678 Timeout = timeout()
1679 HttpPacket = any()
1680 See the description of HttpPacket in erlang:decode_packet/3
1681 in ERTS.
1682 Receives a packet from a socket in passive mode. A closed socket
1684 is indicated by return value {error, closed}.
1685 Argument Length is meaningful only when the socket is in mode
1687 raw and denotes the number of bytes to read. If Length = 0, all
1688 available bytes are returned. If Length > 0, exactly Length
1689 bytes are returned, or an error; possibly discarding less than
1690 Length bytes of data when the socket gets closed from the other
1691 side.
1692 Optional argument Timeout specifies a time-out in milliseconds.
1694 The default value is infinity.
1695 renegotiate(SslSocket) -> ok | {error, reason()}
1697 Types:
1699 SslSocket = sslsocket()
1701 Initiates a new handshake. A notable return value is {error,
1703 renegotiation_rejected} indicating that the peer refused to go
1704 through with the renegotiation, but the connection is still
1705 active using the previously negotiated session.
1706 update_keys(SslSocket, Type) -> ok | {error, reason()}
1708 Types:
1710 SslSocket = sslsocket()
1712 Type = write | read_write
1713 There are cryptographic limits on the amount of plaintext which
1715 can be safely encrypted under a given set of keys. If the amount
1716 of data surpasses those limits, a key update is triggered and a
1717 new set of keys are installed. See also the option
1718 key_update_at.
1719 This function can be used to explicitly start a key update on a
1721 TLS 1.3 connection. There are two types of the key update: if
1722 Type is set to write, only the writing key is updated; if Type
1723 is set to read_write, both the reading and writing keys are
1724 updated.
1725 send(SslSocket, Data) -> ok | {error, reason()}
1727 Types:
1729 SslSocket = sslsocket()
1731 Data = iodata()
1732 Writes Data to SslSocket.
1734 A notable return value is {error, closed} indicating that the
1736 socket is closed.
1737 setopts(SslSocket, Options) -> ok | {error, reason()}
1739 Types:
1741 SslSocket = sslsocket()
1743 Options = [gen_tcp:option()]
1744 Sets options according to Options for socket SslSocket.
1746 shutdown(SslSocket, How) -> ok | {error, reason()}
1748 Types:
1750 SslSocket = sslsocket()
1752 How = read | write | read_write
1753 Immediately closes a socket in one or two directions.
1755 How == write means closing the socket for writing, reading from
1757 it is still possible.
1758 To be able to handle that the peer has done a shutdown on the
1760 write side, option {exit_on_close, false} is useful.
1761 ssl_accept(SslSocket) -> ok | {error, Reason}
1763 ssl_accept(Socket, TimeoutOrOptions) ->
1765 ok | {ok, sslsocket()} | {error, Reason}
1766 Types:
1768 Socket = sslsocket() | socket()
1770 TimeoutOrOptions = timeout() | [tls_server_option()]
1771 Reason = timeout | closed | {options, any()} | error_alert()
1772 Deprecated in OTP 21, use handshake/[1,2] instead.
1774 Note:
1776 handshake/[1,2] always returns a new socket.
1777 ssl_accept(Socket, Options, Timeout) ->
1780 ok | {ok, sslsocket()} | {error, Reason}
1781 Types:
1783 Socket = sslsocket() | socket()
1785 Options = [tls_server_option()]
1786 Timeout = timeout()
1787 Reason = timeout | closed | {options, any()} | error_alert()
1788 Deprecated in OTP 21, use handshake/[2,3] instead.
1790 Note:
1792 handshake/[2,3] always returns a new socket.
1793 sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1796 Types:
1798 SslSocket = sslsocket()
1800 Address = inet:ip_address()
1801 Port = inet:port_number()
1802 Returns the local address and port number of socket SslSocket.
1804 start() -> ok | {error, reason()}
1806 start(Type :: permanent | transient | temporary) ->
1808 ok | {error, reason()}
1809 Starts the SSL application. Default type is temporary.
1811 stop() -> ok
1813 Stops the SSL application.
1815 str_to_suite(CipherSuiteName) -> erl_cipher_suite()
1817 Types:
1819 CipherSuiteName =
1821 string() |
1822 {error, {not_recognized, CipherSuiteName :: string()}}
1823 Converts an RFC or OpenSSL name string to an erl_cipher_suite()
1825 Returns an error if the cipher suite is not supported or the
1826 name is not a valid cipher suite name.
1827 suite_to_openssl_str(CipherSuite) -> string()
1829 Types:
1831 CipherSuite = erl_cipher_suite()
1833 Converts erl_cipher_suite() to OpenSSL name string.
1835 PRE TLS-1.3 these names differ for RFC names
1837 suite_to_str(CipherSuite) -> string()
1839 Types:
1841 CipherSuite = erl_cipher_suite()
1843 Converts erl_cipher_suite() to RFC name string.
1845 transport_accept(ListenSocket) ->
1847 {ok, SslSocket} | {error, reason()}
1848 transport_accept(ListenSocket, Timeout) ->
1850 {ok, SslSocket} | {error, reason()}
1851 Types:
1853 ListenSocket = sslsocket()
1855 Timeout = timeout()
1856 SslSocket = sslsocket()
1857 Accepts an incoming connection request on a listen socket. Lis‐
1859 tenSocket must be a socket returned from listen/2. The socket
1860 returned is to be passed to handshake/[2,3] to complete hand‐
1861 shaking, that is, establishing the TLS/DTLS connection.
1862 Warning:
1864 Most API functions require that the TLS/DTLS connection is
1865 established to work as expected.
1866 The accepted socket inherits the options set for ListenSocket in
1869 listen/2.
1870 The default value for Timeout is infinity. If Timeout is speci‐
1872 fied and no connection is accepted within the given time,
1873 {error, timeout} is returned.
1874 versions() -> [VersionInfo]
1876 Types:
1878 VersionInfo =
1880 {ssl_app, string()} |
1881 {supported | available | implemented, [tls_version()]} |
1882 {supported_dtls | available_dtls | implemented_dtls,
1883 [dtls_version()]}
1884 Lists information, mainly concerning TLS/DTLS versions, in run‐
1886 time for debugging and testing purposes.
1887 app_vsn:
1889 The application version of the SSL application.
1890 supported:
1892 TLS versions supported with current application environment
1893 and crypto library configuration. Overridden by a version
1894 option on connect/[2,3,4], listen/2, and
1895 ssl_accept/[1,2,3]. For the negotiated TLS version, see con‐
1896 nection_information/1 .
1897 supported_dtls:
1899 DTLS versions supported with current application environment
1900 and crypto library configuration. Overridden by a version
1901 option on connect/[2,3,4], listen/2, and
1902 ssl_accept/[1,2,3]. For the negotiated DTLS version, see
1903 connection_information/1 .
1904 available:
1906 All TLS versions supported with the linked crypto library.
1907 available_dtls:
1909 All DTLS versions supported with the linked crypto library.
1910 implemented:
1912 All TLS versions supported by the SSL application if linked
1913 with a crypto library with the necessary support.
1914 implemented_dtls:
1916 All DTLS versions supported by the SSL application if linked
1917 with a crypto library with the necessary support.
1918
1920 inet(3) and gen_tcp(3) gen_udp(3)
1921Ericsson AB ssl 10.3 ssl(3)