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