1AES_SIV_Encrypt(3) 2================== 3:doctype: manpage 4 5NAME 6---- 7 8AES_SIV_Encrypt, AES_SIV_Decrypt - AES-SIV high-level interface 9 10SYNOPSIS 11-------- 12 13[source,c] 14---- 15#include <aes_siv.h> 16 17int AES_SIV_Encrypt(AES_SIV_CTX *ctx, 18 unsigned char *out, size_t *out_len, 19 unsigned char const* key, size_t key_len, 20 unsigned char const* nonce, size_t nonce_len, 21 unsigned char const* plaintext, size_t plaintext_len, 22 unsigned char const* ad, size_t ad_len); 23 24int AES_SIV_Decrypt(AES_SIV_CTX *ctx, 25 unsigned char *out, size_t *out_len, 26 unsigned char const* key, size_t key_len, 27 unsigned char const* nonce, size_t nonce_len, 28 unsigned char const* ciphertext, size_t ciphertext_len, 29 unsigned char const* ad, size_t ad_len); 30---- 31 32DESCRIPTION 33----------- 34 35These functions provide a high-level interface for AES-SIV encryption 36and decryption, complying with RFC 5297. 37 38*AES_SIV_Encrypt()* uses the provided _ctx_ to encrypt the provided 39_plaintext_ and associated data _ad_ using the provided _key_ and 40_nonce_, and outputs up to _*out_len_ bytes of ciphertext into the 41memory pointed to by _out_. It sets _*out_len_ to the actual output 42length, which will always be _plaintext_len_ + 16. 43 44*AES_SIV_Decrypt()* uses the provided _ctx_ to authenticate and 45decrypt the provided _ciphertext_ and associated data _ad_ using the 46provided _key_ and _nonce_, and outputs up to _*out_len_ bytes of 47plaintext into the memory pointed to by _out_. It sets _*out_len_ to 48the actual output length, which will always be _ciphertext_len_ - 16. 49 50_key_len_ is given in bytes and must be 32, 48, or 64. 51 52For deterministic encryption, the _nonce_ may be NULL; note that this 53is distinct from providing a zero-length nonce; see NOTES. 54 55NOTES 56----- 57 58The output of +AES_SIV_Encrypt()+ is formatted as a 16-byte 59authentication tag followed by the actual ciphertext. Plaintext may be 60encrypted in-place by letting _plaintext_ equal +&out[16]+. Similarly, 61ciphertext may be authenticated and decrypted in-place by letting 62_out_ equal +&ciphertext[16]+. 63 64RFC 5297 defines AES-SIV in such a way that deterministic use (i.e, 65not providing a nonce) is distinct from providing a nonce of zero 66length. The latter (a zero-length-onnce) is supported by libaes_siv 67but not recommended, and RFC 5297 is ambiguous as to whether it ought 68to be permitted: the operation is clearly defined, but the IANA 69registrations for AES-SIV's RFC 5116 interface specify an N_MIN of 1. 70 71RETURN VALUE 72------------ 73 74These functions return 1 on success and 0 on failure. 75 76SEE ALSO 77-------- 78 79*AES_SIV_CTX_new*(3), *AES_SIV_Init*(3), RFC 5297 80