chacha.h
Go to the documentation of this file.
// chacha.h - written and placed in the public domain by Jeffrey Walton.
// Based on Wei Dai's Salsa20, Botan's SSE2 implementation,
// and Bernstein's reference ChaCha family implementation at
// http://cr.yp.to/chacha.html.
// The library added Bernstein's ChaCha classes at Crypto++ 5.6.4. The IETF
// uses a slightly different implementation than Bernstein, and the IETF
// ChaCha and XChaCha classes were added at Crypto++ 8.1. We wanted to maintain
// ABI compatibility at the 8.1 release so the original ChaCha classes were not
// disturbed. Instead new classes were added for IETF ChaCha. The back-end
// implementation shares code as expected, however.
/// \file chacha.h
/// \brief Classes for ChaCha8, ChaCha12 and ChaCha20 stream ciphers
/// \details Crypto++ provides Bernstein and ECRYPT's ChaCha from <a
/// href="http://cr.yp.to/chacha/chacha-20080128.pdf">ChaCha, a
/// variant of Salsa20</a> (2008.01.28). Crypto++ also provides the
/// IETF implementation of ChaCha using the ChaChaTLS name. Bernstein's
/// implementation is _slightly_ different from the TLS working group's
/// implementation for cipher suites
/// <tt>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</tt>,
/// <tt>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</tt>,
/// and <tt>TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256</tt>. Finally,
/// the library provides <a
/// href="https://tools.ietf.org/html/draft-arciszewski-xchacha">XChaCha:
/// eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305 (rev. 03)</a>.
/// \since ChaCha since Crypto++ 5.6.4, ChaChaTLS and XChaCha20 since Crypto++ 8.1
#ifndef CRYPTOPP_CHACHA_H
#define CRYPTOPP_CHACHA_H
#include "strciphr.h"
#include "secblock.h"
NAMESPACE_BEGIN(CryptoPP)
////////////////////////////// Bernstein ChaCha //////////////////////////////
/// \brief ChaCha stream cipher information
/// \since Crypto++ 5.6.4
struct ChaCha_Info : public VariableKeyLength<32, 16, 32, 16, SimpleKeyingInterface::UNIQUE_IV, 8>
{
/// \brief The algorithm name
/// \return the algorithm name
/// \details StaticAlgorithmName returns the algorithm's name as a static
/// member function.
/// \details Bernstein named the cipher variants ChaCha8, ChaCha12 and
/// ChaCha20. More generally, Bernstein called the family ChaCha{r}.
/// AlgorithmName() provides the exact name once rounds are set.
static const char* StaticAlgorithmName() {
return "ChaCha";
}
};
/// \brief ChaCha stream cipher implementation
/// \since Crypto++ 5.6.4
class CRYPTOPP_NO_VTABLE ChaCha_Policy : public AdditiveCipherConcretePolicy<word32, 16>
{
public:
virtual ~ChaCha_Policy() {}
ChaCha_Policy() : m_rounds(ROUNDS) {}
protected:
void CipherSetKey(const NameValuePairs &params, const byte *key, size_t length);
void OperateKeystream(KeystreamOperation operation, byte *output, const byte *input, size_t iterationCount);
void CipherResynchronize(byte *keystreamBuffer, const byte *IV, size_t length);
bool CipherIsRandomAccess() const {return true;}
void SeekToIteration(lword iterationCount);
unsigned int GetAlignment() const;
unsigned int GetOptimalBlockSize() const;
std::string AlgorithmName() const;
std::string AlgorithmProvider() const;
CRYPTOPP_CONSTANT(ROUNDS = 20); // Default rounds
FixedSizeAlignedSecBlock<word32, 16> m_state;
unsigned int m_rounds;
};
/// \brief ChaCha stream cipher
/// \details This is Bernstein and ECRYPT's ChaCha. It is _slightly_ different
/// from the IETF's version of ChaCha called ChaChaTLS.
/// \sa <a href="http://cr.yp.to/chacha/chacha-20080208.pdf">ChaCha, a variant
/// of Salsa20</a> (2008.01.28).
/// \since Crypto++ 5.6.4
struct ChaCha : public ChaCha_Info, public SymmetricCipherDocumentation
{
/// \brief ChaCha Encryption
typedef SymmetricCipherFinal<ConcretePolicyHolder<ChaCha_Policy, AdditiveCipherTemplate<> >, ChaCha_Info > Encryption;
/// \brief ChaCha Decryption
typedef Encryption Decryption;
};
////////////////////////////// IETF ChaChaTLS //////////////////////////////
/// \brief IETF ChaCha20 stream cipher information
/// \since Crypto++ 8.1
struct ChaChaTLS_Info : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 12>, FixedRounds<20>
{
/// \brief The algorithm name
/// \return the algorithm name
/// \details StaticAlgorithmName returns the algorithm's name as a static
/// member function.
/// \details This is the IETF's variant of Bernstein's ChaCha from RFC
/// 8439. IETF ChaCha is called ChaChaTLS in the Crypto++ library. It
/// is _slightly_ different from Bernstein's implementation.
static const char* StaticAlgorithmName() {
return "ChaChaTLS";
}
};
/// \brief IETF ChaCha20 stream cipher implementation
/// \since Crypto++ 8.1
class CRYPTOPP_NO_VTABLE ChaChaTLS_Policy : public AdditiveCipherConcretePolicy<word32, 16>
{
public:
virtual ~ChaChaTLS_Policy() {}
ChaChaTLS_Policy() : m_counter(0) {}
protected:
void CipherSetKey(const NameValuePairs &params, const byte *key, size_t length);
void OperateKeystream(KeystreamOperation operation, byte *output, const byte *input, size_t iterationCount);
void CipherResynchronize(byte *keystreamBuffer, const byte *IV, size_t length);
bool CipherIsRandomAccess() const {return true;}
void SeekToIteration(lword iterationCount);
unsigned int GetAlignment() const;
unsigned int GetOptimalBlockSize() const;
std::string AlgorithmName() const;
std::string AlgorithmProvider() const;
FixedSizeAlignedSecBlock<word32, 16+8> m_state;
unsigned int m_counter;
CRYPTOPP_CONSTANT(ROUNDS = ChaChaTLS_Info::ROUNDS);
CRYPTOPP_CONSTANT(KEY = 16); // Index into m_state
CRYPTOPP_CONSTANT(CTR = 24); // Index into m_state
};
/// \brief IETF ChaCha20 stream cipher
/// \details This is the IETF's variant of Bernstein's ChaCha from RFC 8439.
/// IETF ChaCha is called ChaChaTLS in the Crypto++ library. It is
/// _slightly_ different from the Bernstein implementation. ChaCha-TLS
/// can be used for cipher suites
/// <tt>TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256</tt>,
/// <tt>TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256</tt>, and
/// <tt>TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256</tt>.
/// \sa <a href="https://tools.ietf.org/html/rfc8439">RFC 8439, ChaCha20 and
/// Poly1305 for IETF Protocols</a>, <A
/// HREF="https://mailarchive.ietf.org/arch/msg/cfrg/gsOnTJzcbgG6OqD8Sc0GO5aR_tU">How
/// to handle block counter wrap in IETF's ChaCha algorithm?</A> and
/// <A HREF="https://github.com/weidai11/cryptopp/issues/790">Issue
/// 790, ChaChaTLS results when counter block wraps</A>.
/// \since Crypto++ 8.1
struct ChaChaTLS : public ChaChaTLS_Info, public SymmetricCipherDocumentation
{
/// \brief ChaCha-TLS Encryption
typedef SymmetricCipherFinal<ConcretePolicyHolder<ChaChaTLS_Policy, AdditiveCipherTemplate<> >, ChaChaTLS_Info > Encryption;
/// \brief ChaCha-TLS Decryption
typedef Encryption Decryption;
};
////////////////////////////// IETF XChaCha20 draft //////////////////////////////
/// \brief IETF XChaCha20 stream cipher information
/// \since Crypto++ 8.1
struct XChaCha20_Info : public FixedKeyLength<32, SimpleKeyingInterface::UNIQUE_IV, 24>
{
/// \brief The algorithm name
/// \return the algorithm name
/// \details StaticAlgorithmName returns the algorithm's name as a static
/// member function.
/// \details This is the IETF's XChaCha from draft-arciszewski-xchacha.
static const char* StaticAlgorithmName() {
return "XChaCha20";
}
};
/// \brief IETF XChaCha20 stream cipher implementation
/// \since Crypto++ 8.1
class CRYPTOPP_NO_VTABLE XChaCha20_Policy : public AdditiveCipherConcretePolicy<word32, 16>
{
public:
virtual ~XChaCha20_Policy() {}
XChaCha20_Policy() : m_counter(0), m_rounds(ROUNDS) {}
protected:
void CipherSetKey(const NameValuePairs &params, const byte *key, size_t length);
void OperateKeystream(KeystreamOperation operation, byte *output, const byte *input, size_t iterationCount);
void CipherResynchronize(byte *keystreamBuffer, const byte *IV, size_t length);
bool CipherIsRandomAccess() const {return false;}
void SeekToIteration(lword iterationCount);
unsigned int GetAlignment() const;
unsigned int GetOptimalBlockSize() const;
std::string AlgorithmName() const;
std::string AlgorithmProvider() const;
FixedSizeAlignedSecBlock<word32, 16+8> m_state;
unsigned int m_counter, m_rounds;
CRYPTOPP_CONSTANT(ROUNDS = 20); // Default rounds
CRYPTOPP_CONSTANT(KEY = 16); // Index into m_state
};
/// \brief IETF XChaCha20 stream cipher
/// \details This is the IETF's XChaCha from draft-arciszewski-xchacha.
/// \sa <a href="https://tools.ietf.org/html/draft-arciszewski-xchacha">XChaCha:
/// eXtended-nonce ChaCha and AEAD_XChaCha20_Poly1305 (rev. 03)</a>, <A
/// HREF="https://mailarchive.ietf.org/arch/msg/cfrg/gsOnTJzcbgG6OqD8Sc0GO5aR_tU">How
/// to handle block counter wrap in IETF's ChaCha algorithm?</A> and
/// <A HREF="https://github.com/weidai11/cryptopp/issues/790">Issue
/// 790, ChaCha20 results when counter block wraps</A>.
/// \since Crypto++ 8.1
struct XChaCha20 : public XChaCha20_Info, public SymmetricCipherDocumentation
{
/// \brief XChaCha Encryption
typedef SymmetricCipherFinal<ConcretePolicyHolder<XChaCha20_Policy, AdditiveCipherTemplate<> >, XChaCha20_Info > Encryption;
/// \brief XChaCha Decryption
typedef Encryption Decryption;
};
NAMESPACE_END
#endif // CRYPTOPP_CHACHA_H
FixedKeyLength
Inherited by keyed algorithms with fixed key length.
Definition seckey.h:125
FixedRounds
Inherited by algorithms with fixed number of rounds.
Definition seckey.h:53
FixedRounds< 20 >::ROUNDS
static const int ROUNDS
Definition seckey.h:56
FixedSizeAlignedSecBlock
Fixed size stack-based SecBlock with 16-byte alignment.
Definition secblock.h:1259
NameValuePairs
Interface for retrieving values given their names.
Definition cryptlib.h:327
SimpleKeyingInterface
Interface for algorithms that take byte strings as keys.
Definition cryptlib.h:647
SymmetricCipherFinal
SymmetricCipher implementation.
Definition strciphr.h:684
VariableKeyLength
Inherited by keyed algorithms with variable key length.
Definition seckey.h:166
lword
word64 lword
Large word type.
Definition config_int.h:168
CryptoPP
Crypto++ library namespace.
secblock.h
Classes and functions for secure memory allocations.
strciphr.h
Classes for implementing stream ciphers.
KeystreamOperation
KeystreamOperation
Keystream operation flags.
Definition strciphr.h:88
AdditiveCipherAbstractPolicy::AlgorithmProvider
virtual std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition strciphr.h:192
AdditiveCipherAbstractPolicy::GetOptimalBlockSize
virtual unsigned int GetOptimalBlockSize() const
Provides number of ideal bytes to process.
Definition strciphr.h:123
AdditiveCipherAbstractPolicy::SeekToIteration
virtual void SeekToIteration(lword iterationCount)
Seeks to a random position in the stream.
Definition strciphr.h:174
AdditiveCipherAbstractPolicy::CipherSetKey
virtual void CipherSetKey(const NameValuePairs &params, const byte *key, size_t length)=0
Key the cipher.
AdditiveCipherAbstractPolicy::CipherIsRandomAccess
virtual bool CipherIsRandomAccess() const =0
Flag indicating random access.
AdditiveCipherAbstractPolicy::CipherResynchronize
virtual void CipherResynchronize(byte *keystreamBuffer, const byte *iv, size_t length)
Resynchronize the cipher.
Definition strciphr.h:163
AdditiveCipherConcretePolicy
Base class for additive stream ciphers.
Definition strciphr.h:202
AdditiveCipherConcretePolicy::GetAlignment
unsigned int GetAlignment() const
Provides data alignment requirements.
Definition strciphr.h:220
AdditiveCipherConcretePolicy::OperateKeystream
virtual void OperateKeystream(KeystreamOperation operation, byte *output, const byte *input, size_t iterationCount)=0
Operates the keystream.
ChaCha_Info
ChaCha stream cipher information.
Definition chacha.h:42
ChaCha_Info::StaticAlgorithmName
static const char * StaticAlgorithmName()
The algorithm name.
Definition chacha.h:50
ChaCha
ChaCha stream cipher.
Definition chacha.h:87
ChaCha::Encryption
SymmetricCipherFinal< ConcretePolicyHolder< ChaCha_Policy, AdditiveCipherTemplate<> >, ChaCha_Info > Encryption
ChaCha Encryption.
Definition chacha.h:89
ChaCha::Decryption
Encryption Decryption
ChaCha Decryption.
Definition chacha.h:91
ChaChaTLS_Info
IETF ChaCha20 stream cipher information.
Definition chacha.h:99
ChaChaTLS_Info::StaticAlgorithmName
static const char * StaticAlgorithmName()
The algorithm name.
Definition chacha.h:107
ChaChaTLS
IETF ChaCha20 stream cipher.
Definition chacha.h:155
ChaChaTLS::Encryption
SymmetricCipherFinal< ConcretePolicyHolder< ChaChaTLS_Policy, AdditiveCipherTemplate<> >, ChaChaTLS_Info > Encryption
ChaCha-TLS Encryption.
Definition chacha.h:157
ChaChaTLS::Decryption
Encryption Decryption
ChaCha-TLS Decryption.
Definition chacha.h:159
SymmetricCipherDocumentation
Provides Encryption and Decryption typedefs used by derived classes to implement a symmetric cipher.
Definition seckey.h:414
XChaCha20_Info
IETF XChaCha20 stream cipher information.
Definition chacha.h:167
XChaCha20_Info::StaticAlgorithmName
static const char * StaticAlgorithmName()
The algorithm name.
Definition chacha.h:173
XChaCha20
IETF XChaCha20 stream cipher.
Definition chacha.h:214
XChaCha20::Encryption
SymmetricCipherFinal< ConcretePolicyHolder< XChaCha20_Policy, AdditiveCipherTemplate<> >, XChaCha20_Info > Encryption
XChaCha Encryption.
Definition chacha.h:216
XChaCha20::Decryption
Encryption Decryption
XChaCha Decryption.
Definition chacha.h:218