1ssl(3) Erlang Module Definition ssl(3)
2
6 ssl - Interface Functions for Secure Socket Layer
7
9 This module contains interface functions for the SSL/TLS protocol. For
10 detailed information about the supported standards see ssl(6).
11
13 The following data types are used in the functions for SSL:
14 boolean() =:
16 true | false
17 option() =:
19 socketoption() | ssl_option() | transport_option()
20 socketoption() =:
22 proplists:property()
23 The default socket options are [{mode,list},{packet, 0},{header,
25 0},{active, true}].
26 For valid options, see the inet(3) and gen_tcp(3) manual pages in
28 Kernel.
29 ssl_option() =:
31 {verify, verify_type()}
32 | {verify_fun, {fun(), term()}}
34 | {fail_if_no_peer_cert, boolean()}
36 | {depth, integer()}
38 | {cert, public_key:der_encoded()}
40 | {certfile, path()}
42 | {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' | 'Pri‐
44 vateKeyInfo', public_key:der_encoded()} | #{algorithm := rsa | dss
45 | ecdsa, engine := crypto:engine_ref(), key_id := crypto:key_id(),
46 password => crypto:password()}
47 | {keyfile, path()}
49 | {password, string()}
51 | {cacerts, [public_key:der_encoded()]}
53 | {cacertfile, path()}
55 | {dh, public_key:der_encoded()}
57 | {dhfile, path()}
59 | {ciphers, ciphers()}
61 | {user_lookup_fun, {fun(), term()}}, {psk_identity, string()},
63 {srp_identity, {string(), string()}}
64 | {reuse_sessions, boolean()}
66 | {reuse_session, fun()} {next_protocols_advertised, [binary()]}
68 | {client_preferred_next_protocols, {client | server, [binary()]} |
70 {client | server, [binary()], binary()}}
71 | {log_alert, boolean()}
73 | {server_name_indication, hostname() | disable}
75 | {sni_hosts, [{hostname(), [ssl_option()]}]}
77 | {sni_fun, SNIfun::fun()}
79 transport_option() =:
81 {cb_info, {CallbackModule::atom(), DataTag::atom(), Closed‐
82 Tag::atom(), ErrTag:atom()}}
83 Defaults to {gen_tcp, tcp, tcp_closed, tcp_error}. Can be used to
85 customize the transport layer. The callback module must implement a
86 reliable transport protocol, behave as gen_tcp, and have functions
87 corresponding to inet:setopts/2, inet:getopts/2, inet:peername/1,
88 inet:sockname/1, and inet:port/1. The callback gen_tcp is treated
89 specially and calls inet directly.
90 CallbackModule =:
92 atom()
93 DataTag =:
95 atom()
96 Used in socket data message.
98 ClosedTag =:
100 atom()
101 Used in socket close message.
103 verify_type() =:
105 verify_none | verify_peer
106 path() =:
108 string()
109 Represents a file path.
111 public_key:der_encoded() =:
113 binary()
114 ASN.1 DER-encoded entity as an Erlang binary.
116 host() =:
118 hostname() | ipaddress()
119 hostname() =:
121 string() - DNS hostname
122 ip_address() =:
124 {N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6
125 sslsocket() =:
127 opaque()
128 protocol_version() =:
130 sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'
131 ciphers() =:
133 = [ciphersuite()]
134 Tuples and string formats accepted by versions before ssl-8.2.4
136 will be converted for backwards compatibility
137 ciphersuite() =:
139 #{key_exchange := key_exchange(), cipher := cipher(), mac :=
140 MAC::hash() | aead, prf := PRF::hash() | default_prf}
141 key_exchange()=:
143 rsa | dhe_dss | dhe_rsa | dh_anon | psk | dhe_psk | rsa_psk |
144 srp_anon | srp_dss | srp_rsa | ecdh_anon | ecdh_ecdsa | ecdhe_ecdsa
145 | ecdh_rsa | ecdhe_rsa
146 cipher() =:
148 rc4_128 | des_cbc | '3des_ede_cbc' | aes_128_cbc | aes_256_cbc |
149 aes_128_gcm | aes_256_gcm | chacha20_poly1305
150 hash() =:
152 md5 | sha | sha224 | sha256 | sha348 | sha512
153 prf_random() =:
155 client_random | server_random
156 cipher_filters() =:
158 [{key_exchange | cipher | mac | prf, algo_filter()}])
159 algo_filter() =:
161 fun(key_exchange() | cipher() | hash() | aead | default_prf) ->
162 true | false
163 srp_param_type() =:
165 srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 | srp_6144 |
166 srp_8192
167 SNIfun::fun():
169 = fun(ServerName :: string()) -> [ssl_option()]
170 named_curve() =:
172 sect571r1 | sect571k1 | secp521r1 | brainpoolP512r1 | sect409k1 |
173 sect409r1 | brainpoolP384r1 | secp384r1 | sect283k1 | sect283r1 |
174 brainpoolP256r1 | secp256k1 | secp256r1 | sect239k1 | sect233k1 |
175 sect233r1 | secp224k1 | secp224r1 | sect193r1 | sect193r2 |
176 secp192k1 | secp192r1 | sect163k1 | sect163r1 | sect163r2 |
177 secp160k1 | secp160r1 | secp160r2
178
180 The following options have the same meaning in the client and the
181 server:
182 {protocol, tls | dtls}:
184 Choose TLS or DTLS protocol for the transport layer security.
185 Defaults to tls Introduced in OTP 20, DTLS support is considered
186 experimental in this release. DTLS over other transports than UDP
187 are not yet supported.
188 {cert, public_key:der_encoded()}:
190 The DER-encoded users certificate. If this option is supplied, it
191 overrides option certfile.
192 {certfile, path()}:
194 Path to a file containing the user certificate.
195 {key, {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'Pri‐
197 vateKeyInfo', public_key:der_encoded()} | #{algorithm := rsa | dss |
198 ecdsa, engine := crypto:engine_ref(), key_id := crypto:key_id(),
199 password => crypto:password()}:
200 The DER-encoded user's private key or a map refering to a crypto
201 engine and its key reference that optionally can be password pro‐
202 tected, seealso crypto:engine_load/4 and Crypto's Users Guide.
203 If this option is supplied, it overrides option keyfile.
204 {keyfile, path()}:
206 Path to the file containing the user's private PEM-encoded key. As
207 PEM-files can contain several entries, this option defaults to the
208 same file as given by option certfile.
209 {password, string()}:
211 String containing the user's password. Only used if the private
212 keyfile is password-protected.
213 {ciphers, ciphers()}:
215 Supported cipher suites. The function cipher_suites/0 can be used
216 to find all ciphers that are supported by default.
217 cipher_suites(all) can be called to find all available cipher
218 suites. Pre-Shared Key (RFC 4279 and RFC 5487), Secure Remote Pass‐
219 word (RFC 5054), RC4 cipher suites, and anonymous cipher suites
220 only work if explicitly enabled by this option; they are sup‐
221 ported/enabled by the peer also. Anonymous cipher suites are sup‐
222 ported for testing purposes only and are not be used when security
223 matters.
224 {eccs, [named_curve()]}:
226 Allows to specify the order of preference for named curves and to
227 restrict their usage when using a cipher suite supporting them.
228 {secure_renegotiate, boolean()}:
230 Specifies if to reject renegotiation attempt that does not live up
231 to RFC 5746. By default secure_renegotiate is set to false, that
232 is, secure renegotiation is used if possible, but it falls back to
233 insecure renegotiation if the peer does not support RFC 5746.
234 {depth, integer()}:
236 Maximum number of non-self-issued intermediate certificates that
237 can follow the peer certificate in a valid certification path. So,
238 if depth is 0 the PEER must be signed by the trusted ROOT-CA
239 directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path can
240 be PEER, CA, CA, ROOT-CA, and so on. The default value is 1.
241 {verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}}:
243 The verification fun is to be defined as follows:
244 fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked,
246 atom()}} |
247 {extension, #'Extension'{}}, InitialUserState :: term()) ->
248 {valid, UserState :: term()} | {valid_peer, UserState :: term()} |
249 {fail, Reason :: term()} | {unknown, UserState :: term()}.
250 The verification fun is called during the X509-path validation when
253 an error or an extension unknown to the SSL application is encoun‐
254 tered. It is also called when a certificate is considered valid by
255 the path validation to allow access to each certificate in the path
256 to the user application. It differentiates between the peer cer‐
257 tificate and the CA certificates by using valid_peer or valid as
258 second argument to the verification fun. See the public_key User's
259 Guide for definition of #'OTPCertificate'{} and #'Extension'{}.
260 * If the verify callback fun returns {fail, Reason}, the verifica‐
262 tion process is immediately stopped, an alert is sent to the
263 peer, and the TLS/SSL handshake terminates.
264 * If the verify callback fun returns {valid, UserState}, the veri‐
266 fication process continues.
267 * If the verify callback fun always returns {valid, UserState}, the
269 TLS/SSL handshake does not terminate regarding verification fail‐
270 ures and the connection is established.
271 * If called with an extension unknown to the user application,
273 return value {unknown, UserState} is to be used.
274 Note that if the fun returns unknown for an extension marked as
276 critical, validation will fail.
277 Default option verify_fun in verify_peer mode:
279 {fun(_,{bad_cert, _} = Reason, _) ->
281 {fail, Reason};
282 (_,{extension, _}, UserState) ->
283 {unknown, UserState};
284 (_, valid, UserState) ->
285 {valid, UserState};
286 (_, valid_peer, UserState) ->
287 {valid, UserState}
288 end, []}
289 Default option verify_fun in mode verify_none:
292 {fun(_,{bad_cert, _}, UserState) ->
294 {valid, UserState};
295 (_,{extension, #'Extension'{critical = true}}, UserState) ->
296 {valid, UserState};
297 (_,{extension, _}, UserState) ->
298 {unknown, UserState};
299 (_, valid, UserState) ->
300 {valid, UserState};
301 (_, valid_peer, UserState) ->
302 {valid, UserState}
303 end, []}
304 The possible path validation errors are given on form {bad_cert,
307 Reason} where Reason is:
308 unknown_ca:
310 No trusted CA was found in the trusted store. The trusted CA is
311 normally a so called ROOT CA, which is a self-signed certificate.
312 Trust can be claimed for an intermediate CA (trusted anchor does
313 not have to be self-signed according to X-509) by using option
314 partial_chain.
315 selfsigned_peer:
317 The chain consisted only of one self-signed certificate.
318 PKIX X-509-path validation error:
320 For possible reasons, see public_key:pkix_path_validation/3
321 {crl_check, boolean() | peer | best_effort }:
323 Perform CRL (Certificate Revocation List) verification (pub‐
324 lic_key:pkix_crls_validate/3) on all the certificates during the
325 path validation (public_key:pkix_path_validation/3) of the cer‐
326 tificate chain. Defaults to false.
327 peer:
329 check is only performed on the peer certificate.
330 best_effort:
332 if certificate revocation status can not be determined it will be
333 accepted as valid.
334 The CA certificates specified for the connection will be used to
336 construct the certificate chain validating the CRLs.
337 The CRLs will be fetched from a local or external cache. See
339 ssl_crl_cache_api(3).
340 {crl_cache, {Module :: atom(), {DbHandle :: internal | term(), Args
342 :: list()}}}:
343 Specify how to perform lookup and caching of certificate revocation
344 lists. Module defaults to ssl_crl_cache with DbHandle being
345 internal and an empty argument list.
346 There are two implementations available:
348 ssl_crl_cache:
350 This module maintains a cache of CRLs. CRLs can be added to the
351 cache using the function ssl_crl_cache:insert/1, and optionally
352 automatically fetched through HTTP if the following argument is
353 specified:
354 {http, timeout()}:
356 Enables fetching of CRLs specified as http URIs inX509 certifi‐
357 cate extensions. Requires the OTP inets application.
358 ssl_crl_hash_dir:
360 This module makes use of a directory where CRLs are stored in
361 files named by the hash of the issuer name.
362 The file names consist of eight hexadecimal digits followed by
364 .rN, where N is an integer, e.g. 1a2b3c4d.r0. For the first ver‐
365 sion of the CRL, N starts at zero, and for each new version, N is
366 incremented by one. The OpenSSL utility c_rehash creates symlinks
367 according to this pattern.
368 For a given hash value, this module finds all consecutive .r*
370 files starting from zero, and those files taken together make up
371 the revocation list. CRL files whose nextUpdate fields are in the
372 past, or that are issued by a different CA that happens to have
373 the same name hash, are excluded.
374 The following argument is required:
376 {dir, string()}:
378 Specifies the directory in which the CRLs can be found.
379 max_handshake_size:
381 Integer (24 bits unsigned). Used to limit the size of valid TLS
382 handshake packets to avoid DoS attacks. Defaults to 256*1024.
383 {partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} |
385 unknown_ca }:
386 Claim an intermediate CA in the chain as trusted. TLS then performs
387 public_key:pkix_path_validation/3 with the selected CA as trusted
388 anchor and the rest of the chain.
389 {versions, [protocol_version()]}:
391 TLS protocol versions supported by started clients and servers.
392 This option overrides the application environment option proto‐
393 col_version. If the environment option is not set, it defaults to
394 all versions, except SSL-3.0, supported by the SSL application. See
395 also ssl(6).
396 {hibernate_after, integer()|undefined}:
398 When an integer-value is specified, ssl_connection goes into hiber‐
399 nation after the specified number of milliseconds of inactivity,
400 thus reducing its memory footprint. When undefined is specified
401 (this is the default), the process never goes into hibernation.
402 {user_lookup_fun, {Lookupfun :: fun(), UserState :: term()}}:
404 The lookup fun is to defined as follows:
405 fun(psk, PSKIdentity ::string(), UserState :: term()) ->
407 {ok, SharedSecret :: binary()} | error;
408 fun(srp, Username :: string(), UserState :: term()) ->
409 {ok, {SRPParams :: srp_param_type(), Salt :: binary(), DerivedKey :: binary()}} | error.
410 For Pre-Shared Key (PSK) cipher suites, the lookup fun is called by
413 the client and server to determine the shared secret. When called
414 by the client, PSKIdentity is set to the hint presented by the
415 server or to undefined. When called by the server, PSKIdentity is
416 the identity presented by the client.
417 For Secure Remote Password (SRP), the fun is only used by the
419 server to obtain parameters that it uses to generate its session
420 keys. DerivedKey is to be derived according to RFC 2945 and RFC
421 5054: crypto:sha([Salt, crypto:sha([Username, <<$:>>, Password])])
422 {padding_check, boolean()}:
424 Affects TLS-1.0 connections only. If set to false, it disables the
425 block cipher padding check to be able to interoperate with legacy
426 software.
427 Warning:
429 Using {padding_check, boolean()} makes TLS vulnerable to the Poodle
430 attack.
431 {beast_mitigation, one_n_minus_one | zero_n | disabled}:
434 Affects SSL-3.0 and TLS-1.0 connections only. Used to change the
435 BEAST mitigation strategy to interoperate with legacy software.
436 Defaults to one_n_minus_one.
437 one_n_minus_one - Perform 1/n-1 BEAST mitigation.
439 zero_n - Perform 0/n BEAST mitigation.
441 disabled - Disable BEAST mitigation.
443 Warning:
445 Using {beast_mitigation, disabled} makes SSL or TLS vulnerable to the
446 BEAST attack.
447
450 The following options are client-specific or have a slightly different
451 meaning in the client than in the server:
452 {verify, verify_type()}:
454 In mode verify_none the default behavior is to allow all x509-path
455 validation errors. See also option verify_fun.
456 {reuse_sessions, boolean()}:
458 Specifies if the client is to try to reuse sessions when possible.
459 {cacerts, [public_key:der_encoded()]}:
461 The DER-encoded trusted certificates. If this option is supplied it
462 overrides option cacertfile.
463 {cacertfile, path()}:
465 Path to a file containing PEM-encoded CA certificates. The CA cer‐
466 tificates are used during server authentication and when building
467 the client certificate chain.
468 {alpn_advertised_protocols, [binary()]}:
470 The list of protocols supported by the client to be sent to the
471 server to be used for an Application-Layer Protocol Negotiation
472 (ALPN). If the server supports ALPN then it will choose a protocol
473 from this list; otherwise it will fail the connection with a
474 "no_application_protocol" alert. A server that does not support
475 ALPN will ignore this value.
476 The list of protocols must not contain an empty binary.
478 The negotiated protocol can be retrieved using the negotiated_pro‐
480 tocol/1 function.
481 {client_preferred_next_protocols, {Precedence :: server | client,
483 ClientPrefs :: [binary()]}}
484 {client_preferred_next_protocols, {Precedence :: server | client,
485 ClientPrefs :: [binary()], Default :: binary()}}: Indicates that
486 the client is to try to perform Next Protocol Negotiation.
487 If precedence is server, the negotiated protocol is the first pro‐
489 tocol to be shown on the server advertised list, which is also on
490 the client preference list.
491 If precedence is client, the negotiated protocol is the first pro‐
493 tocol to be shown on the client preference list, which is also on
494 the server advertised list.
495 If the client does not support any of the server advertised proto‐
497 cols or the server does not advertise any protocols, the client
498 falls back to the first protocol in its list or to the default pro‐
499 tocol (if a default is supplied). If the server does not support
500 Next Protocol Negotiation, the connection terminates if no default
501 protocol is supplied.
502 {psk_identity, string()}:
504 Specifies the identity the client presents to the server. The
505 matching secret is found by calling user_lookup_fun.
506 {srp_identity, {Username :: string(), Password :: string()} :
508 Specifies the username and password to use to authenticate to the
509 server.
510 {server_name_indication, HostName :: hostname()}:
512 Specify the hostname to be used in TLS Server Name Indication
513 extension. If not specified it will default to the Host argument of
514 connect/[3,4] unless it is of type inet:ipaddress().
515 The HostName will also be used in the hostname verification of the
517 peer certificate using public_key:pkix_verify_hostname/2.
518 {server_name_indication, disable}:
520 Prevents the Server Name Indication extension from being sent and
521 disables the hostname verification check public_key:pkix_ver‐
522 ify_hostname/2
523 {fallback, boolean()}:
525 Send special cipher suite TLS_FALLBACK_SCSV to avoid undesired TLS
526 version downgrade. Defaults to false
527 Warning:
529 Note this option is not needed in normal TLS usage and should not be
530 used to implement new clients. But legacy clients that retries con‐
531 nections in the following manner
532 ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1', 'tlsv1',
534 'sslv3']}])
535 ssl:connect(Host, Port, [...{versions, [tlsv1.1', 'tlsv1',
537 'sslv3']}, {fallback, true}])
538 ssl:connect(Host, Port, [...{versions, ['tlsv1', 'sslv3']}, {fall‐
540 back, true}])
541 ssl:connect(Host, Port, [...{versions, ['sslv3']}, {fallback,
543 true}])
544 may use it to avoid undesired TLS version downgrade. Note that
546 TLS_FALLBACK_SCSV must also be supported by the server for the pre‐
547 vention to work.
548 {signature_algs, [{hash(), ecdsa | rsa | dsa}]}:
551 In addition to the algorithms negotiated by the cipher suite used
552 for key exchange, payload encryption, message authentication and
553 pseudo random calculation, the TLS signature algorithm extension
554 Section 7.4.1.4.1 in RFC 5246 may be used, from TLS 1.2, to negoti‐
555 ate which signature algorithm to use during the TLS handshake. If
556 no lower TLS versions than 1.2 are supported, the client will send
557 a TLS signature algorithm extension with the algorithms specified
558 by this option. Defaults to
559 [
561 %% SHA2
562 {sha512, ecdsa},
563 {sha512, rsa},
564 {sha384, ecdsa},
565 {sha384, rsa},
566 {sha256, ecdsa},
567 {sha256, rsa},
568 {sha224, ecdsa},
569 {sha224, rsa},
570 %% SHA
571 {sha, ecdsa},
572 {sha, rsa},
573 {sha, dsa},
574 ]
575 The algorithms should be in the preferred order. Selected signature
577 algorithm can restrict which hash functions that may be selected.
578 Default support for {md5, rsa} removed in ssl-8.0
579
581 The following options are server-specific or have a slightly different
582 meaning in the server than in the client:
583 {cacerts, [public_key:der_encoded()]}:
585 The DER-encoded trusted certificates. If this option is supplied it
586 overrides option cacertfile.
587 {cacertfile, path()}:
589 Path to a file containing PEM-encoded CA certificates. The CA cer‐
590 tificates are used to build the server certificate chain and for
591 client authentication. The CAs are also used in the list of accept‐
592 able client CAs passed to the client when a certificate is
593 requested. Can be omitted if there is no need to verify the client
594 and if there are no intermediate CAs for the server certificate.
595 {dh, public_key:der_encoded()}:
597 The DER-encoded Diffie-Hellman parameters. If specified, it over‐
598 rides option dhfile.
599 {dhfile, path()}:
601 Path to a file containing PEM-encoded Diffie Hellman parameters to
602 be used by the server if a cipher suite using Diffie Hellman key
603 exchange is negotiated. If not specified, default parameters are
604 used.
605 {verify, verify_type()}:
607 A server only does x509-path validation in mode verify_peer, as it
608 then sends a certificate request to the client (this message is not
609 sent if the verify option is verify_none). You can then also want
610 to specify option fail_if_no_peer_cert.
611 {fail_if_no_peer_cert, boolean()}:
613 Used together with {verify, verify_peer} by an SSL server. If set
614 to true, the server fails if the client does not have a certificate
615 to send, that is, sends an empty certificate. If set to false, it
616 fails only if the client sends an invalid certificate (an empty
617 certificate is considered valid). Defaults to false.
618 {reuse_sessions, boolean()}:
620 Specifies if the server is to agree to reuse sessions when
621 requested by the clients. See also option reuse_session.
622 {reuse_session, fun(SuggestedSessionId, PeerCert, Compression,
624 CipherSuite) -> boolean()}:
625 Enables the SSL server to have a local policy for deciding if a
626 session is to be reused or not. Meaningful only if reuse_sessions
627 is set to true. SuggestedSessionId is a binary(), PeerCert is a
628 DER-encoded certificate, Compression is an enumeration integer, and
629 CipherSuite is of type ciphersuite().
630 {alpn_preferred_protocols, [binary()]}:
632 Indicates the server will try to perform Application-Layer Protocol
633 Negotiation (ALPN).
634 The list of protocols is in order of preference. The protocol nego‐
636 tiated will be the first in the list that matches one of the proto‐
637 cols advertised by the client. If no protocol matches, the server
638 will fail the connection with a "no_application_protocol" alert.
639 The negotiated protocol can be retrieved using the negotiated_pro‐
641 tocol/1 function.
642 {next_protocols_advertised, Protocols :: [binary()]}:
644 List of protocols to send to the client if the client indicates
645 that it supports the Next Protocol extension. The client can select
646 a protocol that is not on this list. The list of protocols must not
647 contain an empty binary. If the server negotiates a Next Protocol,
648 it can be accessed using the negotiated_next_protocol/1 method.
649 {psk_identity, string()}:
651 Specifies the server identity hint, which the server presents to
652 the client.
653 {log_alert, boolean()}:
655 If set to false, error reports are not displayed.
656 {honor_cipher_order, boolean()}:
658 If set to true, use the server preference for cipher selection. If
659 set to false (the default), use the client preference.
660 {sni_hosts, [{hostname(), [ssl_option()]}]}:
662 If the server receives a SNI (Server Name Indication) from the
663 client matching a host listed in the sni_hosts option, the specific
664 options for that host will override previously specified options.
665 The option sni_fun, and sni_hosts are mutually exclusive.
666 {sni_fun, SNIfun::fun()}:
668 If the server receives a SNI (Server Name Indication) from the
669 client, the given function will be called to retrieve
670 [ssl_option()] for the indicated server. These options will be
671 merged into predefined [ssl_option()]. The function should be
672 defined as: fun(ServerName :: string()) -> [ssl_option()] and can
673 be specified as a fun or as named fun module:function/1 The option
674 sni_fun, and sni_hosts are mutually exclusive.
675 {client_renegotiation, boolean()}:
677 In protocols that support client-initiated renegotiation, the cost
678 of resources of such an operation is higher for the server than the
679 client. This can act as a vector for denial of service attacks. The
680 SSL application already takes measures to counter-act such
681 attempts, but client-initiated renegotiation can be strictly dis‐
682 abled by setting this option to false. The default value is true.
683 Note that disabling renegotiation can result in long-lived connec‐
684 tions becoming unusable due to limits on the number of messages the
685 underlying cipher suite can encipher.
686 {honor_cipher_order, boolean()}:
688 If true, use the server's preference for cipher selection. If false
689 (the default), use the client's preference.
690 {honor_ecc_order, boolean()}:
692 If true, use the server's preference for ECC curve selection. If
693 false (the default), use the client's preference.
694 {signature_algs, [{hash(), ecdsa | rsa | dsa}]}:
696 The algorithms specified by this option will be the ones accepted
697 by the server in a signature algorithm negotiation, introduced in
698 TLS-1.2. The algorithms will also be offered to the client if a
699 client certificate is requested. For more details see the corre‐
700 sponding client option.
701 {v2_hello_compatible, boolean()}:
703 If true, the server accepts clients that send hello messages on
704 SSL-2.0 format but offers supported SSL/TLS versions. Defaults to
705 false, that is the server will not interoperate with clients that
706 offers SSL-2.0.
707
709 When an SSL socket is in active mode (the default), data from the
710 socket is delivered to the owner of the socket in the form of messages:
711 * {ssl, Socket, Data}
713 * {ssl_closed, Socket}
715 * {ssl_error, Socket, Reason}
717 A Timeout argument specifies a time-out in milliseconds. The default
719 value for argument Timeout is infinity.
720
722 append_cipher_suites(Deferred, Suites) -> ciphers()
723 Types:
725 Deferred = ciphers() | cipher_filters()
727 Suites = ciphers()
728 Make Deferred suites become the least preferred suites, that is
730 put them at the end of the cipher suite list Suites after remov‐
731 ing them from Suites if present. Deferred may be a list of
732 cipher suits or a list of filters in which case the filters are
733 use on Suites to extract the Deferred cipher list.
734 cipher_suites() ->
736 cipher_suites(Type) -> old_ciphers()
737 Types:
739 Type = erlang | openssl | all
741 Returns a list of supported cipher suites. This function will
743 become deprecated in OTP 21, and replaced by ssl:cipher-suites/2
744 cipher_suites() is equivalent to cipher_suites(erlang). Type
745 openssl is provided for backwards compatibility with the old
746 SSL, which used OpenSSL. cipher_suites(all) returns all avail‐
747 able cipher suites. The cipher suites not present in
748 cipher_suites(erlang) but included in cipher_suites(all) are not
749 used unless explicitly configured by the user.
750 cipher_suites(Supported, Version) -> ciphers()
752 Types:
754 Supported = default | all | anonymous
756 Version = protocol_version()
757 Returns all default or all supported (except anonymous), or all
759 anonymous cipher suites for a TLS version
760 eccs() ->
762 eccs(protocol_version()) -> [named_curve()]
763 Returns a list of supported ECCs. eccs() is equivalent to call‐
765 ing eccs(Protocol) with all supported protocols and then dedu‐
766 plicating the output.
767 clear_pem_cache() -> ok
769 PEM files, used by ssl API-functions, are cached. The cache is
771 regularly checked to see if any cache entries should be invali‐
772 dated, however this function provides a way to unconditionally
773 clear the whole cache.
774 connect(Socket, SslOptions) ->
776 connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {error, Rea‐
777 son}
778 Types:
780 Socket = socket()
782 SslOptions = [ssl_option()]
783 Timeout = integer() | infinity
784 SslSocket = sslsocket()
785 Reason = term()
786 Upgrades a gen_tcp, or equivalent, connected socket to an SSL
788 socket, that is, performs the client-side ssl handshake.
789 Note:
791 If the option verify is set to verify_peer the option
792 server_name_indication shall also be specified, if it is not no
793 Server Name Indication extension will be sent, and pub‐
794 lic_key:pkix_verify_hostname/2 will be called with the IP-
795 address of the connection as ReferenceID, which is proably not
796 what you want.
797 connect(Host, Port, Options) ->
800 connect(Host, Port, Options, Timeout) -> {ok, SslSocket} | {error, Rea‐
801 son}
802 Types:
804 Host = host()
806 Port = integer()
807 Options = [option()]
808 Timeout = integer() | infinity
809 SslSocket = sslsocket()
810 Reason = term()
811 Opens an SSL connection to Host, Port.
813 When the option verify is set to verify_peer the check pub‐
815 lic_key:pkix_verify_hostname/2 will be performed in addition to
816 the usual x509-path validation checks. If the check fails the
817 error {bad_cert, hostname_check_failed} will be propagated to
818 the path validation fun verify_fun, where it is possible to do
819 customized checks by using the full possibilitis of the pub‐
820 lic_key:pkix_verify_hostname/2 API. When the option
821 server_name_indication is provided, its value (the DNS name)
822 will be used as ReferenceID to public_key:pkix_verify_host‐
823 name/2. When no server_name_indication option is given, the Host
824 argument will be used as Server Name Indication extension. The
825 Host argument will also be used for the public_key:pkix_ver‐
826 ify_hostname/2 check and if the Host argument is an
827 inet:ip_address() the ReferenceID used for the check will be
828 {ip, Host} otherwise dns_id will be assumed with a fallback to
829 ip if that fails.
830 Note:
832 According to good practices certificates should not use IP-
833 addresses as "server names". It would be very surprising if this
834 happen outside a closed network.
835 close(SslSocket) -> ok | {error, Reason}
838 Types:
840 SslSocket = sslsocket()
842 Reason = term()
843 Closes an SSL connection.
845 close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}
847 Types:
849 SslSocket = sslsocket()
851 How = timeout() | {NewController::pid(), timeout()}
852 Reason = term()
853 Closes or downgrades an SSL connection. In the latter case the
855 transport connection will be handed over to the NewController
856 process after receiving the TLS close alert from the peer. The
857 returned transport socket will have the following options set:
858 [{active, false}, {packet, 0}, {mode, binary}]
859 controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}
861 Types:
863 SslSocket = sslsocket()
865 NewOwner = pid()
866 Reason = term()
867 Assigns a new controlling process to the SSL socket. A control‐
869 ling process is the owner of an SSL socket, and receives all
870 messages from the socket.
871 connection_information(SslSocket) -> {ok, Result} | {error, Reason}
873 Types:
875 Item = protocol | cipher_suite | sni_hostname | ecc | ses‐
877 sion_id | atom()
878 Meaningful atoms, not specified above, are the ssl option
879 names.
880 Result = [{Item::atom(), Value::term()}]
881 Reason = term()
882 Returns the most relevant information about the connection, ssl
884 options that are undefined will be filtered out. Note that val‐
885 ues that affect the security of the connection will only be
886 returned if explicitly requested by connection_information/2.
887 connection_information(SslSocket, Items) -> {ok, Result} | {error, Rea‐
889 son}
890 Types:
892 Items = [Item]
894 Item = protocol | cipher_suite | sni_hostname | ecc | ses‐
895 sion_id | client_random | server_random | master_secret |
896 atom()
897 Note that client_random, server_random and master_secret
898 are values that affect the security of connection. Meaning‐
899 ful atoms, not specified above, are the ssl option names.
900 Result = [{Item::atom(), Value::term()}]
901 Reason = term()
902 Returns the requested information items about the connection, if
904 they are defined.
905 Note:
907 If only undefined options are requested the resulting list can
908 be empty.
909 filter_cipher_suites(Suites, Filters) -> ciphers()
912 Types:
914 Suites = ciphers()
916 Filters = cipher_filters()
917 Removes cipher suites if any of the filter functions returns
919 false for any part of the cipher suite. This function also calls
920 default filter functions to make sure the cipher suites are sup‐
921 ported by crypto. If no filter function is supplied for some
922 part the default behaviour is fun(Algorithm) -> true.
923 format_error(Reason) -> string()
925 Types:
927 Reason = term()
929 Presents the error returned by an SSL function as a printable
931 string.
932 getopts(Socket, OptionNames) -> {ok, [socketoption()]} | {error, Rea‐
934 son}
935 Types:
937 Socket = sslsocket()
939 OptionNames = [atom()]
940 Gets the values of the specified socket options.
942 getstat(Socket) -> {ok, OptionValues} | {error, inet:posix()}
944 getstat(Socket, OptionNames) -> {ok, OptionValues} | {error,
945 inet:posix()}
946 Types:
948 Socket = sslsocket()
950 OptionNames = [atom()]
951 OptionValues = [{inet:stat_option(), integer()}]
952 Gets one or more statistic options for the underlying TCP
954 socket.
955 See inet:getstat/2 for statistic options description.
957 listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}
959 Types:
961 Port = integer()
963 Options = options()
964 ListenSocket = sslsocket()
965 Creates an SSL listen socket.
967 negotiated_protocol(Socket) -> {ok, Protocol} | {error, proto‐
969 col_not_negotiated}
970 Types:
972 Socket = sslsocket()
974 Protocol = binary()
975 Returns the protocol negotiated through ALPN or NPN extensions.
977 peercert(Socket) -> {ok, Cert} | {error, Reason}
979 Types:
981 Socket = sslsocket()
983 Cert = binary()
984 The peer certificate is returned as a DER-encoded binary. The
986 certificate can be decoded with public_key:pkix_decode_cert/2.
987 peername(Socket) -> {ok, {Address, Port}} | {error, Reason}
989 Types:
991 Socket = sslsocket()
993 Address = ipaddress()
994 Port = integer()
995 Returns the address and port number of the peer.
997 prepend_cipher_suites(Preferred, Suites) -> ciphers()
999 Types:
1001 Preferred = ciphers() | cipher_filters()
1003 Suites = ciphers()
1004 Make Preferred suites become the most preferred suites that is
1006 put them at the head of the cipher suite list Suites after
1007 removing them from Suites if present. Preferred may be a list of
1008 cipher suits or a list of filters in which case the filters are
1009 use on Suites to extract the preferred cipher list.
1010 prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} |
1012 {error, reason()}
1013 Types:
1015 Socket = sslsocket()
1017 Secret = binary() | master_secret
1018 Label = binary()
1019 Seed = [binary() | prf_random()]
1020 WantedLength = non_neg_integer()
1021 Uses the Pseudo-Random Function (PRF) of a TLS session to gener‐
1023 ate extra key material. It either takes user-generated values
1024 for Secret and Seed or atoms directing it to use a specific
1025 value from the session security parameters.
1026 Can only be used with TLS connections; {error, undefined} is
1028 returned for SSLv3 connections.
1029 recv(Socket, Length) ->
1031 recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}
1032 Types:
1034 Socket = sslsocket()
1036 Length = integer()
1037 Timeout = integer()
1038 Data = [char()] | binary()
1039 Receives a packet from a socket in passive mode. A closed socket
1041 is indicated by return value {error, closed}.
1042 Argument Length is meaningful only when the socket is in mode
1044 raw and denotes the number of bytes to read. If Length = 0, all
1045 available bytes are returned. If Length > 0, exactly Length
1046 bytes are returned, or an error; possibly discarding less than
1047 Length bytes of data when the socket gets closed from the other
1048 side.
1049 Optional argument Timeout specifies a time-out in milliseconds.
1051 The default value is infinity.
1052 renegotiate(Socket) -> ok | {error, Reason}
1054 Types:
1056 Socket = sslsocket()
1058 Initiates a new handshake. A notable return value is {error,
1060 renegotiation_rejected} indicating that the peer refused to go
1061 through with the renegotiation, but the connection is still
1062 active using the previously negotiated session.
1063 send(Socket, Data) -> ok | {error, Reason}
1065 Types:
1067 Socket = sslsocket()
1069 Data = iodata()
1070 Writes Data to Socket.
1072 A notable return value is {error, closed} indicating that the
1074 socket is closed.
1075 setopts(Socket, Options) -> ok | {error, Reason}
1077 Types:
1079 Socket = sslsocket()
1081 Options = [socketoption]()
1082 Sets options according to Options for socket Socket.
1084 shutdown(Socket, How) -> ok | {error, Reason}
1086 Types:
1088 Socket = sslsocket()
1090 How = read | write | read_write
1091 Reason = reason()
1092 Immediately closes a socket in one or two directions.
1094 How == write means closing the socket for writing, reading from
1096 it is still possible.
1097 To be able to handle that the peer has done a shutdown on the
1099 write side, option {exit_on_close, false} is useful.
1100 ssl_accept(Socket) ->
1102 ssl_accept(Socket, Timeout) -> ok | {error, Reason}
1103 Types:
1105 Socket = sslsocket()
1107 Timeout = integer()
1108 Reason = term()
1109 Performs the SSL/TLS server-side handshake.
1111 Socket is a socket as returned by ssl:transport_accept/[1,2]
1113 ssl_accept(Socket, SslOptions) ->
1115 ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error,
1116 Reason}
1117 Types:
1119 Socket = socket() | sslsocket()
1121 SslOptions = [ssl_option()]
1122 Timeout = integer()
1123 Reason = term()
1124 If Socket is a socket(): upgrades a gen_tcp, or equivalent,
1126 socket to an SSL socket, that is, performs the SSL/TLS server-
1127 side handshake and returns the SSL socket.
1128 Warning:
1130 The listen socket is to be in mode {active, false} before
1131 telling the client that the server is ready to upgrade by call‐
1132 ing this function, else the upgrade succeeds or does not succeed
1133 depending on timing.
1134 If Socket is an sslsocket(): provides extra SSL/TLS options to
1137 those specified in ssl:listen/2 and then performs the SSL/TLS
1138 handshake.
1139 sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}
1141 Types:
1143 Socket = sslsocket()
1145 Address = ipaddress()
1146 Port = integer()
1147 Returns the local address and port number of socket Socket.
1149 start() ->
1151 start(Type) -> ok | {error, Reason}
1152 Types:
1154 Type = permanent | transient | temporary
1156 Starts the SSL application. Default type is temporary.
1158 stop() -> ok
1160 Stops the SSL application.
1162 transport_accept(ListenSocket) ->
1164 transport_accept(ListenSocket, Timeout) -> {ok, NewSocket} | {error,
1165 Reason}
1166 Types:
1168 ListenSocket = NewSocket = sslsocket()
1170 Timeout = integer()
1171 Reason = reason()
1172 Accepts an incoming connection request on a listen socket. Lis‐
1174 tenSocket must be a socket returned from ssl:listen/2. The
1175 socket returned is to be passed to ssl:ssl_accept[2,3] to com‐
1176 plete handshaking, that is, establishing the SSL/TLS connection.
1177 Warning:
1179 The socket returned can only be used with ssl:ssl_accept[2,3].
1180 No traffic can be sent or received before that call.
1181 The accepted socket inherits the options set for ListenSocket in
1184 ssl:listen/2.
1185 The default value for Timeout is infinity. If Timeout is speci‐
1187 fied and no connection is accepted within the given time,
1188 {error, timeout} is returned.
1189 versions() -> [versions_info()]
1191 Types:
1193 versions_info() = {app_vsn, string()} | {supported | avail‐
1195 able, [protocol_version()]
1196 Returns version information relevant for the SSL application.
1198 app_vsn:
1200 The application version of the SSL application.
1201 supported:
1203 TLS/SSL versions supported by default. Overridden by a ver‐
1204 sion option on connect/[2,3,4], listen/2, and
1205 ssl_accept/[1,2,3]. For the negotiated TLS/SSL version, see
1206 ssl:connection_information/1 .
1207 available:
1209 All TLS/SSL versions supported by the SSL application. TLS
1210 1.2 requires sufficient support from the Crypto application.
1211
1213 inet(3) and gen_tcp(3)
1214Ericsson AB ssl 8.2.6.4 ssl(3)