Botan 3.0.0-alpha0
Crypto and TLS for C&
aead.h
Go to the documentation of this file.
1/*
2* Interface for AEAD modes
3* (C) 2013 Jack Lloyd
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_AEAD_MODE_H_
9#define BOTAN_AEAD_MODE_H_
10
11#include <botan/cipher_mode.h>
12
13namespace Botan {
14
15/**
16* Interface for AEAD (Authenticated Encryption with Associated Data)
17* modes. These modes provide both encryption and message
18* authentication, and can authenticate additional per-message data
19* which is not included in the ciphertext (for instance a sequence
20* number).
21*/
23 {
24 public:
25 /**
26 * Create an AEAD mode
27 * @param algo the algorithm to create
28 * @param direction specify if this should be an encryption or decryption AEAD
29 * @param provider optional specification for provider to use
30 * @return an AEAD mode or a null pointer if not available
31 */
32 static std::unique_ptr<AEAD_Mode> create(const std::string& algo,
33 Cipher_Dir direction,
34 const std::string& provider = "");
35
36 /**
37 * Create an AEAD mode, or throw
38 * @param algo the algorithm to create
39 * @param direction specify if this should be an encryption or decryption AEAD
40 * @param provider optional specification for provider to use
41 * @return an AEAD mode, or throw an exception
42 */
43 static std::unique_ptr<AEAD_Mode> create_or_throw(const std::string& algo,
44 Cipher_Dir direction,
45 const std::string& provider = "");
46
47 /**
48 * Set associated data that is not included in the ciphertext but
49 * that should be authenticated. Must be called after set_key and
50 * before start.
51 *
52 * Unless reset by another call, the associated data is kept
53 * between messages. Thus, if the AD does not change, calling
54 * once (after set_key) is the optimum.
55 *
56 * @param ad the associated data
57 * @param ad_len length of add in bytes
58 */
59 virtual void set_associated_data(const uint8_t ad[], size_t ad_len) = 0;
60
61 /**
62 * Set associated data that is not included in the ciphertext but
63 * that should be authenticated. Must be called after set_key and
64 * before start.
65 *
66 * Unless reset by another call, the associated data is kept
67 * between messages. Thus, if the AD does not change, calling
68 * once (after set_key) is the optimum.
69 *
70 * Some AEADs (namely SIV) support multiple AD inputs. For
71 * all other modes only nominal AD input 0 is supported; all
72 * other values of i will cause an exception.
73 *
74 * @param ad the associated data
75 * @param ad_len length of add in bytes
76 */
77 virtual void set_associated_data_n(size_t i, const uint8_t ad[], size_t ad_len);
78
79 /**
80 * Returns the maximum supported number of associated data inputs which
81 * can be provided to set_associated_data_n
82 *
83 * If returns 0, then no associated data is supported.
84 */
85 virtual size_t maximum_associated_data_inputs() const { return 1; }
86
87 /**
88 * Most AEADs require the key to be set prior to setting the AD
89 * A few allow the AD to be set even before the cipher is keyed.
90 * Such ciphers would return false from this function.
91 */
92 virtual bool associated_data_requires_key() const { return true; }
93
94 /**
95 * Set associated data that is not included in the ciphertext but
96 * that should be authenticated. Must be called after set_key and
97 * before start.
98 *
99 * See @ref set_associated_data().
100 *
101 * @param ad the associated data
102 */
103 template<typename Alloc>
104 void set_associated_data_vec(const std::vector<uint8_t, Alloc>& ad)
105 {
106 set_associated_data(ad.data(), ad.size());
107 }
108
109 /**
110 * Set associated data that is not included in the ciphertext but
111 * that should be authenticated. Must be called after set_key and
112 * before start.
113 *
114 * See @ref set_associated_data().
115 *
116 * @param ad the associated data
117 */
118 template<typename Alloc>
119 void set_ad(const std::vector<uint8_t, Alloc>& ad)
120 {
121 set_associated_data(ad.data(), ad.size());
122 }
123
124 /**
125 * @return default AEAD nonce size (a commonly supported value among AEAD
126 * modes, and large enough that random collisions are unlikely)
127 */
128 size_t default_nonce_length() const override { return 12; }
129
130 virtual ~AEAD_Mode() = default;
131 };
132
133/**
134* Get an AEAD mode by name (eg "AES-128/GCM" or "Serpent/EAX")
135* @param name AEAD name
136* @param direction ENCRYPTION or DECRYPTION
137*/
138inline AEAD_Mode* get_aead(const std::string& name, Cipher_Dir direction)
139 {
140 return AEAD_Mode::create(name, direction, "").release();
141 }
142
143}
144
145#endif
virtual void set_associated_data(const uint8_t ad[], size_t ad_len)=0
virtual ~AEAD_Mode()=default
virtual size_t maximum_associated_data_inputs() const
Definition: aead.h:85
void set_associated_data_vec(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:104
size_t default_nonce_length() const override
Definition: aead.h:128
void set_ad(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:119
virtual bool associated_data_requires_key() const
Definition: aead.h:92
static std::unique_ptr< AEAD_Mode > create(const std::string &algo, Cipher_Dir direction, const std::string &provider="")
Definition: aead.cpp:60
std::string name
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
Definition: alg_id.cpp:13
AEAD_Mode * get_aead(const std::string &name, Cipher_Dir direction)
Definition: aead.h:138
Cipher_Dir
Definition: cipher_mode.h:23