Botan  2.19.1
Crypto and TLS for C++11
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 
13 namespace 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  bool authenticated() const override { return true; }
48 
49  /**
50  * Set associated data that is not included in the ciphertext but
51  * that should be authenticated. Must be called after set_key and
52  * before start.
53  *
54  * Unless reset by another call, the associated data is kept
55  * between messages. Thus, if the AD does not change, calling
56  * once (after set_key) is the optimum.
57  *
58  * @param ad the associated data
59  * @param ad_len length of add in bytes
60  */
61  virtual void set_associated_data(const uint8_t ad[], size_t ad_len) = 0;
62 
63  /**
64  * Set associated data that is not included in the ciphertext but
65  * that should be authenticated. Must be called after set_key and
66  * before start.
67  *
68  * Unless reset by another call, the associated data is kept
69  * between messages. Thus, if the AD does not change, calling
70  * once (after set_key) is the optimum.
71  *
72  * Some AEADs (namely SIV) support multiple AD inputs. For
73  * all other modes only nominal AD input 0 is supported; all
74  * other values of i will cause an exception.
75  *
76  * @param ad the associated data
77  * @param ad_len length of add in bytes
78  */
79  virtual void set_associated_data_n(size_t i, const uint8_t ad[], size_t ad_len);
80 
81  /**
82  * Returns the maximum supported number of associated data inputs which
83  * can be provided to set_associated_data_n
84  *
85  * If returns 0, then no associated data is supported.
86  */
87  virtual size_t maximum_associated_data_inputs() const { return 1; }
88 
89  /**
90  * Most AEADs require the key to be set prior to setting the AD
91  * A few allow the AD to be set even before the cipher is keyed.
92  * Such ciphers would return false from this function.
93  */
94  virtual bool associated_data_requires_key() const { return true; }
95 
96  /**
97  * Set associated data that is not included in the ciphertext but
98  * that should be authenticated. Must be called after set_key and
99  * before start.
100  *
101  * See @ref set_associated_data().
102  *
103  * @param ad the associated data
104  */
105  template<typename Alloc>
106  void set_associated_data_vec(const std::vector<uint8_t, Alloc>& ad)
107  {
108  set_associated_data(ad.data(), ad.size());
109  }
110 
111  /**
112  * Set associated data that is not included in the ciphertext but
113  * that should be authenticated. Must be called after set_key and
114  * before start.
115  *
116  * See @ref set_associated_data().
117  *
118  * @param ad the associated data
119  */
120  template<typename Alloc>
121  void set_ad(const std::vector<uint8_t, Alloc>& ad)
122  {
123  set_associated_data(ad.data(), ad.size());
124  }
125 
126  /**
127  * @return default AEAD nonce size (a commonly supported value among AEAD
128  * modes, and large enough that random collisions are unlikely)
129  */
130  size_t default_nonce_length() const override { return 12; }
131 
132  virtual ~AEAD_Mode() = default;
133  };
134 
135 /**
136 * Get an AEAD mode by name (eg "AES-128/GCM" or "Serpent/EAX")
137 * @param name AEAD name
138 * @param direction ENCRYPTION or DECRYPTION
139 */
140 inline AEAD_Mode* get_aead(const std::string& name, Cipher_Dir direction)
141  {
142  return AEAD_Mode::create(name, direction, "").release();
143  }
144 
145 }
146 
147 #endif
virtual size_t maximum_associated_data_inputs() const
Definition: aead.h:87
size_t default_nonce_length() const override
Definition: aead.h:130
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:31
void set_ad(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:121
bool authenticated() const override
Definition: aead.h:47
AEAD_Mode * get_aead(const std::string &name, Cipher_Dir direction)
Definition: aead.h:140
std::string name
void set_associated_data_vec(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:106
static std::unique_ptr< AEAD_Mode > create(const std::string &algo, Cipher_Dir direction, const std::string &provider="")
Definition: aead.cpp:60
Definition: alg_id.cpp:13
Cipher_Dir
Definition: cipher_mode.h:23
virtual bool associated_data_requires_key() const
Definition: aead.h:94