LibSodium.Bindings.SHA2

Introduction

The SHA-256 and SHA-512 functions are provided for interoperability with other applications. If you are looking for a generic hash function and not specifically SHA-2, using GenericHashing (BLAKE2b) might be a better choice. These functions are also not suitable for hashing passwords or deriving keys from passwords. Use PasswordHashing instead.

Only use these functions for interoperability with 3rd party services.

These functions are not keyed and are thus deterministic. In addition, the untruncated versions are vulnerable to length extension attacks. A message can be hashed in a single pass, but a streaming API is also available to process a message as a sequence of multiple chunks.

SHA-256

Single-part message

cryptoHashSHA256

Arguments

:: Ptr CUChar

A pointer to the hash of your data.

-> Ptr CUChar

A pointer to the data you want to hash.

-> CULLong

The length of the data you want to hash.

-> IO CInt

Returns 0 on success, -1 on error.

Hash the content of the second buffer and put the result in the first buffer.

See: crypto_hash_sha256()

Since: 0.0.1.0

Multi-part messages

data CryptoHashSHA256State

This is the opaque state held and used by the SHA-256 functions.

Its size is cryptoHashSHA256StateBytes.

See: crypto_hash_sha256_state

Since: 0.0.1.0

withCryptoHashSHA256State :: (Ptr CryptoHashSHA256State -> IO a) -> IO a

Perform an operation with a CryptoHashSHA256State of size cryptoHashSHA256StateBytes allocated and deallocated automatically.

⚠️ The return value of withCryptoHashSHA256State MUST NOT leak the CryptoHashSHA256State.

Please refer to the documentation of allocaBytes for more operational details.

Since: 0.0.1.0

cryptoHashSHA256Init

Arguments

:: Ptr CryptoHashSHA256State

A pointer to an uninitialised hash state. Cannot be nullPtr.

-> IO CInt

Returns 0 on success, -1 on error.

This function initializes the CryptoHashSHA256State state.

Call this function on a Ptr CryptoHashSHA256State before using it as an argument in any other function in this module.

See: crypto_hash_sha256_init()

Since: 0.0.1.0

cryptoHashSHA256Update

Arguments

:: Ptr CryptoHashSHA256State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the new message chunk to process.

-> CULLong

The length in bytes of the chunk.

-> IO CInt

Returns 0 on success, -1 on error.

Add a new chunk to the message that will eventually be hashed.

After all parts have been supplied, cryptoHashSHA256Final can be used to finalise the operation and get the final hash.

See: crypto_hash_sha256_update()

Since: 0.0.1.0

cryptoHashSHA256Final

Arguments

:: Ptr CryptoHashSHA256State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

The buffer in which the final hash is stored.

-> IO CInt

Returns 0 on success, -1 on error.

Finalise the hashing of a message. The final hash is padded with extra zeros if necessary, then put in a buffer.

After this operation, the buffer containing the CryptoHashSHA256State is emptied and cannot be relied upon.

See: crypto_hash_sha256_final()

Since: 0.0.1.0

Constants

cryptoHashSHA256Bytes :: CSize

The size of a SHA256-hashed message.

Since: 0.0.1.0

cryptoHashSHA256StateBytes :: CSize

The size of a CryptoHashSHA256State.

Since: 0.0.1.0

HMAC-SHA-256

Single-part message

cryptoAuthHMACSHA256

Arguments

:: Ptr CUChar

A pointer to the buffer holding the authenticator.

-> Ptr CUChar

A pointer to the message to be authenticated.

-> CULLong

The length of the message to be authenticated.

-> Ptr CUChar

A pointer to the secret key used for authentication, of length cryptoAuthHMACSHA256Bytes.

-> IO CInt

Returns 0 on success, -1 on error.

Authenticate a message given its size and a secret key, and produce an authenticator to be validated with cryptoAuthHMACSHA256Verify.

