/src/botan/build/include/botan/aead.h
Line | Count | Source (jump to first uncovered line) |
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 | | */ |
22 | | class BOTAN_PUBLIC_API(2,0) AEAD_Mode : public Cipher_Mode |
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 | 0 | 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 | 0 | 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 | 932 | { |
82 | 932 | set_associated_data(ad.data(), ad.size()); |
83 | 932 | } |
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 | 2.36k | { |
97 | 2.36k | set_associated_data(ad.data(), ad.size()); |
98 | 2.36k | } |
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 | 2.81k | 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 | 0 | { |
116 | 0 | return AEAD_Mode::create(name, direction, "").release(); |
117 | 0 | } |
118 | | |
119 | | } |
120 | | |
121 | | #endif |