crypto_secretbox_easy()function encrypts a message
mwhose length is
mlenbytes, with a key
kand a nonce
cshould be at least
crypto_secretbox_MACBYTES + mlenbytes long.
c, immediately followed by the encrypted message, whose length is the same as the plaintext:
mcan overlap, making in-place encryption possible. However do not forget that
crypto_secretbox_MACBYTESextra bytes are required to prepend the tag.
crypto_secretbox_open_easy()function verifies and decrypts a ciphertext produced by
cis a pointer to an authentication tag + encrypted message combination, as produced by
clenis the length of this authentication tag + encrypted message combination. Put differently,
clenis the number of bytes written by
crypto_secretbox_easy(), which is
crypto_secretbox_MACBYTES+ the length of the message.
nand the key
khave to match those used to encrypt and authenticate the message.
-1if the verification fails, and
0on success. On success, the decrypted message is stored into
ccan overlap, making in-place decryption possible.
mlenwith a key
kand a nonce
n, and puts the encrypted message into
mlenbytes will be put into
c, since this function does not prepend the authentication tag. The tag, whose size is
crypto_secretbox_MACBYTESbytes, will be put into
crypto_secretbox_open_detached()function verifies and decrypts an encrypted message
cwhose length is
clendoesn't include the tag, so this length is the same as the plaintext.
mafter verifying that
macis a valid authentication tag for this ciphertext, with the given nonce
-1if the verification fails, or
randombytes_buf()but improves code clarity and can prevent misuse by ensuring that the provided key length is always be correct.
crypto_stream_xor()to encrypt the message. As a result, a secret key used with the former should not be reused with the later. But as a general rule, a key should not be reused for different purposes.
crypto_secretboxAPI is also supported, albeit not recommended.
crypto_secretbox()takes a pointer to 32 bytes before the message, and stores the ciphertext 16 bytes after the destination pointer, the first 16 bytes being overwritten with zeros.
crypto_secretbox_open()takes a pointer to 16 bytes before the ciphertext and stores the message 32 bytes after the destination pointer, overwriting the first 32 bytes with zeros.
_detachedAPIs are faster and improve usability by not requiring padding, copying or tricky pointer arithmetic.