Botan  2.7.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  * 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  * See @ref set_associated_data().
69  *
70  * @param ad the associated data
71  */
72  template<typename Alloc>
73  void set_associated_data_vec(const std::vector<uint8_t, Alloc>& ad)
74  {
75  set_associated_data(ad.data(), ad.size());
76  }
77 
78  /**
79  * Set associated data that is not included in the ciphertext but
80  * that should be authenticated. Must be called after set_key and
81  * before start.
82  *
83  * See @ref set_associated_data().
84  *
85  * @param ad the associated data
86  */
87  template<typename Alloc>
88  void set_ad(const std::vector<uint8_t, Alloc>& ad)
89  {
90  set_associated_data(ad.data(), ad.size());
91  }
92 
93  /**
94  * @return default AEAD nonce size (a commonly supported value among AEAD
95  * modes, and large enough that random collisions are unlikely)
96  */
97  size_t default_nonce_length() const override { return 12; }
98 
99  virtual ~AEAD_Mode() = default;
100  };
101 
102 /**
103 * Get an AEAD mode by name (eg "AES-128/GCM" or "Serpent/EAX")
104 * @param name AEAD name
105 * @param direction ENCRYPTION or DECRYPTION
106 */
107 inline AEAD_Mode* get_aead(const std::string& name, Cipher_Dir direction)
108  {
109  return AEAD_Mode::create(name, direction, "").release();
110  }
111 
112 }
113 
114 #endif
size_t default_nonce_length() const override
Definition: aead.h:97
#define BOTAN_PUBLIC_API(maj, min)
Definition: compiler.h:27
void set_ad(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:88
bool authenticated() const override
Definition: aead.h:47
AEAD_Mode * get_aead(const std::string &name, Cipher_Dir direction)
Definition: aead.h:107
void set_associated_data_vec(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:73
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:24