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