Specs

bytes_to_integer(binary()) -> integer().

Convert binary representation, of an integer, to an Erlang integer.

Specs

cipher_info(Type) -> Result | run_time_error()
               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.

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

Specs

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().

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

Specs

crypto_dyn_iv_init(Cipher, Key, FlagOrOptions) -> State | descriptive_error()
                      when
                          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, undefined, FlagOrOptions).

Specs

crypto_dyn_iv_update(State, Data, IV) -> Result | descriptive_error()
                        when
                            State :: crypto_state(),
                            Data :: iodata(),
                            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.

Specs

crypto_final(State) -> FinalResult | descriptive_error()
                when 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.

Specs

crypto_get_data(State) -> Result when State :: crypto_state(), Result :: map().

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 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.

Specs

crypto_init(Cipher, Key, FlagOrOptions) -> State | descriptive_error()
               when
                   Cipher :: cipher_no_iv(),
                   Key :: iodata(),
                   FlagOrOptions :: crypto_opts() | boolean(),
                   State :: crypto_state().

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

Specs

crypto_init(Cipher, Key, IV, FlagOrOptions) -> State | descriptive_error()
               when
                   Cipher :: cipher_iv(),
                   Key :: iodata(),
                   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 without 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.

Specs

crypto_one_time(Cipher, Key, Data, FlagOrOptions) -> Result | descriptive_error()
                   when
                       Cipher :: cipher_no_iv(),
                       Key :: iodata(),
                       Data :: iodata(),
                       FlagOrOptions :: crypto_opts() | boolean(),
                       Result :: binary().

As crypto_one_time/5 but for ciphers without IVs.

Specs

crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) -> Result | descriptive_error()
                   when
                       Cipher :: cipher_iv(),
                       Key :: iodata(),
                       IV :: iodata(),
                       Data :: iodata(),
                       FlagOrOptions :: crypto_opts() | boolean(),
                       Result :: binary().

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.

See examples in the User's Guide.

Specs

crypto_one_time_aead(Cipher, Key, IV, InText, AAD, EncFlag :: true) ->
                        Result | descriptive_error()
                        when
                            Cipher :: cipher_aead(),
                            Key :: iodata(),
                            IV :: iodata(),
                            InText :: iodata(),
                            AAD :: iodata(),
                            Result :: EncryptResult,
                            EncryptResult :: {OutCryptoText, OutTag},
                            OutCryptoText :: binary(),
                            OutTag :: 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 TagOrTagLength 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.

Specs

crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength, EncFlag) ->
                        Result | descriptive_error()
                        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().

Specs

crypto_update(State, Data) -> Result | descriptive_error()
                 when 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.

Specs

ec_curve(CurveName) -> ExplicitCurve
            when CurveName :: ec_named_curve(), ExplicitCurve :: ec_explicit_curve().

Return the defining parameters of a elliptic curve.

Specs

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.

Specs

enable_fips_mode(Enable) -> Result when Enable :: boolean(), 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.

Specs

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.

Specs

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.

Specs

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.

Specs

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.

Specs

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.

Specs

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.

Specs

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.

Specs

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.

Specs

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 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 implementation.

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

Specs

engine_load(EngineId, PreCmds, PostCmds, EngineMethods) -> Result
               when
                   EngineId :: unicode:chardata(),
                   PreCmds :: [engine_cmnd()],
                   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 implementation.

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

Specs

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.

Specs

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.

Specs

ensure_engine_loaded(EngineId, LibPath) -> Result
                        when
                            EngineId :: unicode:chardata(),
                            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 implementation.

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

Specs

ensure_engine_loaded(EngineId, LibPath, EngineMethods) -> Result
                        when
                            EngineId :: unicode:chardata(),
                            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 implementation.

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

Specs

ensure_engine_unloaded(Engine) -> Result
                          when 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 implementation.

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

Specs

ensure_engine_unloaded(Engine, EngineMethods) -> Result
                          when
                              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 implementation.

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

Specs

exor(iodata(), iodata()) -> binary().

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

Specs

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().

Generates a public key of type Type. See also public_key:generate_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.

Specs

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().

Specs

hash(Type, Data) -> Digest when 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.

Specs

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.

Specs

hash_final(State) -> Digest when 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.

Specs

hash_info(Type) -> Result | run_time_error()
             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).

Specs

hash_init(Type) -> State when 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.

Specs

hash_update(State, Data) -> NewState
               when State :: hash_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.

Specs

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.

Specs

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"">>}]
        

Specs

mac(Type :: poly1305, Key, Data) -> Mac | descriptive_error()
       when Key :: iodata(), Data :: iodata(), Mac :: binary().

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

Specs

mac(Type, SubType, Key, Data) -> Mac | descriptive_error()
       when
           Type :: hmac | cmac | poly1305,
           SubType :: hmac_hash_algorithm() | cmac_cipher_algorithm() | undefined,
           Key :: iodata(),
           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.

Specs

macN(Type :: poly1305, Key, Data, MacLength) -> Mac | descriptive_error()
        when Key :: iodata(), Data :: iodata(), Mac :: binary(), MacLength :: pos_integer().

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

Specs

macN(Type, SubType, Key, Data, MacLength) -> Mac | descriptive_error()
        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.

Specs

mac_final(State) -> Mac | descriptive_error() when 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.

Specs

mac_finalN(State, MacLength) -> Mac | descriptive_error()
              when State :: mac_state(), MacLength :: pos_integer(), 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.

Specs

mac_init(Type :: poly1305, Key) -> State | descriptive_error()
            when Key :: iodata(), State :: mac_state().

Short for mac_init(Type, undefined, Key).

Specs

mac_init(Type, SubType, Key) -> State | descriptive_error()
            when
                Type :: hmac | cmac | poly1305,
                SubType :: hmac_hash_algorithm() | cmac_cipher_algorithm() | undefined,
                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.

Specs

mac_update(State0, Data) -> State | descriptive_error()
              when Data :: iodata(), State0 :: mac_state(), 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 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.

Specs

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.

Specs

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().

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]

Specs

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().

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]

Specs

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.

Specs

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().

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]

Specs

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().

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]

Specs

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[

Specs

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

Specs

rand_seed_alg(Alg :: atom()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.

• 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 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[

Specs

rand_seed_alg(Alg :: atom(), Seed :: term()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.

• 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
	

Specs

rand_seed_alg_s(Alg :: atom()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.

• 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 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".

Specs

rand_seed_alg_s(Alg :: atom(), Seed :: term()) -> {rand:alg_handler(), atom() | rand_cache_seed()}.

• 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 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 with Alg =:= crypto or Alg =:= 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.

Specs

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".

Specs

rand_uniform(crypto_integer(), crypto_integer()) -> crypto_integer().

• 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.

Specs

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().

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.

Specs

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().

Specs

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

Equivalent to application:start(crypto).

Specs

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

Equivalent to application:stop(crypto).

Specs

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".

Specs

supports(Type) -> Support
            when
                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 supported by the underlying libcrypto library

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

Specs

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().

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.

Specs

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().