View Source crypto (crypto v5.5)
Crypto Functions
This module provides a set of cryptographic functions.
Hash functions -
SHA1, SHA2 - Secure Hash Standard [FIPS PUB180-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]](http://www.ietf.org/rfc/rfc1321.txt)
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]
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]](https://csrc.nist.gov/publications/detail/sp/800-38a/final)
Asymmetric 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.
Exceptions
Atoms - the older style
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(ciphers).
3-tuples - the new style
The exception is:
error:{Tag, C_FileInfo, Description}
Tag = badarg | notsup | error
C_FileInfo = term() % Usually only useful for the OTP maintainer
Description = string() % Clear text, sometimes only useful for the OTP maintainer
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 C-code to be understood.
Usually there are more information in the call stack about which argument caused the exception and what the values where.
To catch the exception, use for example:
try crypto:crypto_init(Ciph, Key, IV, true)
catch
error:{Tag, _C_FileInfo, Description} ->
do_something(......)
.....
end
Summary
Types: Ciphers
Ciphers known by the CRYPTO application.
Selects encryption ({encrypt,true}
) or decryption ({encrypt,false}
).
The cryptolib_padding
are paddings that may be present in the underlying
cryptolib linked to the Erlang/OTP crypto app.
Erlang/OTP adds a either padding of zeroes or padding with random bytes.
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.
Types: Digests and hash
The compatibility_only_hash/0
algorithms are recommended only for
compatibility with existing applications.
Types: Elliptic Curves
Curve definition details.
Parametric curve definition.
Note that some curves are disabled if FIPS is enabled.
Types: Keys
Always binary/0
when used as return value
Types: Public/Private Keys
dss_public() = [P, Q, G, Y]
Where P, Q and G are the dss parameters and Y is the public key.
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.
Where Verifier is v
, Generator is g
and Prime isN
, DerivedKey is X
, and
Scrambler is u
(optional will be generated if not provided) from
SRP design Version = '3' | '6' | '6a'
srp_public() = key_integer()
Where is A
or B
from SRP design
Types: Public Key Ciphers
Algorithms for public key encrypt/decrypt. Only RSA is supported.
Those option forms are kept only for compatibility and should not be used in new code.
Options for public key encrypt/decrypt. Only RSA is supported.
Types: Diffie-Hellman Keys and parameters
dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
Types: Types for Engines
Pre and Post commands for engine_load/3 and /4.
The result of a call to engine_load/3
.
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.
The password of the key stored in an engine.
Types: Internal data types
Contexts with an internal state that should not be manipulated but passed between function calls.
Engine API
Add the engine to OpenSSL's internal list.
Get a reference to an already loaded engine with EngineId
. An error tuple is
returned if the engine can't be unloaded.
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
.
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 executing 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
.
Returns a list of all possible engine methods.
Return the ID for the engine, or an empty binary if there is no id set.
Return the name (eg a description) for the engine, or an empty binary if there is no name set.
List the id's of all engines in OpenSSL's internal list.
Loads the OpenSSL engine given by EngineId
if it is available and intialize
it. Returns ok and an engine handle, if the engine can't be loaded an error
tuple is returned.
Register engine to handle some type of methods, for example engine_method_digests.
Remove the engine from OpenSSL's internal list.
Unloads the OpenSSL engine given by Engine
. An error tuple is returned if the
engine can't be unloaded.
Unregister engine so it don't handle some type of methods.
Loads an engine given by EngineId
and the path to the dynamic library
implementing the engine. An error tuple is returned if the engine can't be
loaded.
Constant time memory comparison for fixed length binaries, such as results of HMAC computations.
Uses the 3-tuple style for error handling.
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.
Functions
Convert binary representation, of an integer, to an Erlang integer.
Provides a map with information about block_size, key_length, iv_length, aead support and possibly other properties of the cipher algorithm in question.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Return the defining parameters of a elliptic curve.
Can be used to determine which named elliptic curves are supported.
Enables (Enable = true
) or disables (Enable = false
) FIPS mode. Returns
true
if the operation was successful or false
otherwise.
Performs bit-wise XOR (exclusive or) on the data supplied.
Equivalent to generate_key/3
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Provides a map with information about block_size, size and possibly other properties of the hash algorithm in question.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Provides a map with information about the compilation and linking of crypto.
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
.
Provides the name and version of the libraries used by crypto.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
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.
Computes the function N^P mod M
.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
Uses the 3-tuple style for error handling.
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
.
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. Normally this is when strong_rand_bytes/1
raises
error:low_entropy
rand_seed_alg(Alg) -> rand:state()
rand_seed_alg(Alg, Seed) -> rand:state()
rand_seed_alg_s(Alg) -> rand:state()
rand_seed_alg_s(Alg, Seed) -> 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
.
rand_uniform(Lo, Hi) -> N
Equivalent to sign/5
Uses the 3-tuple style for error handling.
Equivalent to application:start(crypto).
Equivalent to application:stop(crypto).
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.
Can be used to determine which crypto algorithms that are supported by the underlying libcrypto library
Equivalent to verify/6
Uses the 3-tuple style for error handling.
Types: Ciphers
-type cipher() :: cipher_no_iv() | cipher_iv() | cipher_aead().
-type cipher_aead() ::
aes_128_ccm | aes_192_ccm | aes_256_ccm | aes_ccm | aes_128_gcm | aes_192_gcm | aes_256_gcm |
aes_gcm | sm4_gcm | sm4_ccm | 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.
-type cipher_iv() ::
aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc | aes_128_ofb | aes_192_ofb | aes_256_ofb |
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 | sm4_cbc |
sm4_ofb | sm4_cfb | sm4_ctr | blowfish_cbc | blowfish_cfb64 | blowfish_ofb64 | chacha20 |
des_ede3_cbc | des_ede3_cfb | des_cbc | des_cfb | rc2_cbc.
-type cipher_no_iv() ::
aes_128_ecb | aes_192_ecb | aes_256_ecb | aes_ecb | blowfish_ecb | des_ecb | sm4_ecb | rc4.
Selects encryption ({encrypt,true}
) or decryption ({encrypt,false}
).
-type crypto_opts() :: boolean() | [crypto_opt()].
-type 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.
-type otp_padding() :: zero | random.
Erlang/OTP adds a either padding of zeroes or padding with random bytes.
-type 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.
Types: Digests and hash
-type blake2() :: blake2b | blake2s.
-type cmac_cipher_algorithm() ::
aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc | blowfish_cbc | des_cbc | des_ede3_cbc |
rc2_cbc.
-type compatibility_only_hash() :: md5 | md4.
The compatibility_only_hash/0
algorithms are recommended only for
compatibility with existing applications.
-type hash_xof_algorithm() :: sha3_xof().
-type hmac_hash_algorithm() :: sha1() | sha2() | sha3() | sm3 | compatibility_only_hash().
-type sha1() :: sha.
-type sha2() :: sha224 | sha256 | sha384 | sha512.
-type sha3() :: sha3_224 | sha3_256 | sha3_384 | sha3_512.
-type sha3_xof() :: shake128 | shake256.
Types: Elliptic Curves
-type ec_basis() :: {tpbasis, K :: non_neg_integer()} | {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | onbasis.
Curve definition details.
Parametric curve definition.
-type ec_field() :: ec_prime_field() | ec_characteristic_two_field().
-type 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.
-type ec_prime_field() :: {prime_field, Prime :: integer()}.
-type edwards_curve_dh() :: x25519 | x448.
-type edwards_curve_ed() :: ed25519 | ed448.
Note that some curves are disabled if FIPS is enabled.
Types: Keys
Always binary/0
when used as return value
Types: Public/Private Keys
-type 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.
-type dss_public() :: [key_integer()].
-type ecdsa_params() :: ec_named_curve() | ec_explicit_curve().
-type ecdsa_private() :: key_integer().
-type ecdsa_public() :: key_integer().
-type eddsa_params() :: edwards_curve_ed().
-type eddsa_private() :: key_integer().
-type eddsa_public() :: key_integer().
-type 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.
-type rsa_private() :: [key_integer()].
-type rsa_public() :: [key_integer()].
-type srp_comp_params() :: {user, srp_user_comp_params()} | {host, srp_host_comp_params()}.
-type srp_gen_params() :: {user, srp_user_gen_params()} | {host, srp_host_gen_params()}.
Where Verifier is v
, Generator is g
and Prime isN
, DerivedKey is X
, and
Scrambler is u
(optional will be generated if not provided) from
SRP design Version = '3' | '6' | '6a'
-type 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
-type srp_public() :: key_integer().
Types: Public Key Ciphers
-type pk_encrypt_decrypt_algs() :: rsa.
Algorithms for public key encrypt/decrypt. Only RSA is supported.
-type pk_encrypt_decrypt_opts() :: [rsa_opt()] | rsa_compat_opts().
-type 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.
-type rsa_opt() :: {rsa_padding, rsa_padding()} | {signature_md, atom()} | {rsa_mgf1_md, sha} | {rsa_oaep_label, binary()} | {rsa_oaep_md, sha}.
-type 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.
Types: Public Key Sign and Verify
-type pk_sign_verify_algs() :: rsa | dss | ecdsa | eddsa.
Algorithms for sign and verify.
-type pk_sign_verify_opts() :: [rsa_sign_verify_opt()].
-type rsa_sign_verify_opt() :: {rsa_padding, rsa_sign_verify_padding()} | {rsa_pss_saltlen, integer()} | {rsa_mgf1_md, sha2()}.
-type 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.
Types: Diffie-Hellman Keys and parameters
-type dh_params() :: [key_integer()].
dh_params() = [P, G] | [P, G, PrivateKeyBitLength]
-type dh_private() :: key_integer().
-type dh_public() :: key_integer().
-type ecdh_params() :: ec_named_curve() | edwards_curve_dh() | ec_explicit_curve().
-type ecdh_private() :: key_integer().
-type ecdh_public() :: key_integer().
Types: Types for Engines
-type engine_cmnd() :: {unicode:chardata(), unicode:chardata()}.
Pre and Post commands for engine_load/3 and /4.
-type engine_key_ref() :: #{engine := engine_ref(), key_id := key_id(), password => password(), term() => term()}.
-type 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.
-type engine_ref() :: term().
The result of a call to engine_load/3
.
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.
The password of the key stored in an engine.
Types: Internal data types
-opaque crypto_state()
-opaque hash_state()
-opaque mac_state()
Contexts with an internal state that should not be manipulated but passed between function calls.
Types
-type rand_cache_seed() :: nonempty_improper_list(non_neg_integer(), binary()).
Engine API
-spec engine_add(Engine) -> Result when 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 implementation.
-spec engine_by_id(EngineId) -> Result when 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 implementation.
See also the chapter Engine Load in the User's Guide.
-spec engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result when Engine :: term(), CmdName :: unicode:chardata(), 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 implementation.
engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional)
View Source (since OTP 20.2)-spec engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) -> Result when Engine :: term(), CmdName :: unicode:chardata(), 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 executing 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 implementation.
-spec engine_get_all_methods() -> Result when Result :: [engine_method_type()].
Returns a list of all possible engine methods.
May raise 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.
-spec engine_get_id(Engine) -> EngineId when 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 implementation.
-spec engine_get_name(Engine) -> EngineName when 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 implementation.
-spec engine_list() -> Result when 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.
-spec engine_load(EngineId, PreCmds, PostCmds) -> Result when EngineId :: unicode:chardata(), PreCmds :: [engine_cmnd()], PostCmds :: [engine_cmnd()], Result :: {ok, Engine :: engine_ref()} | {error, Reason :: term()}.
Loads the OpenSSL engine given by EngineId
if it is available and intialize
it. Returns ok and an engine handle, if the engine can't be loaded an error
tuple is returned.
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 implementation.
See also the chapter Engine Load in the User's Guide.
-spec engine_register(Engine, EngineMethods) -> Result when Engine :: engine_ref(), EngineMethods :: [engine_method_type()], Result :: ok | {error, Reason :: term()}.
Register engine to handle some type of methods, for example engine_method_digests.
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 implementation.
-spec engine_remove(Engine) -> Result when 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 implementation.
-spec engine_unload(Engine) -> Result when 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 implementation.
See also the chapter Engine Load in the User's Guide.
-spec engine_unregister(Engine, EngineMethods) -> Result when Engine :: engine_ref(), EngineMethods :: [engine_method_type()], Result :: ok | {error, Reason :: term()}.
Unregister engine so it don't handle some type of methods.
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 implementation.
-spec ensure_engine_loaded(EngineId, LibPath) -> Result when EngineId :: unicode:chardata(), LibPath :: unicode:chardata(), Result :: {ok, Engine :: engine_ref()} | {error, Reason :: term()}.
Loads an engine given by EngineId
and the path to the dynamic library
implementing the engine. An error tuple is returned if the engine can't be
loaded.
This function differs from the normal engine_load in the sense that it also add the engine id to OpenSSL's internal engine list. The difference between the first call and the following is that the first loads the engine with the dynamical engine and the following calls fetch it from the OpenSSL's engine list. All references that is returned are equal.
Use engine_unload/1
function to remove the references.
But remember that engine_unload/1
just removes the
references to the engine and not the tag in OpenSSL's engine list. That has to
be done with the engine_remove/1
function when needed
(just called once, from any of the references you got).
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 implementation.
See also the chapter Engine Load in the User's Guide.
-spec hash_equals(BinA, BinB) -> Result when BinA :: binary(), BinB :: binary(), Result :: boolean().
Constant time memory comparison for fixed length binaries, such as results of HMAC computations.
Returns true if the binaries are identical, false if they are of the same length
but not identical. The function raises an error:badarg
exception if the
binaries are of different size.
-spec pbkdf2_hmac(Digest, Pass, Salt, Iter, KeyLen) -> Result when Digest :: sha | sha224 | sha256 | sha384 | sha512, Pass :: binary(), Salt :: binary(), Iter :: pos_integer(), KeyLen :: pos_integer(), Result :: binary().
Uses the 3-tuple style for error handling.
PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in combination with HMAC.
-spec privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey when 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.
Functions
Convert binary representation, of an integer, to an Erlang integer.
-spec cipher_info(Type) -> Result when 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
andaes_ccm
has no keylength in theType
as opposed to for exampleaes_128_ctr
. They adapt to the length of the key provided in the encrypt and decrypt function. Therefore 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 supports(ciphers).
compute_key(Type, OthersPublicKey, MyPrivateKey, Params)
View Source (since OTP R16B01)-spec compute_key(Type, OthersPublicKey, MyPrivateKey, Params) -> SharedSecret when Type :: dh | ecdh | eddh | srp, SharedSecret :: binary(), OthersPublicKey :: dh_public() | ecdh_public() | srp_public(), MyPrivateKey :: dh_private() | ecdh_private() | {srp_public(), srp_private()}, Params :: dh_params() | ecdh_params() | srp_comp_params().
Uses the 3-tuple style for error handling.
Computes the shared secret from the private key and the other party's public
key. See also public_key:compute_key/2
-spec crypto_final(State) -> FinalResult when State :: crypto_state(), FinalResult :: binary().
Uses the 3-tuple style for error handling.
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.
-spec crypto_get_data(State) -> Result when State :: crypto_state(), Result :: map().
Uses the 3-tuple style for error handling.
Returns information about the State in the argument. The information 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 tocrypto_final/1
it contains the number of bytes padded. Otherwise 0.padding_type
- The type of the padding as provided in the call to crypto_init/3,4.encrypt
- Istrue
if encryption is performed. It isfalse
otherwise.
-spec crypto_init(Cipher, Key, FlagOrOptions) -> State when Cipher :: cipher_no_iv(), Key :: iodata(), FlagOrOptions :: crypto_opts() | boolean(), State :: crypto_state().
Uses the 3-tuple style for error handling.
Equivalent to the call
crypto_init(Cipher, Key, <<>>, FlagOrOptions)
. It is
intended for ciphers without an IV (nounce).
-spec crypto_init(Cipher, Key, IV, FlagOrOptions) -> State when Cipher :: cipher_iv(), Key :: iodata(), IV :: iodata(), FlagOrOptions :: crypto_opts(), State :: crypto_state().
Uses the 3-tuple style for error handling.
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 without an IV
(nounce). See crypto_init/3
.
The actual encryption or decryption is done by crypto_update/2
.
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 specified 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
.
crypto_one_time(Cipher, Key, Data, FlagOrOptions)
View Source (since OTP 22.0)-spec crypto_one_time(Cipher, Key, Data, FlagOrOptions) -> Result when Cipher :: cipher_no_iv(), Key :: iodata(), Data :: iodata(), FlagOrOptions :: crypto_opts() | boolean(), Result :: binary().
Uses the 3-tuple style for error handling.
As crypto_one_time/5
but for ciphers without IVs.
crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions)
View Source (since OTP 22.0)-spec crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) -> Result when Cipher :: cipher_iv(), Key :: iodata(), IV :: iodata(), Data :: iodata(), FlagOrOptions :: crypto_opts() | boolean(), Result :: binary().
Uses the 3-tuple style for error handling.
Do a complete encrypt or decrypt of the full text in the argument Data
.
For encryption, set the FlagOrOptions
to true
. For decryption, set it to
false
. For setting other options, see crypto_init/4
.
crypto_one_time_aead(Cipher, Key, IV, InText, AAD, EncFlag)
View Source (since OTP 22.0)-spec crypto_one_time_aead(Cipher, Key, IV, InText, AAD, EncFlag :: true) -> Result when Cipher :: cipher_aead(), Key :: iodata(), IV :: iodata(), InText :: iodata(), AAD :: iodata(), Result :: EncryptResult, EncryptResult :: {OutCryptoText, OutTag}, OutCryptoText :: binary(), OutTag :: binary().
Equivalent to crypto_one_time_aead/7
crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength, EncFlag)
View Source (since OTP 22.0)-spec crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength, EncFlag) -> Result when Cipher :: cipher_aead(), Key :: iodata(), IV :: iodata(), InText :: iodata(), AAD :: iodata(), TagOrTagLength :: EncryptTagLength | DecryptTag, EncryptTagLength :: non_neg_integer(), DecryptTag :: iodata(), EncFlag :: boolean(), Result :: EncryptResult | DecryptResult, EncryptResult :: {OutCryptoText, OutTag}, DecryptResult :: OutPlainText | error, OutCryptoText :: binary(), OutTag :: binary(), OutPlainText :: binary().
Uses the 3-tuple style for error handling.
Do a complete encrypt or decrypt with an AEAD cipher of the full text.
For encryption, set the EncryptFlag
to true
and set the TagOrTagLength
to
the wanted size (in bytes) of the tag, that is, the tag length. If the default
length is wanted, the crypto_one_time_aead/6
form may be used.
For decryption, set the EncryptFlag
to false
and put the tag to be checked
in the argument TagOrTagLength
.
Additional Authentication Data (AAD) is plaintext data that will not be
encrypted, but will be covered by authenticity protection. It should be provided
through the AAD
argument, but can be an empty binary as well (<<>>
) if not
needed. In that case, a plain AE (Authenticated Encryption) is performed instead
of AEAD (Authenticated Encryption with Associated Data). This function only
supports ciphers that can be used both with and without AAD.
-spec crypto_update(State, Data) -> Result when State :: crypto_state(), Data :: iodata(), Result :: binary().
Uses the 3-tuple style for error handling.
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
.
-spec ec_curve(CurveName) -> ExplicitCurve when CurveName :: ec_named_curve(), ExplicitCurve :: ec_explicit_curve().
Return the defining parameters of a elliptic curve.
-spec ec_curves() -> [EllipticCurve] when EllipticCurve :: ec_named_curve() | edwards_curve_dh() | edwards_curve_ed().
Can be used to determine which named elliptic curves are supported.
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 successfully, OTP must be built with the configure
option --enable-fips
, and the underlying libcrypto must also support FIPS.
See also info_fips/0
.
Performs bit-wise XOR (exclusive or) on the data supplied.
-spec generate_key(Type, Params) -> {PublicKey, PrivKeyOut} when Type :: dh | ecdh | eddh | eddsa | rsa | srp, PublicKey :: dh_public() | ecdh_public() | rsa_public() | srp_public(), PrivKeyOut :: dh_private() | ecdh_private() | rsa_private() | {srp_public(), srp_private()}, Params :: dh_params() | ecdh_params() | eddsa_params() | rsa_params() | srp_gen_params().
Equivalent to generate_key/3
-spec generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut} when 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().
Uses the 3-tuple style for error handling.
Generates a public key of type Type
. See also public_key:generate_key/1
.
Note
If the linked version of cryptolib is OpenSSL 3.0
- and the
Type
isdh
(diffie-hellman)- and the parameter
P
(indh_params/0
) is one of the MODP groups (see RFC 3526)- and the optional
PrivateKeyBitLength
parameter (indh_params/0
) is present,then the optional key length parameter must be at least 224, 256, 302, 352 and 400 for group sizes of 2048, 3072, 4096, 6144 and 8192, respectively.
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 the exception
error:notsup
.
-spec hash(Type, Data) -> Digest when Type :: hash_algorithm(), Data :: iodata(), Digest :: binary().
Uses the 3-tuple style for error handling.
Computes a message digest of type Type
from Data
.
-spec hash_final(State) -> Digest when State :: hash_state(), Digest :: binary().
Uses the 3-tuple style for error handling.
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.
-spec hash_info(Type) -> Result when Type :: hash_algorithm(), Result :: #{size := integer(), block_size := integer(), type := integer()}.
Provides a map with information about block_size, size and possibly other properties of the hash algorithm in question.
For a list of supported hash algorithms, see supports(hashs).
-spec hash_init(Type) -> State when Type :: hash_algorithm(), State :: hash_state().
Uses the 3-tuple style for error handling.
Initializes the context for streaming hash operations. Type
determines which
digest to use. The returned context should be used as argument to
hash_update.
-spec hash_update(State, Data) -> NewState when State :: hash_state(), NewState :: hash_state(), Data :: iodata().
Uses the 3-tuple style for error handling.
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.
-spec hash_xof(Type, Data, Length) -> Digest when Type :: hash_xof_algorithm(), Data :: iodata(), Length :: non_neg_integer(), Digest :: binary().
Uses the 3-tuple style for error handling.
Computes a message digest of type Type
from Data
of Length
for the chosen
xof_algorithm
.
May raise exception error:notsup
in case the chosen Type
is not supported by
the underlying libcrypto implementation.
-spec 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 linking 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.
-spec 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.
-spec info_lib() -> [{Name, VerNum, VerStr}] when 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
contains 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.
-spec mac(Type :: poly1305, Key, Data) -> Mac when Key :: iodata(), Data :: iodata(), Mac :: binary().
Uses the 3-tuple style for error handling.
Short for mac(Type, undefined, Key, Data).
-spec mac(Type, SubType, Key, Data) -> Mac when Type :: hmac | cmac | poly1305, SubType :: hmac_hash_algorithm() | cmac_cipher_algorithm() | undefined, Key :: iodata(), Data :: iodata(), Mac :: binary().
Uses the 3-tuple style for error handling.
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 toundefined
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.
Uses the 3-tuple style for error handling.
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.
-spec mac_finalN(State, MacLength) -> Mac when State :: mac_state(), MacLength :: pos_integer(), Mac :: binary().
Uses the 3-tuple style for error handling.
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.
Uses the 3-tuple style for error handling.
Short for mac_init(Type, undefined, Key).
-spec mac_init(Type, SubType, Key) -> State when Type :: hmac | cmac | poly1305, SubType :: hmac_hash_algorithm() | cmac_cipher_algorithm() | undefined, Key :: iodata(), State :: mac_state().
Uses the 3-tuple style for error handling.
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 toundefined
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
.
-spec mac_update(State0, Data) -> State when Data :: iodata(), State0 :: mac_state(), State :: mac_state().
Uses the 3-tuple style for error handling.
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 function, 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
.
-spec macN(Type :: poly1305, Key, Data, MacLength) -> Mac when Key :: iodata(), Data :: iodata(), Mac :: binary(), MacLength :: pos_integer().
Uses the 3-tuple style for error handling.
Short for macN(Type, undefined, Key, Data, MacLength).
-spec macN(Type, SubType, Key, Data, MacLength) -> Mac when Type :: hmac | cmac | poly1305, SubType :: hmac_hash_algorithm() | cmac_cipher_algorithm() | undefined, Key :: iodata(), Data :: iodata(), Mac :: binary(), MacLength :: pos_integer().
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.
-spec mod_pow(N, P, M) -> Result when N :: binary() | integer(), P :: binary() | integer(), M :: binary() | integer(), Result :: binary() | error.
Computes the function N^P mod M
.
private_decrypt(Algorithm, CipherText, PrivateKey, Options)
View Source (since OTP R16B01)-spec private_decrypt(Algorithm, CipherText, PrivateKey, Options) -> PlainText when Algorithm :: pk_encrypt_decrypt_algs(), CipherText :: binary(), PrivateKey :: rsa_private() | engine_key_ref(), Options :: pk_encrypt_decrypt_opts(), PlainText :: binary().
Uses the 3-tuple style for error handling.
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 verification 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)
View Source (since OTP R16B01)-spec private_encrypt(Algorithm, PlainText, PrivateKey, Options) -> CipherText when Algorithm :: pk_encrypt_decrypt_algs(), PlainText :: binary(), PrivateKey :: rsa_private() | engine_key_ref(), Options :: pk_encrypt_decrypt_opts(), CipherText :: binary().
Uses the 3-tuple style for error handling.
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
public_key:encrypt_private/2,3
public_decrypt(Algorithm, CipherText, PublicKey, Options)
View Source (since OTP R16B01)-spec public_decrypt(Algorithm, CipherText, PublicKey, Options) -> PlainText when Algorithm :: pk_encrypt_decrypt_algs(), CipherText :: binary(), PublicKey :: rsa_public() | engine_key_ref(), Options :: pk_encrypt_decrypt_opts(), PlainText :: binary().
Uses the 3-tuple style for error handling.
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 verification 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)
View Source (since OTP R16B01)-spec public_encrypt(Algorithm, PlainText, PublicKey, Options) -> CipherText when Algorithm :: pk_encrypt_decrypt_algs(), PlainText :: binary(), PublicKey :: rsa_public() | engine_key_ref(), Options :: pk_encrypt_decrypt_opts(), CipherText :: binary().
Uses the 3-tuple style for error handling.
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
-spec 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
functions 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[
-spec rand_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. Normally this is when strong_rand_bytes/1
raises
error:low_entropy
-spec rand_seed_alg(Alg :: atom()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.
rand_seed_alg(Alg) -> rand:state()
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
functions 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[
-spec rand_seed_alg(Alg :: atom(), Seed :: term()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.
rand_seed_alg(Alg, Seed) -> rand:state()
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
-spec rand_seed_alg_s(Alg :: atom()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.
rand_seed_alg_s(Alg) -> rand:state()
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
functions 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
functions using it
may throw exception 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 reproducible random sequence as from the other
rand
functions, since reproducibility does not match cryptographically safe.In fact since random data is cached some numbers may get reproduced if you try, but this is unpredictable.
The only supported usage is to generate one distinct random sequence from this start state.
-spec rand_seed_alg_s(Alg :: atom(), Seed :: term()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.
rand_seed_alg_s(Alg, Seed) -> rand:state()
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 generator states are scrambled
through AES to create 58-bit pseudo random values.
The result should be statistically completely unpredictable random 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
withAlg =:= crypto
orAlg =:= crypto_cache
. - If you need to be able to repeat the sequence use this function.
- 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
.
-spec 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
functions 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 reproducible random sequence as from the other
rand
functions, since reproducibility does not match cryptographically safe.The only supported usage is to generate one distinct random sequence from this start state.
-spec rand_uniform(crypto_integer(), crypto_integer()) -> crypto_integer().
rand_uniform(Lo, Hi) -> N
Generate a random number N, Lo =< N < Hi.
Uses the crypto
library
pseudo-random number generator. Hi
must be larger than Lo
.
-spec sign(Algorithm, DigestType, Msg, Key) -> Signature when 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(), Signature :: binary().
Equivalent to sign/5
sign(Algorithm, DigestType, Msg, Key, Options)
View Source (since OTP 20.1,OTP R16B01)-spec sign(Algorithm, DigestType, Msg, Key, Options) -> Signature when 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().
Uses the 3-tuple style for error handling.
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
.
-spec start() -> ok | {error, Reason :: term()}.
Equivalent to application:start(crypto).
-spec stop() -> ok | {error, Reason :: term()}.
Equivalent to application:stop(crypto).
-spec strong_rand_bytes(N :: non_neg_integer()) -> 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 generator failed due
to lack of secure "randomness".
-spec supports(Type) -> Support when Type :: hashs | ciphers | public_keys | macs | curves | rsa_opts, Support :: Hashs | Ciphers | PKs | Macs | Curves | RSAopts, Hashs :: [sha1() | sha2() | sha3() | sha3_xof() | 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 supported by the underlying libcrypto library
See hash_info/1
and cipher_info/1
for information about the hash and cipher
algorithms.
verify(Algorithm, DigestType, Msg, Signature, Key)
View Source (since OTP 20.1,OTP R16B01)-spec verify(Algorithm, DigestType, Msg, Signature, Key) -> Result when 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(), Result :: boolean().
Equivalent to verify/6
verify(Algorithm, DigestType, Msg, Signature, Key, Options)
View Source (since OTP 20.1,OTP R16B01)-spec verify(Algorithm, DigestType, Msg, Signature, Key, Options) -> Result when 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().
Uses the 3-tuple style for error handling.
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
.