libsodium-bindings-0.0.1.1: FFI bindings to libsodium
Copyright(C) Hécate Moonlight 2022
LicenseBSD-3-Clause
MaintainerThe Haskell Cryptography Group
StabilityStable
PortabilityGHC only
Safe HaskellNone
LanguageHaskell2010

LibSodium.Bindings.SHA2

Description

 
Synopsis

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

The size of a SHA256-hashed message.

Since: 0.0.1.0

HMAC-SHA-256

Single-part message

cryptoAuthHMACSHA256 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

cryptoAuthHMACSHA256Bytes :: CSize Source #

The size of a HMAC-SHA-256 hash

Since: 0.0.1.0

cryptoAuthHMACSHA256KeyBytes :: CSize Source #

The size of a HMAC-SHA-256 key

Since: 0.0.1.0

SHA-512

Single-part message

cryptoHashSHA512 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

The size of a SHA512-hash message.

Since: 0.0.1.0

HMAC-SHA-512

Single-part message

data CryptoAuthHMACSHA512State Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

cryptoAuthHMACSHA512Bytes :: CSize Source #

The size of a HMAC-SHA-512 hash

Since: 0.0.1.0

cryptoAuthHMACSHA512KeyBytes :: CSize Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

cryptoAuthHMACSHA512256Bytes :: CSize Source #

The size of a HMAC-SHA-512256 hash

Since: 0.0.1.0

cryptoAuthHMACSHA512256KeyBytes :: CSize Source #

The size of a HMAC-SHA-512256 key

Since: 0.0.1.0