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 TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT
211 common_option() =
212 {protocol, protocol()} |
213 {handshake, handshake_completion()} |
214 {cert, cert()} |
215 {certfile, cert_pem()} |
216 {key, key()} |
217 {keyfile, key_pem()} |
218 {password, key_password()} |
219 {ciphers, cipher_suites()} |
220 {eccs, [named_curve()]} |
221 {signature_algs_cert, signature_schemes()} |
222 {supported_groups, supported_groups()} |
223 {secure_renegotiate, secure_renegotiation()} |
224 {depth, allowed_cert_chain_length()} |
225 {verify_fun, custom_verify()} |
226 {crl_check, crl_check()} |
227 {crl_cache, crl_cache_opts()} |
228 {max_handshake_size, handshake_size()} |
229 {partial_chain, root_fun()} |
230 {versions, protocol_versions()} |
231 {user_lookup_fun, custom_user_lookup()} |
232 {log_level, logging_level()} |
233 {log_alert, log_alert()} |
234 {hibernate_after, hibernate_after()} |
235 {padding_check, padding_check()} |
236 {beast_mitigation, beast_mitigation()} |
237 {ssl_imp, ssl_imp()}
238 protocol() = tls | dtls
240 Choose TLS or DTLS protocol for the transport layer security.
242 Defaults to tls. For DTLS other transports than UDP are not yet
243 supported.
244 handshake_completion() = hello | full
246 Defaults to full. If hello is specified the handshake will pause
248 after the hello message and give the user a possibility make
249 decisions based on hello extensions before continuing or abort‐
250 ing the handshake by calling handshake_continue/3 or hand‐
251 shake_cancel/1
252 cert() = public_key:der_encoded()
254 The DER-encoded users certificate. If this option is supplied,
256 it overrides option certfile.
257 cert_pem() = file:filename()
259 Path to a file containing the user certificate on PEM format.
261 key() =
263 {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' |
264 'PrivateKeyInfo',
265 public_key:der_encoded()} |
266 #{algorithm := rsa | dss | ecdsa,
267 engine := crypto:engine_ref(),
268 key_id := crypto:key_id(),
269 password => crypto:password()}
270 The DER-encoded user's private key or a map refering to a crypto
272 engine and its key reference that optionally can be password
273 protected, seealso crypto:engine_load/4 and Crypto's Users
274 Guide. If this option is supplied, it overrides option keyfile.
275 key_pem() = file:filename()
277 Path to the file containing the user's private PEM-encoded key.
279 As PEM-files can contain several entries, this option defaults
280 to the same file as given by option certfile.
281 key_password() = string()
283 String containing the user's password. Only used if the private
285 keyfile is password-protected.
286 cipher_suites() = ciphers()
288 Supported cipher suites. The function cipher_suites/2 can be
290 used to find all ciphers that are supported by default.
291 cipher_suites(all, 'tlsv1.2') can be called to find all avail‐
292 able cipher suites. Pre-Shared Key (RFC 4279 and RFC 5487),
293 Secure Remote Password (RFC 5054), RC4, 3DES, DES cipher suites,
294 and anonymous cipher suites only work if explicitly enabled by
295 this option; they are supported/enabled by the peer also. Anony‐
296 mous cipher suites are supported for testing purposes only and
297 are not be used when security matters.
298 signature_schemes() = [sign_scheme()]
300 In addition to the signature_algorithms extension from TLS 1.2,
302 TLS 1.3 (RFC 5246 Section 4.2.3)adds the signature_algo‐
303 rithms_cert extension which enables having special requirements
304 on the signatures used in the certificates that differs from the
305 requirements on digital signatures as a whole. If this is not
306 required this extension is not needed.
307 The client will send a signature_algorithms_cert extension
309 (ClientHello), if TLS version 1.3 or later is used, and the sig‐
310 nature_algs_cert option is explicitly specified. By default,
311 only the signature_algs extension is sent.
312 The signature schemes shall be ordered according to the client's
314 preference (favorite choice first).
315 supported_groups() = [group()]
317 TLS 1.3 introduces the "supported_groups" extension that is used
319 for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
320 shake. Both client and server can specify a list of parameters
321 that they are willing to use.
322 If it is not specified it will use a default list ([x25519,
324 x448, secp256r1, secp384r1]) that is filtered based on the
325 installed crypto library version.
326 secure_renegotiation() = boolean()
328 Specifies if to reject renegotiation attempt that does not live
330 up to RFC 5746. By default secure_renegotiate is set to true,
331 that is, secure renegotiation is enforced. If set to false
332 secure renegotiation will still be used if possible, but it
333 falls back to insecure renegotiation if the peer does not sup‐
334 port RFC 5746.
335 allowed_cert_chain_length() = integer()
337 Maximum number of non-self-issued intermediate certificates that
339 can follow the peer certificate in a valid certification path.
340 So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
341 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
342 can be PEER, CA, CA, ROOT-CA, and so on. The default value is 1.
343 custom_verify() =
345 {Verifyfun :: function(), InitialUserState :: any()}
346 The verification fun is to be defined as follows:
348 fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() |
350 {revoked, atom()}} |
351 {extension, #'Extension'{}}, InitialUserState :: term()) ->
352 {valid, UserState :: term()} | {valid_peer, UserState :: term()} |
353 {fail, Reason :: term()} | {unknown, UserState :: term()}.
354 The verification fun is called during the X509-path validation
357 when an error or an extension unknown to the SSL application is
358 encountered. It is also called when a certificate is considered
359 valid by the path validation to allow access to each certificate
360 in the path to the user application. It differentiates between
361 the peer certificate and the CA certificates by using valid_peer
362 or valid as second argument to the verification fun. See the
363 public_key User's Guide for definition of #'OTPCertificate'{}
364 and #'Extension'{}.
365 * If the verify callback fun returns {fail, Reason}, the veri‐
367 fication process is immediately stopped, an alert is sent to
368 the peer, and the TLS/DTLS handshake terminates.
369 * If the verify callback fun returns {valid, UserState}, the
371 verification process continues.
372 * If the verify callback fun always returns {valid, User‐
374 State}, the TLS/DTLS handshake does not terminate regarding
375 verification failures and the connection is established.
376 * If called with an extension unknown to the user application,
378 return value {unknown, UserState} is to be used.
379 Note that if the fun returns unknown for an extension marked
381 as critical, validation will fail.
382 Default option verify_fun in verify_peer mode:
384 {fun(_,{bad_cert, _} = Reason, _) ->
386 {fail, Reason};
387 (_,{extension, _}, UserState) ->
388 {unknown, UserState};
389 (_, valid, UserState) ->
390 {valid, UserState};
391 (_, valid_peer, UserState) ->
392 {valid, UserState}
393 end, []}
394 Default option verify_fun in mode verify_none:
397 {fun(_,{bad_cert, _}, UserState) ->
399 {valid, UserState};
400 (_,{extension, #'Extension'{critical = true}}, UserState) ->
401 {valid, UserState};
402 (_,{extension, _}, UserState) ->
403 {unknown, UserState};
404 (_, valid, UserState) ->
405 {valid, UserState};
406 (_, valid_peer, UserState) ->
407 {valid, UserState}
408 end, []}
409 The possible path validation errors are given on form {bad_cert,
412 Reason} where Reason is:
413 unknown_ca:
415 No trusted CA was found in the trusted store. The trusted CA
416 is normally a so called ROOT CA, which is a self-signed cer‐
417 tificate. Trust can be claimed for an intermediate CA
418 (trusted anchor does not have to be self-signed according to
419 X-509) by using option partial_chain.
420 selfsigned_peer:
422 The chain consisted only of one self-signed certificate.
423 PKIX X-509-path validation error:
425 For possible reasons, see public_key:pkix_path_validation/3
426 crl_check() = boolean() | peer | best_effort
428 Perform CRL (Certificate Revocation List) verification (pub‐
430 lic_key:pkix_crls_validate/3) on all the certificates during the
431 path validation (public_key:pkix_path_validation/3) of the cer‐
432 tificate chain. Defaults to false.
433 peer:
435 check is only performed on the peer certificate.
436 best_effort:
438 if certificate revocation status cannot be determined it
439 will be accepted as valid.
440 The CA certificates specified for the connection will be used to
442 construct the certificate chain validating the CRLs.
443 The CRLs will be fetched from a local or external cache. See
445 ssl_crl_cache_api(3).
446 crl_cache_opts() = [any()]
448 Specify how to perform lookup and caching of certificate revoca‐
450 tion lists. Module defaults to ssl_crl_cache with DbHandle
451 being internal and an empty argument list.
452 There are two implementations available:
454 ssl_crl_cache:
456 This module maintains a cache of CRLs. CRLs can be added to
457 the cache using the function ssl_crl_cache:insert/1, and
458 optionally automatically fetched through HTTP if the follow‐
459 ing argument is specified:
460 {http, timeout()}:
462 Enables fetching of CRLs specified as http URIs inX509
463 certificate extensions. Requires the OTP inets applica‐
464 tion.
465 ssl_crl_hash_dir:
467 This module makes use of a directory where CRLs are stored
468 in files named by the hash of the issuer name.
469 The file names consist of eight hexadecimal digits followed
471 by .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the
472 first version of the CRL, N starts at zero, and for each new
473 version, N is incremented by one. The OpenSSL utility
474 c_rehash creates symlinks according to this pattern.
475 For a given hash value, this module finds all consecutive
477 .r* files starting from zero, and those files taken together
478 make up the revocation list. CRL files whose nextUpdate
479 fields are in the past, or that are issued by a different CA
480 that happens to have the same name hash, are excluded.
481 The following argument is required:
483 {dir, string()}:
485 Specifies the directory in which the CRLs can be found.
486 root_fun() = function()
488 fun(Chain::[public_key:der_encoded()]) ->
490 {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
491 Claim an intermediate CA in the chain as trusted. TLS then per‐
494 forms public_key:pkix_path_validation/3 with the selected CA as
495 trusted anchor and the rest of the chain.
496 protocol_versions() = [protocol_version()]
498 TLS protocol versions supported by started clients and servers.
500 This option overrides the application environment option proto‐
501 col_version and dtls_protocol_version. If the environment option
502 is not set, it defaults to all versions, except SSL-3.0, sup‐
503 ported by the SSL application. See also ssl(6).
504 custom_user_lookup() =
506 {Lookupfun :: function(), UserState :: any()}
507 The lookup fun is to defined as follows:
509 fun(psk, PSKIdentity ::string(), UserState :: term()) ->
511 {ok, SharedSecret :: binary()} | error;
512 fun(srp, Username :: string(), UserState :: term()) ->
513 {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
514 DerivedKey :: binary()}} | error.
515 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
518 by the client and server to determine the shared secret. When
519 called by the client, PSKIdentity is set to the hint presented
520 by the server or to undefined. When called by the server, PSKI‐
521 dentity is the identity presented by the client.
522 For Secure Remote Password (SRP), the fun is only used by the
524 server to obtain parameters that it uses to generate its session
525 keys. DerivedKey is to be derived according to RFC 2945 and
526 RFC 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
527 word])])
528 session_id() = binary()
530 Identifies a TLS session.
532 log_alert() = boolean()
534 If set to false, error reports are not displayed. Deprecated in
536 OTP 22, use {log_level, logging_level()} instead.
537 logging_level() = logger:level()
539 Specifies the log level for TLS/DTLS. At verbosity level notice
541 and above error reports are displayed in TLS/DTLS. The level
542 debug triggers verbose logging of TLS/DTLS protocol messages.
543 hibernate_after() = timeout()
545 When an integer-value is specified, TLS/DTLS-connection goes
547 into hibernation after the specified number of milliseconds of
548 inactivity, thus reducing its memory footprint. When undefined
549 is specified (this is the default), the process never goes into
550 hibernation.
551 handshake_size() = integer()
553 Integer (24 bits unsigned). Used to limit the size of valid TLS
555 handshake packets to avoid DoS attacks. Defaults to 256*1024.
556 padding_check() = boolean()
558 Affects TLS-1.0 connections only. If set to false, it disables
560 the block cipher padding check to be able to interoperate with
561 legacy software.
562 Warning:
564 Using {padding_check, boolean()} makes TLS vulnerable to the
565 Poodle attack.
566 beast_mitigation() = one_n_minus_one | zero_n | disabled
569 Affects SSL-3.0 and TLS-1.0 connections only. Used to change the
571 BEAST mitigation strategy to interoperate with legacy software.
572 Defaults to one_n_minus_one.
573 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
575 zero_n - Perform 0/n BEAST mitigation.
577 disabled - Disable BEAST mitigation.
579 Warning:
581 Using {beast_mitigation, disabled} makes SSL-3.0 or TLS-1.0 vul‐
582 nerable to the BEAST attack.
583 ssl_imp() = new | old
586 Deprecated since OTP-17, has no affect.
588 TLS/DTLS OPTION DESCRIPTIONS - CLIENT
590 client_option() =
591 {verify, client_verify_type()} |
592 {reuse_session, client_reuse_session()} |
593 {reuse_sessions, client_reuse_sessions()} |
594 {cacerts, client_cacerts()} |
595 {cacertfile, client_cafile()} |
596 {alpn_advertised_protocols, client_alpn()} |
597 {client_preferred_next_protocols,
598 client_preferred_next_protocols()} |
599 {psk_identity, client_psk_identity()} |
600 {srp_identity, client_srp_identity()} |
601 {server_name_indication, sni()} |
602 {customize_hostname_check, customize_hostname_check()} |
603 {signature_algs, client_signature_algs()} |
604 {fallback, fallback()}
605 client_verify_type() = verify_type()
607 In mode verify_none the default behavior is to allow all
609 x509-path validation errors. See also option verify_fun.
610 client_reuse_session() = session_id()
612 Reuses a specific session earlier saved with the option {re‐
614 use_sessions, save} since OTP-21.3
615 client_reuse_sessions() = boolean() | save
617 When save is specified a new connection will be negotiated and
619 saved for later reuse. The session ID can be fetched with con‐
620 nection_information/2 and used with the client option reuse_ses‐
621 sion The boolean value true specifies that if possible, automa‐
622 tized session reuse will be performed. If a new session is cre‐
623 ated, and is unique in regard to previous stored sessions, it
624 will be saved for possible later reuse. Since OTP-21.3
625 client_cacerts() = [public_key:der_encoded()]
627 The DER-encoded trusted certificates. If this option is supplied
629 it overrides option cacertfile.
630 client_cafile() = file:filename()
632 Path to a file containing PEM-encoded CA certificates. The CA
634 certificates are used during server authentication and when
635 building the client certificate chain.
636 client_alpn() = [app_level_protocol()]
638 The list of protocols supported by the client to be sent to the
640 server to be used for an Application-Layer Protocol Negotiation
641 (ALPN). If the server supports ALPN then it will choose a proto‐
642 col from this list; otherwise it will fail the connection with a
643 "no_application_protocol" alert. A server that does not support
644 ALPN will ignore this value.
645 The list of protocols must not contain an empty binary.
647 The negotiated protocol can be retrieved using the negoti‐
649 ated_protocol/1 function.
650 client_preferred_next_protocols() =
652 {Precedence :: server | client,
653 ClientPrefs :: [app_level_protocol()]} |
654 {Precedence :: server | client,
655 ClientPrefs :: [app_level_protocol()],
656 Default :: app_level_protocol()}
657 Indicates that the client is to try to perform Next Protocol
659 Negotiation.
660 If precedence is server, the negotiated protocol is the first
662 protocol to be shown on the server advertised list, which is
663 also on the client preference list.
664 If precedence is client, the negotiated protocol is the first
666 protocol to be shown on the client preference list, which is
667 also on the server advertised list.
668 If the client does not support any of the server advertised pro‐
670 tocols or the server does not advertise any protocols, the
671 client falls back to the first protocol in its list or to the
672 default protocol (if a default is supplied). If the server does
673 not support Next Protocol Negotiation, the connection terminates
674 if no default protocol is supplied.
675 client_psk_identity() = psk_identity()
677 Specifies the identity the client presents to the server. The
679 matching secret is found by calling user_lookup_fun
680 client_srp_identity() = srp_identity()
682 Specifies the username and password to use to authenticate to
684 the server.
685 sni() = hostname() | disable
687 Specify the hostname to be used in TLS Server Name Indication
689 extension. If not specified it will default to the Host argument
690 of connect/[3,4] unless it is of type inet:ipaddress().
691 The HostName will also be used in the hostname verification of
693 the peer certificate using public_key:pkix_verify_hostname/2.
694 The special value disable prevents the Server Name Indication
696 extension from being sent and disables the hostname verification
697 check public_key:pkix_verify_hostname/2
698 customize_hostname_check() = list()
700 Customizes the hostname verification of the peer certificate, as
702 different protocols that use TLS such as HTTP or LDAP may want
703 to do it differently, for possible options see pub‐
704 lic_key:pkix_verify_hostname/3
705 fallback() = boolean()
707 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired
709 TLS version downgrade. Defaults to false
710 Warning:
712 Note this option is not needed in normal TLS usage and should
713 not be used to implement new clients. But legacy clients that
714 retries connections in the following manner
715 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1',
717 'tlsv1', 'sslv3']}])
718 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1',
720 'sslv3']}, {fallback, true}])
721 ssl:connect(Host, Port, [...{versions, ['tlsv1', 'sslv3']},
723 {fallback, true}])
724 ssl:connect(Host, Port, [...{versions, ['sslv3']}, {fallback,
726 true}])
727 may use it to avoid undesired TLS version downgrade. Note that
729 TLS_FALLBACK_SCSV must also be supported by the server for the
730 prevention to work.
731 client_signature_algs() = signature_algs()
734 In addition to the algorithms negotiated by the cipher suite
736 used for key exchange, payload encryption, message authentica‐
737 tion and pseudo random calculation, the TLS signature algorithm
738 extension Section 7.4.1.4.1 in RFC 5246 may be used, from TLS
739 1.2, to negotiate which signature algorithm to use during the
740 TLS handshake. If no lower TLS versions than 1.2 are supported,
741 the client will send a TLS signature algorithm extension with
742 the algorithms specified by this option. Defaults to
743 [
745 %% SHA2
746 {sha512, ecdsa},
747 {sha512, rsa},
748 {sha384, ecdsa},
749 {sha384, rsa},
750 {sha256, ecdsa},
751 {sha256, rsa},
752 {sha224, ecdsa},
753 {sha224, rsa},
754 %% SHA
755 {sha, ecdsa},
756 {sha, rsa},
757 {sha, dsa},
758 ]
759 The algorithms should be in the preferred order. Selected signa‐
761 ture algorithm can restrict which hash functions that may be
762 selected. Default support for {md5, rsa} removed in ssl-8.0
763 TLS/DTLS OPTION DESCRIPTIONS - SERVER
765 server_option() =
766 {cacerts, server_cacerts()} |
767 {cacertfile, server_cafile()} |
768 {dh, dh_der()} |
769 {dhfile, dh_file()} |
770 {verify, server_verify_type()} |
771 {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
772 {reuse_sessions, server_reuse_sessions()} |
773 {reuse_session, server_reuse_session()} |
774 {alpn_preferred_protocols, server_alpn()} |
775 {next_protocols_advertised, server_next_protocol()} |
776 {psk_identity, server_psk_identity()} |
777 {honor_cipher_order, boolean()} |
778 {sni_hosts, sni_hosts()} |
779 {sni_fun, sni_fun()} |
780 {honor_cipher_order, honor_cipher_order()} |
781 {honor_ecc_order, honor_ecc_order()} |
782 {client_renegotiation, client_renegotiation()} |
783 {signature_algs, server_signature_algs()}
784 server_cacerts() = [public_key:der_encoded()]
786 The DER-encoded trusted certificates. If this option is supplied
788 it overrides option cacertfile.
789 server_cafile() = file:filename()
791 Path to a file containing PEM-encoded CA certificates. The CA
793 certificates are used to build the server certificate chain and
794 for client authentication. The CAs are also used in the list of
795 acceptable client CAs passed to the client when a certificate is
796 requested. Can be omitted if there is no need to verify the
797 client and if there are no intermediate CAs for the server cer‐
798 tificate.
799 dh_der() = binary()
801 The DER-encoded Diffie-Hellman parameters. If specified, it
803 overrides option dhfile.
804 Warning:
806 The dh_der option is not supported by TLS 1.3. Use the sup‐
807 ported_groups option instead.
808 dh_file() = file:filename()
811 Path to a file containing PEM-encoded Diffie Hellman parameters
813 to be used by the server if a cipher suite using Diffie Hellman
814 key exchange is negotiated. If not specified, default parameters
815 are used.
816 Warning:
818 The dh_file option is not supported by TLS 1.3. Use the sup‐
819 ported_groups option instead.
820 server_verify_type() = verify_type()
823 A server only does x509-path validation in mode verify_peer, as
825 it then sends a certificate request to the client (this message
826 is not sent if the verify option is verify_none). You can then
827 also want to specify option fail_if_no_peer_cert.
828 fail_if_no_peer_cert() = boolean()
830 Used together with {verify, verify_peer} by an TLS/DTLS server.
832 If set to true, the server fails if the client does not have a
833 certificate to send, that is, sends an empty certificate. If set
834 to false, it fails only if the client sends an invalid certifi‐
835 cate (an empty certificate is considered valid). Defaults to
836 false.
837 server_reuse_sessions() = boolean()
839 The boolean value true specifies that the server will agree to
841 reuse sessions. Setting it to false will result in an empty ses‐
842 sion table, that is no sessions will be reused. See also option
843 reuse_session
844 server_reuse_session() = function()
846 Enables the TLS/DTLS server to have a local policy for deciding
848 if a session is to be reused or not. Meaningful only if re‐
849 use_sessions is set to true. SuggestedSessionId is a binary(),
850 PeerCert is a DER-encoded certificate, Compression is an enumer‐
851 ation integer, and CipherSuite is of type ciphersuite().
852 server_alpn() = [app_level_protocol()]
854 Indicates the server will try to perform Application-Layer Pro‐
856 tocol Negotiation (ALPN).
857 The list of protocols is in order of preference. The protocol
859 negotiated will be the first in the list that matches one of the
860 protocols advertised by the client. If no protocol matches, the
861 server will fail the connection with a "no_application_protocol"
862 alert.
863 The negotiated protocol can be retrieved using the negoti‐
865 ated_protocol/1 function.
866 server_next_protocol() = [app_level_protocol()]
868 List of protocols to send to the client if the client indicates
870 that it supports the Next Protocol extension. The client can
871 select a protocol that is not on this list. The list of proto‐
872 cols must not contain an empty binary. If the server negotiates
873 a Next Protocol, it can be accessed using the negoti‐
874 ated_next_protocol/1 method.
875 server_psk_identity() = psk_identity()
877 Specifies the server identity hint, which the server presents to
879 the client.
880 honor_cipher_order() = boolean()
882 If set to true, use the server preference for cipher selection.
884 If set to false (the default), use the client preference.
885 sni_hosts() =
887 [{hostname(), [server_option() | common_option()]}]
888 If the server receives a SNI (Server Name Indication) from the
890 client matching a host listed in the sni_hosts option, the spe‐
891 cific options for that host will override previously specified
892 options. The option sni_fun, and sni_hosts are mutually exclu‐
893 sive.
894 sni_fun() = function()
896 If the server receives a SNI (Server Name Indication) from the
898 client, the given function will be called to retrieve
899 [server_option()] for the indicated server. These options will
900 be merged into predefined [server_option()] list. The function
901 should be defined as: fun(ServerName :: string()) ->
902 [server_option()] and can be specified as a fun or as named fun
903 module:function/1 The option sni_fun, and sni_hosts are mutually
904 exclusive.
905 client_renegotiation() = boolean()
907 In protocols that support client-initiated renegotiation, the
909 cost of resources of such an operation is higher for the server
910 than the client. This can act as a vector for denial of service
911 attacks. The SSL application already takes measures to counter-
912 act such attempts, but client-initiated renegotiation can be
913 strictly disabled by setting this option to false. The default
914 value is true. Note that disabling renegotiation can result in
915 long-lived connections becoming unusable due to limits on the
916 number of messages the underlying cipher suite can encipher.
917 honor_cipher_order() = boolean()
919 If true, use the server's preference for cipher selection. If
921 false (the default), use the client's preference.
922 honor_ecc_order() = boolean()
924 If true, use the server's preference for ECC curve selection. If
926 false (the default), use the client's preference.
927 server_signature_algs() = signature_algs()
929 The algorithms specified by this option will be the ones
931 accepted by the server in a signature algorithm negotiation,
932 introduced in TLS-1.2. The algorithms will also be offered to
933 the client if a client certificate is requested. For more
934 details see the corresponding client option.
935
937 append_cipher_suites(Deferred, Suites) -> ciphers()
938 Types:
940 Deferred = ciphers() | cipher_filters()
942 Suites = ciphers()
943 Make Deferred suites become the least preferred suites, that is
945 put them at the end of the cipher suite list Suites after remov‐
946 ing them from Suites if present. Deferred may be a list of
947 cipher suits or a list of filters in which case the filters are
948 use on Suites to extract the Deferred cipher list.
949 cipher_suites() -> [old_cipher_suite()] | [string()]
951 cipher_suites(Type) -> [old_cipher_suite() | string()]
953 Types:
955 Type = erlang | openssl | all
957 Deprecated in OTP 21, use cipher_suites/2 instead.
959 cipher_suites(Supported, Version) -> ciphers()
961 Types:
963 Supported = default | all | anonymous
965 Version = protocol_version()
966 Returns all default or all supported (except anonymous), or all
968 anonymous cipher suites for a TLS version
969 cipher_suites(Supported, Version, StringType :: rfc | openssl) ->
971 [string()]
972 Types:
974 Supported = default | all | anonymous
976 Version = protocol_version()
977 Same as cipher_suites/2 but lists RFC or OpenSSL string names
979 instead of erl_cipher_suite()
980 eccs() -> NamedCurves
982 eccs(Version) -> NamedCurves
984 Types:
986 Version = protocol_version()
988 NamedCurves = [named_curve()]
989 Returns a list of supported ECCs. eccs() is equivalent to call‐
991 ing eccs(Protocol) with all supported protocols and then dedu‐
992 plicating the output.
993 clear_pem_cache() -> ok
995 PEM files, used by ssl API-functions, are cached. The cache is
997 regularly checked to see if any cache entries should be invali‐
998 dated, however this function provides a way to unconditionally
999 clear the whole cache.
1000 connect(TCPSocket, TLSOptions) ->
1002 {ok, sslsocket()} |
1003 {error, reason()} |
1004 {option_not_a_key_value_tuple, any()}
1005 connect(TCPSocket, TLSOptions, Timeout) ->
1007 {ok, sslsocket()} | {error, reason()}
1008 Types:
1010 TCPSocket = socket()
1012 TLSOptions = [tls_client_option()]
1013 Timeout = timeout()
1014 Upgrades a gen_tcp, or equivalent, connected socket to an TLS
1016 socket, that is, performs the client-side TLS handshake.
1017 Note:
1019 If the option verify is set to verify_peer the option
1020 server_name_indication shall also be specified, if it is not no
1021 Server Name Indication extension will be sent, and pub‐
1022 lic_key:pkix_verify_hostname/2 will be called with the IP-
1023 address of the connection as ReferenceID, which is proably not
1024 what you want.
1025 If the option {handshake, hello} is used the handshake is paused
1028 after receiving the server hello message and the success
1029 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1030 Thereafter the handshake is continued or canceled by calling
1031 handshake_continue/3 or handshake_cancel/1.
1032 If the option active is set to once, true or an integer value,
1034 the process owning the sslsocket will receive messages of type
1035 active_msgs()
1036 connect(Host, Port, TLSOptions) ->
1038 {ok, sslsocket()} |
1039 {ok, sslsocket(), Ext :: protocol_extensions()} |
1040 {error, reason()} |
1041 {option_not_a_key_value_tuple, any()}
1042 connect(Host, Port, TLSOptions, Timeout) ->
1044 {ok, sslsocket()} |
1045 {ok, sslsocket(), Ext :: protocol_extensions()} |
1046 {error, reason()} |
1047 {option_not_a_key_value_tuple, any()}
1048 Types:
1050 Host = host()
1052 Port = inet:port_number()
1053 TLSOptions = [tls_client_option()]
1054 Timeout = timeout()
1055 Opens an TLS/DTLS connection to Host, Port.
1057 When the option verify is set to verify_peer the check pub‐
1059 lic_key:pkix_verify_hostname/2 will be performed in addition to
1060 the usual x509-path validation checks. If the check fails the
1061 error {bad_cert, hostname_check_failed} will be propagated to
1062 the path validation fun verify_fun, where it is possible to do
1063 customized checks by using the full possibilities of the pub‐
1064 lic_key:pkix_verify_hostname/3 API. When the option
1065 server_name_indication is provided, its value (the DNS name)
1066 will be used as ReferenceID to public_key:pkix_verify_host‐
1067 name/2. When no server_name_indication option is given, the Host
1068 argument will be used as Server Name Indication extension. The
1069 Host argument will also be used for the public_key:pkix_ver‐
1070 ify_hostname/2 check and if the Host argument is an
1071 inet:ip_address() the ReferenceID used for the check will be
1072 {ip, Host} otherwise dns_id will be assumed with a fallback to
1073 ip if that fails.
1074 Note:
1076 According to good practices certificates should not use IP-
1077 addresses as "server names". It would be very surprising if this
1078 happen outside a closed network.
1079 If the option {handshake, hello} is used the handshake is paused
1082 after receiving the server hello message and the success
1083 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1084 Thereafter the handshake is continued or canceled by calling
1085 handshake_continue/3 or handshake_cancel/1.
1086 If the option active is set to once, true or an integer value,
1088 the process owning the sslsocket will receive messages of type
1089 active_msgs()
1090 close(SslSocket) -> ok | {error, Reason}
1092 Types:
1094 SslSocket = sslsocket()
1096 Reason = any()
1097 Closes an TLS/DTLS connection.
1099 close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}
1101 Types:
1103 SslSocket = sslsocket()
1105 How = timeout() | {NewController :: pid(), timeout()}
1106 Reason = any()
1107 Closes or downgrades an TLS connection. In the latter case the
1109 transport connection will be handed over to the NewController
1110 process after receiving the TLS close alert from the peer. The
1111 returned transport socket will have the following options set:
1112 [{active, false}, {packet, 0}, {mode, binary}]
1113 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1115 Types:
1117 SslSocket = sslsocket()
1119 NewOwner = pid()
1120 Reason = any()
1121 Assigns a new controlling process to the SSL socket. A control‐
1123 ling process is the owner of an SSL socket, and receives all
1124 messages from the socket.
1125 connection_information(SslSocket) ->
1127 {ok, Result} | {error, reason()}
1128 Types:
1130 SslSocket = sslsocket()
1132 Result = [{OptionName, OptionValue}]
1133 OptionName = atom()
1134 OptionValue = any()
1135 Returns the most relevant information about the connection, ssl
1137 options that are undefined will be filtered out. Note that val‐
1138 ues that affect the security of the connection will only be
1139 returned if explicitly requested by connection_information/2.
1140 Note:
1142 The legacy Item = cipher_suite is still supported and returns
1143 the cipher suite on its (undocumented) legacy format. It should
1144 be replaced by selected_cipher_suite.
1145 connection_information(SslSocket, Items) ->
1148 {ok, Result} | {error, reason()}
1149 Types:
1151 SslSocket = sslsocket()
1153 Items = [OptionName]
1154 Result = [{OptionName, OptionValue}]
1155 OptionName = atom()
1156 OptionValue = any()
1157 Returns the requested information items about the connection, if
1159 they are defined.
1160 Note that client_random, server_random and master_secret are
1162 values that affect the security of connection. Meaningful atoms,
1163 not specified above, are the ssl option names.
1164 Note:
1166 If only undefined options are requested the resulting list can
1167 be empty.
1168 filter_cipher_suites(Suites, Filters) -> Ciphers
1171 Types:
1173 Suites = ciphers()
1175 Filters = cipher_filters()
1176 Ciphers = ciphers()
1177 Removes cipher suites if any of the filter functions returns
1179 false for any part of the cipher suite. This function also calls
1180 default filter functions to make sure the cipher suites are sup‐
1181 ported by crypto. If no filter function is supplied for some
1182 part the default behaviour is fun(Algorithm) -> true.
1183 format_error(Reason :: {error, Reason}) -> string()
1185 Types:
1187 Reason = any()
1189 Presents the error returned by an SSL function as a printable
1191 string.
1192 getopts(SslSocket, OptionNames) ->
1194 {ok, [gen_tcp:option()]} | {error, reason()}
1195 Types:
1197 SslSocket = sslsocket()
1199 OptionNames = [gen_tcp:option_name()]
1200 Gets the values of the specified socket options.
1202 getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1204 getstat(SslSocket, Options) ->
1206 {ok, OptionValues} | {error, inet:posix()}
1207 Types:
1209 SslSocket = sslsocket()
1211 Options = [inet:stat_option()]
1212 OptionValues = [{inet:stat_option(), integer()}]
1213 Gets one or more statistic options for the underlying TCP
1215 socket.
1216 See inet:getstat/2 for statistic options description.
1218 handshake(HsSocket) ->
1220 {ok, SslSocket} |
1221 {ok, SslSocket, Ext} |
1222 {error, Reason}
1223 handshake(HsSocket, Timeout) ->
1225 {ok, SslSocket} |
1226 {ok, SslSocket, Ext} |
1227 {error, Reason}
1228 Types:
1230 HsSocket = sslsocket()
1232 Timeout = timeout()
1233 SslSocket = sslsocket()
1234 Ext = protocol_extensions()
1235 Reason = closed | timeout | error_alert()
1236 Performs the SSL/TLS/DTLS server-side handshake.
1238 Returns a new TLS/DTLS socket if the handshake is successful.
1240 If the option active is set to once, true or an integer value,
1242 the process owning the sslsocket will receive messages of type
1243 active_msgs()
1244 handshake(Socket, Options) ->
1246 {ok, SslSocket} |
1247 {ok, SslSocket, Ext} |
1248 {error, Reason}
1249 handshake(Socket, Options, Timeout) ->
1251 {ok, SslSocket} |
1252 {ok, SslSocket, Ext} |
1253 {error, Reason}
1254 Types:
1256 Socket = socket() | sslsocket()
1258 SslSocket = sslsocket()
1259 Options = [server_option()]
1260 Timeout = timeout()
1261 Ext = protocol_extensions()
1262 Reason = closed | timeout | {options, any()} | error_alert()
1263 If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1265 lent, socket to an SSL socket, that is, performs the SSL/TLS
1266 server-side handshake and returns a TLS socket.
1267 Warning:
1269 The Socket shall be in passive mode ({active, false}) before
1270 calling this function or else the behavior of this function is
1271 undefined.
1272 If Socket is an sslsocket() : provides extra SSL/TLS/DTLS
1275 options to those specified in listen/2 and then performs the
1276 SSL/TLS/DTLS handshake. Returns a new TLS/DTLS socket if the
1277 handshake is successful.
1278 If option {handshake, hello} is specified the handshake is
1280 paused after receiving the client hello message and the success
1281 response is {ok, SslSocket, Ext} instead of {ok, SslSocket}.
1282 Thereafter the handshake is continued or canceled by calling
1283 handshake_continue/3 or handshake_cancel/1.
1284 If the option active is set to once, true or an integer value,
1286 the process owning the sslsocket will receive messages of type
1287 active_msgs()
1288 handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1290 Cancel the handshake with a fatal USER_CANCELED alert.
1292 handshake_continue(HsSocket, Options) ->
1294 {ok, SslSocket} | {error, Reason}
1295 handshake_continue(HsSocket, Options, Timeout) ->
1297 {ok, SslSocket} | {error, Reason}
1298 Types:
1300 HsSocket = sslsocket()
1302 Options = [tls_client_option() | tls_server_option()]
1303 Timeout = timeout()
1304 SslSocket = sslsocket()
1305 Reason = closed | timeout | error_alert()
1306 Continue the SSL/TLS handshake possiby with new, additional or
1308 changed options.
1309 listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1311 Types:
1313 Port = inet:port_number()
1315 Options = [tls_server_option()]
1316 ListenSocket = sslsocket()
1317 Creates an SSL listen socket.
1319 negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1321 Types:
1323 SslSocket = sslsocket()
1325 Protocol = binary()
1326 Reason = protocol_not_negotiated
1327 Returns the protocol negotiated through ALPN or NPN extensions.
1329 peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1331 Types:
1333 SslSocket = sslsocket()
1335 Cert = binary()
1336 The peer certificate is returned as a DER-encoded binary. The
1338 certificate can be decoded with public_key:pkix_decode_cert/2
1339 peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1341 Types:
1343 SslSocket = sslsocket()
1345 Address = inet:ip_address()
1346 Port = inet:port_number()
1347 Returns the address and port number of the peer.
1349 prepend_cipher_suites(Preferred, Suites) -> ciphers()
1351 Types:
1353 Preferred = ciphers() | cipher_filters()
1355 Suites = ciphers()
1356 Make Preferred suites become the most preferred suites that is
1358 put them at the head of the cipher suite list Suites after
1359 removing them from Suites if present. Preferred may be a list of
1360 cipher suits or a list of filters in which case the filters are
1361 use on Suites to extract the preferred cipher list.
1362 prf(SslSocket, Secret, Label, Seed, WantedLength) ->
1364 {ok, binary()} | {error, reason()}
1365 Types:
1367 SslSocket = sslsocket()
1369 Secret = binary() | master_secret
1370 Label = binary()
1371 Seed = [binary() | prf_random()]
1372 WantedLength = integer() >= 0
1373 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1375 ate extra key material. It either takes user-generated values
1376 for Secret and Seed or atoms directing it to use a specific
1377 value from the session security parameters.
1378 Can only be used with TLS/DTLS connections; {error, undefined}
1380 is returned for SSLv3 connections.
1381 recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
1383 recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
1385 Types:
1387 SslSocket = sslsocket()
1389 Length = integer()
1390 Data = binary() | list() | HttpPacket
1391 Timeout = timeout()
1392 HttpPacket = any()
1393 See the description of HttpPacket in erlang:decode_packet/3
1394 in ERTS.
1395 Receives a packet from a socket in passive mode. A closed socket
1397 is indicated by return value {error, closed}.
1398 Argument Length is meaningful only when the socket is in mode
1400 raw and denotes the number of bytes to read. If Length = 0, all
1401 available bytes are returned. If Length > 0, exactly Length
1402 bytes are returned, or an error; possibly discarding less than
1403 Length bytes of data when the socket gets closed from the other
1404 side.
1405 Optional argument Timeout specifies a time-out in milliseconds.
1407 The default value is infinity.
1408 renegotiate(SslSocket) -> ok | {error, reason()}
1410 Types:
1412 SslSocket = sslsocket()
1414 Initiates a new handshake. A notable return value is {error,
1416 renegotiation_rejected} indicating that the peer refused to go
1417 through with the renegotiation, but the connection is still
1418 active using the previously negotiated session.
1419 send(SslSocket, Data) -> ok | {error, reason()}
1421 Types:
1423 SslSocket = sslsocket()
1425 Data = iodata()
1426 Writes Data to SslSocket.
1428 A notable return value is {error, closed} indicating that the
1430 socket is closed.
1431 setopts(SslSocket, Options) -> ok | {error, reason()}
1433 Types:
1435 SslSocket = sslsocket()
1437 Options = [gen_tcp:option()]
1438 Sets options according to Options for socket SslSocket.
1440 shutdown(SslSocket, How) -> ok | {error, reason()}
1442 Types:
1444 SslSocket = sslsocket()
1446 How = read | write | read_write
1447 Immediately closes a socket in one or two directions.
1449 How == write means closing the socket for writing, reading from
1451 it is still possible.
1452 To be able to handle that the peer has done a shutdown on the
1454 write side, option {exit_on_close, false} is useful.
1455 ssl_accept(SslSocket) -> ok | {error, Reason}
1457 ssl_accept(Socket, TimeoutOrOptions) ->
1459 ok | {ok, sslsocket()} | {error, Reason}
1460 Types:
1462 Socket = sslsocket() | socket()
1464 TimeoutOrOptions = timeout() | [tls_server_option()]
1465 Reason = timeout | closed | {options, any()} | error_alert()
1466 Deprecated in OTP 21, use handshake/[1,2] instead.
1468 Note:
1470 handshake/[1,2] always returns a new socket.
1471 ssl_accept(Socket, Options, Timeout) ->
1474 ok | {ok, sslsocket()} | {error, Reason}
1475 Types:
1477 Socket = sslsocket() | socket()
1479 Options = [tls_server_option()]
1480 Timeout = timeout()
1481 Reason = timeout | closed | {options, any()} | error_alert()
1482 Deprecated in OTP 21, use handshake/[2,3] instead.
1484 Note:
1486 handshake/[2,3] always returns a new socket.
1487 sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1490 Types:
1492 SslSocket = sslsocket()
1494 Address = inet:ip_address()
1495 Port = inet:port_number()
1496 Returns the local address and port number of socket SslSocket.
1498 start() -> ok | {error, reason()}
1500 start(Type) -> ok | {error, Reason}
1501 Starts the SSL application. Default type is temporary.
1503 stop() -> ok
1505 Stops the SSL application.
1507 str_to_suite(CipherSuiteName) -> erl_cipher_suite()
1509 Types:
1511 CipherSuiteName =
1513 string() |
1514 {error, {not_recognized, CipherSuiteName :: string()}}
1515 Converts an RFC or OpenSSL name string to an erl_cipher_suite()
1517 Returns an error if the cipher suite is not supported or the
1518 name is not a valid cipher suite name.
1519 suite_to_openssl_str(CipherSuite) -> string()
1521 Types:
1523 CipherSuite = erl_cipher_suite()
1525 Converts erl_cipher_suite() to OpenSSL name string.
1527 PRE TLS-1.3 these names differ for RFC names
1529 suite_to_str(CipherSuite) -> string()
1531 Types:
1533 CipherSuite = erl_cipher_suite()
1535 Converts erl_cipher_suite() to RFC name string.
1537 transport_accept(ListenSocket) ->
1539 {ok, SslSocket} | {error, reason()}
1540 transport_accept(ListenSocket, Timeout) ->
1542 {ok, SslSocket} | {error, reason()}
1543 Types:
1545 ListenSocket = sslsocket()
1547 Timeout = timeout()
1548 SslSocket = sslsocket()
1549 Accepts an incoming connection request on a listen socket. Lis‐
1551 tenSocket must be a socket returned from listen/2. The socket
1552 returned is to be passed to handshake/[2,3] to complete hand‐
1553 shaking, that is, establishing the SSL/TLS/DTLS connection.
1554 Warning:
1556 Most API functions require that the TLS/DTLS connection is
1557 established to work as expected.
1558 The accepted socket inherits the options set for ListenSocket in
1561 listen/2.
1562 The default value for Timeout is infinity. If Timeout is speci‐
1564 fied and no connection is accepted within the given time,
1565 {error, timeout} is returned.
1566 versions() -> [VersionInfo]
1568 Types:
1570 VersionInfo =
1572 {ssl_app, string()} |
1573 {supported | available, [tls_version()]} |
1574 {supported_dtls | available_dtls, [dtls_version()]}
1575 Returns version information relevant for the SSL application.
1577 app_vsn:
1579 The application version of the SSL application.
1580 supported:
1582 SSL/TLS versions supported by default. Overridden by a ver‐
1583 sion option on connect/[2,3,4], listen/2, and
1584 ssl_accept/[1,2,3]. For the negotiated SSL/TLS version, see
1585 connection_information/1 .
1586 supported_dtls:
1588 DTLS versions supported by default. Overridden by a version
1589 option on connect/[2,3,4], listen/2, and
1590 ssl_accept/[1,2,3]. For the negotiated DTLS version, see
1591 connection_information/1 .
1592 available:
1594 All SSL/TLS versions supported by the SSL application. TLS
1595 1.2 requires sufficient support from the Crypto application.
1596 available_dtls:
1598 All DTLS versions supported by the SSL application. DTLS 1.2
1599 requires sufficient support from the Crypto application.
1600
1602 inet(3) and gen_tcp(3) gen_udp(3)
1603Ericsson AB ssl 9.4 ssl(3)