xts.h
Go to the documentation of this file.
// xts.h - written and placed in the public domain by Jeffrey Walton
/// \file xts.h
/// \brief Classes for XTS block cipher mode of operation
/// \details XTS mode is a wide block mode defined by IEEE P1619-2008. NIST
/// SP-800-38E approves the mode for storage devices citing IEEE 1619-2007.
/// IEEE 1619-2007 provides both a reference implementation and test vectors.
/// The IEEE reference implementation fails to arrive at the expected result
/// for some test vectors.
/// \sa <A HREF="http://www.cryptopp.com/wiki/Modes_of_Operation">Modes of
/// Operation</A> on the Crypto++ wiki, <A
/// HREF="https://web.cs.ucdavis.edu/~rogaway/papers/modes.pdf"> Evaluation of Some
/// Blockcipher Modes of Operation</A>, <A
/// HREF="https://csrc.nist.gov/publications/detail/sp/800-38e/final">Recommendation
/// for Block Cipher Modes of Operation: The XTS-AES Mode for Confidentiality on
/// Storage Devices</A>, <A
/// HREF="http://libeccio.di.unisa.it/Crypto14/Lab/p1619.pdf">IEEE P1619-2007</A>
/// and <A HREF="https://crypto.stackexchange.com/q/74925/10496">IEEE P1619/XTS,
/// inconsistent reference implementation and test vectors</A>.
/// \since Crypto++ 8.3
#ifndef CRYPTOPP_XTS_MODE_H
#define CRYPTOPP_XTS_MODE_H
#include "cryptlib.h"
#include "secblock.h"
#include "modes.h"
#include "misc.h"
/// \brief Enable XTS for wide block ciphers
/// \details XTS is only defined for AES. The library can support wide
/// block ciphers like Kaylna and Threefish since we know the polynomials.
/// To enable wide block ciphers define <tt>CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS</tt>
/// to non-zero. Note this is a library compile time define.
/// \details There is risk involved with using XTS with wider block ciphers.
/// According to Phillip Rogaway, "The narrow width of the underlying PRP and
/// the poor treatment of fractional final blocks are problems."
/// \sa <A HREF="https://web.cs.ucdavis.edu/~rogaway/papers/modes.pdf">Evaluation
/// of Some Blockcipher Modes of Operation</A>
/// \since Crypto++ 8.3
#ifndef CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS
# define CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS 0
#endif // CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS
NAMESPACE_BEGIN(CryptoPP)
/// \brief XTS block cipher mode of operation default implementation
/// \since Crypto++ 8.3
class CRYPTOPP_NO_VTABLE XTS_ModeBase : public BlockOrientedCipherModeBase
{
public:
/// \brief The algorithm name
/// \return the algorithm name
/// \details StaticAlgorithmName returns the algorithm's name as a static
/// member function.
CRYPTOPP_STATIC_CONSTEXPR const char* StaticAlgorithmName()
{return "XTS";}
virtual ~XTS_ModeBase() {}
std::string AlgorithmName() const
{return GetBlockCipher().AlgorithmName() + "/XTS";}
std::string AlgorithmProvider() const
{return GetBlockCipher().AlgorithmProvider();}
size_t MinKeyLength() const
{return GetBlockCipher().MinKeyLength()*2;}
size_t MaxKeyLength() const
{return GetBlockCipher().MaxKeyLength()*2;}
size_t DefaultKeyLength() const
{return GetBlockCipher().DefaultKeyLength()*2;}
size_t GetValidKeyLength(size_t n) const
{return 2*GetBlockCipher().GetValidKeyLength((n+1)/2);}
bool IsValidKeyLength(size_t keylength) const
{return keylength == GetValidKeyLength(keylength);}
/// \brief Validates the key length
/// \param length the size of the keying material, in bytes
/// \throw InvalidKeyLength if the key length is invalid
void ThrowIfInvalidKeyLength(size_t length);
/// Provides the block size of the cipher
/// \return the block size of the cipher, in bytes
unsigned int BlockSize() const
{return GetBlockCipher().BlockSize();}
/// \brief Provides the input block size most efficient for this cipher
/// \return The input block size that is most efficient for the cipher
/// \details The base class implementation returns MandatoryBlockSize().
/// \note Optimal input length is
/// <tt>n * OptimalBlockSize() - GetOptimalBlockSizeUsed()</tt> for
/// any <tt>n > 0</tt>.
unsigned int GetOptimalBlockSize() const
{return GetBlockCipher().BlockSize()*ParallelBlocks;}
unsigned int MinLastBlockSize() const
{return GetBlockCipher().BlockSize()+1;}
unsigned int OptimalDataAlignment() const
{return GetBlockCipher().OptimalDataAlignment();}
/// \brief Validates the block size
/// \param length the block size of the cipher, in bytes
/// \throw InvalidArgument if the block size is invalid
/// \details If <tt>CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS</tt> is 0,
/// then CIPHER must be a 16-byte block cipher. If
/// <tt>CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS</tt> is non-zero then
/// CIPHER can be 16, 32, 64, or 128-byte block cipher.
void ThrowIfInvalidBlockSize(size_t length);
void SetKey(const byte *key, size_t length, const NameValuePairs &params = g_nullNameValuePairs);
IV_Requirement IVRequirement() const {return UNIQUE_IV;}
void Resynchronize(const byte *iv, int ivLength=-1);
void ProcessData(byte *outString, const byte *inString, size_t length);
size_t ProcessLastBlock(byte *outString, size_t outLength, const byte *inString, size_t inLength);
/// \brief Resynchronize the cipher
/// \param sector a 64-bit sector number
/// \param order the endian order the word should be written
/// \details The Resynchronize() overload was provided for API
/// compatibility with the IEEE P1619 paper.
void Resynchronize(word64 sector, ByteOrder order=BIG_ENDIAN_ORDER);
protected:
virtual void ResizeBuffers();
inline size_t ProcessLastPlainBlock(byte *outString, size_t outLength, const byte *inString, size_t inLength);
inline size_t ProcessLastCipherBlock(byte *outString, size_t outLength, const byte *inString, size_t inLength);
virtual BlockCipher& AccessBlockCipher() = 0;
virtual BlockCipher& AccessTweakCipher() = 0;
const BlockCipher& GetBlockCipher() const
{return const_cast<XTS_ModeBase*>(this)->AccessBlockCipher();}
const BlockCipher& GetTweakCipher() const
{return const_cast<XTS_ModeBase*>(this)->AccessTweakCipher();}
// Buffers are sized based on ParallelBlocks
AlignedSecByteBlock m_xregister;
AlignedSecByteBlock m_xworkspace;
// Intel lacks the SSE registers to run 8 or 12 parallel blocks.
// Do not change this value after compiling. It has no effect.
#if CRYPTOPP_BOOL_X64 || CRYPTOPP_BOOL_X32 || CRYPTOPP_BOOL_X86
enum {ParallelBlocks = 4};
#else
enum {ParallelBlocks = 12};
#endif
};
/// \brief XTS block cipher mode of operation implementation
/// \tparam CIPHER BlockCipher derived class or type
/// \details XTS_Final() provides access to CIPHER in base class XTS_ModeBase()
/// through an interface. AccessBlockCipher() and AccessTweakCipher() allow
/// the XTS_ModeBase() base class to access the user's block cipher without
/// recompiling the library.
/// \details If <tt>CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS</tt> is 0, then CIPHER must
/// be a 16-byte block cipher. If <tt>CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS</tt> is
/// non-zero then CIPHER can be 16, 32, 64, or 128-byte block cipher.
/// There is risk involved with using XTS with wider block ciphers.
/// According to Phillip Rogaway, "The narrow width of the underlying PRP and
/// the poor treatment of fractional final blocks are problems." To enable
/// wide block cipher support define <tt>CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS</tt> to
/// non-zero.
/// \sa <A HREF="http://www.cryptopp.com/wiki/Modes_of_Operation">Modes of
/// Operation</A> on the Crypto++ wiki, <A
/// HREF="https://web.cs.ucdavis.edu/~rogaway/papers/modes.pdf"> Evaluation of Some
/// Blockcipher Modes of Operation</A>, <A
/// HREF="https://csrc.nist.gov/publications/detail/sp/800-38e/final">Recommendation
/// for Block Cipher Modes of Operation: The XTS-AES Mode for Confidentiality on
/// Storage Devices</A>, <A
/// HREF="http://libeccio.di.unisa.it/Crypto14/Lab/p1619.pdf">IEEE P1619-2007</A>
/// and <A HREF="https://crypto.stackexchange.com/q/74925/10496">IEEE P1619/XTS,
/// inconsistent reference implementation and test vectors</A>.
/// \since Crypto++ 8.3
template <class CIPHER>
class CRYPTOPP_NO_VTABLE XTS_Final : public XTS_ModeBase
{
protected:
BlockCipher& AccessBlockCipher()
{return *m_cipher;}
BlockCipher& AccessTweakCipher()
{return m_tweaker;}
protected:
typename CIPHER::Encryption m_tweaker;
};
/// \brief XTS block cipher mode of operation
/// \tparam CIPHER BlockCipher derived class or type
/// \details XTS mode is a wide block mode defined by IEEE P1619-2008. NIST
/// SP-800-38E approves the mode for storage devices citing IEEE 1619-2007.
/// IEEE 1619-2007 provides both a reference implementation and test vectors.
/// The IEEE reference implementation fails to arrive at the expected result
/// for some test vectors.
/// \details XTS is only defined for AES. The library can support wide
/// block ciphers like Kaylna and Threefish since we know the polynomials.
/// There is risk involved with using XTS with wider block ciphers.
/// According to Phillip Rogaway, "The narrow width of the underlying PRP and
/// the poor treatment of fractional final blocks are problems." To enable
/// wide block cipher support define <tt>CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS</tt> to
/// non-zero.
/// \sa <A HREF="http://www.cryptopp.com/wiki/Modes_of_Operation">Modes of
/// Operation</A> on the Crypto++ wiki, <A
/// HREF="https://web.cs.ucdavis.edu/~rogaway/papers/modes.pdf"> Evaluation of Some
/// Blockcipher Modes of Operation</A>, <A
/// HREF="https://csrc.nist.gov/publications/detail/sp/800-38e/final">Recommendation
/// for Block Cipher Modes of Operation: The XTS-AES Mode for Confidentiality on
/// Storage Devices</A>, <A
/// HREF="http://libeccio.di.unisa.it/Crypto14/Lab/p1619.pdf">IEEE P1619-2007</A>
/// and <A HREF="https://crypto.stackexchange.com/q/74925/10496">IEEE P1619/XTS,
/// inconsistent reference implementation and test vectors</A>.
/// \since Crypto++ 8.3
template <class CIPHER>
struct XTS : public CipherModeDocumentation
{
typedef CipherModeFinalTemplate_CipherHolder<typename CIPHER::Encryption, XTS_Final<CIPHER> > Encryption;
typedef CipherModeFinalTemplate_CipherHolder<typename CIPHER::Decryption, XTS_Final<CIPHER> > Decryption;
};
// C++03 lacks the mechanics to typedef a template
#define XTS_Mode XTS
NAMESPACE_END
#endif // CRYPTOPP_XTS_MODE_H
AlignedSecByteBlock
SecBlock using AllocatorWithCleanup<byte, true> typedef.
Definition secblock.h:1230
BlockCipher
Interface for one direction (encryption or decryption) of a block cipher.
Definition cryptlib.h:1288
BlockOrientedCipherModeBase
Block cipher mode of operation default implementation.
Definition modes.h:251
CipherModeFinalTemplate_CipherHolder
Block cipher mode of operation aggregate.
Definition modes.h:347
NameValuePairs
Interface for retrieving values given their names.
Definition cryptlib.h:327
SimpleKeyingInterface::IV_Requirement
IV_Requirement
Secure IVs requirements as enumerated values.
Definition cryptlib.h:724
XTS_Final
XTS block cipher mode of operation implementation.
Definition xts.h:176
XTS_ModeBase
XTS block cipher mode of operation default implementation.
Definition xts.h:50
XTS_ModeBase::MinLastBlockSize
unsigned int MinLastBlockSize() const
Provides the size of the last block.
Definition xts.h:95
XTS_ModeBase::DefaultKeyLength
size_t DefaultKeyLength() const
Returns default key length.
Definition xts.h:70
XTS_ModeBase::IsValidKeyLength
bool IsValidKeyLength(size_t keylength) const
Returns whether keylength is a valid key length.
Definition xts.h:74
XTS_ModeBase::AlgorithmProvider
std::string AlgorithmProvider() const
Retrieve the provider of this algorithm.
Definition xts.h:63
XTS_ModeBase::IVRequirement
IV_Requirement IVRequirement() const
Minimal requirement for secure IVs.
Definition xts.h:110
XTS_ModeBase::GetValidKeyLength
size_t GetValidKeyLength(size_t n) const
Returns a valid key length for the algorithm.
Definition xts.h:72
XTS_ModeBase::StaticAlgorithmName
static const char * StaticAlgorithmName()
The algorithm name.
Definition xts.h:56
XTS_ModeBase::MaxKeyLength
size_t MaxKeyLength() const
Returns largest valid key length.
Definition xts.h:68
XTS_ModeBase::OptimalDataAlignment
unsigned int OptimalDataAlignment() const
Provides input and output data alignment for optimal performance.
Definition xts.h:97
XTS_ModeBase::BlockSize
unsigned int BlockSize() const
Provides the block size of the cipher.
Definition xts.h:84
XTS_ModeBase::GetOptimalBlockSize
unsigned int GetOptimalBlockSize() const
Provides the input block size most efficient for this cipher.
Definition xts.h:93
XTS_ModeBase::AlgorithmName
std::string AlgorithmName() const
Provides the name of this algorithm.
Definition xts.h:61
XTS_ModeBase::MinKeyLength
size_t MinKeyLength() const
Returns smallest valid key length.
Definition xts.h:66
word64
unsigned long long word64
64-bit unsigned datatype
Definition config_int.h:101
cryptlib.h
Abstract base classes that provide a uniform interface to this library.
g_nullNameValuePairs
const NameValuePairs & g_nullNameValuePairs
An empty set of name-value pairs.
Definition cryptlib.h:534
ByteOrder
ByteOrder
Provides the byte ordering.
Definition cryptlib.h:148
BIG_ENDIAN_ORDER
@ BIG_ENDIAN_ORDER
byte order is big-endian
Definition cryptlib.h:152
misc.h
Utility functions for the Crypto++ library.
modes.h
Classes for block cipher modes of operation.
CryptoPP
Crypto++ library namespace.
secblock.h
Classes and functions for secure memory allocations.
CipherModeDocumentation
Block cipher mode of operation information.
Definition modes.h:45
XTS
XTS block cipher mode of operation.
Definition xts.h:214