Go to main content

man pages section 3: Extended Library Functions, Volume 1

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

crypto (3erl)

Name

crypto - Crypto Functions

Synopsis

Please see following description for synopsis

Description

crypto(3)                  Erlang Module Definition                  crypto(3)



NAME
       crypto - Crypto Functions

DESCRIPTION
       This module provides a set of cryptographic functions.

         Hash functions:


           SHA1, SHA2:
              Secure Hash Standard [FIPS PUB 180-4]

           SHA3:
              SHA-3  Standard:  Permutation-Based  Hash  and Extendable-Output
             Functions [FIPS PUB 202]

           BLAKE2:
             BLAKE2 -- fast secure hashing

           MD5:
             The MD5 Message Digest Algorithm [RFC 1321]

           MD4:
             The MD4 Message Digest Algorithm [RFC 1320]

         MACs - Message Authentication Codes:


           Hmac functions:
              Keyed-Hashing for Message Authentication [RFC 2104]

           Cmac functions:
              The AES-CMAC Algorithm [RFC 4493]

           POLY1305:
              ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]

         Symmetric Ciphers:


           DES, 3DES and AES:
             Block Cipher Techniques [NIST]

           Blowfish:
              Fast Software Encryption, Cambridge Security  Workshop  Proceed-
             ings (December 1993), Springer-Verlag, 1994, pp. 191-204.

           Chacha20:
              ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]

           Chacha20_poly1305:
              ChaCha20 and Poly1305 for IETF Protocols [RFC 7539]

         Modes:


           ECB, CBC, CFB, OFB and CTR:
              Recommendation  for Block Cipher Modes of Operation: Methods and
             Techniques [NIST SP 800-38A]

           GCM:
              Recommendation   for   Block   Cipher   Modes   of    Operation:
             Galois/Counter Mode (GCM) and GMAC [NIST SP 800-38D]

           CCM:
              Recommendation for Block Cipher Modes of Operation: The CCM Mode
             for Authentication and Confidentiality [NIST SP 800-38C]

         Asymetric Ciphers - Public Key Techniques:


           RSA:
              PKCS #1: RSA Cryptography Specifications [RFC 3447]

           DSS:
              Digital Signature Standard (DSS) [FIPS 186-4]

           ECDSA:
              Elliptic Curve Digital Signature Algorithm [ECDSA]

           SRP:
              The SRP Authentication and Key Exchange System [RFC 2945]

   Note:
       The actual supported algorithms and features depends  on  their  avail-
       ability in the actual libcrypto used. See the crypto (App) about depen-
       dencies.

       Enabling FIPS mode will also disable algorithms and features.


       The CRYPTO User's Guide has more information on FIPS, Engines and Algo-
       rithm Details like key lengths.

