Crypto++ 8.2
Free C&
chachapoly.h
Go to the documentation of this file.
1// chachapoly.h - written and placed in the public domain by Jeffrey Walton
2// RFC 8439, Section 2.8, AEAD Construction, http://tools.ietf.org/html/rfc8439
3
4/// \file chachapoly.h
5/// \brief ChaCha20/Poly1305-TLS AEAD scheme
6/// \details ChaCha20Poly1305 is an authenticated encryption scheme that combines
7/// ChaCha20TLS and Poly1305TLS. The scheme is defined in RFC 8439, section 2.8,
8/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha
9/// and Poly1305.
10/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
11/// for IETF Protocols</A>.
12/// \since Crypto++ 8.1
13
14#ifndef CRYPTOPP_CHACHA_POLY1305_H
15#define CRYPTOPP_CHACHA_POLY1305_H
16
17#include "cryptlib.h"
18#include "authenc.h"
19#include "chacha.h"
20#include "poly1305.h"
21
22NAMESPACE_BEGIN(CryptoPP)
23
24////////////////////////////// IETF ChaChaTLS //////////////////////////////
25
26/// \brief ChaCha20Poly1305 cipher base implementation
27/// \details Base implementation of the AuthenticatedSymmetricCipher interface
28/// \since Crypto++ 8.1
30{
31public:
32 virtual ~ChaCha20Poly1305_Base() {}
33
34 virtual const MessageAuthenticationCode & GetMAC() const = 0;
35 virtual MessageAuthenticationCode & AccessMAC() = 0;
36
37public:
38 // AuthenticatedSymmetricCipher
39 std::string AlgorithmName() const
40 {return std::string("ChaCha20/Poly1305");}
41 std::string AlgorithmProvider() const
42 {return GetSymmetricCipher().AlgorithmProvider();}
43 size_t MinKeyLength() const
44 {return 32;}
45 size_t MaxKeyLength() const
46 {return 32;}
47 size_t DefaultKeyLength() const
48 {return 32;}
49 size_t GetValidKeyLength(size_t n) const
50 {CRYPTOPP_UNUSED(n); return 32;}
51 bool IsValidKeyLength(size_t n) const
52 {return n==32;}
53 unsigned int OptimalDataAlignment() const
54 {return GetSymmetricCipher().OptimalDataAlignment();}
56 {return UNIQUE_IV;}
57 unsigned int IVSize() const
58 {return 12;}
59 unsigned int MinIVLength() const
60 {return 12;}
61 unsigned int MaxIVLength() const
62 {return 12;}
63 unsigned int DigestSize() const
64 {return 16;}
65 lword MaxHeaderLength() const
66 {return LWORD_MAX;} // 2^64-1 bytes
67 lword MaxMessageLength() const
68 {return W64LIT(274877906880);} // 2^38-1 blocks
69 lword MaxFooterLength() const
70 {return 0;}
71
72 /// \brief Encrypts and calculates a MAC in one call
73 /// \param ciphertext the encryption buffer
74 /// \param mac the mac buffer
75 /// \param macSize the size of the MAC buffer, in bytes
76 /// \param iv the iv buffer
77 /// \param ivLength the size of the IV buffer, in bytes
78 /// \param aad the AAD buffer
79 /// \param aadLength the size of the AAD buffer, in bytes
80 /// \param message the message buffer
81 /// \param messageLength the size of the messagetext buffer, in bytes
82 /// \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function
83 /// truncates the MAC if <tt>macSize < TagSize()</tt>.
84 virtual void EncryptAndAuthenticate(byte *ciphertext, byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *aad, size_t aadLength, const byte *message, size_t messageLength);
85
86 /// \brief Decrypts and verifies a MAC in one call
87 /// \param message the decryption buffer
88 /// \param mac the mac buffer
89 /// \param macSize the size of the MAC buffer, in bytes
90 /// \param iv the iv buffer
91 /// \param ivLength the size of the IV buffer, in bytes
92 /// \param aad the AAD buffer
93 /// \param aadLength the size of the AAD buffer, in bytes
94 /// \param ciphertext the cipher buffer
95 /// \param ciphertextLength the size of the ciphertext buffer, in bytes
96 /// \return true if the MAC is valid and the decoding succeeded, false otherwise
97 /// \details DecryptAndVerify() decrypts and verifies the MAC in one call.
98 /// <tt>message</tt> is a decryption buffer and should be at least as large as the ciphertext buffer.
99 /// \details The function returns true iff MAC is valid. DecryptAndVerify() assumes the MAC
100 /// is truncated if <tt>macLength < TagSize()</tt>.
101 virtual bool DecryptAndVerify(byte *message, const byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *aad, size_t aadLength, const byte *ciphertext, size_t ciphertextLength);
102
103protected:
104 // AuthenticatedSymmetricCipherBase
105 bool AuthenticationIsOnPlaintext() const {return false;}
106 unsigned int AuthenticationBlockSize() const {return 1;}
107 void SetKeyWithoutResync(const byte *userKey, size_t keylength, const NameValuePairs &params);
108 void Resync(const byte *iv, size_t len);
109 size_t AuthenticateBlocks(const byte *data, size_t len);
110 void AuthenticateLastHeaderBlock();
111 void AuthenticateLastConfidentialBlock();
112 void AuthenticateLastFooterBlock(byte *mac, size_t macSize);
113
114protected:
115 // See comments in chachapoly.cpp
116 void RekeyCipherAndMac(const byte *userKey, size_t userKeyLength, const NameValuePairs &params);
117
118 SecByteBlock m_userKey;
119};
120
121/// \brief ChaCha20Poly1305 cipher final implementation
122/// \tparam T_IsEncryption flag indicating cipher direction
123/// \details ChaCha20Poly1305 is an authenticated encryption scheme that combines
124/// ChaCha20TLS and Poly1305TLS. The scheme is defined in RFC 8439, section 2.8,
125/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha
126/// and Poly1305.
127/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
128/// for IETF Protocols</A>.
129/// \since Crypto++ 8.1
130template <bool T_IsEncryption>
132{
133public:
134 static std::string StaticAlgorithmName()
135 {return std::string("ChaCha20/Poly1305");}
136
137protected:
138 const SymmetricCipher & GetSymmetricCipher()
139 {return const_cast<ChaCha20Poly1305_Final *>(this)->AccessSymmetricCipher();}
140 SymmetricCipher & AccessSymmetricCipher()
141 {return m_cipher;}
142 bool IsForwardTransformation() const
143 {return T_IsEncryption;}
144
145 const MessageAuthenticationCode & GetMAC() const
146 {return const_cast<ChaCha20Poly1305_Final *>(this)->AccessMAC();}
147 MessageAuthenticationCode & AccessMAC()
148 {return m_mac;}
149
150private:
151 ChaChaTLS::Encryption m_cipher;
152 Poly1305TLS m_mac;
153};
154
155/// \brief ChaCha20/Poly1305-TLS AEAD scheme
156/// \details ChaCha20Poly1305 is an authenticated encryption scheme that combines
157/// ChaCha20TLS and Poly1305TLS. The scheme is defined in RFC 8439, section 2.8,
158/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha
159/// and Poly1305.
160/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
161/// for IETF Protocols</A>.
162/// \since Crypto++ 8.1
164{
165 /// \brief ChaCha20Poly1305 encryption
167 /// \brief ChaCha20Poly1305 decryption
169};
170
171////////////////////////////// IETF XChaCha20 draft //////////////////////////////
172
173/// \brief XChaCha20Poly1305 cipher base implementation
174/// \details Base implementation of the AuthenticatedSymmetricCipher interface
175/// \since Crypto++ 8.1
177{
178public:
179 virtual ~XChaCha20Poly1305_Base() {}
180
181 virtual const MessageAuthenticationCode & GetMAC() const = 0;
182 virtual MessageAuthenticationCode & AccessMAC() = 0;
183
184public:
185 // AuthenticatedSymmetricCipher
186 std::string AlgorithmName() const
187 {return std::string("XChaCha20/Poly1305");}
188 std::string AlgorithmProvider() const
189 {return GetSymmetricCipher().AlgorithmProvider();}
190 size_t MinKeyLength() const
191 {return 32;}
192 size_t MaxKeyLength() const
193 {return 32;}
194 size_t DefaultKeyLength() const
195 {return 32;}
196 size_t GetValidKeyLength(size_t n) const
197 {CRYPTOPP_UNUSED(n); return 32;}
198 bool IsValidKeyLength(size_t n) const
199 {return n==32;}
200 unsigned int OptimalDataAlignment() const
201 {return GetSymmetricCipher().OptimalDataAlignment();}
203 {return UNIQUE_IV;}
204 unsigned int IVSize() const
205 {return 24;}
206 unsigned int MinIVLength() const
207 {return 24;}
208 unsigned int MaxIVLength() const
209 {return 24;}
210 unsigned int DigestSize() const
211 {return 16;}
212 lword MaxHeaderLength() const
213 {return LWORD_MAX;} // 2^64-1 bytes
214 lword MaxMessageLength() const
215 {return W64LIT(274877906880);} // 2^38-1 blocks
216 lword MaxFooterLength() const
217 {return 0;}
218
219 /// \brief Encrypts and calculates a MAC in one call
220 /// \param ciphertext the encryption buffer
221 /// \param mac the mac buffer
222 /// \param macSize the size of the MAC buffer, in bytes
223 /// \param iv the iv buffer
224 /// \param ivLength the size of the IV buffer, in bytes
225 /// \param aad the AAD buffer
226 /// \param aadLength the size of the AAD buffer, in bytes
227 /// \param message the message buffer
228 /// \param messageLength the size of the messagetext buffer, in bytes
229 /// \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function
230 /// truncates the MAC if <tt>macSize < TagSize()</tt>.
231 virtual void EncryptAndAuthenticate(byte *ciphertext, byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *aad, size_t aadLength, const byte *message, size_t messageLength);
232
233 /// \brief Decrypts and verifies a MAC in one call
234 /// \param message the decryption buffer
235 /// \param mac the mac buffer
236 /// \param macSize the size of the MAC buffer, in bytes
237 /// \param iv the iv buffer
238 /// \param ivLength the size of the IV buffer, in bytes
239 /// \param aad the AAD buffer
240 /// \param aadLength the size of the AAD buffer, in bytes
241 /// \param ciphertext the cipher buffer
242 /// \param ciphertextLength the size of the ciphertext buffer, in bytes
243 /// \return true if the MAC is valid and the decoding succeeded, false otherwise
244 /// \details DecryptAndVerify() decrypts and verifies the MAC in one call.
245 /// <tt>message</tt> is a decryption buffer and should be at least as large as the ciphertext buffer.
246 /// \details The function returns true iff MAC is valid. DecryptAndVerify() assumes the MAC
247 /// is truncated if <tt>macLength < TagSize()</tt>.
248 virtual bool DecryptAndVerify(byte *message, const byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *aad, size_t aadLength, const byte *ciphertext, size_t ciphertextLength);
249
250protected:
251 // AuthenticatedSymmetricCipherBase
252 bool AuthenticationIsOnPlaintext() const {return false;}
253 unsigned int AuthenticationBlockSize() const {return 1;}
254 void SetKeyWithoutResync(const byte *userKey, size_t keylength, const NameValuePairs &params);
255 void Resync(const byte *iv, size_t len);
256 size_t AuthenticateBlocks(const byte *data, size_t len);
257 void AuthenticateLastHeaderBlock();
258 void AuthenticateLastConfidentialBlock();
259 void AuthenticateLastFooterBlock(byte *mac, size_t macSize);
260
261protected:
262 // See comments in chachapoly.cpp
263 void RekeyCipherAndMac(const byte *userKey, size_t userKeyLength, const NameValuePairs &params);
264
265 SecByteBlock m_userKey;
266};
267
268/// \brief XChaCha20Poly1305 cipher final implementation
269/// \tparam T_IsEncryption flag indicating cipher direction
270/// \details XChaCha20Poly1305 is an authenticated encryption scheme that combines
271/// XChaCha20 and Poly1305-TLS. The scheme is defined in RFC 8439, section 2.8,
272/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha
273/// and Poly1305.
274/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
275/// for IETF Protocols</A>.
276/// \since Crypto++ 8.1
277template <bool T_IsEncryption>
279{
280public:
281 static std::string StaticAlgorithmName()
282 {return std::string("XChaCha20/Poly1305");}
283
284protected:
285 const SymmetricCipher & GetSymmetricCipher()
286 {return const_cast<XChaCha20Poly1305_Final *>(this)->AccessSymmetricCipher();}
287 SymmetricCipher & AccessSymmetricCipher()
288 {return m_cipher;}
289 bool IsForwardTransformation() const
290 {return T_IsEncryption;}
291
292 const MessageAuthenticationCode & GetMAC() const
293 {return const_cast<XChaCha20Poly1305_Final *>(this)->AccessMAC();}
294 MessageAuthenticationCode & AccessMAC()
295 {return m_mac;}
296
297private:
298 XChaCha20::Encryption m_cipher;
299 Poly1305TLS m_mac;
300};
301
302/// \brief XChaCha20/Poly1305-TLS AEAD scheme
303/// \details XChaCha20Poly1305 is an authenticated encryption scheme that combines
304/// XChaCha20 and Poly1305-TLS. The scheme is defined in RFC 8439, section 2.8,
305/// AEAD_XCHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha
306/// and Poly1305.
307/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
308/// for IETF Protocols</A>.
309/// \since Crypto++ 8.1
311{
312 /// \brief XChaCha20Poly1305 encryption
314 /// \brief XChaCha20Poly1305 decryption
316};
317
318NAMESPACE_END
319
320#endif // CRYPTOPP_CHACHA_POLY1305_H
Classes for authenticated encryption modes of operation.
Classes for ChaCha8, ChaCha12 and ChaCha20 stream ciphers.
Base class for authenticated encryption modes of operation.
Definition: authenc.h:41
ChaCha20Poly1305 cipher base implementation.
Definition: chachapoly.h:30
unsigned int MinIVLength() const
Provides the minimum size of an IV.
Definition: chachapoly.h:59
size_t MinKeyLength() const
Returns smallest valid key length.
Definition: chachapoly.h:43
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition: chachapoly.h:41
size_t GetValidKeyLength(size_t n) const
Returns a valid key length for the algorithm.
Definition: chachapoly.h:49
unsigned int MaxIVLength() const
Provides the maximum size of an IV.
Definition: chachapoly.h:61
lword MaxMessageLength() const
Provides the maximum length of encrypted data.
Definition: chachapoly.h:67
bool IsValidKeyLength(size_t n) const
Returns whether keylength is a valid key length.
Definition: chachapoly.h:51
size_t MaxKeyLength() const
Returns largest valid key length.
Definition: chachapoly.h:45
lword MaxHeaderLength() const
Provides the maximum length of AAD that can be input.
Definition: chachapoly.h:65
IV_Requirement IVRequirement() const
Minimal requirement for secure IVs.
Definition: chachapoly.h:55
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition: chachapoly.h:39
unsigned int IVSize() const
Returns length of the IV accepted by this object.
Definition: chachapoly.h:57
size_t DefaultKeyLength() const
Returns default key length.
Definition: chachapoly.h:47
unsigned int DigestSize() const
Provides the digest size of the hash.
Definition: chachapoly.h:63
unsigned int OptimalDataAlignment() const
Provides input and output data alignment for optimal performance.
Definition: chachapoly.h:53
lword MaxFooterLength() const
Provides the the maximum length of AAD.
Definition: chachapoly.h:69
ChaCha20Poly1305 cipher final implementation.
Definition: chachapoly.h:132
Interface for message authentication codes.
Definition: cryptlib.h:1267
Interface for retrieving values given their names.
Definition: cryptlib.h:294
Poly1305-TLS message authentication code.
Definition: poly1305.h:237
SecBlock<byte> typedef.
Definition: secblock.h:1058
IV_Requirement
Secure IVs requirements as enumerated values.
Definition: cryptlib.h:691
@ UNIQUE_IV
The IV must be unique.
Definition: cryptlib.h:693
Interface for one direction (encryption or decryption) of a stream cipher or cipher mode.
Definition: cryptlib.h:1259
XChaCha20Poly1305 cipher base implementation.
Definition: chachapoly.h:177
unsigned int DigestSize() const
Provides the digest size of the hash.
Definition: chachapoly.h:210
unsigned int MaxIVLength() const
Provides the maximum size of an IV.
Definition: chachapoly.h:208
lword MaxMessageLength() const
Provides the maximum length of encrypted data.
Definition: chachapoly.h:214
size_t DefaultKeyLength() const
Returns default key length.
Definition: chachapoly.h:194
virtual void EncryptAndAuthenticate(byte *ciphertext, byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *aad, size_t aadLength, const byte *message, size_t messageLength)
Encrypts and calculates a MAC in one call.
Definition: chachapoly.cpp:191
bool IsValidKeyLength(size_t n) const
Returns whether keylength is a valid key length.
Definition: chachapoly.h:198
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition: chachapoly.h:186
unsigned int IVSize() const
Returns length of the IV accepted by this object.
Definition: chachapoly.h:204
size_t GetValidKeyLength(size_t n) const
Returns a valid key length for the algorithm.
Definition: chachapoly.h:196
virtual bool DecryptAndVerify(byte *message, const byte *mac, size_t macSize, const byte *iv, int ivLength, const byte *aad, size_t aadLength, const byte *ciphertext, size_t ciphertextLength)
Decrypts and verifies a MAC in one call.
Definition: chachapoly.cpp:199
lword MaxHeaderLength() const
Provides the maximum length of AAD that can be input.
Definition: chachapoly.h:212
size_t MinKeyLength() const
Returns smallest valid key length.
Definition: chachapoly.h:190
lword MaxFooterLength() const
Provides the the maximum length of AAD.
Definition: chachapoly.h:216
IV_Requirement IVRequirement() const
Minimal requirement for secure IVs.
Definition: chachapoly.h:202
unsigned int OptimalDataAlignment() const
Provides input and output data alignment for optimal performance.
Definition: chachapoly.h:200
unsigned int MinIVLength() const
Provides the minimum size of an IV.
Definition: chachapoly.h:206
size_t MaxKeyLength() const
Returns largest valid key length.
Definition: chachapoly.h:192
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition: chachapoly.h:188
XChaCha20Poly1305 cipher final implementation.
Definition: chachapoly.h:279
Abstract base classes that provide a uniform interface to this library.
Crypto++ library namespace.
Classes for Poly1305 message authentication code.
Provides Encryption and Decryption typedefs used by derived classes to implement an authenticated enc...
Definition: seckey.h:426
ChaCha20/Poly1305-TLS AEAD scheme.
Definition: chachapoly.h:164
ChaCha20Poly1305_Final< false > Decryption
ChaCha20Poly1305 decryption.
Definition: chachapoly.h:168
ChaCha20Poly1305_Final< true > Encryption
ChaCha20Poly1305 encryption.
Definition: chachapoly.h:166
XChaCha20/Poly1305-TLS AEAD scheme.
Definition: chachapoly.h:311
XChaCha20Poly1305_Final< false > Decryption
XChaCha20Poly1305 decryption.
Definition: chachapoly.h:315
XChaCha20Poly1305_Final< true > Encryption
XChaCha20Poly1305 encryption.
Definition: chachapoly.h:313