1ssl(3)                     Erlang Module Definition                     ssl(3)
2
3
4

NAME

6       ssl - Interface Functions for Secure Socket Layer
7

DESCRIPTION

9       This module contains interface functions for the TLS/DTLS protocol. For
10       detailed information about the supported standards see ssl(6).
11

DATA TYPES

13   Types used in TLS/DTLS
14       socket() = gen_tcp:socket()
15
16       sslsocket() = any()
17
18              An opaque reference to the TLS/DTLS connection, may be used  for
19              equality matching.
20
21       tls_option() = tls_client_option() | tls_server_option()
22
23       tls_client_option() =
24           client_option() |
25           common_option() |
26           socket_option() |
27           transport_option()
28
29       tls_server_option() =
30           server_option() |
31           common_option() |
32           socket_option() |
33           transport_option()
34
35       socket_option() =
36           gen_tcp:connect_option() |
37           gen_tcp:listen_option() |
38           gen_udp:option()
39
40              The default socket options are [{mode,list},{packet, 0},{header,
41              0},{active, true}].
42
43              For valid options, see the inet(3),  gen_tcp(3)  and  gen_udp(3)
44              manual  pages  in Kernel. Note that stream oriented options such
45              as packet are only relevant for TLS and not DTLS
46
47       active_msgs() =
48           {ssl, sslsocket(), Data :: binary() | list()} |
49           {ssl_closed, sslsocket()} |
50           {ssl_error, sslsocket(), Reason :: any()} |
51           {ssl_passive, sslsocket()}
52
53              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
57              The ssl_passive message is sent only when the socket is in  {ac‐
58              tive,  N}  mode  and the counter dropped to 0. It indicates that
59              the socket has transitioned to passive ({active, false}) mode.
60
61       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
74              Defaults to {gen_tcp, tcp, tcp_closed,  tcp_error,  tcp_passive}
75              for  TLS  (for  backward compatibility a four tuple will be con‐
76              verted to a  five  tuple  with  the  last  element  "second_ele‐
77              ment"_passive)  and  {gen_udp,  udp,  udp_closed, udp_error} for
78              DTLS (might also be changed to five tuple in the future). Can be
79              used  to customize the transport layer. The tag values should be
80              the values used by the underlying transport in its  active  mode
81              messages.  For TLS the callback module must implement a reliable
82              transport protocol, behave as gen_tcp, and have functions corre‐
83              sponding  to  inet:setopts/2,  inet:getopts/2,  inet:peername/1,
84              inet:sockname/1,  and  inet:port/1.  The  callback  gen_tcp   is
85              treated specially and calls inet directly. For DTLS this feature
86              must be considered experimental.
87
88       host() = hostname() | ip_address()
89
90       hostname() = string()
91
92       ip_address() = inet:ip_address()
93
94       protocol_version() = tls_version() | dtls_version()
95
96       tls_version() = 'tlsv1.2' | 'tlsv1.3' | tls_legacy_version()
97
98       dtls_version() = 'dtlsv1.2' | dtls_legacy_version()
99
100       tls_legacy_version() = tlsv1 | 'tlsv1.1'
101
102       dtls_legacy_version() = dtlsv1
103
104       prf_random() = client_random | server_random
105
106       verify_type() = verify_none | verify_peer
107
108       ciphers() = [erl_cipher_suite()] | string()
109
110       erl_cipher_suite() =
111           #{key_exchange := kex_algo(),
112             cipher := cipher(),
113             mac := hash() | aead,
114             prf := hash() | default_prf}
115
116       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
122       legacy_cipher() = rc4_128 | des_cbc | '3des_ede_cbc'
123
124       cipher_filters() =
125           [{key_exchange | cipher | mac | prf, algo_filter()}]
126
127       hash() = sha | sha2() | legacy_hash()
128
129       sha2() = sha224 | sha256 | sha384 | sha512
130
131       legacy_hash() = md5
132
133       old_cipher_suite() =
134           {kex_algo(), cipher(), hash()} |
135           {kex_algo(), cipher(), hash() | aead, hash()}
136
137       sign_algo() = rsa | dsa | ecdsa | eddsa
138
139       sign_scheme() =
140           eddsa_ed25519 | eddsa_ed448 | ecdsa_secp256r1_sha256 |
141           ecdsa_secp384r1_sha384 | ecdsa_secp521r1_sha512 |
142           rsassa_pss_scheme() |
143           sign_scheme_legacy()
144
145       rsassa_pss_scheme() =
146           rsa_pss_rsae_sha256 | rsa_pss_rsae_sha384 |
147           rsa_pss_rsae_sha512 | rsa_pss_pss_sha256 |
148           rsa_pss_pss_sha384 | rsa_pss_pss_sha512
149
150       sign_scheme_legacy() =
151           rsa_pkcs1_sha256 | rsa_pkcs1_sha384 | rsa_pkcs1_sha512 |
152           rsa_pkcs1_sha1 | ecdsa_sha1
153
154       group() =
155           secp256r1 | secp384r1 | secp521r1 | ffdhe2048 | ffdhe3072 |
156           ffdhe4096 | ffdhe6144 | ffdhe8192
157
158       kex_algo() =
159           rsa | dhe_rsa | dhe_dss | ecdhe_ecdsa | ecdh_ecdsa |
160           ecdh_rsa | srp_rsa | srp_dss | psk | dhe_psk | rsa_psk |
161           dh_anon | ecdh_anon | srp_anon | any
162
163       algo_filter() =
164           fun((kex_algo() | cipher() | hash() | aead | default_prf) ->
165                   true | false)
166
167       named_curve() =
168           sect571r1 | sect571k1 | secp521r1 | brainpoolP512r1 |
169           sect409k1 | sect409r1 | brainpoolP384r1 | secp384r1 |
170           sect283k1 | sect283r1 | brainpoolP256r1 | secp256k1 |
171           secp256r1 | sect239k1 | sect233k1 | sect233r1 | secp224k1 |
172           secp224r1 | sect193r1 | sect193r2 | secp192k1 | secp192r1 |
173           sect163k1 | sect163r1 | sect163r2 | secp160k1 | secp160r1 |
174           secp160r2
175
176       psk_identity() = string()
177
178       srp_identity() = {Username :: string(), Password :: string()}
179
180       srp_param_type() =
181           srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 |
182           srp_6144 | srp_8192
183
184       app_level_protocol() = binary()
185
186       protocol_extensions() =
187           #{renegotiation_info => binary(),
188             signature_algs => signature_algs(),
189             alpn => app_level_protocol(),
190             srp => binary(),
191             next_protocol => app_level_protocol(),
192             max_frag_enum => 1..4,
193             ec_point_formats => [0..2],
194             elliptic_curves => [public_key:oid()],
195             sni => hostname()}
196
197       error_alert() =
198           {tls_alert, {tls_alert(), Description :: string()}}
199
200       tls_alert() =
201           close_notify | unexpected_message | bad_record_mac |
202           record_overflow | handshake_failure | bad_certificate |
203           unsupported_certificate | certificate_revoked |
204           certificate_expired | certificate_unknown |
205           illegal_parameter | unknown_ca | access_denied |
206           decode_error | decrypt_error | export_restriction |
207           protocol_version | insufficient_security | internal_error |
208           inappropriate_fallback | user_canceled | no_renegotiation |
209           unsupported_extension | certificate_unobtainable |
210           unrecognized_name | bad_certificate_status_response |
211           bad_certificate_hash_value | unknown_psk_identity |
212           no_application_protocol
213
214       reason() = any()
215
216       bloom_filter_window_size() = integer()
217
218       bloom_filter_hash_functions() = integer()
219
220       bloom_filter_bits() = integer()
221
222       client_session_tickets() = disabled | manual | auto
223
224       server_session_tickets() = disabled | stateful | stateless
225
226   TLS/DTLS OPTION DESCRIPTIONS - COMMON for SERVER and CLIENT
227       common_option() =
228           {protocol, protocol()} |
229           {handshake, handshake_completion()} |
230           {cert, cert() | [cert()]} |
231           {certfile, cert_pem()} |
232           {key, key()} |
233           {keyfile, key_pem()} |
234           {password, key_pem_password()} |
235           {certs_keys, certs_keys()} |
236           {ciphers, cipher_suites()} |
237           {eccs, [named_curve()]} |
238           {signature_algs, signature_algs()} |
239           {signature_algs_cert, sign_schemes()} |
240           {supported_groups, supported_groups()} |
241           {secure_renegotiate, secure_renegotiation()} |
242           {keep_secrets, keep_secrets()} |
243           {depth, allowed_cert_chain_length()} |
244           {verify_fun, custom_verify()} |
245           {crl_check, crl_check()} |
246           {crl_cache, crl_cache_opts()} |
247           {max_handshake_size, handshake_size()} |
248           {partial_chain, root_fun()} |
249           {versions, protocol_versions()} |
250           {user_lookup_fun, custom_user_lookup()} |
251           {log_level, logging_level()} |
252           {log_alert, log_alert()} |
253           {hibernate_after, hibernate_after()} |
254           {padding_check, padding_check()} |
255           {beast_mitigation, beast_mitigation()} |
256           {ssl_imp, ssl_imp()} |
257           {session_tickets, session_tickets()} |
258           {key_update_at, key_update_at()} |
259           {receiver_spawn_opts, spawn_opts()} |
260           {sender_spawn_opts, spawn_opts()}
261
262       protocol() = tls | dtls
263
264              Choose TLS or DTLS protocol for the  transport  layer  security.
265              Defaults  to tls. For DTLS other transports than UDP are not yet
266              supported.
267
268       handshake_completion() = hello | full
269
270              Defaults to full. If hello is specified the handshake will pause
271              after the hello message and give the user a possibility make de‐
272              cisions based on hello extensions before continuing or  aborting
273              the   handshake   by  calling   handshake_continue/3  or   hand‐
274              shake_cancel/1
275
276       cert() = public_key:der_encoded()
277
278              The DER-encoded user certificate. Note that the cert option  may
279              also  be  a list of DER-encoded certificates where the first one
280              is the user certificate, and the rest of the  certificates  con‐
281              stitutes the certificate chain. For maximum interoperability the
282              certificates in the chain should be in the  correct  order,  the
283              chain  will be sent as is to the peer. If chain certificates are
284              not provided, certificates  from  client_cacerts(),  server_cac‐
285              erts(),  or  client_cafile(),  server_cafile()  are used to con‐
286              struct the chain. If this option is supplied, it  overrides  op‐
287              tion certfile.
288
289       cert_pem() = file:filename()
290
291              Path  to a file containing the user certificate on PEM format or
292              possible several certificates where the first one  is  the  user
293              certificate  and  the  rest  of the certificates constitutes the
294              certificate chain. For more details see cert(),
295
296       key() =
297           {'RSAPrivateKey' | 'DSAPrivateKey' | 'ECPrivateKey' |
298            'PrivateKeyInfo',
299            public_key:der_encoded()} |
300           #{algorithm := rsa | dss | ecdsa,
301             engine := crypto:engine_ref(),
302             key_id := crypto:key_id(),
303             password => crypto:password()}
304
305              The DER-encoded user's private key  or  a  map  referring  to  a
306              crypto engine and its key reference that optionally can be pass‐
307              word protected, see also   crypto:engine_load/3   and   Crypto's
308              Users  Guide.  If  this  option is supplied, it overrides option
309              keyfile.
310
311       key_pem() = file:filename()
312
313              Path to the file containing the user's private PEM-encoded  key.
314              As  PEM-files  can contain several entries, this option defaults
315              to the same file as given by option certfile.
316
317       key_pem_password() = iodata() | fun(() -> iodata())
318
319              String containing the user's password or  a  function  returning
320              same  type.  Only  used  if the private keyfile is password-pro‐
321              tected.
322
323       certs_keys() = [cert_key_conf()]
324
325              A list of a certificate  (or  possible  a  certificate  and  its
326              chain)  and  the  associated key of the certificate, that may be
327              used to authenticate the client or the server.  The  certificate
328              key  pair that is considered best and matches negotiated parame‐
329              ters for the connection will be  selected.  Different  signature
330              algorithms   are   prioritized   in  the  order   eddsa,  ecdsa,
331              rsa_pss_pss, rsa and dsa . If more than one key is supplied  for
332              the  same  signing  algorithm  (which is probably an unusual use
333              case) they will prioritized by strength unless it is a so called
334              engine key that will be favoured over other keys. As engine keys
335              cannot be inspected, supplying more than  one  engine  key  will
336              make no sense. This offers flexibility to for instance configure
337              a newer certificate that is expected to be used  in  most  cases
338              and  an  older but acceptable certificate that will only be used
339              to communicate with legacy systems. Note that there is  a  trade
340              off between the induced overhead and the flexibility so alterna‐
341              tives should be chosen for good reasons. If the  certs_keys  op‐
342              tion  is  specified  it overrides all single certificate and key
343              options. For examples see  the Users Guide
344
345          Note:
346              eddsa certificates are only supported by TLS-1.3 that  does  not
347              support  dsa  certificates.  rsa_pss_pss (RSA certificates using
348              Probabilistic Signature Scheme) are  supported  in  TLS-1.2  and
349              TLS-1.3,  but  some  TLS-1.2  implementations  may  not  support
350              rsa_pss_pss.
351
352
353       cert_key_conf() =
354           #{cert => cert(),
355             key => key(),
356             certfile => cert_pem(),
357             keyfile => key_pem(),
358             password => key_pem_password()}
359
360              A certificate (or possibly a certificate and its chain) and  its
361              associated  key on one of the possible formats. For the PEM file
362              format there may also be a password  associated  with  the  file
363              containg the key.
364
365       cipher_suites() = ciphers()
366
367              A list of cipher suites that should be supported
368
369              The  function   ssl:cipher_suites/2  can be used to find all ci‐
370              pher suites that are supported by default and all cipher  suites
371              that may be configured.
372
373              If  you compose your own cipher_suites() make sure they are fil‐
374              tered for cryptolib support   ssl:filter_cipher_suites/2   Addi‐
375              tionally    the    functions     ssl:append_cipher_suites/2    ,
376              ssl:prepend_cipher_suites/2,                 ssl:suite_to_str/1,
377              ssl:str_to_suite/1, and ssl:suite_to_openssl_str/1 also exist to
378              help creating customized cipher suite lists.
379
380          Note:
381              Note that TLS-1.3 and TLS-1.2 cipher suites are not  overlapping
382              sets  of  cipher suites so to support both these versions cipher
383              suites from both versions need to be included. Also if the  sup‐
384              plied list does not comply with the configured versions or cryp‐
385              tolib so that the list becomes empty, this option will  fallback
386              on its appropriate default value for the configured versions.
387
388
389              Non-default cipher suites including anonymous cipher suites (PRE
390              TLS-1.3) are supported for interop/testing purposes and  may  be
391              used  by  adding  them to your cipher suite list. Note that they
392              must also be supported/enabled by the peer to actually be used.
393
394       signature_algs() = [{hash(), sign_algo()} | sign_scheme()]
395
396              Explicitly list acceptable signature algorithms for certificates
397              and  handshake  messages in the preferred order. The client will
398              send its list as the client hello signature_algorithm  extension
399              introduced in TLS-1.2, see Section 7.4.1.4.1 in RFC 5246. Previ‐
400              ously these algorithms where implicitly chosen  and  partly  de‐
401              rived from the cipher suite.
402
403              In TLS-1.2 a somewhat more explicit negotiation is made possible
404              using a list of {hash(), sign_algo()} pairs.
405
406              In TLS-1.3 these algorithm pairs are replaced by so called  sig‐
407              nature  schemes  sign_scheme() and completely decoupled from the
408              cipher suite.
409
410              Signature algorithms used for certificates may be overridden  by
411              the  signature  schemes  (algorithms)  supplied  by  the  signa‐
412              ture_algs_cert option.
413
414              TLS-1.2 default  is  Default_TLS_12_Alg_Pairs  interleaved  with
415              rsa_pss_schemes since ssl-11.0 (OTP-25) pss_pss is prefered over
416              pss_rsae that is prefered over rsa
417
418              Default_TLS_12_Alg_Pairs =
419
420              [
421              %% SHA2
422              {sha512, ecdsa},
423              {sha512, rsa},
424              {sha384, ecdsa},
425              {sha384, rsa},
426              {sha256, ecdsa},
427              {sha256, rsa},
428              {sha224, ecdsa},
429              {sha224, rsa},
430              %% SHA
431              {sha, ecdsa},
432              {sha, rsa},
433              {sha, dsa}
434              ]
435
436              Support for {md5, rsa} was removed from the the TLS-1.2  default
437              in ssl-8.0 (OTP-22)
438
439               rsa_pss_schemes =
440
441              [rsa_pss_pss_sha512,
442              rsa_pss_pss_sha384,
443              rsa_pss_pss_sha256,
444              rsa_pss_rsae_sha512,
445              rsa_pss_rsae_sha384,
446              rsa_pss_rsae_sha256]
447
448
449               TLS_13_Legacy_Schemes =
450
451               [
452               %% Legacy algorithms only applicable to certificate signatures
453              rsa_pkcs1_sha512, %% Corresponds to {sha512, rsa}
454              rsa_pkcs1_sha384, %% Corresponds to {sha384, rsa}
455              rsa_pkcs1_sha256, %% Corresponds to {sha256, rsa}
456              ecdsa_sha1,       %% Corresponds to {sha, ecdsa}
457              rsa_pkcs1_sha1    %% Corresponds to {sha, rsa}
458              ]
459
460
461               Default_TLS_13_Schemes =
462
463               [
464               %% EDDSA
465              eddsa_ed25519,
466              eddsa_ed448
467
468              %% ECDSA
469              ecdsa_secp521r1_sha512,
470              ecdsa_secp384r1_sha384,
471              ecdsa_secp256r1_sha256] ++
472
473              %% RSASSA-PSS
474              rsa_pss_schemes()
475
476
477              EDDSA was made highest priority in ssl-11.0 (OTP-25)
478
479              TLS-1.3 default is
480
481              Default_TLS_13_Schemes ++ Legacy_TLS_13_Schemes
482
483              If both TLS-1.3 and TLS-1.2 are supported the default will be
484
485              Default_TLS_13_Schemes ++ Default_TLS_12_Alg_Pairs
486
487              so  appropriate algorithms can be chosen for the negotiated ver‐
488              sion.
489
490          Note:
491              TLS-1.2 algorithms will  not  be  negotiated  for  TLS-1.3,  but
492              TLS-1.3  RSASSA-PSS rsassa_pss_scheme() signature schemes may be
493              negotiated also  for  TLS-1.2  from  24.1  (fully  working  from
494              24.1.3).  However if TLS-1.3 is negotiated when both TLS-1.3 and
495              TLS-1.2 is supported using defaults, the  corresponding  TLS-1.2
496              algorithms  to the TLS-1.3 legacy signature schemes will be con‐
497              sidered as the legacy schemes and applied  only  to  certificate
498              signatures.
499
500
501       sign_schemes() = [sign_scheme()]
502
503              Explicitly list acceptable signature schemes (algorithms) in the
504              preferred order. Overrides the  algorithms  supplied  in  signa‐
505              ture_algs option for certificates.
506
507              In  addition to the signature_algorithms extension from TLS 1.2,
508              TLS 1.3  (RFC  5246  Section  4.2.3)  adds  the  signature_algo‐
509              rithms_cert  extension which enables having special requirements
510              on the signatures used in the certificates that differs from the
511              requirements  on  digital  signatures as a whole. If this is not
512              required this extension is not need.
513
514              The client will send a signature_algorithms_cert  extension  (in
515              the  client  hello  message), if TLS version 1.2 (back-ported to
516              TLS 1.2 in 24.1) or later is used, and  the  signature_algs_cert
517              option  is  explicitly  specified.  By  default, only the signa‐
518              ture_algs extension is sent.
519
520          Note:
521              Note  that  supported  signature   schemes   for   TLS-1.2   are
522              sign_scheme_legacy() and rsassa_pss_scheme()
523
524
525       supported_groups() = [group()]
526
527              TLS 1.3 introduces the "supported_groups" extension that is used
528              for negotiating the Diffie-Hellman parameters in a TLS 1.3 hand‐
529              shake.  Both  client and server can specify a list of parameters
530              that they are willing to use.
531
532              If it is not specified it will  use  a  default  list  ([x25519,
533              x448,  secp256r1,  secp384r1]) that is filtered based on the in‐
534              stalled crypto library version.
535
536       secure_renegotiation() = boolean()
537
538              Specifies if to reject renegotiation attempt that does not  live
539              up  to  RFC  5746. By default secure_renegotiate is set to true,
540              that is, secure renegotiation is enforced. If set to  false  se‐
541              cure  renegotiation will still be used if possible, but it falls
542              back to insecure renegotiation if the peer does not support  RFC
543              5746.
544
545       allowed_cert_chain_length() = integer()
546
547              Maximum number of non-self-issued intermediate certificates that
548              can follow the peer certificate in a valid  certification  path.
549              So, if depth is 0 the PEER must be signed by the trusted ROOT-CA
550              directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the  path
551              can  be  PEER,  CA, CA, ROOT-CA, and so on. The default value is
552              10.
553
554       custom_verify() =
555           {Verifyfun :: function(), InitialUserState :: any()}
556
557              The verification fun is to be defined as follows:
558
559              fun(OtpCert :: #'OTPCertificate'{},
560                  Event, InitialUserState :: term()) ->
561                   {valid, UserState :: term()} |
562                   {fail, Reason :: term()} | {unknown, UserState :: term()}.
563
564              fun(OtpCert :: #'OTPCertificate'{}, DerCert :: public_key:der_encoded(),
565                  Event, InitialUserState :: term()) ->
566                   {valid, UserState :: term()} |
567                   {fail, Reason :: term()} | {unknown, UserState :: term()}.
568
569              Types:
570                    Event = {bad_cert, Reason :: atom() |
571                            {revoked, atom()}} |
572                         {extension, #'Extension'{}} |
573                            valid |
574                            valid_peer
575
576
577              The verification fun is called during the  X509-path  validation
578              when  an error or an extension unknown to the SSL application is
579              encountered. It is also called when a certificate is  considered
580              valid by the path validation to allow access to each certificate
581              in the path to the user application. It  differentiates  between
582              the peer certificate and the CA certificates by using valid_peer
583              or valid as Event argument to the verification fun. See the pub‐
584              lic_key  User's  Guide for definition of #'OTPCertificate'{} and
585              #'Extension'{}.
586
587                * If the verify callback fun returns {fail, Reason}, the veri‐
588                  fication process is immediately stopped, an alert is sent to
589                  the peer, and the TLS/DTLS handshake terminates.
590
591                * If the verify callback fun returns {valid,  UserState},  the
592                  verification process continues.
593
594                * If  the  verify  callback  fun  always returns {valid, User‐
595                  State}, the TLS/DTLS handshake does not terminate  regarding
596                  verification failures and the connection is established.
597
598                * If called with an extension unknown to the user application,
599                  return value {unknown, UserState} is to be used.
600
601                  Note that if the fun returns unknown for an extension marked
602                  as critical, validation will fail.
603
604              Default option verify_fun in verify_peer mode:
605
606              {fun(_,{bad_cert, _} = Reason, _) ->
607                    {fail, Reason};
608                  (_,{extension, _}, UserState) ->
609                    {unknown, UserState};
610                  (_, valid, UserState) ->
611                    {valid, UserState};
612                  (_, valid_peer, UserState) ->
613                       {valid, UserState}
614               end, []}
615
616
617              Default option verify_fun in mode verify_none:
618
619              {fun(_,{bad_cert, _}, UserState) ->
620                    {valid, UserState};
621                  (_,{extension, #'Extension'{critical = true}}, UserState) ->
622                    {valid, UserState};
623                  (_,{extension, _}, UserState) ->
624                    {unknown, UserState};
625                  (_, valid, UserState) ->
626                    {valid, UserState};
627                  (_, valid_peer, UserState) ->
628                       {valid, UserState}
629               end, []}
630
631
632              The possible path validation errors are given on form {bad_cert,
633              Reason} where Reason is:
634
635                unknown_ca:
636                  No trusted CA was found in the trusted store. The trusted CA
637                  is normally a so called ROOT CA, which is a self-signed cer‐
638                  tificate. Trust  can  be  claimed  for  an  intermediate  CA
639                  (trusted anchor does not have to be self-signed according to
640                  X-509) by using option partial_chain.
641
642                selfsigned_peer:
643                  The chain consisted only of one self-signed certificate.
644
645                PKIX X-509-path validation error:
646                  For possible reasons, see public_key:pkix_path_validation/3
647
648       crl_check() = boolean() | peer | best_effort
649
650              Perform CRL (Certificate Revocation  List)  verification   (pub‐
651              lic_key:pkix_crls_validate/3) on all the certificates during the
652              path validation (public_key:pkix_path_validation/3)  of the cer‐
653              tificate chain. Defaults to false.
654
655                peer:
656                  check is only performed on the peer certificate.
657
658                best_effort:
659                  if  certificate  revocation  status  cannot be determined it
660                  will be accepted as valid.
661
662              The CA certificates specified for the connection will be used to
663              construct the certificate chain validating the CRLs.
664
665              The  CRLs  will  be  fetched from a local or external cache. See
666              ssl_crl_cache_api(3).
667
668       crl_cache_opts() =
669           {Module :: atom(),
670            {DbHandle :: internal | term(), Args :: list()}}
671
672              Specify how to perform lookup and caching of certificate revoca‐
673              tion lists. Module defaults to ssl_crl_cache with  DbHandle  be‐
674              ing internal and an empty argument list.
675
676              There are two implementations available:
677
678                ssl_crl_cache:
679                  This module maintains a cache of CRLs. CRLs can be added  to
680                  the cache using the function ssl_crl_cache:insert/1, and op‐
681                  tionally automatically fetched through HTTP if the following
682                  argument is specified:
683
684                  {http, timeout()}:
685                    Enables  fetching  of  CRLs  specified as http URIs inX509
686                    certificate extensions. Requires the  OTP  inets  applica‐
687                    tion.
688
689                ssl_crl_hash_dir:
690                  This  module  makes use of a directory where CRLs are stored
691                  in files named by the hash of the issuer name.
692
693                  The file names consist of eight hexadecimal digits  followed
694                  by  .rN,  where  N  is an integer, e.g. 1a2b3c4d.r0. For the
695                  first version of the CRL, N starts at zero, and for each new
696                  version,  N is incremented by one. The OpenSSL utility c_re‐
697                  hash creates symlinks according to this pattern.
698
699                  For a given hash value, this module  finds  all  consecutive
700                  .r* files starting from zero, and those files taken together
701                  make up the revocation  list.  CRL  files  whose  nextUpdate
702                  fields are in the past, or that are issued by a different CA
703                  that happens to have the same name hash, are excluded.
704
705                  The following argument is required:
706
707                  {dir, string()}:
708                    Specifies the directory in which the CRLs can be found.
709
710       root_fun() = function()
711
712              fun(Chain::[public_key:der_encoded()]) ->
713                   {trusted_ca, DerCert::public_key:der_encoded()} | unknown_ca}
714
715
716              Claim an intermediate CA in the chain as trusted. TLS then  per‐
717              forms  public_key:pkix_path_validation/3 with the selected CA as
718              trusted anchor and the rest of the chain.
719
720       protocol_versions() = [protocol_version()]
721
722              TLS protocol versions supported by started clients and  servers.
723              This  option overrides the application environment option proto‐
724              col_version and dtls_protocol_version. If the environment option
725              is  not  set,  it defaults to all versions, supported by the SSL
726              application. See also ssl(6).
727
728       custom_user_lookup() =
729           {Lookupfun :: function(), UserState :: any()}
730
731              The lookup fun is to defined as follows:
732
733              fun(psk, PSKIdentity :: binary(), UserState :: term()) ->
734                   {ok, SharedSecret :: binary()} | error;
735              fun(srp, Username :: binary(), UserState :: term()) ->
736                   {ok, {SRPParams :: srp_param_type(), Salt :: binary(),
737                         DerivedKey :: binary()}} | error.
738
739
740              For Pre-Shared Key (PSK) cipher suites, the lookup fun is called
741              by  the  client  and server to determine the shared secret. When
742              called by the client, PSKIdentity is set to the  hint  presented
743              by  the server or to undefined. When called by the server, PSKI‐
744              dentity is the identity presented by the client.
745
746              For Secure Remote Password (SRP), the fun is only  used  by  the
747              server to obtain parameters that it uses to generate its session
748              keys. DerivedKey is to be derived according  to   RFC  2945  and
749              RFC  5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Pass‐
750              word])])
751
752       session_id() = binary()
753
754              Identifies a TLS session.
755
756       log_alert() = boolean()
757
758              If set to false, TLS/DTLS Alert reports are not displayed.  Dep‐
759              recated in OTP 22, use {log_level, logging_level()} instead.
760
761       logging_level() = logger:level() | none | all
762
763              Specifies  the  log  level for a TLS/DTLS connection. Alerts are
764              logged on notice level, which is the default  level.  The  level
765              debug  triggers  verbose  logging of TLS/DTLS protocol messages.
766              See also ssl(6)
767
768       hibernate_after() = timeout()
769
770              When an integer-value  is  specified,  TLS/DTLS-connection  goes
771              into  hibernation  after the specified number of milliseconds of
772              inactivity, thus reducing its memory footprint.  When  undefined
773              is  specified (this is the default), the process never goes into
774              hibernation.
775
776       handshake_size() = integer()
777
778              Integer (24 bits unsigned). Used to limit the size of valid  TLS
779              handshake packets to avoid DoS attacks. Defaults to 256*1024.
780
781       padding_check() = boolean()
782
783              Affects  TLS-1.0  connections only. If set to false, it disables
784              the block cipher padding check to be able to  interoperate  with
785              legacy software.
786
787          Warning:
788              Using  {padding_check,  boolean()}  makes  TLS vulnerable to the
789              Poodle attack.
790
791
792       beast_mitigation() = one_n_minus_one | zero_n | disabled
793
794              Affects TLS-1.0 connections only. Used to change the BEAST miti‐
795              gation  strategy  to interoperate with legacy software. Defaults
796              to one_n_minus_one.
797
798              one_n_minus_one - Perform 1/n-1 BEAST mitigation.
799
800              zero_n - Perform 0/n BEAST mitigation.
801
802              disabled - Disable BEAST mitigation.
803
804          Warning:
805              Using {beast_mitigation, disabled} makes TLS-1.0  vulnerable  to
806              the BEAST attack.
807
808
809       ssl_imp() = new | old
810
811              Deprecated since OTP-17, has no effect.
812
813       session_tickets() =
814           client_session_tickets() | server_session_tickets()
815
816              Configures  the  session  ticket functionality in TLS 1.3 client
817              and server.
818
819       key_update_at() = integer() >= 1
820
821              Configures the maximum amount of bytes that can be sent on a TLS
822              1.3 connection before an automatic key update is performed.
823
824              There  are cryptographic limits on the amount of plaintext which
825              can be safely encrypted under a given set of keys.  The  current
826              default  ensures  that  data integrity will not be breached with
827              probability greater than 1/2^57. For more information see Limits
828              on Authenticated Encryption Use in TLS.
829
830          Warning:
831              The  default  value  of this option shall provide the above men‐
832              tioned security guarantees and it shall be reasonable  for  most
833              applications (~353 TB).
834
835
836       middlebox_comp_mode() = boolean()
837
838              Configures the middlebox compatibility mode on a TLS 1.3 connec‐
839              tion.
840
841              A significant number of middleboxes misbehave  when  a  TLS  1.3
842              connection  is  negotiated.  Implementations  can  increase  the
843              chance of making connections through those middleboxes by making
844              the TLS 1.3 handshake more like a TLS 1.2 handshake.
845
846              The middlebox compatibility mode is enabled (true) by default.
847
848       spawn_opts() = [erlang:spawn_opt_option()]
849
850              Configures spawn options of TLS sender and receiver processes.
851
852              Setting  up garbage collection options can be helpful for trade-
853              offs between CPU usage and Memory usage. See erlang:spawn_opt/2.
854
855              For dist connections, default sender  option  is  [...{priority,
856              max}],  this  priority option cannot be changed. For all connec‐
857              tions, ...link is added to receiver and cannot be changed.
858
859       keep_secrets() = boolean()
860
861              Configures a TLS 1.3 connection for keylogging
862
863              In order to retrieve keylog information on a TLS 1.3 connection,
864              it  must  be configured in advance to keep the client_random and
865              various handshake secrets.
866
867              The keep_secrets functionality is disabled (false) by default.
868
869              Added in OTP 23.2
870
871   TLS/DTLS OPTION DESCRIPTIONS - CLIENT
872       client_option() =
873           {verify, client_verify_type()} |
874           {reuse_session, client_reuse_session()} |
875           {reuse_sessions, client_reuse_sessions()} |
876           {cacerts, client_cacerts()} |
877           {cacertfile, client_cafile()} |
878           {alpn_advertised_protocols, client_alpn()} |
879           {client_preferred_next_protocols,
880            client_preferred_next_protocols()} |
881           {psk_identity, client_psk_identity()} |
882           {srp_identity, client_srp_identity()} |
883           {server_name_indication, sni()} |
884           {max_fragment_length, max_fragment_length()} |
885           {customize_hostname_check, customize_hostname_check()} |
886           {fallback, fallback()} |
887           {middlebox_comp_mode, middlebox_comp_mode()} |
888           {certificate_authorities, client_certificate_authorities()} |
889           {session_tickets, client_session_tickets()} |
890           {use_ticket, use_ticket()} |
891           {early_data, client_early_data()}
892
893       client_verify_type() = verify_type()
894
895              Defaults to verify_none as additional options are needed  to  be
896              able  to perform the certificate verification. A warning will be
897              emitted unless verify_none is explicitly configured. Usually the
898              applications will want to configure verify_peer together with an
899              appropriate cacert or cacertfile option. For  example  an  HTTPS
900              client  would  normally use the option {cacerts, public_key:cac‐
901              erts_get()} (available since OTP-25) to access the  CA  certifi‐
902              cates  provided  by  the  OS.  Using  verify_none means that all
903              x509-certificate path validation errors  will  be  ignored.  See
904              also option verify_fun.
905
906       client_reuse_session() =
907           session_id() | {session_id(), SessionData :: binary()}
908
909              Reuses a specific session. The session should be referred by its
910              session id if it is earlier saved with  the  option  {reuse_ses‐
911              sions,  save} since OTP-21.3 or explicitly specified by its ses‐
912              sion id and associated data  since  OTP-22.3.  See  also   SSL's
913              Users Guide, Session Reuse pre TLS 1.3.
914
915       client_reuse_sessions() = boolean() | save
916
917              When  save  is specified a new connection will be negotiated and
918              saved for later reuse. The session ID can be fetched  with  con‐
919              nection_information/2 and used with the client option reuse_ses‐
920              sion The boolean value true specifies that  if  possible,  auto‐
921              mated  session reuse will be performed. If a new session is cre‐
922              ated, and is unique in regard to previous  stored  sessions,  it
923              will be saved for possible later reuse. Since OTP-21.3.
924
925       client_certificate_authorities() = boolean()
926
927              If  set  to true, sends the certificate authorities extension in
928              TLS-1.3 client hello. The default is false. Note that setting it
929              to true may result in a big overhead if you have many trusted CA
930              certificates. Since OTP-24.3.
931
932       client_cacerts() =
933           [public_key:der_encoded()] | [public_key:combined_cert()]
934
935              The DER-encoded trusted certificates. If this option is supplied
936              it overrides option cacertfile.
937
938       client_cafile() = file:filename()
939
940              Path  to  a  file containing PEM-encoded CA certificates. The CA
941              certificates are used  during  server  authentication  and  when
942              building the client certificate chain.
943
944          Note:
945              When  PEM  caching  is  enabled, files provided with this option
946              will be checked for updates at fixed time intervals specified by
947              the ssl_pem_cache_clean environment parameter.
948
949
950          Note:
951              Alternatively,  CA certificates can be provided as a DER-encoded
952              binary with client_cacerts option.
953
954
955       client_alpn() = [app_level_protocol()]
956
957              The list of protocols supported by the client to be sent to  the
958              server  to be used for an Application-Layer Protocol Negotiation
959              (ALPN). If the server supports ALPN then it will choose a proto‐
960              col from this list; otherwise it will fail the connection with a
961              "no_application_protocol" alert. A server that does not  support
962              ALPN will ignore this value.
963
964              The list of protocols must not contain an empty binary.
965
966              The  negotiated  protocol  can  be  retrieved  using the negoti‐
967              ated_protocol/1 function.
968
969       client_preferred_next_protocols() =
970           {Precedence :: server | client,
971            ClientPrefs :: [app_level_protocol()]} |
972           {Precedence :: server | client,
973            ClientPrefs :: [app_level_protocol()],
974            Default :: app_level_protocol()}
975
976              Indicates that the client is to try to perform Next Protocol Ne‐
977              gotiation.
978
979              If  precedence  is  server, the negotiated protocol is the first
980              protocol to be shown on the server  advertised  list,  which  is
981              also on the client preference list.
982
983              If  precedence  is  client, the negotiated protocol is the first
984              protocol to be shown on the client  preference  list,  which  is
985              also on the server advertised list.
986
987              If the client does not support any of the server advertised pro‐
988              tocols or the server  does  not  advertise  any  protocols,  the
989              client  falls  back  to the first protocol in its list or to the
990              default protocol (if a default is supplied). If the server  does
991              not support Next Protocol Negotiation, the connection terminates
992              if no default protocol is supplied.
993
994       max_fragment_length() = undefined | 512 | 1024 | 2048 | 4096
995
996              Specifies the maximum fragment length the client is prepared  to
997              accept from the server. See RFC 6066
998
999       client_psk_identity() = psk_identity()
1000
1001              Specifies  the  identity  the client presents to the server. The
1002              matching secret is found by calling user_lookup_fun
1003
1004       client_srp_identity() = srp_identity()
1005
1006              Specifies the username and password to use  to  authenticate  to
1007              the server.
1008
1009       sni() = hostname() | disable
1010
1011              Specify  the  hostname  to be used in TLS Server Name Indication
1012              extension. If not specified it will default to the Host argument
1013              of connect/[3,4] unless it is of type inet:ipaddress().
1014
1015              The  HostName  will also be used in the hostname verification of
1016              the peer certificate using public_key:pkix_verify_hostname/2.
1017
1018              The special value disable prevents the  Server  Name  Indication
1019              extension from being sent and disables the hostname verification
1020              check public_key:pkix_verify_hostname/2
1021
1022       customize_hostname_check() = list()
1023
1024              Customizes the hostname verification of the peer certificate, as
1025              different  protocols  that use TLS such as HTTP or LDAP may want
1026              to  do  it  differently,   for   possible   options   see   pub‐
1027              lic_key:pkix_verify_hostname/3
1028
1029       fallback() = boolean()
1030
1031              Send  special  cipher suite TLS_FALLBACK_SCSV to avoid undesired
1032              TLS version downgrade. Defaults to false
1033
1034          Warning:
1035              Note this option is not needed in normal TLS  usage  and  should
1036              not  be  used  to implement new clients. But legacy clients that
1037              retries connections in the following manner
1038
1039               ssl:connect(Host,  Port,  [...{versions,  ['tlsv2',  'tlsv1.1',
1040              'tlsv1']}])
1041
1042               ssl:connect(Host,  Port,  [...{versions,  [tlsv1.1', 'tlsv1']},
1043              {fallback, true}])
1044
1045               ssl:connect(Host, Port, [...{versions,  ['tlsv1']},  {fallback,
1046              true}])
1047
1048              may  use  it to avoid undesired TLS version downgrade. Note that
1049              TLS_FALLBACK_SCSV must also be supported by the server  for  the
1050              prevention to work.
1051
1052
1053       client_session_tickets() = disabled | manual | auto
1054
1055              Configures  the session ticket functionality. Allowed values are
1056              disabled, manual and auto. If it is set  to  manual  the  client
1057              will send the ticket information to user process in a 3-tuple:
1058
1059              {ssl, session_ticket, {SNI, TicketData}}
1060
1061              where  SNI is the ServerNameIndication and TicketData is the ex‐
1062              tended ticket data that can be used in  subsequent  session  re‐
1063              sumptions.
1064
1065              If  it is set to auto, the client automatically handles received
1066              tickets and tries to use them when making  new  TLS  connections
1067              (session resumption with pre-shared keys).
1068
1069          Note:
1070              This  option  is supported by TLS 1.3 and above. See also  SSL's
1071              Users Guide, Session Tickets and Session Resumption in TLS 1.3
1072
1073
1074       use_ticket() = [binary()]
1075
1076              Configures the session tickets to be used  for  session  resump‐
1077              tion. It is a mandatory option in manual mode (session_tickets =
1078              manual).
1079
1080          Note:
1081              Session tickets are only sent to user if option  session_tickets
1082              is set to manual
1083
1084              This  option  is supported by TLS 1.3 and above. See also  SSL's
1085              Users Guide, Session Tickets and Session Resumption in TLS 1.3
1086
1087
1088       client_early_data() = binary()
1089
1090              Configures the early data to be sent by the client.
1091
1092              In order to be able to verify that the server has the  intention
1093              to  process the early data, the following 3-tuple is sent to the
1094              user process:
1095
1096              {ssl, SslSocket, {early_data, Result}}
1097
1098              where Result is either accepted or rejected.
1099
1100          Warning:
1101              It is the responsibility of the user to handle a rejected  Early
1102              Data and to resend when it is appropriate.
1103
1104
1105   TLS/DTLS OPTION DESCRIPTIONS - SERVER
1106       server_option() =
1107           {cacerts, server_cacerts()} |
1108           {cacertfile, server_cafile()} |
1109           {dh, dh_der()} |
1110           {dhfile, dh_file()} |
1111           {verify, server_verify_type()} |
1112           {fail_if_no_peer_cert, fail_if_no_peer_cert()} |
1113           {certificate_authorities, server_certificate_authorities()} |
1114           {reuse_sessions, server_reuse_sessions()} |
1115           {reuse_session, server_reuse_session()} |
1116           {alpn_preferred_protocols, server_alpn()} |
1117           {next_protocols_advertised, server_next_protocol()} |
1118           {psk_identity, server_psk_identity()} |
1119           {sni_hosts, sni_hosts()} |
1120           {sni_fun, sni_fun()} |
1121           {honor_cipher_order, honor_cipher_order()} |
1122           {honor_ecc_order, honor_ecc_order()} |
1123           {client_renegotiation, client_renegotiation()} |
1124           {session_tickets, server_session_tickets()} |
1125           {anti_replay, anti_replay()} |
1126           {cookie, cookie()} |
1127           {early_data, server_early_data()}
1128
1129       server_cacerts() =
1130           [public_key:der_encoded()] | [public_key:combined_cert()]
1131
1132              The DER-encoded trusted certificates. If this option is supplied
1133              it overrides option cacertfile.
1134
1135       server_certificate_authorities() = boolean()
1136
1137              Determines if a TLS-1.3 server should  include  the  authorities
1138              extension  in  its certificate request message that will be sent
1139              if the option verify is set to verify_peer. Defaults to true.
1140
1141              A reason to exclude the extension would be if the  server  wants
1142              to  communicate  with clients incapable of sending complete cer‐
1143              tificate chains that adhere to the  extension,  but  the  server
1144              still has the capability to recreate a chain that it can verify.
1145
1146       server_cafile() = file:filename()
1147
1148              Path  to  a  file containing PEM-encoded CA certificates. The CA
1149              certificates are used to build the server certificate chain  and
1150              for  client authentication. The CAs are also used in the list of
1151              acceptable client CAs passed to the client when a certificate is
1152              requested.  Can  be  omitted  if  there is no need to verify the
1153              client and if there are no intermediate CAs for the server  cer‐
1154              tificate.
1155
1156          Note:
1157              When  PEM  caching  is  enabled, files provided with this option
1158              will be checked for updates at fixed time intervals specified by
1159              the ssl_pem_cache_clean environment parameter.
1160
1161
1162          Note:
1163              Alternatively,  CA certificates can be provided as a DER-encoded
1164              binary with server_cacerts option.
1165
1166
1167       dh_der() = binary()
1168
1169              The DER-encoded  Diffie-Hellman  parameters.  If  specified,  it
1170              overrides option dhfile.
1171
1172          Warning:
1173              The  dh_der  option  is  not  supported by TLS 1.3. Use the sup‐
1174              ported_groups option instead.
1175
1176
1177       dh_file() = file:filename()
1178
1179              Path to a file containing PEM-encoded Diffie Hellman  parameters
1180              to  be used by the server if a cipher suite using Diffie Hellman
1181              key exchange is negotiated. If not specified, default parameters
1182              are used.
1183
1184          Warning:
1185              The  dh_file  option  is  not supported by TLS 1.3. Use the sup‐
1186              ported_groups option instead.
1187
1188
1189       server_verify_type() = verify_type()
1190
1191              Client certificates are an optional part of the TLS protocol.  A
1192              server  only  does x509-certificate path validation in mode ver‐
1193              ify_peer. By default the server is in verify_none mode an  hence
1194              will  not  send an certificate request to the client. When using
1195              verify_peer  you  may  also  want   to   specify   the   options
1196              fail_if_no_peer_cert and certificate_authorities.
1197
1198       fail_if_no_peer_cert() = boolean()
1199
1200              Used  together with {verify, verify_peer} by an TLS/DTLS server.
1201              If set to true, the server fails if the client does not  have  a
1202              certificate to send, that is, sends an empty certificate. If set
1203              to false, it fails only if the client sends an invalid  certifi‐
1204              cate  (an  empty  certificate  is considered valid). Defaults to
1205              false.
1206
1207       server_reuse_sessions() = boolean()
1208
1209              The boolean value true specifies that the server will  agree  to
1210              reuse sessions. Setting it to false will result in an empty ses‐
1211              sion table, that is no sessions will be reused. See also  option
1212              reuse_session.
1213
1214       server_reuse_session() = function()
1215
1216              Enables  the TLS/DTLS server to have a local policy for deciding
1217              if a session is to be reused or  not.  Meaningful  only  if  re‐
1218              use_sessions  is  set to true. SuggestedSessionId is a binary(),
1219              PeerCert is a DER-encoded certificate, Compression is an enumer‐
1220              ation integer, and CipherSuite is of type ciphersuite().
1221
1222       server_alpn() = [app_level_protocol()]
1223
1224              Indicates  the server will try to perform Application-Layer Pro‐
1225              tocol Negotiation (ALPN).
1226
1227              The list of protocols is in order of  preference.  The  protocol
1228              negotiated will be the first in the list that matches one of the
1229              protocols advertised by the client. If no protocol matches,  the
1230              server will fail the connection with a "no_application_protocol"
1231              alert.
1232
1233              The negotiated protocol  can  be  retrieved  using  the  negoti‐
1234              ated_protocol/1 function.
1235
1236       server_next_protocol() = [app_level_protocol()]
1237
1238              List  of protocols to send to the client if the client indicates
1239              that it supports the Next Protocol extension. The client can se‐
1240              lect  a protocol that is not on this list. The list of protocols
1241              must not contain an empty binary. If  the  server  negotiates  a
1242              Next Protocol, it can be accessed using the negotiated_next_pro‐
1243              tocol/1 method.
1244
1245       server_psk_identity() = psk_identity()
1246
1247              Specifies the server identity hint, which the server presents to
1248              the client.
1249
1250       honor_cipher_order() = boolean()
1251
1252              If  set to true, use the server preference for cipher selection.
1253              If set to false (the default), use the client preference.
1254
1255       sni_hosts() =
1256           [{hostname(), [server_option() | common_option()]}]
1257
1258              If the server receives a SNI (Server Name Indication)  from  the
1259              client  matching a host listed in the sni_hosts option, the spe‐
1260              cific options for that host will override  previously  specified
1261              options.  The  option sni_fun, and sni_hosts are mutually exclu‐
1262              sive.
1263
1264       sni_fun() = function()
1265
1266              If the server receives a SNI (Server Name Indication)  from  the
1267              client,   the   given   function  will  be  called  to  retrieve
1268              [server_option()]  for the indicated server. These options  will
1269              be  merged into predefined [server_option()]  list. The function
1270              should be defined as: fun(ServerName :: string()) -> [server_op‐
1271              tion()]   and  can  be  specified  as a fun or as named fun mod‐
1272              ule:function/1 The option sni_fun, and  sni_hosts  are  mutually
1273              exclusive.
1274
1275       client_renegotiation() = boolean()
1276
1277              In  protocols  that  support client-initiated renegotiation, the
1278              cost of resources of such an operation is higher for the  server
1279              than  the client. This can act as a vector for denial of service
1280              attacks. The SSL application already takes measures to  counter-
1281              act  such  attempts,  but  client-initiated renegotiation can be
1282              strictly disabled by setting this option to false.  The  default
1283              value  is  true. Note that disabling renegotiation can result in
1284              long-lived connections becoming unusable due to  limits  on  the
1285              number of messages the underlying cipher suite can encipher.
1286
1287       honor_cipher_order() = boolean()
1288
1289              If  true,  use  the server's preference for cipher selection. If
1290              false (the default), use the client's preference.
1291
1292       honor_ecc_order() = boolean()
1293
1294              If true, use the server's preference for ECC curve selection. If
1295              false (the default), use the client's preference.
1296
1297       server_session_tickets() = disabled | stateful | stateless
1298
1299              Configures  the session ticket functionality. Allowed values are
1300              disabled, stateful and stateless.
1301
1302              If it is set to stateful or stateless, session  resumption  with
1303              pre-shared  keys is enabled and the server will send stateful or
1304              stateless session tickets to the client after successful connec‐
1305              tions.
1306
1307              A  stateful  session  ticket is a database reference to internal
1308              state information. A stateless  session  ticket  is  a  self-en‐
1309              crypted  binary that contains both cryptographic keying material
1310              and state data.
1311
1312          Note:
1313              This option is supported by TLS 1.3 and above. See  also   SSL's
1314              Users Guide, Session Tickets and Session Resumption in TLS 1.3
1315
1316
1317       anti_replay() =
1318           '10k' | '100k' |
1319           {bloom_filter_window_size(),
1320            bloom_filter_hash_functions(),
1321            bloom_filter_bits()}
1322
1323              Configures  the  server's  built-in anti replay feature based on
1324              Bloom filters.
1325
1326              Allowed values are the pre-defined '10k',  '100k'  or  a  custom
1327              3-tuple  that defines the properties of the bloom filters: {Win‐
1328              dowSize, HashFunctions, Bits}. WindowSize is the number of  sec‐
1329              onds after the current Bloom filter is rotated and also the win‐
1330              dow size used for freshness checks. HashFunctions is the  number
1331              hash functions and Bits is the number of bits in the bit vector.
1332              '10k' and '100k' are simple defaults with the following  proper‐
1333              ties:
1334
1335                * '10k':  Bloom filters can hold 10000 elements with 3% proba‐
1336                  bility of false positives. WindowSize: 10, HashFunctions: 5,
1337                  Bits: 72985 (8.91 KiB).
1338
1339                * '100k': Bloom filters can hold 100000 elements with 3% prob‐
1340                  ability of false positives. WindowSize:  10,  HashFunctions:
1341                  5, Bits: 729845 (89.09 KiB).
1342
1343          Note:
1344              This  option  is  supported  by  TLS 1.3 and above and only with
1345              stateless session tickets. Ticket lifetime, the number of  tick‐
1346              ets  sent by the server and the maximum number of tickets stored
1347              by the server in stateful mode  are  configured  by  application
1348              variables.  See  also  SSL's Users Guide, Anti-Replay Protection
1349              in TLS 1.3
1350
1351
1352       cookie() = boolean()
1353
1354              If true (default), the server sends a cookie  extension  in  its
1355              HelloRetryRequest messages.
1356
1357          Note:
1358              The cookie extension has two main purposes. It allows the server
1359              to force the client to demonstrate reachability at their  appar‐
1360              ent  network  address  (thus  providing a measure of DoS protec‐
1361              tion). This  is  primarily  useful  for  non-connection-oriented
1362              transports.  It also allows to offload the server's state to the
1363              client. The cookie extension is enabled by default as  it  is  a
1364              mandatory extension in RFC8446.
1365
1366
1367       server_early_data() = disabled | enabled
1368
1369              Configures  if the server accepts (enabled) or rejects (rejects)
1370              early data sent by a client. The default value is disabled.
1371
1372          Warning:
1373              This option is a placeholder, early data is not yet  implemented
1374              on the server side.
1375
1376
1377       connection_info() =
1378           [common_info() |
1379            curve_info() |
1380            ssl_options_info() |
1381            security_info()]
1382
1383       common_info() =
1384           {protocol, protocol_version()} |
1385           {session_id, session_id()} |
1386           {session_resumption, boolean()} |
1387           {selected_cipher_suite, erl_cipher_suite()} |
1388           {sni_hostname, term()} |
1389           {srp_username, term()}
1390
1391       curve_info() = {ecc, {named_curve, term()}}
1392
1393       ssl_options_info() = tls_option()
1394
1395       security_info() =
1396           {client_random, binary()} |
1397           {server_random, binary()} |
1398           {master_secret, binary()}
1399
1400       connection_info_items() = [connection_info_item()]
1401
1402       connection_info_item() =
1403           protocol | session_id | session_resumption |
1404           selected_cipher_suite | sni_hostname | srp_username | ecc |
1405           client_random | server_random | master_secret | keylog |
1406           tls_options_name()
1407
1408       tls_options_name() = atom()
1409

EXPORTS

1411       append_cipher_suites(Deferred, Suites) -> ciphers()
1412
1413              Types:
1414
1415                 Deferred = ciphers() | cipher_filters()
1416                 Suites = ciphers()
1417
1418              Make  Deferred suites become the least preferred suites, that is
1419              put them at the end of the cipher suite list Suites after remov‐
1420              ing  them  from Suites if present. Deferred may be a list of ci‐
1421              pher suites or a list of filters in which case the  filters  are
1422              use on Suites to extract the Deferred cipher list.
1423
1424       cipher_suites(Description, Version) -> ciphers()
1425
1426              Types:
1427
1428                 Description =
1429                     default  | all | exclusive | anonymous | exclusive_anony‐
1430                 mous
1431                 Version = protocol_version()
1432
1433              Lists all possible cipher suites  corresponding  to  Description
1434              that are available. The exclusive and exclusive_anonymous option
1435              will exclusively list cipher suites first supported  in  Version
1436              whereas the other options are inclusive from the lowest possible
1437              version to Version. The all options includes all  suites  except
1438              the anonymous and no anonymous suites are supported by default.
1439
1440          Note:
1441              TLS-1.3  has no overlapping cipher suites with previous TLS ver‐
1442              sions, that is the result of cipher_suites(all, 'tlsv1.3'). con‐
1443              tains  a separate set of suites that can be used with TLS-1.3 an
1444              other set that can be used if a lower version is negotiated. PRE
1445              TLS-1.3 so called PSK and SRP suites need extra configuration to
1446              work see user lookup function. No anonymous suites are supported
1447              by TLS-1.3.
1448
1449              Also  note  that the cipher suites returned by this function are
1450              the cipher suites that the OTP ssl application can support  pro‐
1451              vided  that  they are supported by the cryptolib linked with the
1452              OTP crypto  application.  Use   ssl:filter_cipher_suites(Suites,
1453              []). to filter the list for the current cryptolib. Note that ci‐
1454              pher suites may be filtered out because they are too old or  too
1455              new depending on the cryptolib
1456
1457
1458       cipher_suites(Description, Version, StringType :: rfc | openssl) ->
1459                        [string()]
1460
1461              Types:
1462
1463                 Description = default | all | exclusive | anonymous
1464                 Version = protocol_version()
1465
1466              Same  as  cipher_suites/2  but lists RFC or OpenSSL string names
1467              instead of erl_cipher_suite()
1468
1469       eccs() -> NamedCurves
1470
1471       eccs(Version) -> NamedCurves
1472
1473              Types:
1474
1475                 Version = protocol_version()
1476                 NamedCurves = [named_curve()]
1477
1478              Returns a list of supported ECCs. eccs() is equivalent to  call‐
1479              ing  eccs(Protocol)  with all supported protocols and then dedu‐
1480              plicating the output.
1481
1482       clear_pem_cache() -> ok
1483
1484              PEM files, used by ssl API-functions, are cached for performance
1485              reasons. The cache is automatically checked at regular intervals
1486              to see if any cache entries should be invalidated.
1487
1488              This function provides a way to unconditionally clear the entire
1489              cache, thereby forcing a reload of previously cached PEM files.
1490
1491       connect(TCPSocket, TLSOptions) ->
1492                  {ok, sslsocket()} |
1493                  {error, reason()} |
1494                  {option_not_a_key_value_tuple, any()}
1495
1496       connect(TCPSocket, TLSOptions, Timeout) ->
1497                  {ok, sslsocket()} | {error, reason()}
1498
1499              Types:
1500
1501                 TCPSocket = socket()
1502                 TLSOptions = [tls_client_option()]
1503                 Timeout = timeout()
1504
1505              Upgrades  a  gen_tcp,  or  equivalent, connected socket to a TLS
1506              socket, that is, performs the client-side TLS handshake.
1507
1508          Note:
1509              If  the  option  verify  is  set  to  verify_peer   the   option
1510              server_name_indication  shall also be specified, if it is not no
1511              Server  Name  Indication  extension  will  be  sent,  and   pub‐
1512              lic_key:pkix_verify_hostname/2  will  be  called with the IP-ad‐
1513              dress of the connection as ReferenceID, which  is  probably  not
1514              what you want.
1515
1516
1517              If the option {handshake, hello} is used the handshake is paused
1518              after receiving the server hello message  and  the  success  re‐
1519              sponse  is  {ok,  SslSocket,  Ext}  instead  of {ok, SslSocket}.
1520              Thereafter the handshake is continued  or  canceled  by  calling
1521              handshake_continue/3 or handshake_cancel/1.
1522
1523              If  the  option active is set to once, true or an integer value,
1524              the process owning the sslsocket will receive messages  of  type
1525              active_msgs()
1526
1527       connect(Host, Port, TLSOptions) ->
1528                  {ok, sslsocket()} |
1529                  {ok, sslsocket(), Ext :: protocol_extensions()} |
1530                  {error, reason()} |
1531                  {option_not_a_key_value_tuple, any()}
1532
1533       connect(Host, Port, TLSOptions, Timeout) ->
1534                  {ok, sslsocket()} |
1535                  {ok, sslsocket(), Ext :: protocol_extensions()} |
1536                  {error, reason()} |
1537                  {option_not_a_key_value_tuple, any()}
1538
1539              Types:
1540
1541                 Host = host()
1542                 Port = inet:port_number()
1543                 TLSOptions = [tls_client_option()]
1544                 Timeout = timeout()
1545
1546              Opens a TLS/DTLS connection to Host, Port.
1547
1548              When  the  option  verify  is  set to verify_peer the check pub‐
1549              lic_key:pkix_verify_hostname/2 will be performed in addition  to
1550              the  usual  x509-path  validation checks. If the check fails the
1551              error {bad_cert, hostname_check_failed} will  be  propagated  to
1552              the  path  validation fun verify_fun, where it is possible to do
1553              customized checks by using the full possibilities  of  the  pub‐
1554              lic_key:pkix_verify_hostname/3     API.    When    the    option
1555              server_name_indication is provided, its  value  (the  DNS  name)
1556              will  be  used  as  ReferenceID  to public_key:pkix_verify_host‐
1557              name/2. When no server_name_indication option is given, the Host
1558              argument  will  be used as Server Name Indication extension. The
1559              Host argument will also be  used  for  the  public_key:pkix_ver‐
1560              ify_hostname/2  check and if the Host argument is an inet:ip_ad‐
1561              dress() the ReferenceID used for the check will  be  {ip,  Host}
1562              otherwise  dns_id  will be assumed with a fallback to ip if that
1563              fails.
1564
1565          Note:
1566              According to good practices certificates should not  use  IP-ad‐
1567              dresses  as  "server names". It would be very surprising if this
1568              happened outside a closed network.
1569
1570
1571              If the option {handshake, hello} is used the handshake is paused
1572              after  receiving  the  server  hello message and the success re‐
1573              sponse is {ok,  SslSocket,  Ext}  instead  of  {ok,  SslSocket}.
1574              Thereafter  the  handshake  is  continued or canceled by calling
1575              handshake_continue/3 or handshake_cancel/1.
1576
1577              If the option active is set to once, true or an  integer  value,
1578              the  process  owning the sslsocket will receive messages of type
1579              active_msgs()
1580
1581       close(SslSocket) -> ok | {error, Reason}
1582
1583              Types:
1584
1585                 SslSocket = sslsocket()
1586                 Reason = any()
1587
1588              Closes a TLS/DTLS connection.
1589
1590       close(SslSocket, How) ->
1591                ok | {ok, port()} | {ok, port(), Data} | {error, Reason}
1592
1593              Types:
1594
1595                 SslSocket = sslsocket()
1596                 How = timeout() | {NewController :: pid(), timeout()}
1597                 Data = binary()
1598                 Reason = any()
1599
1600              Closes or downgrades a TLS connection. In the  latter  case  the
1601              transport  connection  will  be handed over to the NewController
1602              process after receiving the TLS close alert from the  peer.  The
1603              returned  transport  socket will have the following options set:
1604              [{active, false}, {packet, 0}, {mode, binary}].
1605
1606              In case of downgrade, the close function might return  some  bi‐
1607              nary  data that should be treated by the user as the first bytes
1608              received on the downgraded connection.
1609
1610       controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
1611
1612              Types:
1613
1614                 SslSocket = sslsocket()
1615                 NewOwner = pid()
1616                 Reason = any()
1617
1618              Assigns a new controlling process to the SSL socket. A  control‐
1619              ling  process  is  the  owner of an SSL socket, and receives all
1620              messages from the socket.
1621
1622       connection_information(SslSocket) ->
1623                                 {ok, Result} | {error, reason()}
1624
1625              Types:
1626
1627                 SslSocket = sslsocket()
1628                 Result = connection_info()
1629
1630              Returns the most relevant information about the connection,  ssl
1631              options  that are undefined will be filtered out. Note that val‐
1632              ues that affect the security of the connection will only be  re‐
1633              turned if explicitly requested by connection_information/2.
1634
1635          Note:
1636              The legacy Item = cipher_suite was removed in OTP-23. Previously
1637              it returned the cipher suite on its (undocumented)  legacy  for‐
1638              mat. It is replaced by selected_cipher_suite.
1639
1640
1641       connection_information(SslSocket, Items) ->
1642                                 {ok, Result} | {error, reason()}
1643
1644              Types:
1645
1646                 SslSocket = sslsocket()
1647                 Items = connection_info_items()
1648                 Result = connection_info()
1649
1650              Returns the requested information items about the connection, if
1651              they are defined.
1652
1653              Note that client_random, server_random, master_secret and keylog
1654              are  values  that  affect the security of connection. Meaningful
1655              atoms, not specified above, are the ssl option names.
1656
1657              In order to retrieve keylog and other secret information from  a
1658              TLS  1.3  connection, keep_secrets must be configured in advance
1659              and set to true.
1660
1661          Note:
1662              If only undefined options are requested the resulting  list  can
1663              be empty.
1664
1665
1666       filter_cipher_suites(Suites, Filters) -> Ciphers
1667
1668              Types:
1669
1670                 Suites = ciphers()
1671                 Filters = cipher_filters()
1672                 Ciphers = ciphers()
1673
1674              Removes  cipher  suites  if  any of the filter functions returns
1675              false for any part of the cipher suite. If no filter function is
1676              supplied  for  some  part the default behaviour regards it as if
1677              there was a filter function that returned true. For examples see
1678              Customizing cipher suites  Additionally, this function also fil‐
1679              ters the cipher suites to exclude cipher suites not supported by
1680              the  cryptolib used by the OTP crypto application. That is call‐
1681              ing ssl:filter_cipher_suites(Suites, []) will be  equivalent  to
1682              only applying the filters for cryptolib support.
1683
1684       format_error(Reason :: Reason | {error, Reason}) -> string()
1685
1686              Types:
1687
1688                 Reason = any()
1689
1690              Presents  the  error  returned by an SSL function as a printable
1691              string.
1692
1693       getopts(SslSocket, OptionNames) ->
1694                  {ok, [gen_tcp:option()]} | {error, reason()}
1695
1696              Types:
1697
1698                 SslSocket = sslsocket()
1699                 OptionNames = [gen_tcp:option_name()]
1700
1701              Gets the values of the specified socket options.
1702
1703       getstat(SslSocket) -> {ok, OptionValues} | {error, inet:posix()}
1704
1705       getstat(SslSocket, Options) ->
1706                  {ok, OptionValues} | {error, inet:posix()}
1707
1708              Types:
1709
1710                 SslSocket = sslsocket()
1711                 Options = [inet:stat_option()]
1712                 OptionValues = [{inet:stat_option(), integer()}]
1713
1714              Gets one or  more  statistic  options  for  the  underlying  TCP
1715              socket.
1716
1717              See inet:getstat/2 for statistic options description.
1718
1719       handshake(HsSocket) ->
1720                    {ok, SslSocket} |
1721                    {ok, SslSocket, Ext} |
1722                    {error, Reason}
1723
1724       handshake(HsSocket, Timeout) ->
1725                    {ok, SslSocket} |
1726                    {ok, SslSocket, Ext} |
1727                    {error, Reason}
1728
1729              Types:
1730
1731                 HsSocket = sslsocket()
1732                 Timeout = timeout()
1733                 SslSocket = sslsocket()
1734                 Ext = protocol_extensions()
1735                 Reason = closed | timeout | error_alert()
1736
1737              Performs the TLS/DTLS server-side handshake.
1738
1739              Returns a new TLS/DTLS socket if the handshake is successful.
1740
1741              If  the  option active is set to once, true or an integer value,
1742              the process owning the sslsocket will receive messages  of  type
1743              active_msgs()
1744
1745          Warning:
1746              Not  setting the timeout makes the server more vulnerable to DoS
1747              attacks.
1748
1749
1750       handshake(Socket, Options) ->
1751                    {ok, SslSocket} |
1752                    {ok, SslSocket, Ext} |
1753                    {error, Reason}
1754
1755       handshake(Socket, Options, Timeout) ->
1756                    {ok, SslSocket} |
1757                    {ok, SslSocket, Ext} |
1758                    {error, Reason}
1759
1760              Types:
1761
1762                 Socket = socket() | sslsocket()
1763                 SslSocket = sslsocket()
1764                 Options = [server_option()]
1765                 Timeout = timeout()
1766                 Ext = protocol_extensions()
1767                 Reason = closed | timeout | {options, any()} | error_alert()
1768
1769              If Socket is a ordinary socket(): upgrades a gen_tcp, or equiva‐
1770              lent, socket to an SSL socket, that is, performs the TLS server-
1771              side handshake and returns a TLS socket.
1772
1773          Warning:
1774              The ordinary Socket shall be in passive mode  ({active,  false})
1775              before  calling  this  function,  and before the client tries to
1776              connect with TLS, or else the behavior of this function is unde‐
1777              fined.  The  best  way  to ensure this is to create the ordinary
1778              listen socket in passive mode.
1779
1780
1781              If Socket is an  sslsocket() : provides extra  TLS/DTLS  options
1782              to  those  specified  in listen/2 and then performs the TLS/DTLS
1783              handshake. Returns a new TLS/DTLS socket  if  the  handshake  is
1784              successful.
1785
1786          Warning:
1787              Not  setting the timeout makes the server more vulnerable to DoS
1788              attacks.
1789
1790
1791              If option {handshake,  hello}  is  specified  the  handshake  is
1792              paused  after receiving the client hello message and the success
1793              response is {ok, SslSocket, Ext}  instead  of  {ok,  SslSocket}.
1794              Thereafter  the  handshake  is  continued or canceled by calling
1795              handshake_continue/3 or handshake_cancel/1.
1796
1797              If the option active is set to once, true or an  integer  value,
1798              the  process  owning the sslsocket will receive messages of type
1799              active_msgs()
1800
1801       handshake_cancel(Sslsocket :: #sslsocket{}) -> any()
1802
1803              Cancel the handshake with a fatal USER_CANCELED alert.
1804
1805       handshake_continue(HsSocket, Options) ->
1806                             {ok, SslSocket} | {error, Reason}
1807
1808       handshake_continue(HsSocket, Options, Timeout) ->
1809                             {ok, SslSocket} | {error, Reason}
1810
1811              Types:
1812
1813                 HsSocket = sslsocket()
1814                 Options = [tls_client_option() | tls_server_option()]
1815                 Timeout = timeout()
1816                 SslSocket = sslsocket()
1817                 Reason = closed | timeout | error_alert()
1818
1819              Continue the TLS handshake, possibly  with  new,  additional  or
1820              changed options.
1821
1822       listen(Port, Options) -> {ok, ListenSocket} | {error, reason()}
1823
1824              Types:
1825
1826                 Port = inet:port_number()
1827                 Options = [tls_server_option()]
1828                 ListenSocket = sslsocket()
1829
1830              Creates an SSL listen socket.
1831
1832       negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason}
1833
1834              Types:
1835
1836                 SslSocket = sslsocket()
1837                 Protocol = binary()
1838                 Reason = protocol_not_negotiated
1839
1840              Returns the protocol negotiated through ALPN or NPN extensions.
1841
1842       peercert(SslSocket) -> {ok, Cert} | {error, reason()}
1843
1844              Types:
1845
1846                 SslSocket = sslsocket()
1847                 Cert = public_key:der_encoded()
1848
1849              The  peer  certificate  is returned as a DER-encoded binary. The
1850              certificate can be  decoded  with  public_key:pkix_decode_cert/2
1851              Suggested  further  reading  about  certificates  is  public_key
1852              User's Guide and ssl User's Guide
1853
1854       peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1855
1856              Types:
1857
1858                 SslSocket = sslsocket()
1859                 Address = inet:ip_address()
1860                 Port = inet:port_number()
1861
1862              Returns the address and port number of the peer.
1863
1864       prepend_cipher_suites(Preferred, Suites) -> ciphers()
1865
1866              Types:
1867
1868                 Preferred = ciphers() | cipher_filters()
1869                 Suites = ciphers()
1870
1871              Make Preferred suites become the most preferred suites  that  is
1872              put  them  at the head of the cipher suite list Suites after re‐
1873              moving them from Suites if present. Preferred may be a  list  of
1874              cipher suites or a list of filters in which case the filters are
1875              use on Suites to extract the preferred cipher list.
1876
1877       prf(SslSocket, Secret, Label, Seed, WantedLength) ->
1878              {ok, binary()} | {error, reason()}
1879
1880              Types:
1881
1882                 SslSocket = sslsocket()
1883                 Secret = binary() | master_secret
1884                 Label = binary()
1885                 Seed = [binary() | prf_random()]
1886                 WantedLength = integer() >= 0
1887
1888              Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1889              ate  extra  key  material. It either takes user-generated values
1890              for Secret and Seed or atoms directing  it  to  use  a  specific
1891              value from the session security parameters.
1892
1893       recv(SslSocket, Length) -> {ok, Data} | {error, reason()}
1894
1895       recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()}
1896
1897              Types:
1898
1899                 SslSocket = sslsocket()
1900                 Length = integer() >= 0
1901                 Data = binary() | list() | HttpPacket
1902                 Timeout = timeout()
1903                 HttpPacket = any()
1904                   See the description of HttpPacket in erlang:decode_packet/3
1905                   in ERTS.
1906
1907              Receives a packet from a socket in passive mode. A closed socket
1908              is indicated by return value {error, closed}.
1909
1910              Argument  Length  is  meaningful only when the socket is in mode
1911              raw and denotes the number of bytes to read. If Length = 0,  all
1912              available  bytes  are  returned.  If  Length > 0, exactly Length
1913              bytes are returned, or an error; possibly discarding  less  than
1914              Length  bytes of data when the socket gets closed from the other
1915              side.
1916
1917              Optional argument Timeout specifies a time-out in  milliseconds.
1918              The default value is infinity.
1919
1920       renegotiate(SslSocket) -> ok | {error, reason()}
1921
1922              Types:
1923
1924                 SslSocket = sslsocket()
1925
1926              Initiates  a  new  handshake.  A notable return value is {error,
1927              renegotiation_rejected} indicating that the peer refused  to  go
1928              through  with the renegotiation, but the connection is still ac‐
1929              tive using the previously negotiated session.
1930
1931       update_keys(SslSocket, Type) -> ok | {error, reason()}
1932
1933              Types:
1934
1935                 SslSocket = sslsocket()
1936                 Type = write | read_write
1937
1938              There are cryptographic limits on the amount of plaintext  which
1939              can be safely encrypted under a given set of keys. If the amount
1940              of data surpasses those limits, a key update is triggered and  a
1941              new  set  of  keys  are  installed.  See also the option key_up‐
1942              date_at.
1943
1944              This function can be used to explicitly start a key update on  a
1945              TLS  1.3  connection.  There are two types of the key update: if
1946              Type is set to write, only the writing key is updated;  if  Type
1947              is  set to read_write, both the reading and writing keys are up‐
1948              dated.
1949
1950       send(SslSocket, Data) -> ok | {error, reason()}
1951
1952              Types:
1953
1954                 SslSocket = sslsocket()
1955                 Data = iodata()
1956
1957              Writes Data to SslSocket.
1958
1959              A notable return value is {error, closed}  indicating  that  the
1960              socket is closed.
1961
1962       setopts(SslSocket, Options) -> ok | {error, reason()}
1963
1964              Types:
1965
1966                 SslSocket = sslsocket()
1967                 Options = [gen_tcp:option()]
1968
1969              Sets options according to Options for socket SslSocket.
1970
1971       shutdown(SslSocket, How) -> ok | {error, reason()}
1972
1973              Types:
1974
1975                 SslSocket = sslsocket()
1976                 How = read | write | read_write
1977
1978              Immediately closes a socket in one or two directions.
1979
1980              How  == write means closing the socket for writing, reading from
1981              it is still possible.
1982
1983              To be able to handle that the peer has done a  shutdown  on  the
1984              write side, option {exit_on_close, false} is useful.
1985
1986       sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()}
1987
1988              Types:
1989
1990                 SslSocket = sslsocket()
1991                 Address = inet:ip_address()
1992                 Port = inet:port_number()
1993
1994              Returns the local address and port number of socket SslSocket.
1995
1996       start() -> ok | {error, reason()}
1997
1998       start(Type :: permanent | transient | temporary) ->
1999                ok | {error, reason()}
2000
2001              Starts the SSL application. Default type is temporary.
2002
2003       stop() -> ok
2004
2005              Stops the SSL application.
2006
2007       str_to_suite(CipherSuiteName) ->
2008                       erl_cipher_suite() |
2009                       {error, {not_recognized, CipherSuiteName}}
2010
2011              Types:
2012
2013                 CipherSuiteName = string()
2014
2015              Converts  an RFC or OpenSSL name string to an erl_cipher_suite()
2016              Returns an error if the cipher suite is  not  supported  or  the
2017              name is not a valid cipher suite name.
2018
2019       suite_to_openssl_str(CipherSuite) -> string()
2020
2021              Types:
2022
2023                 CipherSuite = erl_cipher_suite()
2024
2025              Converts erl_cipher_suite() to OpenSSL name string.
2026
2027              PRE TLS-1.3 these names differ for RFC names
2028
2029       suite_to_str(CipherSuite) -> string()
2030
2031              Types:
2032
2033                 CipherSuite = erl_cipher_suite()
2034
2035              Converts erl_cipher_suite() to RFC name string.
2036
2037       transport_accept(ListenSocket) ->
2038                           {ok, SslSocket} | {error, reason()}
2039
2040       transport_accept(ListenSocket, Timeout) ->
2041                           {ok, SslSocket} | {error, reason()}
2042
2043              Types:
2044
2045                 ListenSocket = sslsocket()
2046                 Timeout = timeout()
2047                 SslSocket = sslsocket()
2048
2049              Accepts  an incoming connection request on a listen socket. Lis‐
2050              tenSocket must be a socket returned from  listen/2.  The  socket
2051              returned  is  to be passed to  handshake/[2,3] to complete hand‐
2052              shaking, that is, establishing the TLS/DTLS connection.
2053
2054          Warning:
2055              Most API functions require that the TLS/DTLS connection  is  es‐
2056              tablished to work as expected.
2057
2058
2059              The accepted socket inherits the options set for ListenSocket in
2060              listen/2.
2061
2062              The default value for Timeout is infinity. If Timeout is  speci‐
2063              fied  and  no connection is accepted within the given time, {er‐
2064              ror, timeout} is returned.
2065
2066       versions() -> [VersionInfo]
2067
2068              Types:
2069
2070                 VersionInfo =
2071                     {ssl_app, string()} |
2072                     {supported | available | implemented, [tls_version()]} |
2073                     {supported_dtls | available_dtls | implemented_dtls,
2074                      [dtls_version()]}
2075
2076              Lists information, mainly concerning TLS/DTLS versions, in  run‐
2077              time for debugging and testing purposes.
2078
2079                app_vsn:
2080                  The application version of the SSL application.
2081
2082                supported:
2083                  TLS  versions supported with current application environment
2084                  and crypto library configuration. Overridden  by  a  version
2085                  option  on  connect/[2,3,4],  listen/2, and handshake/[2,3].
2086                  For the negotiated TLS version, see connection_information/1
2087                  .
2088
2089                supported_dtls:
2090                  DTLS versions supported with current application environment
2091                  and crypto library configuration. Overridden  by  a  version
2092                  option  on  connect/[2,3,4],  listen/2, and handshake/[2,3].
2093                  For the negotiated  DTLS  version,  see  connection_informa‐
2094                  tion/1 .
2095
2096                available:
2097                  All TLS versions supported with the linked crypto library.
2098
2099                available_dtls:
2100                  All DTLS versions supported with the linked crypto library.
2101
2102                implemented:
2103                  All  TLS versions supported by the SSL application if linked
2104                  with a crypto library with the necessary support.
2105
2106                implemented_dtls:
2107                  All DTLS versions supported by the SSL application if linked
2108                  with a crypto library with the necessary support.
2109

SEE ALSO

2111       inet(3) and gen_tcp(3) gen_udp(3)
2112
2113
2114
2115Ericsson AB                      ssl 10.9.1.2                           ssl(3)
Impressum