Modulelibsodium-bindings-0.0.1.1Haskell2010

LibSodium.Bindings.CryptoSign

1 type
18 values

Packagelibsodium-bindings-0.0.1.1
Exports19
LanguageHaskell2010
LicenceBSD-3-Clause
SourceCryptoSign.hs

Introduction

0 declarations

When signing with public-key cryptography, a signer generates a key pair consisting of:

A secret key, which you can use to append a signature to any number of messages.
A public key, which anybody can use to verify that the signature appended to a message was issued by the creator of the public key.

Verifiers need to already know and ultimately trust a public key before messages signed using it can be verified.

Warning: this is different from authenticated encryption. Appending a signature does not change the representation of the message itself.

Key pair generation

2 declarations

valuecryptoSignKeyPair

:: Ptr CUChar
A pointer to the buffer holding the public key. It has a length of cryptoSignPublicKeyBytes bytes.
-> Ptr CUChar
A pointer to the buffer holding the secret key. It has a length of cryptoSignSecretKeyBytes bytes.
-> IO CInt
Returns 0 on success, -1 on error.

Randomly generate a secret key and a corresponding public key.

See: crypto_sign_keypair()

valuecryptoSignSeedKeyPair

:: Ptr CUChar
A pointer to the buffer holding the public key. It has a length of cryptoSignPublicKeyBytes.
-> Ptr CUChar
A pointer to the buffer holding the secret key. It has a length of cryptoSignSecretKeyBytes.
-> Ptr CUChar
A pointer to the seed. It has a length of cryptoSignSeedBytes.
-> IO CInt
Returns 0 on success, -1 on error.

Derive a keypair (secret key and public key) from a seed. It is deterministic.

See: crypto_sign_seed_keypair()

Combined mode

2 declarations

valuecryptoSign

:: Ptr CUChar
Pointer to the signed message.
-> Ptr CULLong
Pointer to the length of the signed message.
-> Ptr CUChar
Pointer to the message to sign.
-> CULLong
Length of the message.
-> Ptr CUChar
Pointer to the secret key.
-> IO CInt
Returns 0 on success, -1 on error.

Prepend a signature to a message, using the secret key.

The signed message, which includes the signature plus an unaltered copy of the message, is put into the signed message buffer, and is of length cryptoSignBytes + length of the message bytes.

If the pointer to the length of the signed message is not a Foreign.nullPtr, then the actual length of the signed message is stored in it.

See: crypto_sign()

valuecryptoSignOpen

:: Ptr CUChar
Pointer to the buffer holding the message without the signature.
-> Ptr CULLong
Pointer to the buffer holding the length of the message, if it is not a Foreign.nullPtr.
-> Ptr CUChar
Pointer to the signed message.
-> CULLong
Length of the signed message.
-> Ptr CUChar
Pointer to the public key.
-> IO CInt
On success, the function returns 0 If the signature isn't valid, then the function returns -1.

Check that the signed message has a valid signature for the public key.

On success, it puts the message, without the signature into the first buffer. The length of the message will be stored in the , if the pointer is not a Foreign.nullPtr.

See: crypto_sign_open()

Detached Mode

2 declarations

In detached mode, the signature is stored without attaching a copy of the original message to it.

valuecryptoSignDetached

:: Ptr CUChar
Pointer to the signature.
-> Ptr CULLong
Pointer to the length of the signature.
-> Ptr CUChar
Pointer to the message to sign.
-> CULLong
Length of the message.
-> Ptr CUChar
Pointer to the secret key.
-> IO CInt
Returns 0 on success, -1 on error.

Sign the message using the secret key and put the signature into a buffer, which can be up to cryptoSignBytes bytes long. The actual length of the signature is put into a buffer if its pointer is not Foreign.nullPtr. It is safe to ignore the length of the signature and always consider a signature as cryptoSignBytes bytes long; shorter signatures will be transparently padded with zeros if necessary.

See: crypto_sign_detached()

valuecryptoSignVerifyDetached

:: Ptr CUChar
Pointer to the signature
-> Ptr CUChar
Pointer to the message
-> CULLong
Length of the message
-> Ptr CUChar
Pointer to the signer's public key
-> IO CInt
Returns 0 on success, -1 on error.

