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 SSL/TLS/DTLS protocol.
10 For detailed information about the supported standards see ssl(6).
11
13 Types used in SSL/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 SSL/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' | sslv3
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 ec_point_formats => [0..2],
188 elliptic_curves => [public_key:oid()],
189 sni => hostname()}
190 error_alert() =
192 {tls_alert, {tls_alert(), Description :: string()}}
193 tls_alert() =
195 close_notify | unexpected_message | bad_record_mac |
196 record_overflow | handshake_failure | bad_certificate |
197 unsupported_certificate | certificate_revoked |
198 certificate_expired | certificate_unknown |
199 illegal_parameter | unknown_ca | access_denied |
200 decode_error | decrypt_error | export_restriction |
201 protocol_version | insufficient_security | internal_error |
202 inappropriate_fallback | user_canceled | no_renegotiation |
203 unsupported_extension | certificate_unobtainable |
204 unrecognized_name | bad_certificate_status_response |
205 bad_certificate_hash_value | unknown_psk_identity |
206 no_application_protocol
207 reason() = any()
209 bloom_filter_window_size() = integer()
211 bloom_filter_hash_functions() = integer()
213 bloom_filter_bits() = integer()
215 client_session_tickets() = disabled | manual | auto
217 server_session_tickets() = disabled | stateful | stateless
219 TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT
221 common_option() =
222 {protocol, protocol()} |
223 {handshake, handshake_completion()} |
224 {cert, cert()} |
225 {certfile, cert_pem()} |
226 {key, key()} |
227 {keyfile, key_pem()} |
228 {password, key_password()} |
229 {ciphers, cipher_suites()} |
230 {eccs, [named_curve()]} |
231 {signature_algs_cert, signature_schemes()} |
232 {supported_groups, supported_groups()} |
233 {secure_renegotiate, secure_renegotiation()} |
234 {depth, allowed_cert_chain_length()} |
235 {verify_fun, custom_verify()} |
236 {crl_check, crl_check()} |
237 {crl_cache, crl_cache_opts()} |
238 {max_handshake_size, handshake_size()} |
239 {partial_chain, root_fun()} |
240 {versions, protocol_versions()} |
241 {user_lookup_fun, custom_user_lookup()} |
242 {log_level, logging_level()} |
243 {log_alert, log_alert()} |
244 {hibernate_after, hibernate_after()} |
245 {padding_check, padding_check()} |
246 {beast_mitigation, beast_mitigation()} |
247 {ssl_imp, ssl_imp()} |
248 {session_tickets, session_tickets()} |
249 {key_update_at, key_update_at()}
250 protocol() = tls | dtls
252 Choose TLS or DTLS protocol for the transport layer security.
254 Defaults to tls. For DTLS other transports than UDP are not yet
255 supported.
256 handshake_completion() = hello | full
258 Defaults to full. If hello is specified the handshake will pause
260 after the hello message and give the user a possibility make
261 decisions based on hello extensions before continuing or abort‐
262 ing the handshake by calling handshake_continue/3 or hand‐
263 shake_cancel/1
264 cert() = public_key:der_encoded()
266 The DER-encoded users certificate. If this option is supplied,
268 it overrides option certfile.
269 cert_pem() = file:filename()
271 Path to a file containing the user certificate on PEM format.
273 key() =
275 {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' |
276 'PrivateKeyInfo',
277 public_key:der_encoded()} |
278 #{algorithm := rsa | dss | ecdsa,
279 engine := crypto:engine_ref(),
280 key_id := crypto:key_id(),
281 password => crypto:password()}
282 The DER-encoded user's private key or a map refering to a crypto
284 engine and its key reference that optionally can be password
285 protected, seealso crypto:engine_load/4 and Crypto's Users
286 Guide. If this option is supplied, it overrides option keyfile.
287 key_pem() = file:filename()
289 Path to the file containing the user's private PEM-encoded key.
291 As PEM-files can contain several entries, this option defaults
292 to the same file as given by option certfile.
293 key_password() = string()
295 String containing the user's password. Only used if the private
297 keyfile is password-protected.
298 cipher_suites() = ciphers()
300 A list of cipher suites that should be supported
302 The function ssl:cipher_suites/2 can be used to find all
304 cipher suites that are supported by default and all cipher
305 suites that may be configured.
306 If you compose your own cipher_suites() make sure they are fil‐
308 tered for cryptolib support ssl:filter_cipher_suites/2 Addi‐
309 tionaly the functions ssl:append_cipher_suites/2 ,
310 ssl:prepend_cipher_suites/2, ssl:suite_to_str/1,
311 ssl:str_to_suite/1, and ssl:suite_to_openssl_str/1 also exist to
312 help creating customized cipher suite lists.
313 Note:
315 Note that TLS-1.3 and TLS-1.2 cipher suites are not overlapping
316 sets of cipher suites so to support both these versions cipher
317 suites from both versions need to be included. If supporting
318 TLS-1.3 versions prior to TLS-1.2 can not be supported.
319 Non-default cipher suites including anonymous cipher suites (PRE
322 TLS-1.3) are supported for interop/testing purposes and may be
323 used by adding them to your cipher suite list. Note that they
324 must also be supported/enabled by the peer to actually be used.
325 signature_schemes() = [sign_scheme()]
327 In addition to the signature_algorithms extension from TLS 1.2,
329 TLS 1.3 (RFC 5246 Section 4.2.3)adds the signature_algo‐
330 rithms_cert extension which enables having special requirements
331 on the signatures used in the certificates that differs from the
332 requirements on digital signatures as a whole. If this is not
333 required this extension is not needed.
334 The client will send a signature_algorithms_cert extension
336 (ClientHello), if TLS version 1.3 or later is used, and the sig‐
337 nature_algs_cert option is explicitly specified. By default,
338 only the signature_algs extension is sent.
339 The signature schemes shall be ordered according to the client's
341 preference (favorite choice first).
342 supported_groups() = [group()]
344 TLS 1.3 introduces the "supported_groups" extension that is used
346 for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
347 shake. Both client and server can specify a list of parameters
348 that they are willing to use.
349 If it is not specified it will use a default list ([x25519,
351 x448, secp256r1, secp384r1]) that is filtered based on the
352 installed crypto library version.
353 secure_renegotiation() = boolean()
355 Specifies if to reject renegotiation attempt that does not live
357 up to RFC 5746. By default secure_renegotiate is set to true,
358 that is, secure renegotiation is enforced. If set to false
359 secure renegotiation will still be used if possible, but it
360 falls back to insecure renegotiation if the peer does not sup‐
361 port RFC 5746.
362 allowed_cert_chain_length() = integer()
364 Maximum number of non-self-issued intermediate certificates that
366 can follow the peer certificate in a valid certification path.
367 So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
368 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
369 can be PEER, CA, CA, ROOT-CA, and so on. The default value is 1.
370 custom_verify() =
372 {Verifyfun :: function(), InitialUserState :: any()}
373 The verification fun is to be defined as follows:
375 fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() |
377 {revoked, atom()}} |
378 {extension, #'Extension'{}}, InitialUserState :: term()) ->
379 {valid, UserState :: term()} | {valid_peer, UserState :: term()} |
380 {fail, Reason :: term()} | {unknown, UserState :: term()}.
381 The verification fun is called during the X509-path validation
384 when an error or an extension unknown to the SSL application is
385 encountered. It is also called when a certificate is considered
386 valid by the path validation to allow access to each certificate
387 in the path to the user application. It differentiates between
388 the peer certificate and the CA certificates by using valid_peer
389 or valid as second argument to the verification fun. See the
390 public_key User's Guide for definition of #'OTPCertificate'{}
391 and #'Extension'{}.
392 * If the verify callback fun returns {fail, Reason}, the veri‐
394 fication process is immediately stopped, an alert is sent to
395 the peer, and the TLS/DTLS handshake terminates.
396 * If the verify callback fun returns {valid, UserState}, the
398 verification process continues.
399 * If the verify callback fun always returns {valid, User‐
401 State}, the TLS/DTLS handshake does not terminate regarding
402 verification failures and the connection is established.
403 * If called with an extension unknown to the user application,
405 return value {unknown, UserState} is to be used.
406 Note that if the fun returns unknown for an extension marked
408 as critical, validation will fail.
409 Default option verify_fun in verify_peer mode:
411 {fun(_,{bad_cert, _} = Reason, _) ->
413 {fail, Reason};
414 (_,{extension, _}, UserState) ->
415 {unknown, UserState};
416 (_, valid, UserState) ->
417 {valid, UserState};
418 (_, valid_peer, UserState) ->
419 {valid, UserState}
420 end, []}
421 Default option verify_fun in mode verify_none:
424 {fun(_,{bad_cert, _}, UserState) ->
426 {valid, UserState};
427 (_,{extension, #'Extension'{critical = true}}, UserState) ->
428 {valid, UserState};
429 (_,{extension, _}, UserState) ->
430 {unknown, UserState};
431 (_, valid, UserState) ->
432 {valid, UserState};
433 (_, valid_peer, UserState) ->
434 {valid, UserState}
435 end, []}
436 The possible path validation errors are given on form {bad_cert,
439 Reason} where Reason is:
440 unknown_ca:
442 No trusted CA was found in the trusted store. The trusted CA
443 is normally a so called ROOT CA, which is a self-signed cer‐
444 tificate. Trust can be claimed for an intermediate CA
445 (trusted anchor does not have to be self-signed according to
446 X-509) by using option partial_chain.
447 selfsigned_peer:
449 The chain consisted only of one self-signed certificate.
450 PKIX X-509-path validation error:
452 For possible reasons, see public_key:pkix_path_validation/3
453 crl_check() = boolean() | peer | best_effort
455 Perform CRL (Certificate Revocation List) verification (pub‐
457 lic_key:pkix_crls_validate/3) on all the certificates during the
458 path validation (public_key:pkix_path_validation/3) of the cer‐
459 tificate chain. Defaults to false.
460 peer:
462 check is only performed on the peer certificate.
463 best_effort:
465 if certificate revocation status cannot be determined it
466 will be accepted as valid.
467 The CA certificates specified for the connection will be used to
469 construct the certificate chain validating the CRLs.
470 The CRLs will be fetched from a local or external cache. See
472 ssl_crl_cache_api(3).
473 crl_cache_opts() = [any()]
475 Specify how to perform lookup and caching of certificate revoca‐
477 tion lists. Module defaults to ssl_crl_cache with DbHandle
478 being internal and an empty argument list.
479 There are two implementations available:
481 ssl_crl_cache:
483 This module maintains a cache of CRLs. CRLs can be added to
484 the cache using the function ssl_crl_cache:insert/1, and
485 optionally automatically fetched through HTTP if the follow‐
486 ing argument is specified:
487 {http, timeout()}:
489 Enables fetching of CRLs specified as http URIs inX509
490 certificate extensions. Requires the OTP inets applica‐
491 tion.
492 ssl_crl_hash_dir:
494 This module makes use of a directory where CRLs are stored
495 in files named by the hash of the issuer name.
496 The file names consist of eight hexadecimal digits followed
498 by .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the
499 first version of the CRL, N starts at zero, and for each new
500 version, N is incremented by one. The OpenSSL utility
501 c_rehash creates symlinks according to this pattern.
502 For a given hash value, this module finds all consecutive
504 .r* files starting from zero, and those files taken together
505 make up the revocation list. CRL files whose nextUpdate
506 fields are in the past, or that are issued by a different CA
507 that happens to have the same name hash, are excluded.
508 The following argument is required:
510 {dir, string()}:
512 Specifies the directory in which the CRLs can be found.
513 root_fun() = function()
515 fun(Chain::[public_key:der_encoded()]) ->
517 {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
518 Claim an intermediate CA in the chain as trusted. TLS then per‐
521 forms public_key:pkix_path_validation/3 with the selected CA as
522 trusted anchor and the rest of the chain.
523 protocol_versions() = [protocol_version()]
525 TLS protocol versions supported by started clients and servers.
527 This option overrides the application environment option proto‐
528 col_version and dtls_protocol_version. If the environment option
529 is not set, it defaults to all versions, except SSL-3.0, sup‐
530 ported by the SSL application. See also ssl(6).
531 custom_user_lookup() =
533 {Lookupfun :: function(), UserState :: any()}
534 The lookup fun is to defined as follows:
536 fun(psk, PSKIdentity ::string(), UserState :: term()) ->
538 {ok, SharedSecret :: binary()} | error;
539 fun(srp, Username :: string(), UserState :: term()) ->
540 {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
541 DerivedKey :: binary()}} | error.
542 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
545 by the client and server to determine the shared secret. When
546 called by the client, PSKIdentity is set to the hint presented
547 by the server or to undefined. When called by the server, PSKI‐
548 dentity is the identity presented by the client.
549 For Secure Remote Password (SRP), the fun is only used by the
551 server to obtain parameters that it uses to generate its session
552 keys. DerivedKey is to be derived according to RFC 2945 and
553 RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
554 word])])
555 session_id() = binary()
557 Identifies a TLS session.
559 log_alert() = boolean()
561 If set to false, TLS/DTLS Alert reports are not displayed. Dep‐
563 recated in OTP 22, use {log_level, logging_level()} instead.
564 logging_level() = logger:level()
566 Specifies the log level for a TLS/DTLS connection. Alerts are
568 logged on notice level, which is the default level. The level
569 debug triggers verbose logging of TLS/DTLS protocol messages.
570 See also ssl(6)
571 hibernate_after() = timeout()
573 When an integer-value is specified, TLS/DTLS-connection goes
575 into hibernation after the specified number of milliseconds of
576 inactivity, thus reducing its memory footprint. When undefined
577 is specified (this is the default), the process never goes into
578 hibernation.
579 handshake_size() = integer()
581 Integer (24 bits unsigned). Used to limit the size of valid TLS
583 handshake packets to avoid DoS attacks. Defaults to 256*1024.
584 padding_check() = boolean()
586 Affects TLS-1.0 connections only. If set to false, it disables
588 the block cipher padding check to be able to interoperate with
589 legacy software.
590 Warning:
592 Using {padding_check, boolean()} makes TLS vulnerable to the
593 Poodle attack.
594 beast_mitigation() = one_n_minus_one | zero_n | disabled
597 Affects SSL-3.0 and TLS-1.0 connections only. Used to change the
599 BEAST mitigation strategy to interoperate with legacy software.
600 Defaults to one_n_minus_one.
601 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
603 zero_n - Perform 0/n BEAST mitigation.
605 disabled - Disable BEAST mitigation.
607 Warning:
609 Using {beast_mitigation, disabled} makes SSL-3.0 or TLS-1.0 vul‐
610 nerable to the BEAST attack.
611 ssl_imp() = new | old
614 Deprecated since OTP-17, has no affect.
616 session_tickets() =
618 client_session_tickets() | server_session_tickets()
619 Configures the session ticket functionalty in TLS 1.3 client and
621 server.
622 key_update_at() = integer() >= 1
624 Configures the maximum amount of bytes that can be sent on a TLS
626 1.3 connection before an automatic key update is performed.
627 There are cryptographic limits on the amount of plaintext which
629 can be safely encrypted under a given set of keys. The current
630 default ensures that data integrity will not be breached with
631 probability greater than 1/2^57. For more information see Limits
632 on Authenticated Encryption Use in TLS.
633 Warning:
635 The default value of this option shall provide the above men‐
636 tioned security guarantees and it shall be reasonable for most
637 applications (~353 TB).
638 TLS/DTLS OPTION DESCRIPTIONS - CLIENT
641 client_option() =
642 {verify, client_verify_type()} |
643 {reuse_session, client_reuse_session()} |
644 {reuse_sessions, client_reuse_sessions()} |
645 {cacerts, client_cacerts()} |
646 {cacertfile, client_cafile()} |
647 {alpn_advertised_protocols, client_alpn()} |
648 {client_preferred_next_protocols,
649 client_preferred_next_protocols()} |
650 {psk_identity, client_psk_identity()} |
651 {srp_identity, client_srp_identity()} |
652 {server_name_indication, sni()} |
653 {customize_hostname_check, customize_hostname_check()} |
654 {signature_algs, client_signature_algs()} |
655 {fallback, fallback()} |
656 {session_tickets, client_session_tickets()} |
657 {use_ticket, use_ticket()}
658 client_verify_type() = verify_type()
660 In mode verify_none the default behavior is to allow all
662 x509-path validation errors. See also option verify_fun.
663 client_reuse_session() = session_id()
665 Reuses a specific session earlier saved with the option {re‐
667 use_sessions, save} since OTP-21.3
668 client_reuse_sessions() = boolean() | save
670 When save is specified a new connection will be negotiated and
672 saved for later reuse. The session ID can be fetched with con‐
673 nection_information/2 and used with the client option reuse_ses‐
674 sion The boolean value true specifies that if possible, automa‐
675 tized session reuse will be performed. If a new session is cre‐
676 ated, and is unique in regard to previous stored sessions, it
677 will be saved for possible later reuse. Since OTP-21.3
678 client_cacerts() = [public_key:der_encoded()]
680 The DER-encoded trusted certificates. If this option is supplied
682 it overrides option cacertfile.
683 client_cafile() = file:filename()
685 Path to a file containing PEM-encoded CA certificates. The CA
687 certificates are used during server authentication and when
688 building the client certificate chain.
689 client_alpn() = [app_level_protocol()]
691 The list of protocols supported by the client to be sent to the
693 server to be used for an Application-Layer Protocol Negotiation
694 (ALPN). If the server supports ALPN then it will choose a proto‐
695 col from this list; otherwise it will fail the connection with a
696 "no_application_protocol" alert. A server that does not support
697 ALPN will ignore this value.
698 The list of protocols must not contain an empty binary.
700 The negotiated protocol can be retrieved using the negoti‐
702 ated_protocol/1 function.
703 client_preferred_next_protocols() =
705 {Precedence :: server | client,
706 ClientPrefs :: [app_level_protocol()]} |
707 {Precedence :: server | client,
708 ClientPrefs :: [app_level_protocol()],
709 Default :: app_level_protocol()}
710 Indicates that the client is to try to perform Next Protocol
712 Negotiation.
713 If precedence is server, the negotiated protocol is the first
715 protocol to be shown on the server advertised list, which is
716 also on the client preference list.
717 If precedence is client, the negotiated protocol is the first
719 protocol to be shown on the client preference list, which is
720 also on the server advertised list.
721 If the client does not support any of the server advertised pro‐
723 tocols or the server does not advertise any protocols, the
724 client falls back to the first protocol in its list or to the
725 default protocol (if a default is supplied). If the server does
726 not support Next Protocol Negotiation, the connection terminates
727 if no default protocol is supplied.
728 client_psk_identity() = psk_identity()
730 Specifies the identity the client presents to the server. The
732 matching secret is found by calling user_lookup_fun
733 client_srp_identity() = srp_identity()
735 Specifies the username and password to use to authenticate to
737 the server.
738 sni() = hostname() | disable
740 Specify the hostname to be used in TLS Server Name Indication
742 extension. If not specified it will default to the Host argument
743 of connect/[3,4] unless it is of type inet:ipaddress().
744 The HostName will also be used in the hostname verification of
746 the peer certificate using public_key:pkix_verify_hostname/2.
747 The special value disable prevents the Server Name Indication
749 extension from being sent and disables the hostname verification
750 check public_key:pkix_verify_hostname/2
751 customize_hostname_check() = list()
753 Customizes the hostname verification of the peer certificate, as
755 different protocols that use TLS such as HTTP or LDAP may want
756 to do it differently, for possible options see pub‐
757 lic_key:pkix_verify_hostname/3
758 fallback() = boolean()
760 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired
762 TLS version downgrade. Defaults to false
763 Warning:
765 Note this option is not needed in normal TLS usage and should
766 not be used to implement new clients. But legacy clients that
767 retries connections in the following manner
768 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1',
770 'tlsv1', 'sslv3']}])
771 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1',
773 'sslv3']}, {fallback, true}])
774 ssl:connect(Host, Port, [...{versions, ['tlsv1', 'sslv3']},
776 {fallback, true}])
777 ssl:connect(Host, Port, [...{versions, ['sslv3']}, {fallback,
779 true}])
780 may use it to avoid undesired TLS version downgrade. Note that
782 TLS_FALLBACK_SCSV must also be supported by the server for the
783 prevention to work.
784 client_signature_algs() = signature_algs()
787 In addition to the algorithms negotiated by the cipher suite
789 used for key exchange, payload encryption, message authentica‐
790 tion and pseudo random calculation, the TLS signature algorithm
791 extension Section 7.4.1.4.1 in RFC 5246 may be used, from TLS
792 1.2, to negotiate which signature algorithm to use during the
793 TLS handshake. If no lower TLS versions than 1.2 are supported,
794 the client will send a TLS signature algorithm extension with
795 the algorithms specified by this option. Defaults to
796 [
798 %% SHA2
799 {sha512, ecdsa},
800 {sha512, rsa},
801 {sha384, ecdsa},
802 {sha384, rsa},
803 {sha256, ecdsa},
804 {sha256, rsa},
805 {sha224, ecdsa},
806 {sha224, rsa},
807 %% SHA
808 {sha, ecdsa},
809 {sha, rsa},
810 {sha, dsa},
811 ]
812 The algorithms should be in the preferred order. Selected signa‐
814 ture algorithm can restrict which hash functions that may be
815 selected. Default support for {md5, rsa} removed in ssl-8.0
816 client_session_tickets() = disabled | manual | auto
818 Configures the session ticket functionality. Allowed values are
820 disabled, manual and auto. If it is set to manual the client
821 will send the ticket information to user process in a 3-tuple:
822 {ssl, session_ticket, {SNI, TicketData}}
824 where SNI is the ServerNameIndication and TicketData is the
826 extended ticket data that can be used in subsequent session
827 resumptions.
828 If it is set to auto, the client automatically handles received
830 tickets and tries to use them when making new TLS connections
831 (session resumption with pre-shared keys).
832 Note:
834 This option is supported by TLS 1.3 and above. See also SSL's
835 Users Guide, Session Tickets and Session Resumption in TLS 1.3
836 use_ticket() = [binary()]
839 Configures the session tickets to be used for session resump‐
841 tion. It is a mandatory option in manual mode (session_tickets =
842 manual).
843 Note:
845 Session tickets are only sent to user if option session_tickets
846 is set to manual
847 This option is supported by TLS 1.3 and above. See also SSL's
849 Users Guide, Session Tickets and Session Resumption in TLS 1.3
850 TLS/DTLS OPTION DESCRIPTIONS - SERVER
853 server_option() =
854 {cacerts, server_cacerts()} |
855 {cacertfile, server_cafile()} |
856 {dh, dh_der()} |
857 {dhfile, dh_file()} |
858 {verify, server_verify_type()} |
859 {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
860 {reuse_sessions, server_reuse_sessions()} |
861 {reuse_session, server_reuse_session()} |
862 {alpn_preferred_protocols, server_alpn()} |
863 {next_protocols_advertised, server_next_protocol()} |
864 {psk_identity, server_psk_identity()} |
865 {honor_cipher_order, boolean()} |
866 {sni_hosts, sni_hosts()} |
867 {sni_fun, sni_fun()} |
868 {honor_cipher_order, honor_cipher_order()} |
869 {honor_ecc_order, honor_ecc_order()} |
870 {client_renegotiation, client_renegotiation()} |
871 {signature_algs, server_signature_algs()} |
872 {session_tickets, server_session_tickets()} |
873 {anti_replay, anti_replay()}
874 server_cacerts() = [public_key:der_encoded()]
876 The DER-encoded trusted certificates. If this option is supplied
878 it overrides option cacertfile.
879 server_cafile() = file:filename()
881 Path to a file containing PEM-encoded CA certificates. The CA
883 certificates are used to build the server certificate chain and
884 for client authentication. The CAs are also used in the list of
885 acceptable client CAs passed to the client when a certificate is
886 requested. Can be omitted if there is no need to verify the
887 client and if there are no intermediate CAs for the server cer‐
888 tificate.
889 dh_der() = binary()
891 The DER-encoded Diffie-Hellman parameters. If specified, it
893 overrides option dhfile.
894 Warning:
896 The dh_der option is not supported by TLS 1.3. Use the sup‐
897 ported_groups option instead.
898 dh_file() = file:filename()
901 Path to a file containing PEM-encoded Diffie Hellman parameters
903 to be used by the server if a cipher suite using Diffie Hellman
904 key exchange is negotiated. If not specified, default parameters
905 are used.
906 Warning:
908 The dh_file option is not supported by TLS 1.3. Use the sup‐
909 ported_groups option instead.
910 server_verify_type() = verify_type()
913 A server only does x509-path validation in mode verify_peer, as
915 it then sends a certificate request to the client (this message
916 is not sent if the verify option is verify_none). You can then
917 also want to specify option fail_if_no_peer_cert.
918 fail_if_no_peer_cert() = boolean()
920 Used together with {verify, verify_peer} by an TLS/DTLS server.
922 If set to true, the server fails if the client does not have a
923 certificate to send, that is, sends an empty certificate. If set
924 to false, it fails only if the client sends an invalid certifi‐
925 cate (an empty certificate is considered valid). Defaults to
926 false.
927 server_reuse_sessions() = boolean()
929 The boolean value true specifies that the server will agree to
931 reuse sessions. Setting it to false will result in an empty ses‐
932 sion table, that is no sessions will be reused. See also option
933 reuse_session
934 server_reuse_session() = function()
936 Enables the TLS/DTLS server to have a local policy for deciding
938 if a session is to be reused or not. Meaningful only if re‐
939 use_sessions is set to true. SuggestedSessionId is a binary(),
940 PeerCert is a DER-encoded certificate, Compression is an enumer‐
941 ation integer, and CipherSuite is of type ciphersuite().
942 server_alpn() = [app_level_protocol()]
944 Indicates the server will try to perform Application-Layer Pro‐
946 tocol Negotiation (ALPN).
947 The list of protocols is in order of preference. The protocol
949 negotiated will be the first in the list that matches one of the
950 protocols advertised by the client. If no protocol matches, the
951 server will fail the connection with a "no_application_protocol"
952 alert.
953 The negotiated protocol can be retrieved using the negoti‐
955 ated_protocol/1 function.
956 server_next_protocol() = [app_level_protocol()]
958 List of protocols to send to the client if the client indicates
960 that it supports the Next Protocol extension. The client can
961 select a protocol that is not on this list. The list of proto‐
962 cols must not contain an empty binary. If the server negotiates
963 a Next Protocol, it can be accessed using the negoti‐
964 ated_next_protocol/1 method.
965 server_psk_identity() = psk_identity()
967 Specifies the server identity hint, which the server presents to
969 the client.
970 honor_cipher_order() = boolean()
972 If set to true, use the server preference for cipher selection.
974 If set to false (the default), use the client preference.
975 sni_hosts() =
977 [{hostname(), [server_option() | common_option()]}]
978 If the server receives a SNI (Server Name Indication) from the
980 client matching a host listed in the sni_hosts option, the spe‐
981 cific options for that host will override previously specified
982 options. The option sni_fun, and sni_hosts are mutually exclu‐
983 sive.
984 sni_fun() = function()
986 If the server receives a SNI (Server Name Indication) from the
988 client, the given function will be called to retrieve
989 [server_option()] for the indicated server. These options will
990 be merged into predefined [server_option()] list. The function
991 should be defined as: fun(ServerName :: string()) ->
992 [server_option()] and can be specified as a fun or as named fun
993 module:function/1 The option sni_fun, and sni_hosts are mutually
994 exclusive.
995 client_renegotiation() = boolean()
997 In protocols that support client-initiated renegotiation, the
999 cost of resources of such an operation is higher for the server
1000 than the client. This can act as a vector for denial of service
1001 attacks. The SSL application already takes measures to counter-
1002 act such attempts, but client-initiated renegotiation can be
1003 strictly disabled by setting this option to false. The default
1004 value is true. Note that disabling renegotiation can result in
1005 long-lived connections becoming unusable due to limits on the
1006 number of messages the underlying cipher suite can encipher.
1007 honor_cipher_order() = boolean()
1009 If true, use the server's preference for cipher selection. If
1011 false (the default), use the client's preference.
1012 honor_ecc_order() = boolean()
1014 If true, use the server's preference for ECC curve selection. If
1016 false (the default), use the client's preference.
1017 server_signature_algs() = signature_algs()
1019 The algorithms specified by this option will be the ones
1021 accepted by the server in a signature algorithm negotiation,
1022 introduced in TLS-1.2. The algorithms will also be offered to
1023 the client if a client certificate is requested. For more
1024 details see the corresponding client option.
1025 server_session_tickets() = disabled | stateful | stateless
1027 Configures the session ticket functionality. Allowed values are
1029 disabled, stateful and stateless.
1030 If it is set to stateful or stateless, session resumption with
1032 pre-shared keys is enabled and the server will send stateful or
1033 stateless session tickets to the client after successful connec‐
1034 tions.
1035 A stateful session ticket is a database reference to internal
1037 state information. A stateless session ticket is a self-
1038 encrypted binary that contains both cryptographic keying mate‐
1039 rial and state data.
1040 Note:
1042 This option is supported by TLS 1.3 and above. See also SSL's
1043 Users Guide, Session Tickets and Session Resumption in TLS 1.3
1044 anti_replay() =
1047 '10k' | '100k' |
1048 {bloom_filter_window_size(),
1049 bloom_filter_hash_functions(),
1050 bloom_filter_bits()}
1051 Configures the server's built-in anti replay feature based on
1053 Bloom filters.
1054 Allowed values are the pre-defined '10k', '100k' or a custom
1056 3-tuple that defines the properties of the bloom filters: {Win‐
1057 dowSize, HashFunctions, Bits}. WindowSize is the number of sec‐
1058 onds after the current Bloom filter is rotated and also the win‐
1059 dow size used for freshness checks. HashFunctions is the number
1060 hash functions and Bits is the number of bits in the bit vector.
1061 '10k' and '100k' are simple defaults with the following proper‐
1062 ties:
1063 * '10k': Bloom filters can hold 10000 elements with 3% proba‐
1065 bility of false positives. WindowSize: 10, HashFunctions: 5,
1066 Bits: 72985 (8.91 KiB).
1067 * '100k': Bloom filters can hold 100000 elements with 3% prob‐
1069 ability of false positives. WindowSize: 10, HashFunctions:
1070 5, Bits: 729845 (89.09 KiB).
1071 Note:
1073 This option is supported by TLS 1.3 and above and only with
1074 stateless session tickets. Ticket lifetime, the number of tick‐
1075 ets sent by the server and the maximum number of tickets stored
1076 by the server in stateful mode are configured by application
1077 variables. See also SSL's Users Guide, Anti-Replay Protection
1078 in TLS 1.3
1079
1082 append_cipher_suites(Deferred, Suites) -> ciphers()
1083 Types:
1085 Deferred = ciphers() | cipher_filters()
1087 Suites = ciphers()
1088 Make Deferred suites become the least preferred suites, that is
1090 put them at the end of the cipher suite list Suites after remov‐
1091 ing them from Suites if present. Deferred may be a list of
1092 cipher suits or a list of filters in which case the filters are
1093 use on Suites to extract the Deferred cipher list.
1094 cipher_suites() -> [old_cipher_suite()] | [string()]
1096 cipher_suites(Type) -> [old_cipher_suite() | string()]
1098 Types:
1100 Type = erlang | openssl | all
1102 Deprecated in OTP 21, use cipher_suites/2 instead.
1104 cipher_suites(Supported, Version) -> ciphers()
1106 Types:
1108 Supported = default | all | anonymous
1110 Version = protocol_version()
1111 Returns all default or all supported (except anonymous), or all
1113 anonymous cipher suites for a TLS version
1114 Note:
1116 The cipher suites returned by this function are the cipher
1117 suites that the OTP ssl application can support provided that
1118 they are supported by the cryptolib linked with the OTP crypto
1119 application. Use ssl:filter_cipher_suites(Suites, []). to fil‐
1120 ter the list for the current cryptolib. Note that cipher suites
1121 may be filtered out because they are too old or too new depend‐
1122 ing on the cryptolib
1123 cipher_suites(Supported, Version, StringType :: rfc | openssl) ->
1126 [string()]
1127 Types:
1129 Supported = default | all | anonymous
1131 Version = protocol_version()
1132 Same as cipher_suites/2 but lists RFC or OpenSSL string names
1134 instead of erl_cipher_suite()
1135 eccs() -> NamedCurves
1137 eccs(Version) -> NamedCurves
1139 Types:
1141 Version = protocol_version()
1143 NamedCurves = [named_curve()]
1144 Returns a list of supported ECCs. eccs() is equivalent to call‐
1146 ing eccs(Protocol) with all supported protocols and then dedu‐
1147 plicating the output.
1148 clear_pem_cache() -> ok
1150 PEM files, used by ssl API-functions, are cached. The cache is
1152 regularly checked to see if any cache entries should be invali‐
1153 dated, however this function provides a way to unconditionally
1154 clear the whole cache.
1155 connect(TCPSocket, TLSOptions) ->
1157 {ok, sslsocket()} |
1158 {error, reason()} |
1159 {option_not_a_key_value_tuple, any()}
1160 connect(TCPSocket, TLSOptions, Timeout) ->
1162 {ok, sslsocket()} | {error, reason()}
1163 Types:
1165 TCPSocket = socket()
1167 TLSOptions = [tls_client_option()]
1168 Timeout = timeout()
1169 Upgrades a gen_tcp, or equivalent, connected socket to an TLS
1171 socket, that is, performs the client-side TLS handshake.
1172 Note:
1174 If the option verify is set to verify_peer the option
1175 server_name_indication shall also be specified, if it is not no
1176 Server Name Indication extension will be sent, and pub‐
1177 lic_key:pkix_verify_hostname/2 will be called with the IP-
1178 address of the connection as ReferenceID, which is proably not
1179 what you want.
1180 If the option {handshake, hello} is used the handshake is paused
1183 after receiving the server hello message and the success
1184 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1185 Thereafter the handshake is continued or canceled by calling
1186 handshake_continue/3 or handshake_cancel/1.
1187 If the option active is set to once, true or an integer value,
1189 the process owning the sslsocket will receive messages of type
1190 active_msgs()
1191 connect(Host, Port, TLSOptions) ->
1193 {ok, sslsocket()} |
1194 {ok, sslsocket(), Ext :: protocol_extensions()} |
1195 {error, reason()} |
1196 {option_not_a_key_value_tuple, any()}
1197 connect(Host, Port, TLSOptions, Timeout) ->
1199 {ok, sslsocket()} |
1200 {ok, sslsocket(), Ext :: protocol_extensions()} |
1201 {error, reason()} |
1202 {option_not_a_key_value_tuple, any()}
1203 Types:
1205 Host = host()
1207 Port = inet:port_number()
1208 TLSOptions = [tls_client_option()]
1209 Timeout = timeout()
1210 Opens an TLS/DTLS connection to Host, Port.
1212 When the option verify is set to verify_peer the check pub‐
1214 lic_key:pkix_verify_hostname/2 will be performed in addition to
1215 the usual x509-path validation checks. If the check fails the
1216 error {bad_cert, hostname_check_failed} will be propagated to
1217 the path validation fun verify_fun, where it is possible to do
1218 customized checks by using the full possibilities of the pub‐
1219 lic_key:pkix_verify_hostname/3 API. When the option
1220 server_name_indication is provided, its value (the DNS name)
1221 will be used as ReferenceID to public_key:pkix_verify_host‐
1222 name/2. When no server_name_indication option is given, the Host
1223 argument will be used as Server Name Indication extension. The
1224 Host argument will also be used for the public_key:pkix_ver‐
1225 ify_hostname/2 check and if the Host argument is an
1226 inet:ip_address() the ReferenceID used for the check will be
1227 {ip, Host} otherwise dns_id will be assumed with a fallback to
1228 ip if that fails.
1229 Note:
1231 According to good practices certificates should not use IP-
1232 addresses as "server names". It would be very surprising if this
1233 happen outside a closed network.
1234 If the option {handshake, hello} is used the handshake is paused
1237 after receiving the server hello message and the success
1238 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1239 Thereafter the handshake is continued or canceled by calling
1240 handshake_continue/3 or handshake_cancel/1.
1241 If the option active is set to once, true or an integer value,
1243 the process owning the sslsocket will receive messages of type
1244 active_msgs()
1245 close(SslSocket) -> ok | {error, Reason}
1247 Types:
1249 SslSocket = sslsocket()
1251 Reason = any()
1252 Closes an TLS/DTLS connection.
1254 close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}
1256 Types:
1258 SslSocket = sslsocket()
1260 How = timeout() | {NewController :: pid(), timeout()}
1261 Reason = any()
1262 Closes or downgrades an TLS connection. In the latter case the
1264 transport connection will be handed over to the NewController
1265 process after receiving the TLS close alert from the peer. The
1266 returned transport socket will have the following options set:
1267 [{active, false}, {packet, 0}, {mode, binary}]
1268 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1270 Types:
1272 SslSocket = sslsocket()
1274 NewOwner = pid()
1275 Reason = any()
1276 Assigns a new controlling process to the SSL socket. A control‐
1278 ling process is the owner of an SSL socket, and receives all
1279 messages from the socket.
1280 connection_information(SslSocket) ->
1282 {ok, Result} | {error, reason()}
1283 Types:
1285 SslSocket = sslsocket()
1287 Result = [{OptionName, OptionValue}]
1288 OptionName = atom()
1289 OptionValue = any()
1290 Returns the most relevant information about the connection, ssl
1292 options that are undefined will be filtered out. Note that val‐
1293 ues that affect the security of the connection will only be
1294 returned if explicitly requested by connection_information/2.
1295 Note:
1297 The legacy Item = cipher_suite is still supported and returns
1298 the cipher suite on its (undocumented) legacy format. It should
1299 be replaced by selected_cipher_suite.
1300 connection_information(SslSocket, Items) ->
1303 {ok, Result} | {error, reason()}
1304 Types:
1306 SslSocket = sslsocket()
1308 Items = [OptionName]
1309 Result = [{OptionName, OptionValue}]
1310 OptionName = atom()
1311 OptionValue = any()
1312 Returns the requested information items about the connection, if
1314 they are defined.
1315 Note that client_random, server_random and master_secret are
1317 values that affect the security of connection. Meaningful atoms,
1318 not specified above, are the ssl option names.
1319 Note:
1321 If only undefined options are requested the resulting list can
1322 be empty.
1323 filter_cipher_suites(Suites, Filters) -> Ciphers
1326 Types:
1328 Suites = ciphers()
1330 Filters = cipher_filters()
1331 Ciphers = ciphers()
1332 Removes cipher suites if any of the filter functions returns
1334 false for any part of the cipher suite. If no filter function is
1335 supplied for some part the default behaviour regards it as if
1336 there was a filter function that returned true. For examples see
1337 Customizing cipher suits Additionaly this function also filters
1338 the cipher suites to exclude cipher suites not supported by the
1339 cryptolib used by the OTP crypto application. That is calling
1340 ssl:filter_cipher_suites(Suites, []) will be equivalent to only
1341 applying the filters for cryptolib support.
1342 format_error(Reason :: {error, Reason}) -> string()
1344 Types:
1346 Reason = any()
1348 Presents the error returned by an SSL function as a printable
1350 string.
1351 getopts(SslSocket, OptionNames) ->
1353 {ok, [gen_tcp:option()]} | {error, reason()}
1354 Types:
1356 SslSocket = sslsocket()
1358 OptionNames = [gen_tcp:option_name()]
1359 Gets the values of the specified socket options.
1361 getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1363 getstat(SslSocket, Options) ->
1365 {ok, OptionValues} | {error, inet:posix()}
1366 Types:
1368 SslSocket = sslsocket()
1370 Options = [inet:stat_option()]
1371 OptionValues = [{inet:stat_option(), integer()}]
1372 Gets one or more statistic options for the underlying TCP
1374 socket.
1375 See inet:getstat/2 for statistic options description.
1377 handshake(HsSocket) ->
1379 {ok, SslSocket} |
1380 {ok, SslSocket, Ext} |
1381 {error, Reason}
1382 handshake(HsSocket, Timeout) ->
1384 {ok, SslSocket} |
1385 {ok, SslSocket, Ext} |
1386 {error, Reason}
1387 Types:
1389 HsSocket = sslsocket()
1391 Timeout = timeout()
1392 SslSocket = sslsocket()
1393 Ext = protocol_extensions()
1394 Reason = closed | timeout | error_alert()
1395 Performs the SSL/TLS/DTLS server-side handshake.
1397 Returns a new TLS/DTLS socket if the handshake is successful.
1399 If the option active is set to once, true or an integer value,
1401 the process owning the sslsocket will receive messages of type
1402 active_msgs()
1403 handshake(Socket, Options) ->
1405 {ok, SslSocket} |
1406 {ok, SslSocket, Ext} |
1407 {error, Reason}
1408 handshake(Socket, Options, Timeout) ->
1410 {ok, SslSocket} |
1411 {ok, SslSocket, Ext} |
1412 {error, Reason}
1413 Types:
1415 Socket = socket() | sslsocket()
1417 SslSocket = sslsocket()
1418 Options = [server_option()]
1419 Timeout = timeout()
1420 Ext = protocol_extensions()
1421 Reason = closed | timeout | {options, any()} | error_alert()
1422 If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1424 lent, socket to an SSL socket, that is, performs the SSL/TLS
1425 server-side handshake and returns a TLS socket.
1426 Warning:
1428 The Socket shall be in passive mode ({active, false}) before
1429 calling this function or else the behavior of this function is
1430 undefined.
1431 If Socket is an sslsocket() : provides extra SSL/TLS/DTLS
1434 options to those specified in listen/2 and then performs the
1435 SSL/TLS/DTLS handshake. Returns a new TLS/DTLS socket if the
1436 handshake is successful.
1437 If option {handshake, hello} is specified the handshake is
1439 paused after receiving the client hello message and the success
1440 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1441 Thereafter the handshake is continued or canceled by calling
1442 handshake_continue/3 or handshake_cancel/1.
1443 If the option active is set to once, true or an integer value,
1445 the process owning the sslsocket will receive messages of type
1446 active_msgs()
1447 handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1449 Cancel the handshake with a fatal USER_CANCELED alert.
1451 handshake_continue(HsSocket, Options) ->
1453 {ok, SslSocket} | {error, Reason}
1454 handshake_continue(HsSocket, Options, Timeout) ->
1456 {ok, SslSocket} | {error, Reason}
1457 Types:
1459 HsSocket = sslsocket()
1461 Options = [tls_client_option() | tls_server_option()]
1462 Timeout = timeout()
1463 SslSocket = sslsocket()
1464 Reason = closed | timeout | error_alert()
1465 Continue the SSL/TLS handshake possiby with new, additional or
1467 changed options.
1468 listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1470 Types:
1472 Port = inet:port_number()
1474 Options = [tls_server_option()]
1475 ListenSocket = sslsocket()
1476 Creates an SSL listen socket.
1478 negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1480 Types:
1482 SslSocket = sslsocket()
1484 Protocol = binary()
1485 Reason = protocol_not_negotiated
1486 Returns the protocol negotiated through ALPN or NPN extensions.
1488 peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1490 Types:
1492 SslSocket = sslsocket()
1494 Cert = binary()
1495 The peer certificate is returned as a DER-encoded binary. The
1497 certificate can be decoded with public_key:pkix_decode_cert/2
1498 peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1500 Types:
1502 SslSocket = sslsocket()
1504 Address = inet:ip_address()
1505 Port = inet:port_number()
1506 Returns the address and port number of the peer.
1508 prepend_cipher_suites(Preferred, Suites) -> ciphers()
1510 Types:
1512 Preferred = ciphers() | cipher_filters()
1514 Suites = ciphers()
1515 Make Preferred suites become the most preferred suites that is
1517 put them at the head of the cipher suite list Suites after
1518 removing them from Suites if present. Preferred may be a list of
1519 cipher suits or a list of filters in which case the filters are
1520 use on Suites to extract the preferred cipher list.
1521 prf(SslSocket, Secret, Label, Seed, WantedLength) ->
1523 {ok, binary()} | {error, reason()}
1524 Types:
1526 SslSocket = sslsocket()
1528 Secret = binary() | master_secret
1529 Label = binary()
1530 Seed = [binary() | prf_random()]
1531 WantedLength = integer() >= 0
1532 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1534 ate extra key material. It either takes user-generated values
1535 for Secret and Seed or atoms directing it to use a specific
1536 value from the session security parameters.
1537 Can only be used with TLS/DTLS connections; {error, undefined}
1539 is returned for SSLv3 connections.
1540 recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
1542 recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
1544 Types:
1546 SslSocket = sslsocket()
1548 Length = integer()
1549 Data = binary() | list() | HttpPacket
1550 Timeout = timeout()
1551 HttpPacket = any()
1552 See the description of HttpPacket in erlang:decode_packet/3
1553 in ERTS.
1554 Receives a packet from a socket in passive mode. A closed socket
1556 is indicated by return value {error, closed}.
1557 Argument Length is meaningful only when the socket is in mode
1559 raw and denotes the number of bytes to read. If Length = 0, all
1560 available bytes are returned. If Length > 0, exactly Length
1561 bytes are returned, or an error; possibly discarding less than
1562 Length bytes of data when the socket gets closed from the other
1563 side.
1564 Optional argument Timeout specifies a time-out in milliseconds.
1566 The default value is infinity.
1567 renegotiate(SslSocket) -> ok | {error, reason()}
1569 Types:
1571 SslSocket = sslsocket()
1573 Initiates a new handshake. A notable return value is {error,
1575 renegotiation_rejected} indicating that the peer refused to go
1576 through with the renegotiation, but the connection is still
1577 active using the previously negotiated session.
1578 update_keys(SslSocket, Type) -> ok | {error, reason()}
1580 Types:
1582 SslSocket = sslsocket()
1584 Type = write | read_write
1585 There are cryptographic limits on the amount of plaintext which
1587 can be safely encrypted under a given set of keys. If the amount
1588 of data surpasses those limits, a key update is triggered and a
1589 new set of keys are installed. See also the option
1590 key_update_at.
1591 This function can be used to explicitly start a key update on a
1593 TLS 1.3 connection. There are two types of the key update: if
1594 Type is set to write, only the writing key is updated; if Type
1595 is set to read_write, both the reading and writing keys are
1596 updated.
1597 send(SslSocket, Data) -> ok | {error, reason()}
1599 Types:
1601 SslSocket = sslsocket()
1603 Data = iodata()
1604 Writes Data to SslSocket.
1606 A notable return value is {error, closed} indicating that the
1608 socket is closed.
1609 setopts(SslSocket, Options) -> ok | {error, reason()}
1611 Types:
1613 SslSocket = sslsocket()
1615 Options = [gen_tcp:option()]
1616 Sets options according to Options for socket SslSocket.
1618 shutdown(SslSocket, How) -> ok | {error, reason()}
1620 Types:
1622 SslSocket = sslsocket()
1624 How = read | write | read_write
1625 Immediately closes a socket in one or two directions.
1627 How == write means closing the socket for writing, reading from
1629 it is still possible.
1630 To be able to handle that the peer has done a shutdown on the
1632 write side, option {exit_on_close, false} is useful.
1633 ssl_accept(SslSocket) -> ok | {error, Reason}
1635 ssl_accept(Socket, TimeoutOrOptions) ->
1637 ok | {ok, sslsocket()} | {error, Reason}
1638 Types:
1640 Socket = sslsocket() | socket()
1642 TimeoutOrOptions = timeout() | [tls_server_option()]
1643 Reason = timeout | closed | {options, any()} | error_alert()
1644 Deprecated in OTP 21, use handshake/[1,2] instead.
1646 Note:
1648 handshake/[1,2] always returns a new socket.
1649 ssl_accept(Socket, Options, Timeout) ->
1652 ok | {ok, sslsocket()} | {error, Reason}
1653 Types:
1655 Socket = sslsocket() | socket()
1657 Options = [tls_server_option()]
1658 Timeout = timeout()
1659 Reason = timeout | closed | {options, any()} | error_alert()
1660 Deprecated in OTP 21, use handshake/[2,3] instead.
1662 Note:
1664 handshake/[2,3] always returns a new socket.
1665 sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1668 Types:
1670 SslSocket = sslsocket()
1672 Address = inet:ip_address()
1673 Port = inet:port_number()
1674 Returns the local address and port number of socket SslSocket.
1676 start() -> ok | {error, reason()}
1678 start(Type) -> ok | {error, Reason}
1679 Starts the SSL application. Default type is temporary.
1681 stop() -> ok
1683 Stops the SSL application.
1685 str_to_suite(CipherSuiteName) -> erl_cipher_suite()
1687 Types:
1689 CipherSuiteName =
1691 string() |
1692 {error, {not_recognized, CipherSuiteName :: string()}}
1693 Converts an RFC or OpenSSL name string to an erl_cipher_suite()
1695 Returns an error if the cipher suite is not supported or the
1696 name is not a valid cipher suite name.
1697 suite_to_openssl_str(CipherSuite) -> string()
1699 Types:
1701 CipherSuite = erl_cipher_suite()
1703 Converts erl_cipher_suite() to OpenSSL name string.
1705 PRE TLS-1.3 these names differ for RFC names
1707 suite_to_str(CipherSuite) -> string()
1709 Types:
1711 CipherSuite = erl_cipher_suite()
1713 Converts erl_cipher_suite() to RFC name string.
1715 transport_accept(ListenSocket) ->
1717 {ok, SslSocket} | {error, reason()}
1718 transport_accept(ListenSocket, Timeout) ->
1720 {ok, SslSocket} | {error, reason()}
1721 Types:
1723 ListenSocket = sslsocket()
1725 Timeout = timeout()
1726 SslSocket = sslsocket()
1727 Accepts an incoming connection request on a listen socket. Lis‐
1729 tenSocket must be a socket returned from listen/2. The socket
1730 returned is to be passed to handshake/[2,3] to complete hand‐
1731 shaking, that is, establishing the SSL/TLS/DTLS connection.
1732 Warning:
1734 Most API functions require that the TLS/DTLS connection is
1735 established to work as expected.
1736 The accepted socket inherits the options set for ListenSocket in
1739 listen/2.
1740 The default value for Timeout is infinity. If Timeout is speci‐
1742 fied and no connection is accepted within the given time,
1743 {error, timeout} is returned.
1744 versions() -> [VersionInfo]
1746 Types:
1748 VersionInfo =
1750 {ssl_app, string()} |
1751 {supported | available, [tls_version()]} |
1752 {supported_dtls | available_dtls, [dtls_version()]}
1753 Returns version information relevant for the SSL application.
1755 app_vsn:
1757 The application version of the SSL application.
1758 supported:
1760 SSL/TLS versions supported by default. Overridden by a ver‐
1761 sion option on connect/[2,3,4], listen/2, and
1762 ssl_accept/[1,2,3]. For the negotiated SSL/TLS version, see
1763 connection_information/1 .
1764 supported_dtls:
1766 DTLS versions supported by default. Overridden by a version
1767 option on connect/[2,3,4], listen/2, and
1768 ssl_accept/[1,2,3]. For the negotiated DTLS version, see
1769 connection_information/1 .
1770 available:
1772 All SSL/TLS versions supported by the SSL application. TLS
1773 1.2 requires sufficient support from the Crypto application.
1774 available_dtls:
1776 All DTLS versions supported by the SSL application. DTLS 1.2
1777 requires sufficient support from the Crypto application.
1778
1780 inet(3) and gen_tcp(3) gen_udp(3)
1781Ericsson AB ssl 9.6.1 ssl(3)