Coverage Report

Created: 2021-05-04 09:02

/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
      * 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
0
      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
0
      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
604
         {
108
604
         set_associated_data(ad.data(), ad.size());
109
604
         }
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
871
         {
123
871
         set_associated_data(ad.data(), ad.size());
124
871
         }
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
0
      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
0
   {
142
0
   return AEAD_Mode::create(name, direction, "").release();
143
0
   }
144
145
}
146
147
#endif