TCryptoSecretBox
Encrypts a message with a secret key to keep it confidential.
Computes a nonce and an authentication tag. This tag is used to make sure that the message hasn't been tampered with before decrypting it.
A single key is used both to encrypt/sign and verify/decrypt messages. For this reason, it is critical to keep the key confidential.
Functions
Function KeyGen:TCryptoSecretBoxKey()
Generates a secret key suitable for use with TCryptoSecretBox.
Function Encrypt:Int(c:Byte Ptr, cLen:Size_T, m:Byte Ptr, mLen:Size_T, msgId:ULong, context:String, key:TCryptoKey)
Encrypts a message m of length mLen bytes using a context, a secret key and a message counter msgId.
It puts the ciphertext whose length is CRYPTO_SECRETBOX_HEADERBYTES + mlen into c.
The header includes an automatically-generated 160-bit nonce as well as a 128-bit authentication tag.
A nonce doesn't have to be provided: it is automatically computed using the output of the PRNG and a keyed hash of the message and its metadata. This prevents catastrophic failures even if the PRNG cannot be trusted.
msgId is an optional message tag. For example, if 3 messages are sent to the same recipient using the same key, these messages can sequentially use 0, 1 and 2 as identifiers.
If the recipient expects message 2, but receives a message with a different identifier, it will not decrypt it even if it was encrypted with the correct key.
This can be used to discard duplicate or old messages.
A msgId doesn't have to be secret and it doesn't have to be sequential either. Some applications might prefer a coarse timestamp instead. Any value up to 2^64-1 is acceptable.
If this mechanism is not required by an application, using a constant msgId such as 0 is also totally fine. Message identifiers are optional and do not have to be unique.
Function Encrypt:Int(c:Byte[], m:Byte[], msgId:ULong, context:String, key:TCryptoKey)
Encrypts a message m using a context, a secret key and a message counter msgId.
It puts the ciphertext whose length is CRYPTO_SECRETBOX_HEADERBYTES + m.length into c.
The header includes an automatically-generated 160-bit nonce as well as a 128-bit authentication tag.
A nonce doesn't have to be provided: it is automatically computed using the output of the PRNG and a keyed hash of the message and its metadata. This prevents catastrophic failures even if the PRNG cannot be trusted.
msgId is an optional message tag. For example, if 3 messages are sent to the same recipient using the same key, these messages can sequentially use 0, 1 and 2 as identifiers.
If the recipient expects message 2, but receives a message with a different identifier, it will not decrypt it even if it was encrypted with the correct key.
This can be used to discard duplicate or old messages.
A msgId doesn't have to be secret and it doesn't have to be sequential either. Some applications might prefer a coarse timestamp instead. Any value up to 2^64-1 is acceptable.
If this mechanism is not required by an application, using a constant msgId such as 0 is also totally fine. Message identifiers are optional and do not have to be unique.
Function Decrypt:Int(m:Byte Ptr, mLen:Size_T, c:Byte Ptr, cLen:Size_T, msgId:ULong, context:String, key:TCryptoKey)
Decrypts the ciphertext c of length cLen (which includes the CRYPTO_SECRETBOX_HEADERBYTES bytes header) using the secret key key, the context and the message identifier msgId.
If the authentication tag can be verified using these parameters, the function stores the decrypted message into m. The length of this decrypted message is cLen - CRYPTO_SECRETBOX_KEYBYTES. It then returns True.
If the authentication tag doesn't appear to be valid for these parameters, the function returns False.
Function Decrypt:Int(m:Byte[], c:Byte[], msgId:ULong, context:String, key:TCryptoKey)
Decrypts the ciphertext c (which includes the CRYPTO_SECRETBOX_HEADERBYTES bytes header) using the secret key key, the context and the message identifier msgId.
If the authentication tag can be verified using these parameters, the function stores the decrypted message into m. The length of this decrypted message is c.length - CRYPTO_SECRETBOX_KEYBYTES. It then returns True.
If the authentication tag doesn't appear to be valid for these parameters, the function returns False.
Function ProbeCreate(probe:Byte Ptr, probeLen:Size_T, c:Byte Ptr, cLen:Size_T, context:String, key:TCryptoKey)
Computes a probe for the ciphertext c whose length is cLen, using the context and a shared secret key key.
The probe is put into probe whose size is CRYPTO_SECRETBOX_PROBEBYTES bytes.
Function ProbeCreate(probe:Byte[], c:Byte[], context:String, key:TCryptoKey)
Computes a probe for the ciphertext c, using the context and a shared secret key key.
The probe is put into probe whose size is CRYPTO_SECRETBOX_PROBEBYTES bytes.
Function ProbeVerify:Int(probe:Byte Ptr, probeLen:Size_T, c:Byte Ptr, cLen:Size_T, context:String, key:TCryptoKey)
Verifies that a received probe probe is valid for the ciphertext c whose length is cLen, using the context and the shared secret key key that was initially used to compute the probe.
It returns True on success, and False if the probe didn't pass verification.
Function ProbeVerify:Int(probe:Byte[], c:Byte[], context:String, key:TCryptoKey)
Verifies that a received probe probe is valid for the ciphertext c, using the context and the shared secret key key that was initially used to compute the probe.
It returns True on success, and False if the probe didn't pass verification.