Crypto++  6.0
Free C++ class library of cryptographic schemes
authenc.h
Go to the documentation of this file.
1 // authenc.h - originally written and placed in the public domain by Wei Dai
2 
3 /// \file
4 /// \brief Classes for authenticated encryption modes of operation
5 /// \details Authenticated encryption (AE) schemes combine confidentiality and authenticity
6 /// into a single mode of operation They gained traction in the early 2000's because manually
7 /// combining them was error prone for the typical developer. Around that time, the desire to
8 /// authenticate but not ecrypt additional data (AAD) was also identified. When both features
9 /// are available from a scheme, the system is referred to as an AEAD scheme.
10 /// \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM
11 /// and OCB mode. All modes derive from AuthenticatedSymmetricCipherBase() and the
12 /// motivation for the API, like calling AAD a "header", can be found in Bellare,
13 /// Rogaway and Wagner's <A HREF="http://web.cs.ucdavis.edu/~rogaway/papers/eax.pdf">The EAX
14 /// Mode of Operation</A>. The EAX paper suggested a basic API to help standardize AEAD
15 /// schemes in software and promote adoption of the modes.
16 /// \sa <A HREF="http://www.cryptopp.com/wiki/Authenticated_Encryption">Authenticated
17 /// Encryption</A> on the Crypto++ wiki.
18 /// \since Crypto++ 5.6.0
19 
20 #ifndef CRYPTOPP_AUTHENC_H
21 #define CRYPTOPP_AUTHENC_H
22 
23 #include "cryptlib.h"
24 #include "secblock.h"
25 
26 NAMESPACE_BEGIN(CryptoPP)
27 
28 /// \brief Base class for authenticated encryption modes of operation
29 /// \details AuthenticatedSymmetricCipherBase() serves as a base implementation for one direction
30 /// (encryption or decryption) of a stream cipher or block cipher mode with authentication.
31 /// \details Crypto++ provides four authenticated encryption modes of operation - CCM, EAX, GCM
32 /// and OCB mode. All modes derive from AuthenticatedSymmetricCipherBase() and the
33 /// motivation for the API, like calling AAD a &quot;header&quot;, can be found in Bellare,
34 /// Rogaway and Wagner's <A HREF="http://web.cs.ucdavis.edu/~rogaway/papers/eax.pdf">The EAX
35 /// Mode of Operation</A>. The EAX paper suggested a basic API to help standardize AEAD
36 /// schemes in software and promote adoption of the modes.
37 /// \sa <A HREF="http://www.cryptopp.com/wiki/Authenticated_Encryption">Authenticated
38 /// Encryption</A> on the Crypto++ wiki.
39 /// \since Crypto++ 5.6.0
40 class CRYPTOPP_DLL CRYPTOPP_NO_VTABLE AuthenticatedSymmetricCipherBase : public AuthenticatedSymmetricCipher
41 {
42 public:
43  AuthenticatedSymmetricCipherBase() : m_totalHeaderLength(0), m_totalMessageLength(0),
44  m_totalFooterLength(0), m_bufferedDataLength(0), m_state(State_Start) {}
45 
46  // StreamTransformation interface
47  bool IsRandomAccess() const {return false;}
48  bool IsSelfInverting() const {return true;}
49 
50  void SetKey(const byte *userKey, size_t keylength, const NameValuePairs &params);
51  void Restart() {if (m_state > State_KeySet) m_state = State_KeySet;}
52  void Resynchronize(const byte *iv, int length=-1);
53  void Update(const byte *input, size_t length);
54  void ProcessData(byte *outString, const byte *inString, size_t length);
55  void TruncatedFinal(byte *mac, size_t macSize);
56 
57 protected:
58  void UncheckedSetKey(const byte * key, unsigned int length,const CryptoPP::NameValuePairs &params)
59  {CRYPTOPP_UNUSED(key), CRYPTOPP_UNUSED(length), CRYPTOPP_UNUSED(params); CRYPTOPP_ASSERT(false);}
60 
61  void AuthenticateData(const byte *data, size_t len);
62  const SymmetricCipher & GetSymmetricCipher() const
63  {return const_cast<AuthenticatedSymmetricCipherBase *>(this)->AccessSymmetricCipher();};
64 
65  virtual SymmetricCipher & AccessSymmetricCipher() =0;
66  virtual bool AuthenticationIsOnPlaintext() const =0;
67  virtual unsigned int AuthenticationBlockSize() const =0;
68  virtual void SetKeyWithoutResync(const byte *userKey, size_t keylength, const NameValuePairs &params) =0;
69  virtual void Resync(const byte *iv, size_t len) =0;
70  virtual size_t AuthenticateBlocks(const byte *data, size_t len) =0;
71  virtual void AuthenticateLastHeaderBlock() =0;
72  virtual void AuthenticateLastConfidentialBlock() {}
73  virtual void AuthenticateLastFooterBlock(byte *mac, size_t macSize) =0;
74 
75  // State_AuthUntransformed: authentication is applied to plain text (Authenticate-then-Encrypt)
76  // State_AuthTransformed: authentication is applied to cipher text (Encrypt-then-Authenticate)
77  enum State {State_Start, State_KeySet, State_IVSet, State_AuthUntransformed, State_AuthTransformed, State_AuthFooter};
78 
79  AlignedSecByteBlock m_buffer;
80  lword m_totalHeaderLength, m_totalMessageLength, m_totalFooterLength;
81  unsigned int m_bufferedDataLength;
82  State m_state;
83 };
84 
85 NAMESPACE_END
86 
87 #endif
Interface for authenticated encryption modes of operation.
Definition: cryptlib.h:1266
Abstract base classes that provide a uniform interface to this library.
bool IsRandomAccess() const
Determines whether the cipher supports random access.
Definition: authenc.h:47
void Restart()
Restart the hash.
Definition: authenc.h:51
Classes and functions for secure memory allocations.
bool IsSelfInverting() const
Determines whether the cipher is self-inverting.
Definition: authenc.h:48
Interface for one direction (encryption or decryption) of a stream cipher or cipher mode...
Definition: cryptlib.h:1236
Base class for authenticated encryption modes of operation.
Definition: authenc.h:40
SecBlock using AllocatorWithCleanup<byte, true> typedef.
Definition: secblock.h:826
#define CRYPTOPP_ASSERT(exp)
Debugging and diagnostic assertion.
Definition: trap.h:60
Crypto++ library namespace.
Interface for retrieving values given their names.
Definition: cryptlib.h:291