Verify that the signature is valid for the message, using the signer's public key.

See: crypto_sign_verify_detached()

Multi-part messages

8 declarations

If the message you're trying to sign doesn't fit in memory, then it can be provided as a sequence of arbitrarily-sized chunks. This uses the Ed25519ph signature system, which pre-hashes the message. In other words, what gets signed is not the message itself but its image through a hash function. If the message can fit in memory and be supplied as a single chunk, then the single-part API should be preferred.

Note

Ed25519ph(m) is intentionally not equivalent to Ed25519(SHA512(m)). If, for some reason, you need to pre-hash the message yourself, then use the multi-part LibSodium.Bindings.GenericHashing module and sign the 512-bit output.

datadata CryptoSignState

Opaque tag representing the hash state struct crypto_sign_state used by the C API.

It is of size cryptoSignStateBytes.

To use a CryptoSignState, use withSignState.

valuewithSignState :: (Ptr CryptoSignState -> IO a) -> IO a

Perform an operation with a CryptoSignState of size cryptoSignStateBytes allocated and deallocated automatically.

⚠️ The return value of withSignState MUST NOT leak the CryptoSignState.

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

valuecryptoSignInit

:: Ptr CryptoSignState
A pointer to the cryptographic state. Cannot be Foreign.nullPtr.
-> IO CInt
Returns 0 on success, -1 on error.

Initialise the CryptoSignState state.

It must be called before the first cryptoSignUpdate call.

See: crypto_sign_init()

valuecryptoSignUpdate

:: Ptr CryptoSignState
A pointer to an initialized cryptographic state. Cannot be Foreign.nullPtr.
-> Ptr CUChar
Pointer to the new chunk to sign.
-> CULLong
Length of the new chunk.
-> IO CInt
Returns 0 on success, -1 on error.

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

After all parts have been supplied, cryptoSignFinalCreate or cryptoSignFinalVerify can be used.

See: crypto_sign_update()

valuecryptoSignFinalCreate

:: Ptr CryptoSignState
A pointer to an initialized cryptographic state. Cannot be Foreign.nullPtr.
-> Ptr CUChar
Pointer to the signature. Cannot be Foreign.nullPtr.
-> Ptr CULLong
A pointer to the length of the signature. Can be Foreign.nullPtr.
-> Ptr CUChar
Pointer to the secret key. Cannot be Foreign.nullPtr.
-> IO CInt
Returns 0 on success, -1 on error.

Compute a signature for the previously supplied message using the secret key, and put it into the signature buffer.

If the pointer to the length of the signature is not a Foreign.nullPtr, then the length of the signature is stored at this address. It is safe to ignore the length of the signature and always consider a signature as cryptoSignBytes bytes long; shorter signatures will be transparently padded with zeros if necessary.

See: crypto_sign_final_create()

valuecryptoSignFinalVerify

:: Ptr CryptoSignState
A pointer to an initialized cryptographic state. Cannot be Foreign.nullPtr.
-> Ptr CUChar
Pointer to the signature.
-> Ptr CUChar
Pointer to the public key.
-> IO CInt
Returns 0 on success, -1 on error.

Verify that the signature is valid using the public key for the message whose content has been previously supplied using cryptoSignUpdate.

See: crypto_sign_final_verify()

valuecryptoSignED25519SkToSeed

:: Ptr CUChar
Pointer to the seed.
-> Ptr CUChar
Pointer to the secret key.
-> IO CInt
Returns 0 on success, -1 on error.

This function extracts the seed from the secret key secret key and copies it into the buffer holding the seed. The size of the seed will be equal to cryptoSignSeedBytes.

See: crypto_sign_ed25519_sk_to_seed()

valuecryptoSignED25519SkToPk

:: Ptr CUChar
Pointer to the public key.
-> Ptr CUChar
Pointer to the secret key.
-> IO CInt
Returns 0 on success, -1 on error.

This function extracts the public key from the secret key secret key and copies it into public key. The size of public key will be equal to cryptoSignPublicKeyBytes.

See: crypto_sign_ed25519_sk_to_pk()