| Copyright | (C) Hécate Moonlight 2022 |
|---|---|
| License | BSD-3-Clause |
| Maintainer | The Haskell Cryptography Group |
| Stability | Stable |
| Portability | GHC only |
| Safe Haskell | Trustworthy |
| Language | Haskell2010 |
LibSodium.Bindings.CryptoSign
Description
Synopsis
- cryptoSignKeyPair :: Ptr CUChar -> Ptr CUChar -> IO CInt
- cryptoSignSeedKeyPair :: Ptr CUChar -> Ptr CUChar -> Ptr CUChar -> IO CInt
- cryptoSign :: Ptr CUChar -> Ptr CULLong -> Ptr CUChar -> CULLong -> Ptr CUChar -> IO CInt
- cryptoSignOpen :: Ptr CUChar -> Ptr CULLong -> Ptr CUChar -> CULLong -> Ptr CUChar -> IO CInt
- cryptoSignDetached :: Ptr CUChar -> Ptr CULLong -> Ptr CUChar -> CULLong -> Ptr CUChar -> IO CInt
- cryptoSignVerifyDetached :: Ptr CUChar -> Ptr CUChar -> CULLong -> Ptr CUChar -> IO CInt
- data CryptoSignState
- withSignState :: (Ptr CryptoSignState -> IO a) -> IO a
- cryptoSignInit :: Ptr CryptoSignState -> IO CInt
- cryptoSignUpdate :: Ptr CryptoSignState -> Ptr CUChar -> CULLong -> IO CInt
- cryptoSignFinalCreate :: Ptr CryptoSignState -> Ptr CUChar -> Ptr CULLong -> Ptr CUChar -> IO CInt
- cryptoSignFinalVerify :: Ptr CryptoSignState -> Ptr CUChar -> Ptr CUChar -> IO CInt
- cryptoSignED25519SkToSeed :: Ptr CUChar -> Ptr CUChar -> IO CInt
- cryptoSignED25519SkToPk :: Ptr CUChar -> Ptr CUChar -> IO CInt
- cryptoSignStateBytes :: CSize
- cryptoSignPublicKeyBytes :: CSize
- cryptoSignSecretKeyBytes :: CSize
- cryptoSignBytes :: CSize
- cryptoSignSeedBytes :: CSize
Introduction
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
Arguments
| :: Ptr CUChar | A pointer to the buffer holding the public key. It has a length of |
| -> Ptr CUChar | A pointer to the buffer holding the secret key. It has a length of |
| -> IO CInt | Returns 0 on success, -1 on error. |
Randomly generate a secret key and a corresponding public key.
Since: 0.0.1.0
cryptoSignSeedKeyPair Source #
Arguments
| :: Ptr CUChar | A pointer to the buffer holding the public key. It has a length of |
| -> Ptr CUChar | A pointer to the buffer holding the secret key. It has a length of |
| -> Ptr CUChar | A pointer to the seed. It has a length of |
| -> 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()
Since: 0.0.1.0
Combined mode
Arguments
| :: 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 nullPtr,
then the actual length of the signed message is stored in it.
See: crypto_sign()
Since: 0.0.1.0
Arguments
| :: 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 |
| -> 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 nullPtr.
See: crypto_sign_open()
Since: 0.0.1.0
Detached Mode
In detached mode, the signature is stored without attaching a copy of the original message to it.
Arguments
| :: 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 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.
Since: 0.0.1.0
cryptoSignVerifyDetached Source #
Arguments
| :: 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()
Since: 0.0.1.0
Multi-part messages
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
GenericHashing module and sign the 512-bit output.
data CryptoSignState Source #
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.
Since: 0.0.1.0
withSignState :: (Ptr CryptoSignState -> IO a) -> IO a Source #
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.
Since: 0.0.1.0
Arguments
| :: Ptr CryptoSignState | A pointer to the cryptographic state. Cannot be |
| -> 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()
Since: 0.0.1.0
Arguments
| :: Ptr CryptoSignState | A pointer to an initialized cryptographic state. Cannot be |
| -> 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()
Since: 0.0.1.0
cryptoSignFinalCreate Source #
Arguments
| :: Ptr CryptoSignState | A pointer to an initialized cryptographic state. Cannot be |
| -> Ptr CUChar | Pointer to the signature. Cannot be |
| -> Ptr CULLong | A pointer to the length of the signature. Can be |
| -> Ptr CUChar | Pointer to the secret key. Cannot be |
| -> 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 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()
Since: 0.0.1.0
cryptoSignFinalVerify Source #
Arguments
| :: Ptr CryptoSignState | A pointer to an initialized cryptographic state. Cannot be |
| -> 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()
Since: 0.0.1.0
cryptoSignED25519SkToSeed Source #
Arguments
| :: 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()
Since: 0.0.1.0
cryptoSignED25519SkToPk Source #
Arguments
| :: 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()
Since: 0.0.1.0
Constants
cryptoSignPublicKeyBytes :: CSize Source #
See: crypto_sign_PUBLICKEYBYTES
Since: 0.0.1.0
cryptoSignSecretKeyBytes :: CSize Source #
See: crypto_sign_SECRETKEYBYTES
Since: 0.0.1.0
cryptoSignBytes :: CSize Source #
See: crypto_sign_BYTES
Since: 0.0.1.0
cryptoSignSeedBytes :: CSize Source #
Since: 0.0.1.0