DATA TYPES
   Ciphers
       cipher() = cipher_no_iv() | cipher_iv() | cipher_aead()

       cipher_no_iv() =
           aes_128_ecb | aes_192_ecb | aes_256_ecb | aes_ecb |
           blowfish_ecb | des_ecb | rc4

       cipher_iv() =
           aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
           aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
           aes_cfb128 | aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 |
           aes_cfb8 | aes_128_ctr | aes_192_ctr | aes_256_ctr | aes_ctr |
           blowfish_cbc | blowfish_cfb64 | blowfish_ofb64 | chacha20 |
           des_ede3_cbc | des_ede3_cfb | des_cbc | des_cfb | rc2_cbc

       cipher_aead() =
           aes_128_ccm | aes_192_ccm | aes_256_ccm | aes_ccm |
           aes_128_gcm | aes_192_gcm | aes_256_gcm | aes_gcm |
           chacha20_poly1305

              Ciphers known by the CRYPTO application.

              Note that this list might be reduced if the underlying libcrypto
              does not support all of them.

       crypto_opts() = boolean() | [crypto_opt()]

       crypto_opt() = {encrypt, boolean()} | {padding, padding()}

              Selects    encryption     ({encrypt,true})     or     decryption
              ({encrypt,false}).

       padding() = cryptolib_padding() | otp_padding()

              This  option  handles  padding in the last block. If not set, no
              padding is done and any bytes in  the  last  unfilled  block  is
              silently discarded.

       cryptolib_padding() = none | pkcs_padding

              The  cryptolib_padding  are  paddings that may be present in the
              underlying cryptolib linked to the Erlang/OTP crypto app.

              For  OpenSSL,  see   the   OpenSSL   documentation.   and   find
              EVP_CIPHER_CTX_set_padding()  in  cryptolib for your linked ver-
              sion.

       otp_padding() = zero | random

              Erlang/OTP adds a either padding of zeroes or padding with  ran-
              dom bytes.

   Digests and hash
       hash_algorithm() =
           sha1() |
           sha2() |
           sha3() |
           blake2() |
           ripemd160 |
           compatibility_only_hash()

       hmac_hash_algorithm() =
           sha1() | sha2() | sha3() | compatibility_only_hash()

       cmac_cipher_algorithm() =
           aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc |
           aes_128_cfb128 | aes_192_cfb128 | aes_256_cfb128 |
           aes_cfb128 | aes_128_cfb8 | aes_192_cfb8 | aes_256_cfb8 |
           aes_cfb8 | blowfish_cbc | des_cbc | des_ede3_cbc | rc2_cbc

       rsa_digest_type() = sha1() | sha2() | md5 | ripemd160

       dss_digest_type() = sha1() | sha2()

       ecdsa_digest_type() = sha1() | sha2()

       sha1() = sha

       sha2() = sha224 | sha256 | sha384 | sha512

       sha3() = sha3_224 | sha3_256 | sha3_384 | sha3_512

       blake2() = blake2b | blake2s

       compatibility_only_hash() = md5 | md4

              The  compatibility_only_hash()  algorithms  are recommended only
              for compatibility with existing applications.

   Elliptic Curves
       ec_named_curve() =
           brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 |
           brainpoolP192t1 | brainpoolP224r1 | brainpoolP224t1 |
           brainpoolP256r1 | brainpoolP256t1 | brainpoolP320r1 |
           brainpoolP320t1 | brainpoolP384r1 | brainpoolP384t1 |
           brainpoolP512r1 | brainpoolP512t1 | c2pnb163v1 | c2pnb163v2 |
           c2pnb163v3 | c2pnb176v1 | c2pnb208w1 | c2pnb272w1 |
           c2pnb304w1 | c2pnb368w1 | c2tnb191v1 | c2tnb191v2 |
           c2tnb191v3 | c2tnb239v1 | c2tnb239v2 | c2tnb239v3 |
           c2tnb359v1 | c2tnb431r1 | ipsec3 | ipsec4 | prime192v1 |
           prime192v2 | prime192v3 | prime239v1 | prime239v2 |
           prime239v3 | prime256v1 | secp112r1 | secp112r2 | secp128r1 |
           secp128r2 | secp160k1 | secp160r1 | secp160r2 | secp192k1 |
           secp192r1 | secp224k1 | secp224r1 | secp256k1 | secp256r1 |
           secp384r1 | secp521r1 | sect113r1 | sect113r2 | sect131r1 |
           sect131r2 | sect163k1 | sect163r1 | sect163r2 | sect193r1 |
           sect193r2 | sect233k1 | sect233r1 | sect239k1 | sect283k1 |
           sect283r1 | sect409k1 | sect409r1 | sect571k1 | sect571r1 |
           wtls1 | wtls10 | wtls11 | wtls12 | wtls3 | wtls4 | wtls5 |
           wtls6 | wtls7 | wtls8 | wtls9

       edwards_curve_dh() = x25519 | x448

       edwards_curve_ed() = ed25519 | ed448

              Note that some curves are disabled if FIPS is enabled.

       ec_explicit_curve() =
           {Field :: ec_field(),
            Curve :: ec_curve(),
            BasePoint :: binary(),
            Order :: binary(),
            CoFactor :: none | binary()}

       ec_field() = ec_prime_field() | ec_characteristic_two_field()

       ec_curve() =
           {A :: binary(), B :: binary(), Seed :: none | binary()}

              Parametric curve definition.

       ec_prime_field() = {prime_field, Prime :: integer()}

       ec_characteristic_two_field() =
           {characteristic_two_field,
            M :: integer(),
            Basis :: ec_basis()}

       ec_basis() =
           {tpbasis, K :: integer() >= 0} |
           {ppbasis,
            K1 :: integer() >= 0,
            K2 :: integer() >= 0,
            K3 :: integer() >= 0} |
           onbasis

              Curve definition details.

   Keys
       key_integer() = integer() | binary()

              Always binary() when used as return value

   Public/Private Keys
       rsa_public() = [key_integer()]

       rsa_private() = [key_integer()]

       rsa_params() =
           {ModulusSizeInBits :: integer(),
            PublicExponent :: key_integer()}

              rsa_public() = [E, N]

              rsa_private() = [E, N, D] | [E, N, D, P1, P2, E1, E2, C]

              Where E is the public exponent, N is public modulus and D is the
              private  exponent.  The  longer  key  format  contains redundant
              information that will make the calculation faster. P1 and P2 are
              first  and  second prime factors. E1 and E2 are first and second
              exponents. C is the CRT coefficient. The  terminology  is  taken
              from  RFC 3447.

       dss_public() = [key_integer()]

       dss_private() = [key_integer()]

              dss_public() = [P, Q, G, Y]

              Where P, Q and G are the dss parameters and Y is the public key.

              dss_private() = [P, Q, G, X]

              Where  P,  Q  and  G are the dss parameters and X is the private
              key.

       ecdsa_public() = key_integer()

       ecdsa_private() = key_integer()

       ecdsa_params() = ec_named_curve() | ec_explicit_curve()

       eddsa_public() = key_integer()

       eddsa_private() = key_integer()

       eddsa_params() = edwards_curve_ed()

       srp_public() = key_integer()

       srp_private() = key_integer()

              srp_public() = key_integer()

              Where is A or B from SRP design

              srp_private() = key_integer()

              Where is a or b from SRP design

       srp_gen_params() =
           {user, srp_user_gen_params()} | {host, srp_host_gen_params()}

       srp_comp_params() =
           {user, srp_user_comp_params()} |
           {host, srp_host_comp_params()}

       srp_user_gen_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom()]

       srp_host_gen_params() = [Verifier::binary(), Prime::binary(), Version::atom() ]

       srp_user_comp_params() = [DerivedKey::binary(), Prime::binary(), Generator::binary(), Version::atom() | ScramblerArg::list()]

       srp_host_comp_params() = [Verifier::binary(), Prime::binary(), Version::atom() | ScramblerArg::list()]

              Where Verifier is v, Generator is g and Prime is  N,  DerivedKey
              is X, and Scrambler is u (optional will be generated if not pro-
              vided) from SRP design Version = '3' | '6' | '6a'

   Public Key Ciphers
       pk_encrypt_decrypt_algs() = rsa

              Algorithms for public key  encrypt/decrypt.  Only  RSA  is  sup-
              ported.

       pk_encrypt_decrypt_opts() = [rsa_opt()] | rsa_compat_opts()

       rsa_opt() =
           {rsa_padding, rsa_padding()} |
           {signature_md, atom()} |
           {rsa_mgf1_md, sha} |
           {rsa_oaep_label, binary()} |
           {rsa_oaep_md, sha}

       rsa_padding() =
           rsa_pkcs1_padding | rsa_pkcs1_oaep_padding |
           rsa_sslv23_padding | rsa_x931_padding | rsa_no_padding

              Options for public key encrypt/decrypt. Only RSA is supported.

          Warning:

              The RSA options are experimental.

              The exact set of options and there syntax may be changed without
              prior notice.


       rsa_compat_opts() = [{rsa_pad, rsa_padding()}] | rsa_padding()

              Those option forms are kept only for  compatibility  and  should
              not be used in new code.

   Public Key Sign and Verify
       pk_sign_verify_algs() = rsa | dss | ecdsa | eddsa

              Algorithms for sign and verify.

       pk_sign_verify_opts() = [rsa_sign_verify_opt()]

       rsa_sign_verify_opt() =
           {rsa_padding, rsa_sign_verify_padding()} |
           {rsa_pss_saltlen, integer()} |
           {rsa_mgf1_md, sha2()}

       rsa_sign_verify_padding() =
           rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding |
           rsa_no_padding

              Options for sign and verify.

          Warning:

              The RSA options are experimental.

              The exact set of options and there syntax may be changed without
              prior notice.


   Diffie-Hellman Keys and parameters
       dh_public() = key_integer()

       dh_private() = key_integer()

       dh_params() = [key_integer()]

              dh_params() = [P, G] | [P, G, PrivateKeyBitLength]

       ecdh_public() = key_integer()

       ecdh_private() = key_integer()

       ecdh_params() =
           ec_named_curve() | edwards_curve_dh() | ec_explicit_curve()

   Types for Engines
       engine_key_ref() =
           #{engine := engine_ref(),
             key_id := key_id(),
             password => password(),
             term() => term()}

       engine_ref() = term()

              The result of a call to engine_load/3.

       key_id() = string() | binary()

              Identifies the key to be used. The format depends on the  loaded
              engine.  It  is  passed  to the ENGINE_load_(private|public)_key
              functions in libcrypto.

       password() = string() | binary()

              The password of the key stored in an engine.

       engine_method_type() =
           engine_method_rsa | engine_method_dsa | engine_method_dh |
           engine_method_rand | engine_method_ecdh |
           engine_method_ecdsa | engine_method_ciphers |
           engine_method_digests | engine_method_store |
           engine_method_pkey_meths | engine_method_pkey_asn1_meths |
           engine_method_ec

       engine_cmnd() = {unicode:chardata(), unicode:chardata()}

              Pre and Post commands for engine_load/3 and /4.

   Internal data types
       crypto_state()

       hash_state()

       mac_state()

              Contexts with an internal state that should not  be  manipulated
              but passed between function calls.

   Error types
       run_time_error() = any()

              The  exception error:badarg signifies that one or more arguments
              are of wrong data type, or are otherwise badly formed.

              The exception error:notsup signifies that the algorithm is known
              but  is not supported by current underlying libcrypto or explic-
              itly disabled when building that.

              For a list of supported algorithms, see supports(ciphers).

       descriptive_error() = any()

              This is a more developed variant of the older run_time_error().

              The exception is:

                     {Tag, {C_FileName,LineNumber}, Description}

                      Tag = badarg | notsup | error
                      C_FileName = string()
                      LineNumber = integer()
                      Description = string()


              It is like the older type an exception of the  error  class.  In
              addition  they  contain a descriptive text in English. That text
              is targeted to a developer.  Examples  are  "Bad  key  size"  or
              "Cipher id is not an atom".

              The exception tags are:

                badarg:
                  Signifies  that one or more arguments are of wrong data type
                  or are otherwise badly formed.

                notsup:
                  Signifies that the algorithm is known but is  not  supported
                  by  current underlying libcrypto or explicitly disabled when
                  building that one.

                error:
                  An error condition that should not occur, for example a mem-
                  ory  allocation  failed or the underlying cryptolib returned
                  an error code, for example "Can't initialize  context,  step
                  1".  Those  text  usually  needs  searching the C-code to be
                  understood.

              To catch the exception, use for example:

                     try crypto:crypto_init(Ciph, Key, IV, true)
                     catch
                         error:{Tag, {C_FileName,LineNumber}, Description} ->
                                 do_something(......)
                         .....
                     end