See: crypto_auth_hmacsha256().

Since: 0.0.1.0

cryptoAuthHMACSHA256Verify

Arguments

:: Ptr CUChar

A pointer to buffer holding the authenticator.

-> Ptr CUChar

A pointer to the message that is being authenticated.

-> CULLong

The length of the message that is being authenticated.

-> Ptr CUChar

A pointer to the secret key, of size cryptoAuthHMACSHA256KeyBytes.

-> IO CInt

Returns 0 on success, -1 on failure.

Verify that an authenticator provided by cryptoAuthHMACSHA256 is correct.

See: crypto_auth_hmacsha256_verify()

Since: 0.0.1.0

cryptoAuthHMACSHA256Keygen

Arguments

:: Ptr CUChar

A pointer to the buffer that will hold the secret key, of size cryptoAuthHMACSHA256KeyBytes.

-> IO ()

Nothing is returned

Create a random key of the correct length.

See: crypto_auth_hmacsha256_keygen()

Since: 0.0.1.0

Multi-part messages

data CryptoAuthHMACSHA256State

This is the opaque state held and used by the HMAC-SHA-256 functions.

Its size is cryptoAuthHMACSHA256StateBytes bytes.

Please refer to the documentation of allocaBytes for more operational details.

See: crypto_auth_hmacsha256_state

Since: 0.0.1.0

withCryptoAuthHMACSHA256State :: (Ptr CryptoAuthHMACSHA256State -> IO a) -> IO a

Perform an operation with a CryptoAuthHMACSHA256State of size cryptoAuthHMACSHA256StateBytes allocated and deallocated automatically.

⚠️ The return value of withCryptoAuthHMACSHA256State MUST NOT leak the CryptoAuthHMACSHA256State.

Please refer to the documentation of allocaBytes for more operational details.

Since: 0.0.1.0

cryptoAuthHMACSHA256Init

Arguments

:: Ptr CryptoAuthHMACSHA256State

A pointer to an uninitialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the secret key.

-> CSize

The size of the key.

-> IO CInt

Returns 0 on success, -1 on error.

This function initializes the CryptoAuthHMACSHA256State state.

Call this function on a Ptr CryptoAuthHMACSHA256State before using it as an argument in any other function in this module.

See: crypto_auth_hmacsha256_init()

Since: 0.0.1.0

cryptoAuthHMACSHA256Update

Arguments

:: Ptr CryptoAuthHMACSHA256State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the message to authenticate.

-> CULLong

The size of the message to authenticate.

-> IO CInt

Returns 0 on success, -1 on error.

Add a new chunk to the message that will eventually be hashed.

After all parts have been supplied, cryptoAuthHMACSHA256Final can be used to finalise the operation and get the final hash.

See: crypto_auth_hmacsha256_update()

Since: 0.0.1.0

cryptoAuthHMACSHA256Final

Arguments

:: Ptr CryptoAuthHMACSHA256State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the buffer that will hold the authenticator.

-> IO CInt

Returns 0 on success, -1 on error.

Finalise the hashing of a message. The final hash is padded with extra zeros if necessary, then put in a buffer.

After this operation, the buffer containing the CryptoAuthHMACSHA256State is emptied and cannot be relied upon.

See: crypto_auth_hmacsha256_final()

Since: 0.0.1.0

Constants

cryptoAuthHMACSHA256StateBytes :: CSize

The size of a CryptoAuthHMACSHA256State.

Since: 0.0.1.0

cryptoAuthHMACSHA256Bytes :: CSize

The size of a HMAC-SHA-256 hash

Since: 0.0.1.0

cryptoAuthHMACSHA256KeyBytes :: CSize

The size of a HMAC-SHA-256 key

Since: 0.0.1.0

SHA-512

Single-part message

cryptoHashSHA512

Arguments

:: Ptr CUChar

A pointer to the hash of your data.

-> Ptr CUChar

