Botan 2.19.1
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 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*/
140inline 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 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:87
void set_associated_data_vec(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:106
size_t default_nonce_length() const override
Definition: aead.h:130
void set_ad(const std::vector< uint8_t, Alloc > &ad)
Definition: aead.h:121
bool authenticated() const override
Definition: aead.h:47
virtual bool associated_data_requires_key() const
Definition: aead.h:94
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:140
Cipher_Dir
Definition: cipher_mode.h:23