Provided by: erlang-manpages_20.2.2+dfsg-1ubuntu2_all bug


       ssl - Interface Functions for Secure Socket Layer


       This   module  contains  interface  functions  for  the  SSL/TLS  protocol.  For  detailed
       information about the supported standards see ssl(7).


       The following data types are used in the functions for SSL:

         boolean() =:
           true | false

         option() =:
           socketoption() | ssl_option() | transport_option()

         socketoption() =:

           The default socket options are [{mode,list},{packet, 0},{header, 0},{active, true}].

           For valid options, see the inet(3erl) and gen_tcp(3erl) manual pages in Kernel.

         ssl_option() =:
           {verify, verify_type()}

           | {verify_fun, {fun(), term()}}

           | {fail_if_no_peer_cert, boolean()}

           | {depth, integer()}

           | {cert, public_key:der_encoded()}

           | {certfile, path()}

           |  {key,  {'RSAPrivateKey'|  'DSAPrivateKey'  |  'ECPrivateKey'  |   'PrivateKeyInfo',
           public_key:der_encoded()}   |   #{algorithm   :=   rsa   |  dss  |  ecdsa,  engine  :=
           crypto:engine_ref(), key_id := crypto:key_id(), password => crypto:password()}

           | {keyfile, path()}

           | {password, string()}

           | {cacerts, [public_key:der_encoded()]}

           | {cacertfile, path()}

           | {dh, public_key:der_encoded()}

           | {dhfile, path()}

           | {ciphers, ciphers()}

           |  {user_lookup_fun,  {fun(),  term()}},  {psk_identity,   string()},   {srp_identity,
           {string(), string()}}

           | {reuse_sessions, boolean()}

           | {reuse_session, fun()} {next_protocols_advertised, [binary()]}

           |  {client_preferred_next_protocols, {client | server, [binary()]} | {client | server,
           [binary()], binary()}}

           | {log_alert, boolean()}

           | {server_name_indication, hostname() | disable}

           | {sni_hosts, [{hostname(), [ssl_option()]}]}

           | {sni_fun, SNIfun::fun()}

         transport_option() =:
           {cb_info, {CallbackModule::atom(), DataTag::atom(), ClosedTag::atom(), ErrTag:atom()}}

           Defaults to {gen_tcp, tcp, tcp_closed,  tcp_error}.  Can  be  used  to  customize  the
           transport  layer.  The  callback  module must implement a reliable transport protocol,
           behave as gen_tcp, and have functions corresponding to inet:setopts/2, inet:getopts/2,
           inet:peername/1,  inet:sockname/1,  and  inet:port/1.  The callback gen_tcp is treated
           specially and calls inet directly.

           CallbackModule =:

           DataTag =:

             Used in socket data message.

           ClosedTag =:

             Used in socket close message.

         verify_type() =:
           verify_none | verify_peer

         path() =:

           Represents a file path.

         public_key:der_encoded() =:

           ASN.1 DER-encoded entity as an Erlang binary.

         host() =:
           hostname() | ipaddress()

         hostname() =:
           string() - DNS hostname

         ip_address() =:
           {N1,N2,N3,N4} % IPv4 | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6

         sslsocket() =:

         protocol() =:
           sslv3 | tlsv1 | 'tlsv1.1' | 'tlsv1.2'

         ciphers() =:
           = [ciphersuite()] | string()

           According to old API.

         ciphersuite() =:
           {key_exchange(), cipher(),  MAC::hash()}  |  {key_exchange(),  cipher(),  MAC::hash(),

           rsa  |  dhe_dss  |  dhe_rsa | dh_anon | psk | dhe_psk | rsa_psk | srp_anon | srp_dss |
           srp_rsa | ecdh_anon | ecdh_ecdsa | ecdhe_ecdsa | ecdh_rsa | ecdhe_rsa

         cipher() =:
           rc4_128 | des_cbc |  '3des_ede_cbc'  |  aes_128_cbc  |  aes_256_cbc  |  aes_128_gcm  |
           aes_256_gcm | chacha20_poly1305

         hash() =:
           md5 | sha | sha224 | sha256 | sha348 | sha512

         prf_random() =:
           client_random | server_random

         srp_param_type() =:
           srp_1024 | srp_1536 | srp_2048 | srp_3072 | srp_4096 | srp_6144 | srp_8192

           = fun(ServerName :: string()) -> [ssl_option()]

         named_curve() =:
           sect571r1  |  sect571k1  |  secp521r1  |  brainpoolP512r1  |  sect409k1  | sect409r1 |
           brainpoolP384r1 | secp384r1 | sect283k1 | sect283r1 | brainpoolP256r1  |  secp256k1  |
           secp256r1  |  sect239k1  | sect233k1 | sect233r1 | secp224k1 | secp224r1 | sect193r1 |
           sect193r2 | secp192k1 | secp192r1 | sect163k1 | sect163r1 | sect163r2  |  secp160k1  |
           secp160r1 | secp160r2


       The following options have the same meaning in the client and the server:

         {protocol, tls | dtls}:
           Choose  TLS  or  DTLS  protocol  for  the  transport  layer  security. Defaults to tls
           Introduced in OTP 20, DTLS support is considered experimental in  this  release.  DTLS
           over other transports than UDP are not yet supported.

         {cert, public_key:der_encoded()}:
           The  DER-encoded  users  certificate.  If this option is supplied, it overrides option

         {certfile, path()}:
           Path to a file containing the user certificate.

         {key,   {'RSAPrivateKey'|   'DSAPrivateKey'    |    'ECPrivateKey'    |'PrivateKeyInfo',
         public_key:der_encoded()}   |   #{algorithm   :=   rsa   |   dss   |  ecdsa,  engine  :=
         crypto:engine_ref(), key_id := crypto:key_id(), password => crypto:password()}:
           The DER-encoded user's private key or a map refering to a crypto engine  and  its  key
           reference  that  optionally  can be password protected, seealso  crypto:engine_load/4
           and  Crypto's Users Guide. If this option is supplied, it overrides option keyfile.

         {keyfile, path()}:
           Path to the file containing the user's  private  PEM-encoded  key.  As  PEM-files  can
           contain  several  entries,  this  option  defaults to the same file as given by option

         {password, string()}:
           String containing the user's password. Only used if the private keyfile  is  password-

         {ciphers, ciphers()}:
           Supported  cipher suites. The function cipher_suites/0 can be used to find all ciphers
           that are supported by default. cipher_suites(all) can be called to find all  available
           cipher  suites.  Pre-Shared  Key  (RFC 4279 and RFC 5487), Secure Remote Password (RFC
           5054), RC4 cipher suites, and anonymous cipher suites only work if explicitly  enabled
           by  this  option; they are supported/enabled by the peer also. Anonymous cipher suites
           are supported for testing purposes only and are not be used when security matters.

         {eccs, [named_curve()]}:
           Allows to specify the order of preference for named curves and to restrict their usage
           when using a cipher suite supporting them.

         {secure_renegotiate, boolean()}:
           Specifies  if  to  reject  renegotiation attempt that does not live up to RFC 5746. By
           default secure_renegotiate is set to false, that is, secure renegotiation is  used  if
           possible, but it falls back to insecure renegotiation if the peer does not support RFC

         {depth, integer()}:
           Maximum number of non-self-issued intermediate certificates that can follow  the  peer
           certificate  in  a valid certification path. So, if depth is 0 the PEER must be signed
           by the trusted ROOT-CA directly; if 1 the path can be PEER, CA, ROOT-CA; if 2 the path
           can be PEER, CA, CA, ROOT-CA, and so on. The default value is 1.

         {verify_fun, {Verifyfun :: fun(), InitialUserState :: term()}}:
           The verification fun is to be defined as follows:

         fun(OtpCert :: #'OTPCertificate'{}, Event :: {bad_cert, Reason :: atom() | {revoked,
         atom()}} |
                   {extension, #'Extension'{}}, InitialUserState :: term()) ->
              {valid, UserState :: term()} | {valid_peer, UserState :: term()} |
              {fail, Reason :: term()} | {unknown, UserState :: term()}.

           The  verification  fun  is  called during the X509-path validation when an error or an
           extension unknown to the SSL application is encountered. It  is  also  called  when  a
           certificate  is  considered  valid  by  the  path  validation  to allow access to each
           certificate in the path to the user application. It differentiates  between  the  peer
           certificate and the CA certificates by using valid_peer or valid as second argument to
           the  verification  fun.  See  the  public_key   User's   Guide   for   definition   of
           #'OTPCertificate'{} and #'Extension'{}.

           * If  the  verify  callback  fun  returns  {fail, Reason}, the verification process is
             immediately stopped, an alert is  sent  to  the  peer,  and  the  TLS/SSL  handshake

           * If  the  verify  callback  fun  returns {valid, UserState}, the verification process

           * If the verify callback fun always returns {valid, UserState}, the TLS/SSL  handshake
             does   not   terminate   regarding  verification  failures  and  the  connection  is

           * If called with an extension unknown to the user application, return value  {unknown,
             UserState} is to be used.

             Note that if the fun returns unknown for an extension marked as critical, validation
             will fail.

           Default option verify_fun in verify_peer mode:

         {fun(_,{bad_cert, _} = Reason, _) ->
               {fail, Reason};
             (_,{extension, _}, UserState) ->
               {unknown, UserState};
             (_, valid, UserState) ->
               {valid, UserState};
             (_, valid_peer, UserState) ->
                  {valid, UserState}
          end, []}

           Default option verify_fun in mode verify_none:

         {fun(_,{bad_cert, _}, UserState) ->
               {valid, UserState};
             (_,{extension, #'Extension'{critical = true}}, UserState) ->
               {valid, UserState};
             (_,{extension, _}, UserState) ->
               {unknown, UserState};
             (_, valid, UserState) ->
               {valid, UserState};
             (_, valid_peer, UserState) ->
                  {valid, UserState}
          end, []}

           The possible path validation errors are given on form {bad_cert, Reason} where  Reason

             No trusted CA was found in the trusted store. The trusted CA is normally a so called
             ROOT  CA,  which  is  a  self-signed  certificate.  Trust  can  be  claimed  for  an
             intermediate  CA (trusted anchor does not have to be self-signed according to X-509)
             by using option partial_chain.

             The chain consisted only of one self-signed certificate.

           PKIX X-509-path validation error:
             For possible reasons, see public_key:pkix_path_validation/3

         {crl_check, boolean() | peer | best_effort }:
           Perform       CRL       (Certificate       Revocation        List)        verification
           (public_key:pkix_crls_validate/3)  on  all the certificates during the path validation
           (public_key:pkix_path_validation/3)  of the certificate chain. Defaults to false.

             check is only performed on the peer certificate.

             if certificate revocation status can not be determined it will be accepted as valid.

           The CA certificates specified for  the  connection  will  be  used  to  construct  the
           certificate chain validating the CRLs.

           The CRLs will be fetched from a local or external cache. See ssl_crl_cache_api(3erl).

         {crl_cache, {Module :: atom(), {DbHandle :: internal | term(), Args :: list()}}}:
           Specify  how  to  perform  lookup  and caching of certificate revocation lists. Module
           defaults to ssl_crl_cache with  DbHandle  being internal and an empty argument list.

           There are two implementations available:

             This module maintains a cache of CRLs. CRLs can be added  to  the  cache  using  the
             function  ssl_crl_cache:insert/1,  and optionally automatically fetched through HTTP
             if the following argument is specified:

             {http, timeout()}:
               Enables fetching of CRLs specified as http  URIs  inX509  certificate  extensions.
               Requires the OTP inets application.

             This  module  makes  use  of a directory where CRLs are stored in files named by the
             hash of the issuer name.

             The file names consist of eight hexadecimal digits followed by .rN, where  N  is  an
             integer,  e.g.  1a2b3c4d.r0. For the first version of the CRL, N starts at zero, and
             for each new version, N is incremented by one. The OpenSSL utility c_rehash  creates
             symlinks according to this pattern.

             For  a  given  hash value, this module finds all consecutive .r* files starting from
             zero, and those files taken together make up the revocation list.  CRL  files  whose
             nextUpdate fields are in the past, or that are issued by a different CA that happens
             to have the same name hash, are excluded.

             The following argument is required:

             {dir, string()}:
               Specifies the directory in which the CRLs can be found.

             Integer (24 bits unsigned). Used to limit the size of valid TLS handshake packets to
             avoid DoS attacks. Defaults to 256*1024.

         {partial_chain, fun(Chain::[DerCert]) -> {trusted_ca, DerCert} | unknown_ca }:
           Claim   an   intermediate   CA   in   the   chain   as   trusted.  TLS  then  performs
           public_key:pkix_path_validation/3 with the selected CA as trusted anchor and the  rest
           of the chain.

         {versions, [protocol()]}:
           TLS  protocol versions supported by started clients and servers. This option overrides
           the application environment option protocol_version. If the environment option is  not
           set,  it  defaults  to all versions, except SSL-3.0, supported by the SSL application.
           See also ssl(7).

         {hibernate_after, integer()|undefined}:
           When an integer-value is specified, ssl_connection goes  into  hibernation  after  the
           specified  number  of  milliseconds of inactivity, thus reducing its memory footprint.
           When undefined is specified (this  is  the  default),  the  process  never  goes  into

         {user_lookup_fun, {Lookupfun :: fun(), UserState :: term()}}:
           The lookup fun is to defined as follows:

         fun(psk, PSKIdentity ::string(), UserState :: term()) ->
              {ok, SharedSecret :: binary()} | error;
         fun(srp, Username :: string(), UserState :: term()) ->
              {ok, {SRPParams :: srp_param_type(), Salt :: binary(), DerivedKey :: binary()}} | error.

           For  Pre-Shared  Key  (PSK)  cipher suites, the lookup fun is called by the client and
           server to determine the shared secret. When called by the client, PSKIdentity  is  set
           to  the  hint  presented  by  the  server  or to undefined. When called by the server,
           PSKIdentity is the identity presented by the client.

           For Secure Remote Password (SRP), the fun  is  only  used  by  the  server  to  obtain
           parameters  that  it  uses  to  generate its session keys. DerivedKey is to be derived
           according to  RFC 2945 and  RFC 5054: crypto:sha([Salt, crypto:sha([Username,  <<$:>>,

         {padding_check, boolean()}:
           Affects  TLS-1.0  connections  only.  If  set  to  false, it disables the block cipher
           padding check to be able to interoperate with legacy software.

         Using {padding_check, boolean()} makes TLS vulnerable to the Poodle attack.

         {beast_mitigation, one_n_minus_one | zero_n | disabled}:
           Affects SSL-3.0 and TLS-1.0 connections only. Used  to  change  the  BEAST  mitigation
           strategy to interoperate with legacy software. Defaults to one_n_minus_one.

           one_n_minus_one - Perform 1/n-1 BEAST mitigation.

           zero_n - Perform 0/n BEAST mitigation.

           disabled - Disable BEAST mitigation.

         Using {beast_mitigation, disabled} makes SSL or TLS vulnerable to the BEAST attack.


       The  following  options  are  client-specific  or have a slightly different meaning in the
       client than in the server:

         {verify, verify_type()}:
           In mode verify_none the default behavior is to allow all x509-path validation  errors.
           See also option verify_fun.

         {reuse_sessions, boolean()}:
           Specifies if the client is to try to reuse sessions when possible.

         {cacerts, [public_key:der_encoded()]}:
           The  DER-encoded  trusted certificates. If this option is supplied it overrides option

         {cacertfile, path()}:
           Path to a file containing PEM-encoded CA certificates. The CA  certificates  are  used
           during server authentication and when building the client certificate chain.

         {alpn_advertised_protocols, [binary()]}:
           The  list of protocols supported by the client to be sent to the server to be used for
           an Application-Layer Protocol Negotiation (ALPN). If the server supports ALPN then  it
           will  choose  a  protocol from this list; otherwise it will fail the connection with a
           "no_application_protocol" alert. A server that does not support ALPN will ignore  this

           The list of protocols must not contain an empty binary.

           The negotiated protocol can be retrieved using the negotiated_protocol/1 function.

         {client_preferred_next_protocols,   {Precedence  ::  server  |  client,  ClientPrefs  ::
           {client_preferred_next_protocols, {Precedence  ::  server  |  client,  ClientPrefs  ::
           [binary()], Default :: binary()}}: Indicates that the client is to try to perform Next
           Protocol Negotiation.

           If precedence is server, the negotiated protocol is the first protocol to be shown  on
           the server advertised list, which is also on the client preference list.

           If  precedence is client, the negotiated protocol is the first protocol to be shown on
           the client preference list, which is also on the server advertised list.

           If the client does not support any of the server advertised protocols  or  the  server
           does  not  advertise any protocols, the client falls back to the first protocol in its
           list or to the default protocol (if a default is supplied). If  the  server  does  not
           support Next Protocol Negotiation, the connection terminates if no default protocol is

         {psk_identity, string()}:
           Specifies the identity the client presents to the server. The matching secret is found
           by calling user_lookup_fun.

         {srp_identity, {Username :: string(), Password :: string()} :
           Specifies the username and password to use to authenticate to the server.

         {server_name_indication, HostName :: hostname()}:
           Specify  the  hostname  to  be  used  in  TLS Server Name Indication extension. If not
           specified it will default to the Host argument of connect/[3,4] unless it is  of  type

           The  HostName  will  also be used in the hostname verification of the peer certificate
           using public_key:pkix_verify_hostname/2.

         {server_name_indication, disable}:
           Prevents the Server Name  Indication  extension  from  being  sent  and  disables  the
           hostname verification check public_key:pkix_verify_hostname/2

         {fallback, boolean()}:
           Send  special cipher suite TLS_FALLBACK_SCSV to avoid undesired TLS version downgrade.
           Defaults to false

         Note this option is not needed in normal TLS usage and should not be used  to  implement
         new clients. But legacy clients that retries connections in the following manner

          ssl:connect(Host, Port, [...{versions, ['tlsv2', 'tlsv1.1', 'tlsv1', 'sslv3']}])

          ssl:connect(Host,   Port,  [...{versions,  [tlsv1.1',  'tlsv1',  'sslv3']},  {fallback,

          ssl:connect(Host, Port, [...{versions, ['tlsv1', 'sslv3']}, {fallback, true}])

          ssl:connect(Host, Port, [...{versions, ['sslv3']}, {fallback, true}])

         may use it to avoid undesired TLS version downgrade. Note  that  TLS_FALLBACK_SCSV  must
         also be supported by the server for the prevention to work.

         {signature_algs, [{hash(), ecdsa | rsa | dsa}]}:
           In  addition  to  the algorithms negotiated by the cipher suite used for key exchange,
           payload encryption, message authentication and  pseudo  random  calculation,  the  TLS
           signature algorithm extension Section in RFC 5246 may be used, from TLS 1.2,
           to negotiate which signature algorithm to use during the TLS handshake.  If  no  lower
           TLS  versions  than  1.2 are supported, the client will send a TLS signature algorithm
           extension with the algorithms specified by this option. Defaults to

         %% SHA2
         {sha512, ecdsa},
         {sha512, rsa},
         {sha384, ecdsa},
         {sha384, rsa},
         {sha256, ecdsa},
         {sha256, rsa},
         {sha224, ecdsa},
         {sha224, rsa},
         %% SHA
         {sha, ecdsa},
         {sha, rsa},
         {sha, dsa},

           The algorithms should be in the preferred  order.  Selected  signature  algorithm  can
           restrict  which  hash  functions  that may be selected. Default support for {md5, rsa}
           removed in ssl-8.0


       The following options are server-specific or have a  slightly  different  meaning  in  the
       server than in the client:

         {cacerts, [public_key:der_encoded()]}:
           The  DER-encoded  trusted certificates. If this option is supplied it overrides option

         {cacertfile, path()}:
           Path to a file containing PEM-encoded CA certificates. The CA certificates are used to
           build  the  server  certificate  chain and for client authentication. The CAs are also
           used in the list of acceptable client CAs passed to the client when a  certificate  is
           requested. Can be omitted if there is no need to verify the client and if there are no
           intermediate CAs for the server certificate.

         {dh, public_key:der_encoded()}:
           The DER-encoded Diffie-Hellman parameters. If specified, it overrides option dhfile.

         {dhfile, path()}:
           Path to a file containing PEM-encoded Diffie Hellman parameters  to  be  used  by  the
           server  if  a  cipher  suite  using  Diffie Hellman key exchange is negotiated. If not
           specified, default parameters are used.

         {verify, verify_type()}:
           A server only does x509-path validation in  mode  verify_peer,  as  it  then  sends  a
           certificate  request  to  the client (this message is not sent if the verify option is
           verify_none). You can then also want to specify option fail_if_no_peer_cert.

         {fail_if_no_peer_cert, boolean()}:
           Used together with {verify, verify_peer} by an SSL server. If set to true, the  server
           fails  if  the  client  does  not  have a certificate to send, that is, sends an empty
           certificate. If set to false, it fails only if the client sends an invalid certificate
           (an empty certificate is considered valid). Defaults to false.

         {reuse_sessions, boolean()}:
           Specifies  if  the server is to agree to reuse sessions when requested by the clients.
           See also option reuse_session.

         {reuse_session,   fun(SuggestedSessionId,   PeerCert,   Compression,   CipherSuite)   ->
           Enables  the  SSL  server  to  have  a local policy for deciding if a session is to be
           reused or not. Meaningful only if reuse_sessions is set to true. SuggestedSessionId is
           a  binary(),  PeerCert  is  a  DER-encoded  certificate, Compression is an enumeration
           integer, and CipherSuite is of type ciphersuite().

         {alpn_preferred_protocols, [binary()]}:
           Indicates the server  will  try  to  perform  Application-Layer  Protocol  Negotiation

           The  list  of protocols is in order of preference. The protocol negotiated will be the
           first in the list that matches one of the protocols advertised by the  client.  If  no
           protocol matches, the server will fail the connection with a "no_application_protocol"

           The negotiated protocol can be retrieved using the negotiated_protocol/1 function.

         {next_protocols_advertised, Protocols :: [binary()]}:
           List of protocols to send to the client if the client indicates that it  supports  the
           Next  Protocol  extension.  The client can select a protocol that is not on this list.
           The list of protocols must not contain an empty binary. If  the  server  negotiates  a
           Next Protocol, it can be accessed using the negotiated_next_protocol/1 method.

         {psk_identity, string()}:
           Specifies the server identity hint, which the server presents to the client.

         {log_alert, boolean()}:
           If set to false, error reports are not displayed.

         {honor_cipher_order, boolean()}:
           If  set  to true, use the server preference for cipher selection. If set to false (the
           default), use the client preference.

         {sni_hosts, [{hostname(), [ssl_option()]}]}:
           If the server receives a SNI (Server Name Indication) from the client matching a  host
           listed  in  the  sni_hosts  option,  the  specific options for that host will override
           previously  specified  options.  The  option  sni_fun,  and  sni_hosts  are   mutually

         {sni_fun, SNIfun::fun()}:
           If  the  server  receives  a  SNI  (Server Name Indication) from the client, the given
           function will be called to retrieve [ssl_option()] for  the  indicated  server.  These
           options  will be merged into predefined [ssl_option()]. The function should be defined
           as: fun(ServerName :: string()) -> [ssl_option()] and can be specified as a fun or  as
           named fun module:function/1 The option sni_fun, and sni_hosts are mutually exclusive.

         {client_renegotiation, boolean()}:
           In  protocols  that  support  client-initiated renegotiation, the cost of resources of
           such an operation is higher for the server than the client. This can act as  a  vector
           for  denial of service attacks. The SSL application already takes measures to counter-
           act such attempts, but client-initiated renegotiation  can  be  strictly  disabled  by
           setting  this  option  to  false.  The  default  value  is  true.  Note that disabling
           renegotiation can result in long-lived connections becoming unusable due to limits  on
           the number of messages the underlying cipher suite can encipher.

         {honor_cipher_order, boolean()}:
           If true, use the server's preference for cipher selection. If false (the default), use
           the client's preference.

         {honor_ecc_order, boolean()}:
           If true, use the server's preference for ECC curve selection. If false (the  default),
           use the client's preference.

         {signature_algs, [{hash(), ecdsa | rsa | dsa}]}:
           The  algorithms  specified by this option will be the ones accepted by the server in a
           signature algorithm negotiation, introduced in TLS-1.2. The algorithms  will  also  be
           offered  to  the client if a client certificate is requested. For more details see the
           corresponding client option.

         {v2_hello_compatible, boolean()}:
           If true, the server accepts clients that send hello messages  on  SSL-2.0  format  but
           offers  supported  SSL/TLS  versions.  Defaults  to false, that is the server will not
           interoperate with clients that offers SSL-2.0.


       When an SSL socket is in active mode (the default), data from the socket is  delivered  to
       the owner of the socket in the form of messages:

         * {ssl, Socket, Data}

         * {ssl_closed, Socket}

         * {ssl_error, Socket, Reason}

       A  Timeout  argument  specifies a time-out in milliseconds. The default value for argument
       Timeout is infinity.


       cipher_suites() ->
       cipher_suites(Type) -> ciphers()


                 Type = erlang | openssl | all

              Returns a list  of  supported  cipher  suites.  cipher_suites()  is  equivalent  to
              cipher_suites(erlang).  Type  openssl  is provided for backwards compatibility with
              the old SSL, which used OpenSSL. cipher_suites(all) returns  all  available  cipher
              suites.  The  cipher  suites  not  present in cipher_suites(erlang) but included in
              cipher_suites(all) are not used unless explicitly configured by the user.

       eccs() ->
       eccs(protocol()) -> [named_curve()]

              Returns a list of supported ECCs. eccs() is equivalent  to  calling  eccs(Protocol)
              with all supported protocols and then deduplicating the output.

       clear_pem_cache() -> ok

              PEM files, used by ssl API-functions, are cached. The cache is regularly checked to
              see if any cache entries should be invalidated, however this  function  provides  a
              way to unconditionally clear the whole cache.

       connect(Socket, SslOptions) ->
       connect(Socket, SslOptions, Timeout) -> {ok, SslSocket} | {error, Reason}


                 Socket = socket()
                 SslOptions = [ssl_option()]
                 Timeout = integer() | infinity
                 SslSocket = sslsocket()
                 Reason = term()

              Upgrades  a  gen_tcp,  or  equivalent,  connected socket to an SSL socket, that is,
              performs the client-side ssl handshake.

              If the option verify is set to verify_peer the option server_name_indication  shall
              also  be  specified, if it is not no Server Name Indication extension will be sent,
              and public_key:pkix_verify_hostname/2 will be called with  the  IP-address  of  the
              connection as ReferenceID, which is proably not what you want.

       connect(Host, Port, Options) ->
       connect(Host, Port, Options, Timeout) -> {ok, SslSocket} | {error, Reason}


                 Host = host()
                 Port = integer()
                 Options = [option()]
                 Timeout = integer() | infinity
                 SslSocket = sslsocket()
                 Reason = term()

              Opens an SSL connection to Host, Port.

              When     the     option    verify    is    set    to    verify_peer    the    check
              public_key:pkix_verify_hostname/2 will  be  performed  in  addition  to  the  usual
              x509-path   validation   checks.   If   the   check   fails  the  error  {bad_cert,
              hostname_check_failed} will be propagated to the path  validation  fun  verify_fun,
              where  it is possible to do customized checks by using the full possibilitis of the
              public_key:pkix_verify_hostname/2 API. When the  option  server_name_indication  is
              provided,   its   value   (the   DNS   name)   will   be  used  as  ReferenceID  to
              public_key:pkix_verify_hostname/2. When no server_name_indication option is  given,
              the  Host  argument  will  be  used  as  Server Name Indication extension. The Host
              argument will also be used for the public_key:pkix_verify_hostname/2 check  and  if
              the  Host  argument is an inet:ip_address() the ReferenceID used for the check will
              be {ip, Host} otherwise dns_id will be assumed with a fallback to ip if that fails.

              According to good practices certificates should not  use  IP-addresses  as  "server
              names". It would be very surprising if this happen outside a closed network.

       close(SslSocket) -> ok | {error, Reason}


                 SslSocket = sslsocket()
                 Reason = term()

              Closes an SSL connection.

       close(SslSocket, How) -> ok | {ok, port()} | {error, Reason}


                 SslSocket = sslsocket()
                 How = timeout() | {NewController::pid(), timeout()}
                 Reason = term()

              Closes or downgrades an SSL connection. In the latter case the transport connection
              will be handed over to the NewController process  after  receiving  the  TLS  close
              alert  from the peer. The returned transport socket will have the following options
              set: [{active, false}, {packet, 0}, {mode, binary}]

       controlling_process(SslSocket, NewOwner) -> ok | {error, Reason}


                 SslSocket = sslsocket()
                 NewOwner = pid()
                 Reason = term()

              Assigns a new controlling process to the SSL socket. A controlling process  is  the
              owner of an SSL socket, and receives all messages from the socket.

       connection_information(SslSocket) -> {ok, Result} | {error, Reason}


                 Item = protocol | cipher_suite | sni_hostname | ecc | session_id | atom()
                   Meaningful atoms, not specified above, are the ssl option names.
                 Result = [{Item::atom(), Value::term()}]
                 Reason = term()

              Returns  the  most  relevant information about the connection, ssl options that are
              undefined will be filtered out. Note that values that affect the  security  of  the
              connection    will    only    be    returned    if    explicitly    requested    by

       connection_information(SslSocket, Items) -> {ok, Result} | {error, Reason}


                 Items = [Item]
                 Item = protocol | cipher_suite | sni_hostname | ecc | session_id | client_random
                 | server_random | master_secret | atom()
                   Note  that  client_random,  server_random  and  master_secret  are values that
                   affect the security of connection. Meaningful atoms, not specified above,  are
                   the ssl option names.
                 Result = [{Item::atom(), Value::term()}]
                 Reason = term()

              Returns the requested information items about the connection, if they are defined.

              If only undefined options are requested the resulting list can be empty.

       format_error(Reason) -> string()


                 Reason = term()

              Presents the error returned by an SSL function as a printable string.

       getopts(Socket, OptionNames) -> {ok, [socketoption()]} | {error, Reason}


                 Socket = sslsocket()
                 OptionNames = [atom()]

              Gets the values of the specified socket options.

       getstat(Socket) -> {ok, OptionValues} | {error, inet:posix()}
       getstat(Socket, OptionNames) -> {ok, OptionValues} | {error, inet:posix()}


                 Socket = sslsocket()
                 OptionNames = [atom()]
                 OptionValues = [{inet:stat_option(), integer()}]

              Gets one or more statistic options for the underlying TCP socket.

              See inet:getstat/2 for statistic options description.

       listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}


                 Port = integer()
                 Options = options()
                 ListenSocket = sslsocket()

              Creates an SSL listen socket.

       negotiated_protocol(Socket) -> {ok, Protocol} | {error, protocol_not_negotiated}


                 Socket = sslsocket()
                 Protocol = binary()

              Returns the protocol negotiated through ALPN or NPN extensions.

       peercert(Socket) -> {ok, Cert} | {error, Reason}


                 Socket = sslsocket()
                 Cert = binary()

              The  peer  certificate  is returned as a DER-encoded binary. The certificate can be
              decoded with public_key:pkix_decode_cert/2.

       peername(Socket) -> {ok, {Address, Port}} | {error, Reason}


                 Socket = sslsocket()
                 Address = ipaddress()
                 Port = integer()

              Returns the address and port number of the peer.

       prf(Socket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()}


                 Socket = sslsocket()
                 Secret = binary() | master_secret
                 Label = binary()
                 Seed = [binary() | prf_random()]
                 WantedLength = non_neg_integer()

              Uses the Pseudo-Random Function (PRF) of  a  TLS  session  to  generate  extra  key
              material.  It  either  takes  user-generated  values  for  Secret and Seed or atoms
              directing it to use a specific value from the session security parameters.

              Can only be used with TLS connections; {error, undefined}  is  returned  for  SSLv3

       recv(Socket, Length) ->
       recv(Socket, Length, Timeout) -> {ok, Data} | {error, Reason}


                 Socket = sslsocket()
                 Length = integer()
                 Timeout = integer()
                 Data = [char()] | binary()

              Receives  a  packet  from a socket in passive mode. A closed socket is indicated by
              return value {error, closed}.

              Argument Length is meaningful only when the socket is in mode raw and  denotes  the
              number of bytes to read. If Length = 0, all available bytes are returned. If Length
              > 0, exactly Length bytes are returned, or an error; possibly discarding less  than
              Length bytes of data when the socket gets closed from the other side.

              Optional  argument  Timeout specifies a time-out in milliseconds. The default value
              is infinity.

       renegotiate(Socket) -> ok | {error, Reason}


                 Socket = sslsocket()

              Initiates   a   new   handshake.   A    notable    return    value    is    {error,
              renegotiation_rejected}  indicating  that  the  peer refused to go through with the
              renegotiation, but the connection is still active using the  previously  negotiated

       send(Socket, Data) -> ok | {error, Reason}


                 Socket = sslsocket()
                 Data = iodata()

              Writes Data to Socket.

              A notable return value is {error, closed} indicating that the socket is closed.

       setopts(Socket, Options) -> ok | {error, Reason}


                 Socket = sslsocket()
                 Options = [socketoption]()

              Sets options according to Options for socket Socket.

       shutdown(Socket, How) -> ok | {error, Reason}


                 Socket = sslsocket()
                 How = read | write | read_write
                 Reason = reason()

              Immediately closes a socket in one or two directions.

              How  ==  write  means  closing  the  socket  for  writing, reading from it is still

              To be able to handle that the peer has done a shutdown on the  write  side,  option
              {exit_on_close, false} is useful.

       ssl_accept(Socket) ->
       ssl_accept(Socket, Timeout) -> ok | {error, Reason}


                 Socket = sslsocket()
                 Timeout = integer()
                 Reason = term()

              Performs the SSL/TLS server-side handshake.

              Socket is a socket as returned by ssl:transport_accept/[1,2]

       ssl_accept(Socket, SslOptions) ->
       ssl_accept(Socket, SslOptions, Timeout) -> {ok, Socket} | ok | {error, Reason}


                 Socket = socket() | sslsocket()
                 SslOptions = [ssl_option()]
                 Timeout = integer()
                 Reason = term()

              If  Socket  is  a  socket():  upgrades  a  gen_tcp, or equivalent, socket to an SSL
              socket, that is, performs the SSL/TLS server-side handshake  and  returns  the  SSL

              The  listen  socket is to be in mode {active, false} before telling the client that
              the server is ready to upgrade by calling this function, else the upgrade  succeeds
              or does not succeed depending on timing.

              If  Socket  is an sslsocket(): provides extra SSL/TLS options to those specified in
              ssl:listen/2  and then performs the SSL/TLS handshake.

       sockname(Socket) -> {ok, {Address, Port}} | {error, Reason}


                 Socket = sslsocket()
                 Address = ipaddress()
                 Port = integer()

              Returns the local address and port number of socket Socket.

       start() ->
       start(Type) -> ok | {error, Reason}


                 Type = permanent | transient | temporary

              Starts the SSL application. Default type is temporary.

       stop() -> ok

              Stops the SSL application.

       transport_accept(ListenSocket) ->
       transport_accept(ListenSocket, Timeout) -> {ok, NewSocket} | {error, Reason}


                 ListenSocket = NewSocket = sslsocket()
                 Timeout = integer()
                 Reason = reason()

              Accepts an incoming connection request on a listen socket. ListenSocket must  be  a
              socket  returned  from   ssl:listen/2.  The  socket  returned  is  to  be passed to
              ssl:ssl_accept[2,3] to complete handshaking,  that  is,  establishing  the  SSL/TLS

              The  socket  returned can only be used with  ssl:ssl_accept[2,3]. No traffic can be
              sent or received before that call.

              The accepted socket inherits the options set for ListenSocket in  ssl:listen/2.

              The default value  for  Timeout  is  infinity.  If  Timeout  is  specified  and  no
              connection is accepted within the given time, {error, timeout} is returned.

       versions() -> [versions_info()]


                 versions_info() = {app_vsn, string()} | {supported | available, [protocol()]

              Returns version information relevant for the SSL application.

                  The application version of the SSL application.

                  TLS/SSL  versions  supported  by  default.  Overridden  by  a version option on
                  connect/[2,3,4],  listen/2, and ssl_accept/[1,2,3]. For the negotiated  TLS/SSL
                  version, see ssl:connection_information/1 .

                  All  TLS/SSL  versions  supported  by  the  SSL  application.  TLS 1.2 requires
                  sufficient support from the Crypto application.


       inet(3erl) and gen_tcp(3erl)