chachapoly.h
Go to the documentation of this file.
// chachapoly.h - written and placed in the public domain by Jeffrey Walton
// RFC 8439, Section 2.8, AEAD Construction, http://tools.ietf.org/html/rfc8439
/// \file chachapoly.h
/// \brief IETF ChaCha20/Poly1305 AEAD scheme
/// \details ChaCha20Poly1305 is an authenticated encryption scheme that combines
/// ChaCha20TLS and Poly1305TLS. The scheme is defined in RFC 8439, section 2.8,
/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha20
/// and Poly1305.
/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
/// for IETF Protocols</A>.
/// \since Crypto++ 8.1
#ifndef CRYPTOPP_CHACHA_POLY1305_H
#define CRYPTOPP_CHACHA_POLY1305_H
#include "cryptlib.h"
#include "authenc.h"
#include "chacha.h"
#include "poly1305.h"
NAMESPACE_BEGIN(CryptoPP)
////////////////////////////// IETF ChaChaTLS //////////////////////////////
/// \brief IETF ChaCha20Poly1305 cipher base implementation
/// \details Base implementation of the AuthenticatedSymmetricCipher interface
/// \since Crypto++ 8.1
class ChaCha20Poly1305_Base : public AuthenticatedSymmetricCipherBase
{
public:
CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName()
{return "ChaCha20/Poly1305";}
virtual ~ChaCha20Poly1305_Base() {}
// AuthenticatedSymmetricCipher
std::string AlgorithmName() const
{return std::string("ChaCha20/Poly1305");}
std::string AlgorithmProvider() const
{return GetSymmetricCipher().AlgorithmProvider();}
size_t MinKeyLength() const
{return 32;}
size_t MaxKeyLength() const
{return 32;}
size_t DefaultKeyLength() const
{return 32;}
size_t GetValidKeyLength(size_t n) const
{CRYPTOPP_UNUSED(n); return 32;}
bool IsValidKeyLength(size_t n) const
{return n==32;}
unsigned int OptimalDataAlignment() const
{return GetSymmetricCipher().OptimalDataAlignment();}
IV_Requirement IVRequirement() const
{return UNIQUE_IV;}
unsigned int IVSize() const
{return 12;}
unsigned int MinIVLength() const
{return 12;}
unsigned int MaxIVLength() const
{return 12;}
unsigned int DigestSize() const
{return 16;}
lword MaxHeaderLength() const
{return LWORD_MAX;} // 2^64-1 bytes
lword MaxMessageLength() const
{return W64LIT(274877906880);} // 2^38-1 blocks
lword MaxFooterLength() const
{return 0;}
/// \brief Encrypts and calculates a MAC in one call
/// \param ciphertext the encryption buffer
/// \param mac the mac buffer
/// \param macSize the size of the MAC buffer, in bytes
/// \param iv the iv buffer
/// \param ivLength the size of the IV buffer, in bytes
/// \param aad the AAD buffer
/// \param aadLength the size of the AAD buffer, in bytes
/// \param message the message buffer
/// \param messageLength the size of the messagetext buffer, in bytes
/// \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function
/// truncates the MAC if <tt>macSize < TagSize()</tt>.
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);
/// \brief Decrypts and verifies a MAC in one call
/// \param message the decryption buffer
/// \param mac the mac buffer
/// \param macSize the size of the MAC buffer, in bytes
/// \param iv the iv buffer
/// \param ivLength the size of the IV buffer, in bytes
/// \param aad the AAD buffer
/// \param aadLength the size of the AAD buffer, in bytes
/// \param ciphertext the cipher buffer
/// \param ciphertextLength the size of the ciphertext buffer, in bytes
/// \return true if the MAC is valid and the decoding succeeded, false otherwise
/// \details DecryptAndVerify() decrypts and verifies the MAC in one call.
/// <tt>message</tt> is a decryption buffer and should be at least as large as the ciphertext buffer.
/// \details The function returns true iff MAC is valid. DecryptAndVerify() assumes the MAC
/// is truncated if <tt>macLength < TagSize()</tt>.
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);
protected:
// AuthenticatedSymmetricCipherBase
bool AuthenticationIsOnPlaintext() const {return false;}
unsigned int AuthenticationBlockSize() const {return 1;}
void SetKeyWithoutResync(const byte *userKey, size_t keylength, const NameValuePairs &params);
void Resync(const byte *iv, size_t len);
size_t AuthenticateBlocks(const byte *data, size_t len);
void AuthenticateLastHeaderBlock();
void AuthenticateLastConfidentialBlock();
void AuthenticateLastFooterBlock(byte *mac, size_t macSize);
// See comments in chachapoly.cpp
void RekeyCipherAndMac(const byte *userKey, size_t userKeyLength, const NameValuePairs &params);
virtual const MessageAuthenticationCode & GetMAC() const = 0;
virtual MessageAuthenticationCode & AccessMAC() = 0;
private:
SecByteBlock m_userKey;
};
/// \brief IETF ChaCha20Poly1305 cipher final implementation
/// \tparam T_IsEncryption flag indicating cipher direction
/// \details ChaCha20Poly1305 is an authenticated encryption scheme that combines
/// ChaCha20TLS and Poly1305TLS. The scheme is defined in RFC 8439, section 2.8,
/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha20
/// and Poly1305.
/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
/// for IETF Protocols</A>.
/// \since Crypto++ 8.1
template <bool T_IsEncryption>
class ChaCha20Poly1305_Final : public ChaCha20Poly1305_Base
{
public:
virtual ~ChaCha20Poly1305_Final() {}
protected:
const SymmetricCipher & GetSymmetricCipher()
{return const_cast<ChaCha20Poly1305_Final *>(this)->AccessSymmetricCipher();}
SymmetricCipher & AccessSymmetricCipher()
{return m_cipher;}
bool IsForwardTransformation() const
{return T_IsEncryption;}
const MessageAuthenticationCode & GetMAC() const
{return const_cast<ChaCha20Poly1305_Final *>(this)->AccessMAC();}
MessageAuthenticationCode & AccessMAC()
{return m_mac;}
private:
ChaChaTLS::Encryption m_cipher;
Poly1305TLS m_mac;
};
/// \brief IETF ChaCha20/Poly1305 AEAD scheme
/// \details ChaCha20Poly1305 is an authenticated encryption scheme that combines
/// ChaCha20TLS and Poly1305TLS. The scheme is defined in RFC 8439, section 2.8,
/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha20
/// and Poly1305.
/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
/// for IETF Protocols</A>.
/// \since Crypto++ 8.1
struct ChaCha20Poly1305 : public AuthenticatedSymmetricCipherDocumentation
{
/// \brief ChaCha20Poly1305 encryption
typedef ChaCha20Poly1305_Final<true> Encryption;
/// \brief ChaCha20Poly1305 decryption
typedef ChaCha20Poly1305_Final<false> Decryption;
};
////////////////////////////// IETF XChaCha20 draft //////////////////////////////
/// \brief IETF XChaCha20Poly1305 cipher base implementation
/// \details Base implementation of the AuthenticatedSymmetricCipher interface
/// \since Crypto++ 8.1
class XChaCha20Poly1305_Base : public AuthenticatedSymmetricCipherBase
{
public:
CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName()
{return "XChaCha20/Poly1305";}
virtual ~XChaCha20Poly1305_Base() {}
// AuthenticatedSymmetricCipher
std::string AlgorithmName() const
{return std::string("XChaCha20/Poly1305");}
std::string AlgorithmProvider() const
{return GetSymmetricCipher().AlgorithmProvider();}
size_t MinKeyLength() const
{return 32;}
size_t MaxKeyLength() const
{return 32;}
size_t DefaultKeyLength() const
{return 32;}
size_t GetValidKeyLength(size_t n) const
{CRYPTOPP_UNUSED(n); return 32;}
bool IsValidKeyLength(size_t n) const
{return n==32;}
unsigned int OptimalDataAlignment() const
{return GetSymmetricCipher().OptimalDataAlignment();}
IV_Requirement IVRequirement() const
{return UNIQUE_IV;}
unsigned int IVSize() const
{return 24;}
unsigned int MinIVLength() const
{return 24;}
unsigned int MaxIVLength() const
{return 24;}
unsigned int DigestSize() const
{return 16;}
lword MaxHeaderLength() const
{return LWORD_MAX;} // 2^64-1 bytes
lword MaxMessageLength() const
{return W64LIT(274877906880);} // 2^38-1 blocks
lword MaxFooterLength() const
{return 0;}
/// \brief Encrypts and calculates a MAC in one call
/// \param ciphertext the encryption buffer
/// \param mac the mac buffer
/// \param macSize the size of the MAC buffer, in bytes
/// \param iv the iv buffer
/// \param ivLength the size of the IV buffer, in bytes
/// \param aad the AAD buffer
/// \param aadLength the size of the AAD buffer, in bytes
/// \param message the message buffer
/// \param messageLength the size of the messagetext buffer, in bytes
/// \details EncryptAndAuthenticate() encrypts and generates the MAC in one call. The function
/// truncates the MAC if <tt>macSize < TagSize()</tt>.
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);
/// \brief Decrypts and verifies a MAC in one call
/// \param message the decryption buffer
/// \param mac the mac buffer
/// \param macSize the size of the MAC buffer, in bytes
/// \param iv the iv buffer
/// \param ivLength the size of the IV buffer, in bytes
/// \param aad the AAD buffer
/// \param aadLength the size of the AAD buffer, in bytes
/// \param ciphertext the cipher buffer
/// \param ciphertextLength the size of the ciphertext buffer, in bytes
/// \return true if the MAC is valid and the decoding succeeded, false otherwise
/// \details DecryptAndVerify() decrypts and verifies the MAC in one call.
/// <tt>message</tt> is a decryption buffer and should be at least as large as the ciphertext buffer.
/// \details The function returns true iff MAC is valid. DecryptAndVerify() assumes the MAC
/// is truncated if <tt>macLength < TagSize()</tt>.
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);
protected:
// AuthenticatedSymmetricCipherBase
bool AuthenticationIsOnPlaintext() const {return false;}
unsigned int AuthenticationBlockSize() const {return 1;}
void SetKeyWithoutResync(const byte *userKey, size_t keylength, const NameValuePairs &params);
void Resync(const byte *iv, size_t len);
size_t AuthenticateBlocks(const byte *data, size_t len);
void AuthenticateLastHeaderBlock();
void AuthenticateLastConfidentialBlock();
void AuthenticateLastFooterBlock(byte *mac, size_t macSize);
// See comments in chachapoly.cpp
void RekeyCipherAndMac(const byte *userKey, size_t userKeyLength, const NameValuePairs &params);
virtual const MessageAuthenticationCode & GetMAC() const = 0;
virtual MessageAuthenticationCode & AccessMAC() = 0;
private:
SecByteBlock m_userKey;
};
/// \brief IETF XChaCha20Poly1305 cipher final implementation
/// \tparam T_IsEncryption flag indicating cipher direction
/// \details XChaCha20Poly1305 is an authenticated encryption scheme that combines
/// XChaCha20 and Poly1305-TLS. The scheme is defined in RFC 8439, section 2.8,
/// AEAD_CHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha20
/// and Poly1305.
/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
/// for IETF Protocols</A>.
/// \since Crypto++ 8.1
template <bool T_IsEncryption>
class XChaCha20Poly1305_Final : public XChaCha20Poly1305_Base
{
public:
virtual ~XChaCha20Poly1305_Final() {}
protected:
const SymmetricCipher & GetSymmetricCipher()
{return const_cast<XChaCha20Poly1305_Final *>(this)->AccessSymmetricCipher();}
SymmetricCipher & AccessSymmetricCipher()
{return m_cipher;}
bool IsForwardTransformation() const
{return T_IsEncryption;}
const MessageAuthenticationCode & GetMAC() const
{return const_cast<XChaCha20Poly1305_Final *>(this)->AccessMAC();}
MessageAuthenticationCode & AccessMAC()
{return m_mac;}
private:
XChaCha20::Encryption m_cipher;
Poly1305TLS m_mac;
};
/// \brief IETF XChaCha20/Poly1305 AEAD scheme
/// \details XChaCha20Poly1305 is an authenticated encryption scheme that combines
/// XChaCha20 and Poly1305-TLS. The scheme is defined in RFC 8439, section 2.8,
/// AEAD_XCHACHA20_POLY1305 construction, and uses the IETF versions of ChaCha20
/// and Poly1305.
/// \sa <A HREF="http://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and Poly1305
/// for IETF Protocols</A>.
/// \since Crypto++ 8.1
struct XChaCha20Poly1305 : public AuthenticatedSymmetricCipherDocumentation
{
/// \brief XChaCha20Poly1305 encryption
typedef XChaCha20Poly1305_Final<true> Encryption;
/// \brief XChaCha20Poly1305 decryption
typedef XChaCha20Poly1305_Final<false> Decryption;
};
NAMESPACE_END
#endif // CRYPTOPP_CHACHA_POLY1305_H
authenc.h
Classes for authenticated encryption modes of operation.
chacha.h
Classes for ChaCha8, ChaCha12 and ChaCha20 stream ciphers.
AuthenticatedSymmetricCipherBase
Base class for authenticated encryption modes of operation.
Definition authenc.h:41
ChaCha20Poly1305_Base
IETF ChaCha20Poly1305 cipher base implementation.
Definition chachapoly.h:30
ChaCha20Poly1305_Base::MinIVLength
unsigned int MinIVLength() const
Provides the minimum size of an IV.
Definition chachapoly.h:58
ChaCha20Poly1305_Base::MinKeyLength
size_t MinKeyLength() const
Returns smallest valid key length.
Definition chachapoly.h:42
ChaCha20Poly1305_Base::AlgorithmProvider
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition chachapoly.h:40
ChaCha20Poly1305_Base::GetValidKeyLength
size_t GetValidKeyLength(size_t n) const
Returns a valid key length for the algorithm.
Definition chachapoly.h:48
ChaCha20Poly1305_Base::MaxIVLength
unsigned int MaxIVLength() const
Provides the maximum size of an IV.
Definition chachapoly.h:60
ChaCha20Poly1305_Base::MaxMessageLength
lword MaxMessageLength() const
Provides the maximum length of encrypted data.
Definition chachapoly.h:66
ChaCha20Poly1305_Base::IsValidKeyLength
bool IsValidKeyLength(size_t n) const
Returns whether keylength is a valid key length.
Definition chachapoly.h:50
ChaCha20Poly1305_Base::MaxKeyLength
size_t MaxKeyLength() const
Returns largest valid key length.
Definition chachapoly.h:44
ChaCha20Poly1305_Base::MaxHeaderLength
lword MaxHeaderLength() const
Provides the maximum length of AAD that can be input.
Definition chachapoly.h:64
ChaCha20Poly1305_Base::IVRequirement
IV_Requirement IVRequirement() const
Minimal requirement for secure IVs.
Definition chachapoly.h:54
ChaCha20Poly1305_Base::AlgorithmName
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition chachapoly.h:38
ChaCha20Poly1305_Base::IVSize
unsigned int IVSize() const
Returns length of the IV accepted by this object.
Definition chachapoly.h:56
ChaCha20Poly1305_Base::DefaultKeyLength
size_t DefaultKeyLength() const
Returns default key length.
Definition chachapoly.h:46
ChaCha20Poly1305_Base::DigestSize
unsigned int DigestSize() const
Provides the digest size of the hash.
Definition chachapoly.h:62
ChaCha20Poly1305_Base::OptimalDataAlignment
unsigned int OptimalDataAlignment() const
Provides input and output data alignment for optimal performance.
Definition chachapoly.h:52
ChaCha20Poly1305_Base::MaxFooterLength
lword MaxFooterLength() const
Provides the maximum length of AAD.
Definition chachapoly.h:68
ChaCha20Poly1305_Final
IETF ChaCha20Poly1305 cipher final implementation.
Definition chachapoly.h:134
MessageAuthenticationCode
Interface for message authentication codes.
Definition cryptlib.h:1304
NameValuePairs
Interface for retrieving values given their names.
Definition cryptlib.h:327
Poly1305TLS
Poly1305-TLS message authentication code.
Definition poly1305.h:237
SecByteBlock
SecBlock<byte> typedef.
Definition secblock.h:1226
SimpleKeyingInterface::IV_Requirement
IV_Requirement
Secure IVs requirements as enumerated values.
Definition cryptlib.h:724
SimpleKeyingInterface::UNIQUE_IV
@ UNIQUE_IV
The IV must be unique.
Definition cryptlib.h:726
SymmetricCipherFinal< ConcretePolicyHolder< ChaChaTLS_Policy, AdditiveCipherTemplate<> >, ChaChaTLS_Info >
SymmetricCipher
Interface for one direction (encryption or decryption) of a stream cipher or cipher mode.
Definition cryptlib.h:1296
XChaCha20Poly1305_Base
IETF XChaCha20Poly1305 cipher base implementation.
Definition chachapoly.h:178
XChaCha20Poly1305_Base::DigestSize
unsigned int DigestSize() const
Provides the digest size of the hash.
Definition chachapoly.h:210
XChaCha20Poly1305_Base::MaxIVLength
unsigned int MaxIVLength() const
Provides the maximum size of an IV.
Definition chachapoly.h:208
XChaCha20Poly1305_Base::MaxMessageLength
lword MaxMessageLength() const
Provides the maximum length of encrypted data.
Definition chachapoly.h:214
XChaCha20Poly1305_Base::DefaultKeyLength
size_t DefaultKeyLength() const
Returns default key length.
Definition chachapoly.h:194
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
XChaCha20Poly1305_Base::IsValidKeyLength
bool IsValidKeyLength(size_t n) const
Returns whether keylength is a valid key length.
Definition chachapoly.h:198
XChaCha20Poly1305_Base::AlgorithmName
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition chachapoly.h:186
XChaCha20Poly1305_Base::IVSize
unsigned int IVSize() const
Returns length of the IV accepted by this object.
Definition chachapoly.h:204
XChaCha20Poly1305_Base::GetValidKeyLength
size_t GetValidKeyLength(size_t n) const
Returns a valid key length for the algorithm.
Definition chachapoly.h:196
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
XChaCha20Poly1305_Base::MaxHeaderLength
lword MaxHeaderLength() const
Provides the maximum length of AAD that can be input.
Definition chachapoly.h:212
XChaCha20Poly1305_Base::MinKeyLength
size_t MinKeyLength() const
Returns smallest valid key length.
Definition chachapoly.h:190
XChaCha20Poly1305_Base::MaxFooterLength
lword MaxFooterLength() const
Provides the maximum length of AAD.
Definition chachapoly.h:216
XChaCha20Poly1305_Base::IVRequirement
IV_Requirement IVRequirement() const
Minimal requirement for secure IVs.
Definition chachapoly.h:202
XChaCha20Poly1305_Base::OptimalDataAlignment
unsigned int OptimalDataAlignment() const
Provides input and output data alignment for optimal performance.
Definition chachapoly.h:200
XChaCha20Poly1305_Base::MinIVLength
unsigned int MinIVLength() const
Provides the minimum size of an IV.
Definition chachapoly.h:206
XChaCha20Poly1305_Base::MaxKeyLength
size_t MaxKeyLength() const
Returns largest valid key length.
Definition chachapoly.h:192
XChaCha20Poly1305_Base::AlgorithmProvider
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition chachapoly.h:188
XChaCha20Poly1305_Final
IETF XChaCha20Poly1305 cipher final implementation.
Definition chachapoly.h:282
W64LIT
#define W64LIT(x)
Declare an unsigned word64.
Definition config_int.h:129
LWORD_MAX
const lword LWORD_MAX
Large word type max value.
Definition config_int.h:174
lword
word64 lword
Large word type.
Definition config_int.h:168
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
CryptoPP
Crypto++ library namespace.
poly1305.h
Classes for Poly1305 message authentication code.
AuthenticatedSymmetricCipherDocumentation
Provides Encryption and Decryption typedefs used by derived classes to implement an authenticated enc...
Definition seckey.h:426
ChaCha20Poly1305
IETF ChaCha20/Poly1305 AEAD scheme.
Definition chachapoly.h:165
ChaCha20Poly1305::Decryption
ChaCha20Poly1305_Final< false > Decryption
ChaCha20Poly1305 decryption.
Definition chachapoly.h:169
ChaCha20Poly1305::Encryption
ChaCha20Poly1305_Final< true > Encryption
ChaCha20Poly1305 encryption.
Definition chachapoly.h:167
XChaCha20Poly1305
IETF XChaCha20/Poly1305 AEAD scheme.
Definition chachapoly.h:313
XChaCha20Poly1305::Decryption
XChaCha20Poly1305_Final< false > Decryption
XChaCha20Poly1305 decryption.
Definition chachapoly.h:317
XChaCha20Poly1305::Encryption
XChaCha20Poly1305_Final< true > Encryption
XChaCha20Poly1305 encryption.
Definition chachapoly.h:315