A pointer to the data you want to hash.

-> CULLong

The length of the data you want to hash.

-> IO CInt

Returns 0 on success, -1 on error.

Hash the content of the second buffer and put the result in the first buffer.

See: crypto_hash_sha512()

Since: 0.0.1.0

Multi-part messages

data CryptoHashSHA512State

This is the opaque state held and used by the SHA-512 functions.

Its size is cryptoHashSHA512StateBytes.

See: crypto_hash_sha512_state

Since: 0.0.1.0

withCryptoHashSHA512State :: (Ptr CryptoHashSHA512State -> IO a) -> IO a

Perform an operation with a 'CryptoHashSHA512State of size cryptoHashSHA512StateBytes allocated and deallocated automatically.

⚠️ The return value of withCryptoHashSHA512State MUST NOT leak the CryptoHashSHA512State.

Please refer to the documentation of allocaBytes for more operational details.

Since: 0.0.1.0

cryptoHashSHA512Init

Arguments

:: Ptr CryptoHashSHA512State

A pointer to an initialised hash state. Cannot be nullPtr.

-> IO CInt

Returns 0 on success, -1 on error.

This function initializes the CryptoHashSHA512State state.

Call this function on a 'Ptr CryptoHashSHA512State' before using it as an argument in any other function in this module.

See: crypto_hash_sha512_init()

Since: 0.0.1.0

cryptoHashSHA512Update

Arguments

:: Ptr CryptoHashSHA512State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the new message chunk to process.

-> CULLong

The length in bytes of the chunk.

-> IO CInt

Returns 0 on success, -1 on error.

Add a new chunk to the message that will eventually be hashed.

After all parts have been supplied, cryptoHashSHA512Final can be used to finalise the operation and get the final hash.

See: crypto_hash_sha512_update()

Since: 0.0.1.0

cryptoHashSHA512Final

Arguments

:: Ptr CryptoHashSHA512State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

The buffer in which the final hash is stored.

-> IO CInt

Returns 0 on success, -1 on error.

Finalise the hashing of a message. The final hash is padded with extra zeros if necessary, then put in a buffer.

After this operation, the buffer containing the CryptoHashSHA512State is emptied and cannot be relied upon.

See: crypto_hash_sha512_final()

Since: 0.0.1.0

Constants

cryptoHashSHA512Bytes :: CSize

The size of a SHA512-hash message.

Since: 0.0.1.0

cryptoHashSHA512StateBytes :: CSize

The size of a CryptoHashSHA512State.

Since: 0.0.1.0

HMAC-SHA-512

Single-part message

data CryptoAuthHMACSHA512State

This is the opaque state held and used by the HMAC-SHA-512 functions.

Its size is cryptoAuthHMACSHA512StateBytes bytes.

Please refer to the documentation of allocaBytes for more operational details.

See: crypto_auth_hmacsha512_state

Since: 0.0.1.0

withCryptoAuthHMACSHA512State :: (Ptr CryptoAuthHMACSHA512State -> IO a) -> IO a

Perform an operation with a CryptoAuthHMACSHA512State of size cryptoAuthHMACSHA512StateBytes allocated and deallocated automatically.

⚠️ The return value of withCryptoAuthHMACSHA512State MUST NOT leak the CryptoAuthHMACSHA512State.

Please refer to the documentation of allocaBytes for more operational details.

Since: 0.0.1.0

cryptoAuthHMACSHA512

Arguments

:: Ptr CUChar

A pointer to the buffer holding the authenticator.

-> Ptr CUChar

A pointer to the message to be authenticated.

-> CULLong

The length of the message to be authenticated.

-> Ptr CUChar

A pointer to the secret key used for authentication, of length cryptoAuthHMACSHA512Bytes.

-> IO CInt

Returns 0 on success, -1 on error.

Authenticate a message given its size and a secret key, and produce an authenticator to be validated with cryptoAuthHMACSHA512Verify.

