Ericsson AB
erlangmanpages
Erlang/OTP manual pages
erlangcrypto
Erlang/OTP cryptographic modules
NAME
crypto  Crypto Functions
DESCRIPTION
This module provides a set of cryptographic functions.
Hash functions:


MACs  Message Authentication Codes:


Symmetric Ciphers:


Modes:


Asymetric Ciphers  Public Key Techniques:

Note:
The actual supported algorithms and features depends on their availability in the actual libcrypto used. See the crypto (App) about dependencies.
Enabling FIPS mode will also disable algorithms and features.
The CRYPTO User’s Guide has more information on FIPS, Engines and Algorithm Details like key lengths.
DATA TYPES
Ciphers, new API
cipher() = cipher_no_iv()  cipher_iv()  cipher_aead()
cipher_no_iv() =
aes_128_ecb  aes_192_ecb  aes_256_ecb  blowfish_ecb 
des_ecb  rc4
cipher_iv() =
aes_128_cbc  aes_192_cbc  aes_256_cbc  aes_128_cfb128 
aes_192_cfb128  aes_256_cfb128  aes_128_cfb8 
aes_192_cfb8  aes_256_cfb8  aes_128_ctr  aes_192_ctr 
aes_256_ctr  aes_ige256  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_128_gcm 
aes_192_gcm  aes_256_gcm  chacha20_poly1305
Ciphers known by the CRYPTO application when using the new API.
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}) in the New API .
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 version.
otp_padding() = zero  random
Erlang/OTP adds a either padding of zeroes or padding with random bytes.
Ciphers, old API
block_cipher_with_iv() =
cbc_cipher()  cfb_cipher()  blowfish_ofb64  aes_ige256
block_cipher_without_iv() = ecb_cipher()
stream_cipher() = ctr_cipher()  chacha20  rc4
aead_cipher() = aes_gcm  aes_ccm  chacha20_poly1305
cbc_cipher() =
aes_128_cbc  aes_192_cbc  aes_256_cbc  blowfish_cbc 
des_cbc  des_ede3_cbc  rc2_cbc 
retired_cbc_cipher_aliases()
cfb_cipher() =
aes_128_cfb128  aes_192_cfb128  aes_256_cfb128 
aes_128_cfb8  aes_192_cfb8  aes_256_cfb8  blowfish_cfb64 
des_cfb  des_ede3_cfb 
retired_cfb_cipher_aliases()
ctr_cipher() =
aes_128_ctr  aes_192_ctr  aes_256_ctr 
retired_ctr_cipher_aliases()
ecb_cipher() =
aes_128_ecb  aes_192_ecb  aes_256_ecb  blowfish_ecb 
retired_ecb_cipher_aliases()
Ciphers known by the CRYPTO application when using the old API.
Note that this list might be reduced if the underlying libcrypto does not support all of them.
retired_cbc_cipher_aliases() =
aes_cbc  aes_cbc128  aes_cbc256  des3_cbc  des_ede3
retired_cfb_cipher_aliases() =
aes_cfb8  aes_cfb128  des3_cbf  des3_cfb  des_ede3_cbf
retired_ctr_cipher_aliases() = aes_ctr
retired_ecb_cipher_aliases() = aes_ecb
Alternative, old names of ciphers known by the CRYPTO application when using the old API. See Retired cipher names for names to use instead to be prepared for an easy convertion to the new API.
Note that this list might be reduced if the underlying libcrypto does not support all of them.
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  blowfish_cbc 
des_cbc  des_ede3_cbc  rc2_cbc  aes_128_cfb128 
aes_192_cfb128  aes_256_cfb128  aes_128_cfb8 
aes_192_cfb8  aes_256_cfb8
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() = iodata()
des3_key() = [key()]
For keylengths, ivsizes and blocksizes see the User’s Guide.
A key for des3 is a list of three iolists
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,P2 are first and second prime factors. E1,E2 are first and second exponents. C is the CRT coefficient. 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 provided) from SRP design Version = ’3’  ’6’  ’6a’
Public Key Ciphers
pk_encrypt_decrypt_algs() = rsa
Algorithms for public key encrypt/decrypt. Only RSA is supported.
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.
DiffieHellman 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_(privatepublic)_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()
hmac_state()
mac_state()
stream_state()
Contexts with an internal state that should not be manipulated but passed between function calls.
Error types
run_time_error() = no_return()
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 explicitly disabled when building that.
For a list of supported algorithms, see supports/0.
descriptive_error() = no_return()
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 memory allocation failed or the underlying cryptolib returned an error code, for example "Can’t initialize context, step 1". Those text usually needs searching the Ccode 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
NEW
API
EXPORTS
block_encrypt(Type :: block_cipher_without_iv(), Key :: key(), PlainText :: iodata()) > binary()  run_time_error()
Dont:
Don’t use this function for new programs! Use thenewapi.
Encrypt PlainText according to Type block cipher.
May raise exception error:notsup in case the chosen Type is not supported by the underlying libcrypto implementation.
For keylengths and blocksizes see the User’s Guide.
block_decrypt(Type :: block_cipher_without_iv(), Key :: key(), Data :: iodata()) > binary()  run_time_error()
Dont:
Don’t use this function for new programs! Use the new api.
Decrypt CipherText according to Type block cipher.
May raise exception error:notsup in case the chosen Type is not supported by the underlying libcrypto implementation.
For keylengths and blocksizes see the User’s Guide.
block_encrypt(Type, Key, Ivec, PlainText) > CipherText  Error
block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) > {CipherText, CipherTag}  Error
block_encrypt(aes_gcm  aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) > {CipherText, CipherTag}  Error
block_encrypt(AeadType, Key, Ivec, {AAD, PlainText}) > {CipherText, CipherTag}  Error
block_encrypt(aes_gcm  aes_ccm, Key, Ivec, {AAD, PlainText, TagLength}) > {CipherText, CipherTag}  Error
Types:
Type = block_cipher_with_iv()
AeadType = aead_cipher()
Key = key()  des3_key()
PlainText = iodata()
AAD = IVec = CipherText = CipherTag = binary()
TagLength = 1..16
Error = run_time_error()
AeadType = aead_cipher()
Key = key()  des3_key()
PlainText = iodata()
AAD = IVec = CipherText = CipherTag = binary()
TagLength = 1..16
Error = run_time_error()
Dont:
Don’t use this function for new programs! Use the new api.
Encrypt PlainText according to Type block cipher. IVec is an arbitrary initializing vector.
In AEAD (Authenticated Encryption with Associated Data) mode, encrypt PlainTextaccording to Type block cipher and calculate CipherTag that also authenticates the AAD (Associated Authenticated Data).
May raise exception error:notsup in case the chosen Type is not supported by the underlying libcrypto implementation.
For keylengths, ivsizes and blocksizes see the User’s Guide.
block_decrypt(Type, Key, Ivec, CipherText) > PlainText  Error
block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) > PlainText  Error
block_decrypt(AeadType, Key, Ivec, {AAD, CipherText, CipherTag}) > PlainText  Error
Types:
Type = block_cipher_with_iv()
AeadType = aead_cipher()
Key = key()  des3_key()
PlainText = iodata()
AAD = IVec = CipherText = CipherTag = binary()
Error = BadTag  run_time_error()
BadTag = error
AeadType = aead_cipher()
Key = key()  des3_key()
PlainText = iodata()
AAD = IVec = CipherText = CipherTag = binary()
Error = BadTag  run_time_error()
BadTag = error
Dont:
Don’t use this function for new programs! Use the new api.
Decrypt CipherText according to Type block cipher. IVec is an arbitrary initializing vector.
In AEAD (Authenticated Encryption with Associated Data) mode, decrypt CipherTextaccording to Type block cipher and check the authenticity the PlainText and AAD (Associated Authenticated Data) using the CipherTag. May return error if the decryption or validation fail’s
May raise exception error:notsup in case the chosen Type is not supported by the underlying libcrypto implementation.
For keylengths, ivsizes and blocksizes see the User’s Guide.
stream_init(Type, Key) > State  run_time_error()
Types:
Type = rc4
Key = iodata()
State = stream_state()
Key = iodata()
State = stream_state()
Dont:
Don’t use this function for new programs! Use the new api.
Initializes the state for use in RC4 stream encryption stream_encrypt and stream_decrypt
For keylengths see the User’s Guide.
stream_init(Type, Key, IVec) > State  run_time_error()
Types:
Type = stream_cipher()
Key = iodata()
IVec = binary()
State = stream_state()
Key = iodata()
IVec = binary()
State = stream_state()
Dont:
Don’t use this function for new programs! Use the new api.
Initializes the state for use in streaming AES encryption using Counter mode (CTR). Key is the AES key and must be either 128, 192, or 256 bits long. IVec is an arbitrary initializing vector of 128 bits (16 bytes). This state is for use with stream_encrypt and stream_decrypt.
For keylengths and ivsizes see the User’s Guide.
stream_encrypt(State, PlainText) > {NewState, CipherText}  run_time_error()
Types:
State = stream_state()
PlainText = iodata()
NewState = stream_state()
CipherText = iodata()
PlainText = iodata()
NewState = stream_state()
CipherText = iodata()
Dont:
Don’t use this function for new programs! Use the new api.
Encrypts PlainText according to the stream cipher Type specified in stream_init/3. Text can be any number of bytes. The initial State is created using stream_init. NewState must be passed into the next call to stream_encrypt.
stream_decrypt(State, CipherText) > {NewState, PlainText}  run_time_error()
Types:
State = stream_state()
CipherText = iodata()
NewState = stream_state()
PlainText = iodata()
CipherText = iodata()
NewState = stream_state()
PlainText = iodata()
Dont:
Don’t use this function for new programs! Use the new api.
Decrypts CipherText according to the stream cipher Type specified in stream_init/3. PlainText can be any number of bytes. The initial State is created using stream_init. NewState must be passed into the next call to stream_decrypt.
supports() > [Support]
Types:
Support =
{hashs, Hashs} 
{ciphers, Ciphers} 
{public_keys, PKs} 
{macs, Macs} 
{curves, Curves} 
{rsa_opts, RSAopts}
Hashs =
[sha1() 
sha2() 
sha3() 
blake2() 
ripemd160 
compatibility_only_hash()]
Ciphers = [cipher()]
PKs = [rsa  dss  ecdsa  dh  ecdh  ec_gf2m]
Macs = [hmac  cmac  poly1305]
Curves =
[ec_named_curve()  edwards_curve_dh()  edwards_curve_ed()]
RSAopts = [rsa_sign_verify_opt()  rsa_opt()]
{hashs, Hashs} 
{ciphers, Ciphers} 
{public_keys, PKs} 
{macs, Macs} 
{curves, Curves} 
{rsa_opts, RSAopts}
Hashs =
[sha1() 
sha2() 
sha3() 
blake2() 
ripemd160 
compatibility_only_hash()]
Ciphers = [cipher()]
PKs = [rsa  dss  ecdsa  dh  ecdh  ec_gf2m]
Macs = [hmac  cmac  poly1305]
Curves =
[ec_named_curve()  edwards_curve_dh()  edwards_curve_ed()]
RSAopts = [rsa_sign_verify_opt()  rsa_opt()]
Dont:
Don’t use this function for new programs! Use supports/1 in the new api.
Can be used to determine which crypto algorithms that are supported by the underlying libcrypto library
See hash_info/1 and cipher_info/1 for information about the hash and cipher algorithms.
hmac(Type, Key, Data) > Mac
hmac(Type, Key, Data, MacLength) > Mac
Types:
Type = hmac_hash_algorithm()
Key = Data = iodata()
MacLength = integer()
Mac = binary()
Key = Data = iodata()
MacLength = integer()
Mac = binary()
Dont:
Don’t use this function for new programs! Use mac/4 or macN/5 in the new api.
Computes a HMAC of type Type from Data using Key as the authentication key.
MacLength will limit the size of the resultant Mac.
hmac_init(Type, Key) > State
Types:
Type = hmac_hash_algorithm()
Key = iodata()
State = hmac_state()
Key = iodata()
State = hmac_state()
Dont:
Don’t use this function for new programs! Use mac_init/3 in the new api.
Initializes the context for streaming HMAC operations. Type determines which hash function to use in the HMAC operation. Key is the authentication key. The key can be any length.
hmac_update(State, Data) > NewState
Types:
Data = iodata()
State = NewState = hmac_state()
State = NewState = hmac_state()
Dont:
Don’t use this function for new programs! Use mac_update/2 in the new api.
Updates the HMAC represented by Context using the given Data. Context must have been generated using an HMAC init function (such as hmac_init). Data can be any length. NewContext must be passed into the next call to hmac_update or to one of the functions hmac_final and hmac_final_n
Warning:
Do not use a Context as argument in more than one call to hmac_update or hmac_final. The semantics of reusing old contexts in any way is undefined and could even crash the VM in earlier releases. The reason for this limitation is a lack of support in the underlying libcrypto API.
hmac_final(State) > Mac
Types:
State = hmac_state()
Mac = binary()
Mac = binary()
Dont:
Don’t use this function for new programs! Use mac_final/1 in the new api.
Finalizes the HMAC operation referenced by Context. The size of the resultant MAC is determined by the type of hash function used to generate it.
hmac_final_n(State, HashLen) > Mac
Types:
State = hmac_state()
HashLen = integer()
Mac = binary()
HashLen = integer()
Mac = binary()
Dont:
Don’t use this function for new programs! Use mac_finalN/2 in the new api.
Finalizes the HMAC operation referenced by Context. HashLen must be greater than zero. Mac will be a binary with at most HashLen bytes. Note that if HashLen is greater than the actual number of bytes returned from the underlying hash, the returned hash will have fewer than HashLen bytes.
cmac(Type, Key, Data) > Mac
cmac(Type, Key, Data, MacLength) > Mac
Types:
Type =
cbc_cipher() 
cfb_cipher() 
blowfish_cbc  des_ede3  rc2_cbc
Key = Data = iodata()
MacLength = integer()
Mac = binary()
cbc_cipher() 
cfb_cipher() 
blowfish_cbc  des_ede3  rc2_cbc
Key = Data = iodata()
MacLength = integer()
Mac = binary()
Dont:
Don’t use this function for new programs! Use mac/4 or macN/5 in the new api.
Computes a CMAC of type Type from Data using Key as the authentication key.
MacLength will limit the size of the resultant Mac.
poly1305(Key :: iodata(), Data :: iodata()) > Mac
Types:
Mac = binary()
Dont:
Don’t use this function for new programs! Use mac/3 or macN/4 in the new api.
Computes a POLY1305 message authentication code (Mac) from Data using Key as the authentication key.
API KEPT FROM PREVIOUS
VERSIONS
ENGINE
API
OLD
API