Botan  2.8.0
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  * Most AEADs require the key to be set prior to setting the AD
65  * A few allow the AD to be set even before the cipher is keyed.
66  * Such ciphers would return false from this function.
67  */
68  virtual bool associated_data_requires_key() const { return true; }
69 
70  /**
71  * Set associated data that is not included in the ciphertext but
72  * that should be authenticated. Must be called after set_key and
73  * before start.
74  *
75  * See @ref set_associated_data().
76  *
77  * @param ad the associated data
78  */
79  template<typename Alloc>
80  void set_associated_data_vec(const std::vector<uint8_t, Alloc>& ad)
81  {
82  set_associated_data(ad.data(), ad.size());
83  }
84 
85  /**
86  * Set associated data that is not included in the ciphertext but
87  * that should be authenticated. Must be called after set_key and
88  * before start.
89  *
90  * See @ref set_associated_data().
91  *
92  * @param ad the associated data
93  */
94  template<typename Alloc>
95  void set_ad(const std::vector<uint8_t, Alloc>& ad)
96  {
97  set_associated_data(ad.data(), ad.size());
98  }
99 
100  /**
101  * @return default AEAD nonce size (a commonly supported value among AEAD
102  * modes, and large enough that random collisions are unlikely)
103  */
104  size_t default_nonce_length() const override { return 12; }
105 
106  virtual ~AEAD_Mode() = default;
107  };
108 
109 /**
110 * Get an AEAD mode by name (eg "AES-128/GCM" or "Serpent/EAX")
111 * @param name AEAD name
112 * @param direction ENCRYPTION or DECRYPTION
113 */
114 inline AEAD_Mode* get_aead(const std::string& name, Cipher_Dir direction)
115  {
116  return AEAD_Mode::create(name, direction, "").release();
117  }
118 
119 }
120 
121 #endif
size_t default_nonce_length() const override
Definition: aead.h:104
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
void set_ad(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:95
virtual bool associated_data_requires_key() const
Definition: aead.h:68
bool authenticated() const override
Definition: aead.h:47
AEAD_Mode * get_aead(const std::string &name, Cipher_Dir direction)
Definition: aead.h:114
std::string name
void set_associated_data_vec(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:80
static std::unique_ptr< AEAD_Mode > create(const std::string &algo, Cipher_Dir direction, const std::string &provider="")
Definition: aead.cpp:52
Definition: alg_id.cpp:13
Cipher_Dir
Definition: cipher_mode.h:23