See: crypto_auth_hmacsha512().

Since: 0.0.1.0

cryptoAuthHMACSHA512Verify

Arguments

:: Ptr CUChar

A pointer to buffer holding the authenticator.

-> Ptr CUChar

A pointer to the message that is being authenticated.

-> CULLong

The length of the message that is being authenticated.

-> Ptr CUChar

A pointer to the secret key, of size cryptoAuthHMACSHA512KeyBytes.

-> IO CInt

Returns 0 on success, -1 on failure.

Verify that an authenticator provided by cryptoAuthHMACSHA512 is correct.

See: crypto_auth_hmacsha512_verify()

Since: 0.0.1.0

cryptoAuthHMACSHA512Keygen

Arguments

:: Ptr CUChar

A pointer to the buffer that will hold the secret key, of size cryptoAuthHMACSHA512KeyBytes.

-> IO ()

Nothing is returned

Create a random key of the correct length.

See: crypto_auth_hmacsha512_keygen()

Since: 0.0.1.0

Multi-part messages

cryptoAuthHMACSHA512Init

Arguments

:: Ptr CryptoAuthHMACSHA512State

A pointer to an uninitialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the secret key.

-> CSize

The size of the key.

-> IO CInt

Returns 0 on success, -1 on error.

This function initializes the CryptoAuthHMACSHA512State state.

Call this function on a 'Ptr CryptoAuthHMACSHA512State' before using it as an argument in any other function in this module.

See: crypto_auth_hmacsha512_init()

Since: 0.0.1.0

cryptoAuthHMACSHA512Update

Arguments

:: Ptr CryptoAuthHMACSHA512State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the message to authenticate.

-> CULLong

The size of the message to authenticate.

-> IO CInt

Returns 0 on success, -1 on error.

Add a new chunk to the message that will eventually be hashed.

After all parts have been supplied, cryptoAuthHMACSHA512Final can be used to finalise the operation and get the final hash.

See: crypto_auth_hmacsha512_update()

Since: 0.0.1.0

cryptoAuthHMACSHA512Final

Arguments

:: Ptr CryptoAuthHMACSHA512State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the buffer that will hold the authenticator.

-> IO CInt

Returns 0 on success, -1 on error.

Finalise the hashing of a message. The final hash is padded with extra zeros if necessary, then put in a buffer.

After this operation, the buffer containing the CryptoAuthHMACSHA512State is emptied and cannot be relied upon.

See: crypto_auth_hmacsha512_final()

Since: 0.0.1.0

Constants

cryptoAuthHMACSHA512StateBytes :: CSize

The size of a CryptoAuthHMACSHA512State.

Since: 0.0.1.0

cryptoAuthHMACSHA512Bytes :: CSize

The size of a HMAC-SHA-512 hash

Since: 0.0.1.0

cryptoAuthHMACSHA512KeyBytes :: CSize

The size of a HMAC-SHA-512 key

Since: 0.0.1.0

HMAC-SHA-512-256

HMAC-SHA-512-256 is implemented as HMAC-SHA-512 with the output truncated to 256 bits. This is slightly faster than HMAC-SHA-256. Note that this construction is not the same as HMAC-SHA-512/256, which is HMAC using the SHA-512/256 function.

Single-part message

data CryptoAuthHMACSHA512256State

This is the opaque state held and used by the HMAC-SHA-512256 functions.

Its size is cryptoAuthHMACSHA512256StateBytes bytes.

Please refer to the documentation of allocaBytes for more operational details.

See: crypto_auth_hmacsha512256_state

Since: 0.0.1.0

withCryptoAuthHMACSHA512256State :: (Ptr CryptoAuthHMACSHA512256State -> IO a) -> IO a

Perform an operation with a CryptoAuthHMACSHA512256State of size cryptoAuthHMACSHA512256StateBytes allocated and deallocated automatically.