EXPORTS
       crypto_init(Cipher, Key, FlagOrOptions) ->
                      State | descriptive_error()

              Types:

                 Cipher = cipher_no_iv()
                 Key = iodata()
                 FlagOrOptions = crypto_opts() | boolean()
                 State = crypto_state()

              Equivalent to the call crypto_init(Cipher, Key, <<>>,  FlagOrOp-
              tions). It is intended for ciphers without an IV (nounce).

       crypto_init(Cipher, Key, IV, FlagOrOptions) ->
                      State | descriptive_error()

              Types:

                 Cipher = cipher_iv()
                 Key = IV = iodata()
                 FlagOrOptions = crypto_opts()
                 State = crypto_state()

              Initializes  a  series of encryptions or decryptions and creates
              an internal state with a reference that is returned.

              If IV = <<>>, no IV is used. This is intended for ciphers  with-
              out an IV (nounce). See crypto_init/3.

              If   IV   =  undefined,  the  IV  must  be  added  by  calls  to
              crypto_dyn_iv_update/3. This is intended for cases where the  IV
              (nounce)  need to be changed for each encryption and decryption.
              See crypto_dyn_iv_init/3.

              The actual encryption or decryption is done  by  crypto_update/2
              (or crypto_dyn_iv_update/3 ).

              For    encryption,    set   the   FlagOrOptions   to   true   or
              [{encrypt,true}].  For  decryption,   set   it   to   false   or
              [{encrypt,false}].

              Padding  could be enabled with the option {padding,Padding}. The
              cryptolib_padding enables pkcs_padding or no padding (none). The
              paddings  zero  or  random fills the last part of the last block
              with zeroes or random bytes. If the last block is already  full,
              nothing is added.

              In  decryption,  the  cryptolib_padding removes such padding, if
              present. The otp_padding is not removed -  it  has  to  be  done
              elsewhere.

              If  padding is {padding,none} or not specifed and the total data
              from all subsequent crypto_updates does not fill the last  block
              fully,  that  last data is lost. In case of {padding,none} there
              will be an error in this case. If padding is not specified,  the
              bytes of the unfilled block is silently discarded.

              The actual padding is performed by crypto_final/1.

              For blocksizes call cipher_info/1.

              See  examples in the User's Guide.

       crypto_update(State, Data) -> Result | descriptive_error()

              Types:

                 State = crypto_state()
                 Data = iodata()
                 Result = binary()

              It  does  an actual crypto operation on a part of the full text.
              If the part is less than a number of full blocks, only the  full
              blocks  (possibly  none)  are  encrypted  or  decrypted  and the
              remaining bytes are saved to the next  crypto_update  operation.
              The State should be created with crypto_init/3 or crypto_init/4.

              See  examples in the User's Guide.

       crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) ->
                             State | descriptive_error()

              Types:

                 Cipher = cipher_iv()
                 Key = iodata()
                 FlagOrOptions = crypto_opts() | boolean()
                 State = crypto_state()

              Initializes  a series of encryptions or decryptions where the IV
              is provided later. The actual encryption or decryption  is  done
              by crypto_dyn_iv_update/3.

              The  function  is  equivalent  to crypto_init(Cipher, Key, unde-
              fined, FlagOrOptions).

       crypto_final(State) -> FinalResult | descriptive_error()

              Types:

                 State = crypto_state()
                 FinalResult = binary()

              Finalizes a series of encryptions or  decryptions  and  delivers
              the  final bytes of the final block. The data returned from this
              function  may  be  empty  if   no   padding   was   enabled   in
              crypto_init/3,4 or crypto_dyn_iv_init/3.

       crypto_get_data(State) -> Result

              Types:

                 State = crypto_state()
                 Result = map()

              Returns  information about the State in the argument. The infor-
              mation is the form of a map, which currently contains at least:

                size:
                  The number of bytes encrypted or decrypted so far.

                padding_size:
                  After a call to crypto_final/1 it  contains  the  number  of
                  bytes padded. Otherwise 0.

                padding_type:
                  The  type  of  the  padding  as  provided  in  the  call  ot
                  crypto_init/3,4.

                encrypt:
                  Is true if encryption is performed. It is false otherwise.

       crypto_dyn_iv_update(State, Data, IV) ->
                               Result | descriptive_error()

              Types:

                 State = crypto_state()
                 Data = IV = iodata()
                 Result = binary()

              Do an actual crypto operation on a part of the full text and the
              IV  is  supplied for each part. The State should be created with
              crypto_dyn_iv_init/3.

       crypto_one_time(Cipher, Key, Data, FlagOrOptions) ->
                          Result | descriptive_error()

              Types:

                 Cipher = cipher_no_iv()
                 Key = Data = iodata()
                 FlagOrOptions = crypto_opts() | boolean()
                 Result = binary()

              As crypto_one_time/5 but for ciphers without IVs.

       crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) ->
                          Result | descriptive_error()

              Types:

                 Cipher = cipher_iv()
                 Key = IV = Data = iodata()
                 FlagOrOptions = crypto_opts() | boolean()
                 Result = binary()

              Do a complete encrypt or decrypt of the full text in  the  argu-
              ment Data.

              For  encryption,  set the FlagOrOptions to true. For decryption,
              set it to false. For setting other options, see crypto_init/4.

              See examples in the User's Guide.

       crypto_one_time_aead(Cipher, Key, IV, InText, AAD,
                            EncFlag :: true) ->
                               Result | descriptive_error()

       crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength,
                            EncFlag) ->
                               Result | descriptive_error()

              Types:

                 Cipher = cipher_aead()
                 Key = IV = InText = AAD = iodata()
                 TagOrTagLength = EncryptTagLength | DecryptTag
                 EncryptTagLength = integer() >= 0
                 DecryptTag = iodata()
                 EncFlag = boolean()
                 Result = EncryptResult | DecryptResult
                 EncryptResult = {OutCryptoText, OutTag}
                 DecryptResult = OutPlainText | error
                 OutCryptoText = OutTag = OutPlainText = binary()

              Do a complete encrypt or decrypt with an AEAD cipher of the full
              text.

              For encryption, set the EncryptFlag to true and set the TagOrTa-
              gLength to the wanted size (in bytes) of the tag, that  is,  the
              tag  length.  If the default length is wanted, the crypto_aead/6
              form may be used.

              For decryption, set the EncryptFlag to false and put the tag  to
              be checked in the argument TagOrTagLength.

              See examples in the User's Guide.

       supports(Type) -> Support

              Types:

                 Type  =  hashs  |  ciphers  |  public_keys  | macs | curves |
                 rsa_opts
                 Support = Hashs | Ciphers | PKs | Macs | Curves | RSAopts
                 Hashs =
                     [sha1() |
                      sha2() |
                      sha3() |
                      blake2() |
                      ripemd160 |
                      compatibility_only_hash()]
                 Ciphers = [cipher()]
                 PKs = [rsa | dss | ecdsa | dh | ecdh | eddh | ec_gf2m]
                 Macs = [hmac | cmac | poly1305]
                 Curves =
                     [ec_named_curve()      |       edwards_curve_dh()       |
                 edwards_curve_ed()]
                 RSAopts = [rsa_sign_verify_opt() | rsa_opt()]

              Can  be  used to determine which crypto algorithms that are sup-
              ported by the underlying libcrypto library

              See hash_info/1 and cipher_info/1 for information about the hash
              and cipher algorithms.

       mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()

              Types:

                 Key = Data = iodata()
                 Mac = binary()

              Short for mac(Type, undefined, Key, Data).

       mac(Type, SubType, Key, Data) -> Mac | descriptive_error()

              Types:

                 Type = hmac | cmac | poly1305
                 SubType =
                     hmac_hash_algorithm()  |  cmac_cipher_algorithm() | unde-
                 fined
                 Key = Data = iodata()
                 Mac = binary()

              Computes a MAC (Message Authentication Code) of type  Type  from
              Data.

              SubType depends on the MAC Type:

                * For  hmac  it  is a hash algorithm, see Algorithm Details in
                  the User's Guide.

                * For cmac it is a cipher suitable  for  cmac,  see  Algorithm
                  Details in the User's Guide.

                * For  poly1305  it  should  be  set to undefined or the mac/2
                  function could be used instead, see Algorithm Details in the
                  User's Guide.

              Key  is  the  authentication  key with a length according to the
              Type and SubType.  The  key  length  could  be  found  with  the
              hash_info/1  (hmac)  for and cipher_info/1 (cmac) functions. For
              poly1305 the key length is 32 bytes. Note that the cryptographic
              quality of the key is not checked.

              The  Mac result will have a default length depending on the Type
              and SubType. To set a  shorter  length,  use  macN/4  or  macN/5
              instead.  The  default length is documented in Algorithm Details
              in the User's Guide.

       macN(Type :: poly1305, Key, Data, MacLength) ->
               Mac | descriptive_error()

              Types:

                 Key = Data = iodata()
                 Mac = binary()
                 MacLength = integer() >= 1

              Short for macN(Type, undefined, Key, Data, MacLength).

       macN(Type, SubType, Key, Data, MacLength) ->
               Mac | descriptive_error()

              Types:

                 Type = hmac | cmac | poly1305
                 SubType =
                     hmac_hash_algorithm() | cmac_cipher_algorithm()  |  unde-
                 fined
                 Key = Data = iodata()
                 Mac = binary()
                 MacLength = integer() >= 1

              Computes  a MAC (Message Authentication Code) as mac/3 and mac/4
              but MacLength will limit the size of the  resultant  Mac  to  at
              most MacLength bytes. Note that if MacLength is greater than the
              actual number of bytes returned from the  underlying  hash,  the
              returned hash will have that shorter length instead.

              The  max  MacLength  is  documented  in Algorithm Details in the
              User's Guide.

       mac_init(Type :: poly1305, Key) -> State | descriptive_error()

              Types:

                 Key = iodata()
                 State = mac_state()

              Short for mac_init(Type, undefined, Key).

       mac_init(Type, SubType, Key) -> State | descriptive_error()

              Types:

                 Type = hmac | cmac | poly1305
                 SubType =
                     hmac_hash_algorithm() | cmac_cipher_algorithm()  |  unde-
                 fined
                 Key = iodata()
                 State = mac_state()

              Initializes the context for streaming MAC operations.

              Type determines which mac algorithm to use in the MAC operation.

              SubType depends on the MAC Type:

                * For  hmac  it  is a hash algorithm, see Algorithm Details in
                  the User's Guide.

                * For cmac it is a cipher suitable  for  cmac,  see  Algorithm
                  Details in the User's Guide.

                * For  poly1305  it  should  be  set to undefined or the mac/2
                  function could be used instead, see Algorithm Details in the
                  User's Guide.

              Key  is  the  authentication  key with a length according to the
              Type and SubType.  The  key  length  could  be  found  with  the
              hash_info/1  (hmac)  for and cipher_info/1 (cmac) functions. For
              poly1305 the key length is 32 bytes. Note that the cryptographic
              quality of the key is not checked.

              The  returned  State  should  be  used in one or more subsequent
              calls to mac_update/2. The MAC  value  is  finally  returned  by
              calling mac_final/1 or mac_finalN/2.

              See  examples in the User's Guide.

       mac_update(State0, Data) -> State | descriptive_error()

              Types:

                 Data = iodata()
                 State0 = State = mac_state()

              Updates the MAC represented by State0 using the given Data which
              could be of any length.

              The State0 is the State value originally from a MAC  init  func-
              tion,  that  is  mac_init/2,  mac_init/3  or  a previous call of
              mac_update/2. The value State0  is  returned  unchanged  by  the
              function as State.

       mac_final(State) -> Mac | descriptive_error()

              Types:

                 State = mac_state()
                 Mac = binary()

              Finalizes  the MAC operation referenced by State. The Mac result
              will have a default length depending on the Type and SubType  in
              the mac_init/2,3 call. To set a shorter length, use mac_finalN/2
              instead. The default length is documented in  Algorithm  Details
              in the User's Guide.

       mac_finalN(State, MacLength) -> Mac | descriptive_error()

              Types:

                 State = mac_state()
                 MacLength = integer() >= 1
                 Mac = binary()

              Finalizes the MAC operation referenced by State.

              Mac  will be a binary with at most MacLength bytes. Note that if
              MacLength is greater than the actual number  of  bytes  returned
              from  the  underlying  hash,  the  returned  hash will have that
              shorter length instead.

              The max MacLength is documented  in  Algorithm  Details  in  the
              User's Guide.

       bytes_to_integer(Bin :: binary()) -> integer()

              Convert binary representation, of an integer, to an Erlang inte-
              ger.

       compute_key(Type, OthersPublicKey, MyPrivateKey, Params) ->
                      SharedSecret

              Types:

                 Type = dh | ecdh | eddh | srp
                 SharedSecret = binary()
                 OthersPublicKey = dh_public() | ecdh_public() | srp_public()
                 MyPrivateKey =
                     dh_private() | ecdh_private() |  {srp_public(),  srp_pri-
                 vate()}
                 Params = dh_params() | ecdh_params() | srp_comp_params()

              Computes  the  shared  secret from the private key and the other
              party's public key. See also public_key:compute_key/2

       exor(Bin1 :: iodata(), Bin2 :: iodata()) -> binary()

              Performs bit-wise XOR (exclusive or) on the data supplied.

       generate_key(Type, Params) -> {PublicKey, PrivKeyOut}

       generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut}

              Types:

                 Type = dh | ecdh | eddh | eddsa | rsa | srp
                 PublicKey =
                     dh_public() | ecdh_public() | rsa_public() | srp_public()
                 PrivKeyIn =
                     undefined |
                     dh_private() |
                     ecdh_private() |
                     rsa_private() |
                     {srp_public(), srp_private()}
                 PrivKeyOut =
                     dh_private() |
                     ecdh_private() |
                     rsa_private() |
                     {srp_public(), srp_private()}
                 Params =
                     dh_params() |
                     ecdh_params() |
                     eddsa_params() |
                     rsa_params() |
                     srp_comp_params()

              Generates a public key of type Type. See also  public_key:gener-
              ate_key/1. May raise exception:

                * error:badarg: an argument is of wrong type or has an illegal
                  value,

                * error:low_entropy: the random generator failed due  to  lack
                  of secure "randomness",

                * error:computation_failed:  the  computation fails of another
                  reason than low_entropy.

          Note:
              RSA key generation is only available if the  runtime  was  built
              with  dirty scheduler support. Otherwise, attempting to generate
              an RSA key will raise exception error:notsup.


       hash(Type, Data) -> Digest

              Types:

                 Type = hash_algorithm()
                 Data = iodata()
                 Digest = binary()

              Computes a message digest of type Type from Data.

              May raise exception error:notsup in case the chosen Type is  not
              supported by the underlying libcrypto implementation.

       hash_init(Type) -> State

              Types:

                 Type = hash_algorithm()
                 State = hash_state()

              Initializes  the  context  for  streaming  hash operations. Type
              determines which digest to use. The returned context  should  be
              used as argument to hash_update.

              May  raise exception error:notsup in case the chosen Type is not
              supported by the underlying libcrypto implementation.

       hash_update(State, Data) -> NewState

              Types:

                 State = NewState = hash_state()
                 Data = iodata()

              Updates the digest represented by Context using the given  Data.
              Context  must  have been generated using hash_init or a previous
              call to this function. Data can be any length.  NewContext  must
              be passed into the next call to hash_update or hash_final.

       hash_final(State) -> Digest

              Types:

                 State = hash_state()
                 Digest = binary()

              Finalizes the hash operation referenced by Context returned from
              a previous call to hash_update. The size of Digest is determined
              by the type of hash function used to generate it.

       info_fips() -> not_supported | not_enabled | enabled

              Provides  information  about the FIPS operating status of crypto
              and the underlying libcrypto library. If crypto was  built  with
              FIPS  support  this  can be either enabled (when running in FIPS
              mode) or not_enabled. For other  builds  this  value  is  always
              not_supported.

              See enable_fips_mode/1 about how to enable FIPS mode.

          Warning:
              In  FIPS mode all non-FIPS compliant algorithms are disabled and
              raise exception error:notsup. Check  supports(ciphers)  that  in
              FIPS mode returns the restricted list of available algorithms.


       enable_fips_mode(Enable) -> Result

              Types:

                 Enable = Result = boolean()

              Enables  (Enable = true) or disables (Enable = false) FIPS mode.
              Returns true if the operation was successful or false otherwise.

              Note that to enable FIPS mode succesfully,  OTP  must  be  built
              with  the  configure  option  --enable-fips,  and the underlying
              libcrypto must also support FIPS.

              See also info_fips/0.

       info() ->
               #{compile_type := normal | debug | valgrind | asan,
                 cryptolib_version_compiled => string() | undefined,
                 cryptolib_version_linked := string(),
                 link_type := dynamic | static,
                 otp_crypto_version := string()}

              Provides a map with information about the compilation and  link-
              ing of crypto.

              Example:

              1> crypto:info().
              #{compile_type => normal,
                cryptolib_version_compiled => "OpenSSL 3.0.0 7 sep 2021",
                cryptolib_version_linked => "OpenSSL 3.0.0 7 sep 2021",
                link_type => dynamic,
                otp_crypto_version => "5.0.2"}
              2>


              More  association  types  than  documented may be present in the
              map.

       info_lib() -> [{Name, VerNum, VerStr}]

              Types:

                 Name = binary()
                 VerNum = integer()
                 VerStr = binary()

              Provides the name and version of the libraries used by crypto.

              Name is the name of the library. VerNum is the  numeric  version
              according  to  the  library's own versioning scheme. VerStr con-
              tains a text variant of the version.

              > info_lib().
              [{<<"OpenSSL">>,269484095,<<"OpenSSL 1.1.0c  10 Nov 2016"">>}]


          Note:
              From OTP R16 the numeric version represents the version  of  the
              OpenSSL  header  files (openssl/opensslv.h) used when crypto was
              compiled. The text variant represents the libcrypto library used
              at  runtime.  In  earlier OTP versions both numeric and text was
              taken from the library.


       hash_info(Type) -> Result | run_time_error()

              Types:

                 Type = hash_algorithm()
                 Result =
                     #{size := integer(),
                       block_size := integer(),
                       type := integer()}

              Provides a map with information about block_size, size and  pos-
              sibly other properties of the hash algorithm in question.

              For a list of supported hash algorithms, see supports(hashs).

       cipher_info(Type) -> Result | run_time_error()

              Types:

                 Type = cipher()
                 Result =
                     #{key_length := integer(),
                       iv_length := integer(),
                       block_size := integer(),
                       mode := CipherModes,
                       type := undefined | integer(),
                       prop_aead := boolean()}
                 CipherModes =
                     undefined | cbc_mode | ccm_mode | cfb_mode | ctr_mode |
                     ecb_mode | gcm_mode | ige_mode | ocb_mode | ofb_mode |
                     wrap_mode | xts_mode

              Provides  a  map  with information about block_size, key_length,
              iv_length, aead support and possibly  other  properties  of  the
              cipher algorithm in question.

          Note:
              The  ciphers  aes_cbc,  aes_cfb8,  aes_cfb128, aes_ctr, aes_ecb,
              aes_gcm and aes_ccm has no keylength in the Type as  opposed  to
              for  example  aes_128_ctr.  They  adapt to the length of the key
              provided in the encrypt and decrypt  function.  Therefor  it  is
              impossible to return a valid keylength in the map.

              Always use a Type with an explicit key length,


              For   a   list   of   supported   cipher  algorithms,  see  sup-
              ports(ciphers).

       mod_pow(N, P, M) -> Result

              Types:

                 N = P = M = binary() | integer()
                 Result = binary() | error

              Computes the function N^P mod M.

       private_decrypt(Algorithm, CipherText, PrivateKey, Options) ->
                          PlainText

              Types:

                 Algorithm = pk_encrypt_decrypt_algs()
                 CipherText = binary()
                 PrivateKey = rsa_private() | engine_key_ref()
                 Options = pk_encrypt_decrypt_opts()
                 PlainText = binary()

              Decrypts the CipherText,  encrypted  with  public_encrypt/4  (or
              equivalent  function)  using  the  PrivateKey,  and  returns the
              plaintext (message digest). This is a low level signature  veri-
              fication  operation  used  for instance by older versions of the
              SSL protocol. See also public_key:decrypt_private/[2,3]

       private_encrypt(Algorithm, PlainText, PrivateKey, Options) ->
                          CipherText

              Types:

                 Algorithm = pk_encrypt_decrypt_algs()
                 PlainText = binary()
                 PrivateKey = rsa_private() | engine_key_ref()
                 Options = pk_encrypt_decrypt_opts()
                 CipherText = binary()

              Encrypts the PlainText using  the  PrivateKey  and  returns  the
              ciphertext.  This  is  a  low level signature operation used for
              instance by older versions of the SSL protocol.  See  also  pub-
              lic_key:encrypt_private/[2,3]

       public_decrypt(Algorithm, CipherText, PublicKey, Options) ->
                         PlainText

              Types:

                 Algorithm = pk_encrypt_decrypt_algs()
                 CipherText = binary()
                 PublicKey = rsa_public() | engine_key_ref()
                 Options = pk_encrypt_decrypt_opts()
                 PlainText = binary()

              Decrypts  the  CipherText,  encrypted  with private_encrypt/4(or
              equivalent function)  using  the  PrivateKey,  and  returns  the
              plaintext  (message digest). This is a low level signature veri-
              fication operation used for instance by older  versions  of  the
              SSL protocol. See also public_key:decrypt_public/[2,3]

       public_encrypt(Algorithm, PlainText, PublicKey, Options) ->
                         CipherText

              Types:

                 Algorithm = pk_encrypt_decrypt_algs()
                 PlainText = binary()
                 PublicKey = rsa_public() | engine_key_ref()
                 Options = pk_encrypt_decrypt_opts()
                 CipherText = binary()

              Encrypts  the PlainText (message digest) using the PublicKey and
              returns the CipherText. This is a low level signature  operation
              used  for  instance  by  older versions of the SSL protocol. See
              also public_key:encrypt_public/[2,3]

       rand_seed(Seed :: binary()) -> ok

              Set the seed for PRNG  to  the  given  binary.  This  calls  the
              RAND_seed function from openssl. Only use this if the system you
              are running on does not have enough "randomness" built in.  Nor-
              mally this is when strong_rand_bytes/1 raises error:low_entropy

       rand_uniform(Lo, Hi) -> N

              Types:

                 Lo, Hi, N = integer()

              Generate  a  random  number  N,  Lo  =<  N < Hi. Uses the crypto
              library pseudo-random number generator. Hi must be  larger  than
              Lo.

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

              Equivalent to application:start(crypto).

       stop() -> ok | {error, Reason :: term()}

              Equivalent to application:stop(crypto).

       strong_rand_bytes(N :: integer() >= 0) -> binary()

              Generates  N  bytes  randomly  uniform  0..255,  and returns the
              result in a binary. Uses a cryptographically secure prng  seeded
              and  periodically  mixed with operating system provided entropy.
              By default this is the RAND_bytes method from OpenSSL.

              May raise exception error:low_entropy in case the random genera-
              tor failed due to lack of secure "randomness".

       rand_seed() -> rand:state()

              Creates  state  object for random number generation, in order to
              generate  cryptographically  strong  random  numbers  (based  on
              OpenSSL's BN_rand_range), and saves it in the process dictionary
              before  returning  it  as  well.  See   also   rand:seed/1   and
              rand_seed_s/0.

              When  using  the  state object from this function the rand func-
              tions using it may raise exception error:low_entropy in case the
              random generator failed due to lack of secure "randomness".

              Example

              _ = crypto:rand_seed(),
              _IntegerValue = rand:uniform(42), % [1; 42]
              _FloatValue = rand:uniform().     % [0.0; 1.0[

       rand_seed_s() -> rand:state()

              Creates  state  object for random number generation, in order to
              generate cryptographically strongly  random  numbers  (based  on
              OpenSSL's BN_rand_range). See also rand:seed_s/1.

              When  using  the  state object from this function the rand func-
              tions using it may raise exception error:low_entropy in case the
              random generator failed due to lack of secure "randomness".

          Note:
              The  state  returned  from this function cannot be used to get a
              reproducable random sequence as from the other  rand  functions,
              since reproducability does not match cryptographically safe.

              The  only  supported  usage  is  to generate one distinct random
              sequence from this start state.


       rand_seed_alg(Alg) -> rand:state()

              Types:

                 Alg = crypto | crypto_cache

              Creates state object for random number generation, in  order  to
              generate  cryptographically  strong random numbers, and saves it
              in the process dictionary before returning it as well. See  also
              rand:seed/1 and rand_seed_alg_s/1.

              When  using  the  state object from this function the rand func-
              tions using it may raise exception error:low_entropy in case the
              random generator failed due to lack of secure "randomness".

              Example

              _ = crypto:rand_seed_alg(crypto_cache),
              _IntegerValue = rand:uniform(42), % [1; 42]
              _FloatValue = rand:uniform().     % [0.0; 1.0[

       rand_seed_alg(Alg, Seed) -> rand:state()

              Types:

                 Alg = crypto_aes

              Creates a state object for random number generation, in order to
              generate cryptographically  unpredictable  random  numbers,  and
              saves  it in the process dictionary before returning it as well.
              See also rand_seed_alg_s/2.

              Example

              _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
              IntegerValue = rand:uniform(42), % [1; 42]
              FloatValue = rand:uniform(),     % [0.0; 1.0[
              _ = crypto:rand_seed_alg(crypto_aes, "my seed"),
              IntegerValue = rand:uniform(42), % Same values
              FloatValue = rand:uniform().     % again


       rand_seed_alg_s(Alg) -> rand:state()

              Types:

                 Alg = crypto | crypto_cache

              Creates state object for random number generation, in  order  to
              generate  cryptographically  strongly  random  numbers. See also
              rand:seed_s/1.

              If  Alg  is  crypto   this   function   behaves   exactly   like
              rand_seed_s/0.

              If  Alg  is  crypto_cache this function fetches random data with
              OpenSSL's RAND_bytes and caches it for speed using  an  internal
              word  size  of  56  bits  that makes calculations fast on 64 bit
              machines.

              When using the state object from this function  the  rand  func-
              tions using it may raise exception error:low_entropy in case the
              random generator failed due to lack of secure "randomness".

              The cache size can be changed from its default value  using  the
              crypto app's  configuration parameter rand_cache_size.

              When  using  the  state object from this function the rand func-
              tions using it may throw exception low_entropy in case the  ran-
              dom generator failed due to lack of secure "randomness".

          Note:
              The  state  returned  from this function cannot be used to get a
              reproducable random sequence as from the other  rand  functions,
              since reproducability does not match cryptographically safe.

              In  fact since random data is cached some numbers may get repro-
              duced if you try, but this is unpredictable.

              The only supported usage is  to  generate  one  distinct  random
              sequence from this start state.


       rand_seed_alg_s(Alg, Seed) -> rand:state()

              Types:

                 Alg = crypto_aes

              Creates a state object for random number generation, in order to
              generate cryptographically  unpredictable  random  numbers.  See
              also rand_seed_alg/1.

              To  get  a  long period the Xoroshiro928 generator from the rand
              module is used as a counter (with period 2^928 - 1) and the gen-
              erator  states are scrambled through AES to create 58-bit pseudo
              random values.

              The result should be statistically completely unpredictable ran-
              dom values, since the scrambling is cryptographically strong and
              the period is ridiculously long. But the generated  numbers  are
              not to be regarded as cryptographically strong since there is no
              re-keying schedule.

                * If you need  cryptographically  strong  random  numbers  use
                  rand_seed_alg_s/1   with   Alg   =:=   crypto   or  Alg  =:=
                  crypto_cache.

                * If you need to be able to repeat the sequence use this func-
                  tion.

                * If you do not need the statistical quality of this function,
                  there are faster algorithms in the rand module.

              Thanks to the used  generator  the  state  object  supports  the
              rand:jump/0,1 function with distance 2^512.

              Numbers  are  generated in batches and cached for speed reasons.
              The cache size can be changed from its default value  using  the
              crypto app's  configuration parameter rand_cache_size.

       ec_curves() -> [EllipticCurve]

              Types:

                 EllipticCurve =
                     ec_named_curve()       |       edwards_curve_dh()       |
                 edwards_curve_ed()

              Can be used to determine which named elliptic  curves  are  sup-
              ported.

       ec_curve(CurveName) -> ExplicitCurve

              Types:

                 CurveName = ec_named_curve()
                 ExplicitCurve = ec_explicit_curve()

              Return the defining parameters of a elliptic curve.

       sign(Algorithm, DigestType, Msg, Key) -> Signature

       sign(Algorithm, DigestType, Msg, Key, Options) -> Signature

              Types:

                 Algorithm = pk_sign_verify_algs()
                 DigestType =
                     rsa_digest_type() |
                     dss_digest_type() |
                     ecdsa_digest_type() |
                     none
                 Msg = iodata() | {digest, iodata()}
                 Key =
                     rsa_private() |
                     dss_private() |
                     [ecdsa_private() | ecdsa_params()] |
                     [eddsa_private() | eddsa_params()] |
                     engine_key_ref()
                 Options = pk_sign_verify_opts()
                 Signature = binary()

              Creates a digital signature.

              The msg is either the binary "cleartext" data to be signed or it
              is the hashed value of "cleartext" i.e. the digest (plaintext).

              Algorithm dss can only be used together with digest type sha.

              See also public_key:sign/3.

       verify(Algorithm, DigestType, Msg, Signature, Key) -> Result

       verify(Algorithm, DigestType, Msg, Signature, Key, Options) ->
                 Result

              Types:

                 Algorithm = pk_sign_verify_algs()
                 DigestType =
                     rsa_digest_type() |
                     dss_digest_type() |
                     ecdsa_digest_type() |
                     none
                 Msg = iodata() | {digest, iodata()}
                 Signature = binary()
                 Key =
                     rsa_public() |
                     dss_public() |
                     [ecdsa_public() | ecdsa_params()] |
                     [eddsa_public() | eddsa_params()] |
                     engine_key_ref()
                 Options = pk_sign_verify_opts()
                 Result = boolean()

              Verifies a digital signature

              The msg is either the binary "cleartext" data to be signed or it
              is the hashed value of "cleartext" i.e. the digest (plaintext).

              Algorithm dss can only be used together with digest type sha.

              See also public_key:verify/4.

ENGINE API
EXPORTS
       privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey

              Types:

                 Type = rsa | dss
                 EnginePrivateKeyRef = engine_key_ref()
                 PublicKey = rsa_public() | dss_public()

              Fetches  the  corresponding public key from a private key stored
              in an Engine. The key must be of the type indicated by the  Type
              parameter.

       engine_get_all_methods() -> Result

              Types:

                 Result = [engine_method_type()]

              Returns a list of all possible engine methods.

              May raise exception error:notsup in case there is no engine sup-
              port in the underlying OpenSSL implementation.

              See also the chapter Engine Load in the User's Guide.

       engine_load(EngineId, PreCmds, PostCmds) -> Result

              Types:

                 EngineId = unicode:chardata()
                 PreCmds = PostCmds = [engine_cmnd()]
                 Result =
                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}

              Loads the OpenSSL engine given by EngineId if  it  is  available
              and  then  returns ok and an engine handle. This function is the
              same as calling engine_load/4 with EngineMethods set to  a  list
              of  all  the possible methods. An error tuple is returned if the
              engine can't be loaded.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

              See also the chapter Engine Load in the User's Guide.

       engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result

              Types:

                 EngineId = unicode:chardata()
                 PreCmds = PostCmds = [engine_cmnd()]
                 EngineMethods = [engine_method_type()]
                 Result =
                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}

              Loads  the  OpenSSL  engine given by EngineId if it is available
              and then returns ok and an engine  handle.  An  error  tuple  is
              returned if the engine can't be loaded.

              The  function  raises  a  error:badarg  if the parameters are in
              wrong format. It may also raise the  exception  error:notsup  in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

              See also the chapter Engine Load in the User's Guide.

       engine_unload(Engine) -> Result

              Types:

                 Engine = engine_ref()
                 Result = ok | {error, Reason :: term()}

              Unloads the OpenSSL engine given by Engine. An  error  tuple  is
              returned if the engine can't be unloaded.

              The  function raises a error:badarg if the parameter is in wrong
              format. It may also raise the  exception  error:notsup  in  case
              there is no engine support in the underlying OpenSSL implementa-
              tion.

              See also the chapter Engine Load in the User's Guide.

       engine_by_id(EngineId) -> Result

              Types:

                 EngineId = unicode:chardata()
                 Result =
                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}

              Get a reference to an already loaded engine  with  EngineId.  An
              error tuple is returned if the engine can't be unloaded.

              The  function raises a error:badarg if the parameter is in wrong
              format. It may also raise the  exception  error:notsup  in  case
              there is no engine support in the underlying OpenSSL implementa-
              tion.

              See also the chapter Engine Load in the User's Guide.

       engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result

              Types:

                 Engine = term()
                 CmdName = CmdArg = unicode:chardata()
                 Result = ok | {error, Reason :: term()}

              Sends ctrl commands to the OpenSSL engine given by Engine.  This
              function  is  the  same as calling engine_ctrl_cmd_string/4 with
              Optional set to false.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

       engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) ->
                                 Result

              Types:

                 Engine = term()
                 CmdName = CmdArg = unicode:chardata()
                 Optional = boolean()
                 Result = ok | {error, Reason :: term()}

              Sends  ctrl  commands  to  the  OpenSSL  engine given by Engine.
              Optional is a boolean argument that can relax the  semantics  of
              the  function. If set to true it will only return failure if the
              ENGINE supported the given command name but failed while execut-
              ing  it,  if the ENGINE doesn't support the command name it will
              simply return success without doing anything. In  this  case  we
              assume the user is only supplying commands specific to the given
              ENGINE so we set this to false.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

       engine_add(Engine) -> Result

              Types:

                 Engine = engine_ref()
                 Result = ok | {error, Reason :: term()}

              Add the engine to OpenSSL's internal list.

              The  function  raises  a  error:badarg  if the parameters are in
              wrong format. It may also raise the  exception  error:notsup  in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

       engine_remove(Engine) -> Result

              Types:

                 Engine = engine_ref()
                 Result = ok | {error, Reason :: term()}

              Remove the engine from OpenSSL's internal list.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

       engine_get_id(Engine) -> EngineId

              Types:

                 Engine = engine_ref()
                 EngineId = unicode:chardata()

              Return  the ID for the engine, or an empty binary if there is no
              id set.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

       engine_get_name(Engine) -> EngineName

              Types:

                 Engine = engine_ref()
                 EngineName = unicode:chardata()

              Return  the  name (eg a description) for the engine, or an empty
              binary if there is no name set.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

       engine_list() -> Result

              Types:

                 Result = [EngineId :: unicode:chardata()]

              List the id's of all engines in OpenSSL's internal list.

              It may also raise the exception error:notsup in case there is no
              engine support in the underlying OpenSSL implementation.

              See also the chapter Engine Load in the User's Guide.

              May raise exception error:notsup in case engine functionality is
              not supported by the underlying OpenSSL implementation.

       ensure_engine_loaded(EngineId, LibPath) -> Result

              Types:

                 EngineId = LibPath = unicode:chardata()
                 Result =
                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}

              Loads  the  OpenSSL engine given by EngineId and the path to the
              dynamic library implementing the engine. This  function  is  the
              same as calling ensure_engine_loaded/3 with EngineMethods set to
              a list of all the possible methods. An error tuple  is  returned
              if the engine can't be loaded.

              The  function  raises  a  error:badarg  if the parameters are in
              wrong format. It may also raise the  exception  error:notsup  in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

              See also the chapter Engine Load in the User's Guide.

       ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result

              Types:

                 EngineId = LibPath = unicode:chardata()
                 EngineMethods = [engine_method_type()]
                 Result =
                     {ok, Engine :: engine_ref()} | {error, Reason :: term()}

              Loads the OpenSSL engine given by EngineId and the path  to  the
              dynamic  library  implementing the engine. This function differs
              from the normal engine_load in that sense it also add the engine
              id  to the internal list in OpenSSL. Then in the following calls
              to the function it  just  fetch  the  reference  to  the  engine
              instead  of  loading it again. An error tuple is returned if the
              engine can't be loaded.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

              See also the chapter Engine Load in the User's Guide.

       ensure_engine_unloaded(Engine) -> Result

              Types:

                 Engine = engine_ref()
                 Result = ok | {error, Reason :: term()}

              Unloads an engine loaded with the ensure_engine_loaded function.
              It both removes the label from the OpenSSL internal engine  list
              and  unloads  the  engine.  This function is the same as calling
              ensure_engine_unloaded/2 with EngineMethods set to a list of all
              the  possible  methods. An error tuple is returned if the engine
              can't be unloaded.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

              See also the chapter Engine Load in the User's Guide.

       ensure_engine_unloaded(Engine, EngineMethods) -> Result

              Types:

                 Engine = engine_ref()
                 EngineMethods = [engine_method_type()]
                 Result = ok | {error, Reason :: term()}

              Unloads an engine loaded with the ensure_engine_loaded function.
              It both removes the label from the OpenSSL internal engine  list
              and unloads the engine. An error tuple is returned if the engine
              can't be unloaded.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong  format.  It  may also raise the exception error:notsup in
              case there is no engine support in the underlying OpenSSL imple-
              mentation.

              See also the chapter Engine Load in the User's Guide.

       pbkdf2_hmac(Digest, Pass, Salt, Iter, KeyLen) -> Result

              Types:

                 Digest = sha | sha224 | sha256 | sha384 | sha512
                 Pass = Salt = binary()
                 Iter = KeyLen = integer() >= 1
                 Result = binary()

              PKCS  #5  PBKDF2  (Password-Based  Key Derivation Function 2) in
              combination with HMAC.

              The function raises a error:badarg  if  the  parameters  are  in
              wrong format.



Ericsson AB                      crypto 5.0.5                        crypto(3)