⚠️ The return value of withCryptoAuthHMACSHA512256State MUST NOT leak the CryptoAuthHMACSHA512256State.

Please refer to the documentation of allocaBytes for more operational details.

Since: 0.0.1.0

cryptoAuthHMACSHA512256

Arguments

:: Ptr CUChar

A pointer to the buffer holding the authenticator.

-> Ptr CUChar

A pointer to the message to be authenticated.

-> CULLong

The length of the message to be authenticated.

-> Ptr CUChar

A pointer to the secret key used for authentication, of length cryptoAuthHMACSHA512256Bytes.

-> IO CInt

Returns 0 on success, -1 on error.

Authenticate a message given its size and a secret key, and produce an authenticator to be validated with cryptoAuthHMACSHA512256Verify.

See: crypto_auth_hmacsha512256().

Since: 0.0.1.0

cryptoAuthHMACSHA512256Verify

Arguments

:: Ptr CUChar

A pointer to buffer holding the authenticator.

-> Ptr CUChar

A pointer to the message that is being authenticated.

-> CULLong

The length of the message that is being authenticated.

-> Ptr CUChar

A pointer to the secret key, of size cryptoAuthHMACSHA512256KeyBytes.

-> IO CInt

Returns 0 on success, -1 on failure.

Verify that an authenticator provided by cryptoAuthHMACSHA512256 is correct.

See: crypto_auth_hmacsha512256_verify()

Since: 0.0.1.0

cryptoAuthHMACSHA512256Keygen

Arguments

:: Ptr CUChar

A pointer to the buffer that will hold the secret key, of size cryptoAuthHMACSHA512256KeyBytes.

-> IO ()

Nothing is returned

Create a random key of the correct length.

See: crypto_auth_hmacsha512256_keygen()

Since: 0.0.1.0

Multi-part messages

cryptoAuthHMACSHA512256Init

Arguments

:: Ptr CryptoAuthHMACSHA512256State

A pointer to an uninitialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the secret key.

-> CSize

The size of the key.

-> IO CInt

Returns 0 on success, -1 on error.

This function initializes the CryptoAuthHMACSHA512256State state.

Call this function on a Ptr CryptoAuthHMACSHA512256State before using it as an argument in any other function in this module.

See: crypto_auth_hmacsha512256_init()

Since: 0.0.1.0

cryptoAuthHMACSHA512256Update

Arguments

:: Ptr CryptoAuthHMACSHA512256State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the message to authenticate.

-> CULLong

The size of the message to authenticate.

-> IO CInt

Returns 0 on success, -1 on error.

Add a new chunk to the message that will eventually be hashed.

After all parts have been supplied, cryptoAuthHMACSHA512256Final can be used to finalise the operation and get the final hash.

See: crypto_auth_hmacsha512256_update()

Since: 0.0.1.0

cryptoAuthHMACSHA512256Final

Arguments

:: Ptr CryptoAuthHMACSHA512256State

A pointer to an initialised hash state. Cannot be nullPtr.

-> Ptr CUChar

A pointer to the buffer that will hold the authenticator.

-> IO CInt

Returns 0 on success, -1 on error.

Finalise the hashing of a message. The final hash is padded with extra zeros if necessary, then put in a buffer.

After this operation, the buffer containing the CryptoAuthHMACSHA512256State is emptied and cannot be relied upon.

See: crypto_auth_hmacsha512256_final()

Since: 0.0.1.0

Constants

cryptoAuthHMACSHA512256StateBytes :: CSize

The size of a CryptoAuthHMACSHA512256State.

Since: 0.0.1.0

cryptoAuthHMACSHA512256Bytes :: CSize

The size of a HMAC-SHA-512256 hash

Since: 0.0.1.0

cryptoAuthHMACSHA512256KeyBytes :: CSize

The size of a HMAC-SHA-512256 key

Since: 0.0.1.0