Crypto++ 8.7
Free C++ class library of cryptographic schemes
Public Member Functions | Static Public Member Functions | List of all members
XTS_ModeBase Class Referenceabstract

XTS block cipher mode of operation default implementation. More...

#include <xts.h>

+ Inheritance diagram for XTS_ModeBase:

Public Member Functions

std::string AlgorithmName () const
 Provides the name of this algorithm. More...
 
std::string AlgorithmProvider () const
 Retrieve the provider of this algorithm. More...
 
size_t MinKeyLength () const
 Returns smallest valid key length. More...
 
size_t MaxKeyLength () const
 Returns largest valid key length. More...
 
size_t DefaultKeyLength () const
 Returns default key length. More...
 
size_t GetValidKeyLength (size_t n) const
 Returns a valid key length for the algorithm. More...
 
bool IsValidKeyLength (size_t keylength) const
 Returns whether keylength is a valid key length. More...
 
void ThrowIfInvalidKeyLength (size_t length)
 Validates the key length. More...
 
unsigned int BlockSize () const
 Provides the block size of the cipher. More...
 
unsigned int GetOptimalBlockSize () const
 Provides the input block size most efficient for this cipher. More...
 
unsigned int MinLastBlockSize () const
 Provides the size of the last block. More...
 
unsigned int OptimalDataAlignment () const
 Provides input and output data alignment for optimal performance. More...
 
void ThrowIfInvalidBlockSize (size_t length)
 Validates the block size. More...
 
void SetKey (const byte *key, size_t length, const NameValuePairs &params=g_nullNameValuePairs)
 Sets or reset the key of this object. More...
 
IV_Requirement IVRequirement () const
 Minimal requirement for secure IVs. More...
 
void Resynchronize (const byte *iv, int ivLength=-1)
 Resynchronize with an IV. More...
 
void ProcessData (byte *outString, const byte *inString, size_t length)
 Encrypt or decrypt an array of bytes. More...
 
size_t ProcessLastBlock (byte *outString, size_t outLength, const byte *inString, size_t inLength)
 Encrypt or decrypt the last block of data. More...
 
void Resynchronize (word64 sector, ByteOrder order=BIG_ENDIAN_ORDER)
 Resynchronize the cipher. More...
 
- Public Member Functions inherited from BlockOrientedCipherModeBase
void UncheckedSetKey (const byte *key, unsigned int length, const NameValuePairs &params)
 Sets the key for this object without performing parameter validation. More...
 
unsigned int MandatoryBlockSize () const
 Provides the mandatory block size of the cipher. More...
 
bool IsRandomAccess () const
 Determines whether the cipher supports random access. More...
 
bool IsSelfInverting () const
 Determines whether the cipher is self-inverting. More...
 
bool IsForwardTransformation () const
 Determines if the cipher is being operated in its forward direction. More...
 
void Resynchronize (const byte *iv, int length=-1)
 Resynchronize with an IV. More...
 
- Public Member Functions inherited from CipherModeBase
std::string AlgorithmProvider () const
 Retrieve the provider of this algorithm. More...
 
size_t MinKeyLength () const
 Returns smallest valid key length. More...
 
size_t MaxKeyLength () const
 Returns largest valid key length. More...
 
size_t DefaultKeyLength () const
 Returns default key length. More...
 
size_t GetValidKeyLength (size_t keylength) const
 Returns a valid key length for the algorithm. More...
 
bool IsValidKeyLength (size_t keylength) const
 Returns whether keylength is a valid key length. More...
 
unsigned int OptimalDataAlignment () const
 Provides input and output data alignment for optimal performance. More...
 
unsigned int IVSize () const
 Returns length of the IV accepted by this object. More...
 
virtual IV_Requirement IVRequirement () const =0
 Minimal requirement for secure IVs. More...
 
void SetCipher (BlockCipher &cipher)
 Set external block cipher. More...
 
void SetCipherWithIV (BlockCipher &cipher, const byte *iv, int feedbackSize=0)
 Set external block cipher and IV. More...
 
- Public Member Functions inherited from SimpleKeyingInterface
virtual size_t MinKeyLength () const =0
 Returns smallest valid key length. More...
 
virtual size_t MaxKeyLength () const =0
 Returns largest valid key length. More...
 
virtual size_t DefaultKeyLength () const =0
 Returns default key length. More...
 
virtual size_t GetValidKeyLength (size_t keylength) const =0
 Returns a valid key length for the algorithm. More...
 
virtual bool IsValidKeyLength (size_t keylength) const
 Returns whether keylength is a valid key length. More...
 
virtual void SetKey (const byte *key, size_t length, const NameValuePairs &params=g_nullNameValuePairs)
 Sets or reset the key of this object. More...
 
void SetKeyWithRounds (const byte *key, size_t length, int rounds)
 Sets or reset the key of this object. More...
 
void SetKeyWithIV (const byte *key, size_t length, const byte *iv, size_t ivLength)
 Sets or reset the key of this object. More...
 
void SetKeyWithIV (const byte *key, size_t length, const byte *iv)
 Sets or reset the key of this object. More...
 
virtual IV_Requirement IVRequirement () const =0
 Minimal requirement for secure IVs. More...
 
bool IsResynchronizable () const
 Determines if the object can be resynchronized. More...
 
bool CanUseRandomIVs () const
 Determines if the object can use random IVs. More...
 
bool CanUsePredictableIVs () const
 Determines if the object can use random but possibly predictable IVs. More...
 
bool CanUseStructuredIVs () const
 Determines if the object can use structured IVs. More...
 
virtual unsigned int IVSize () const
 Returns length of the IV accepted by this object. More...
 
unsigned int DefaultIVLength () const
 Provides the default size of an IV. More...
 
virtual unsigned int MinIVLength () const
 Provides the minimum size of an IV. More...
 
virtual unsigned int MaxIVLength () const
 Provides the maximum size of an IV. More...
 
virtual void Resynchronize (const byte *iv, int ivLength=-1)
 Resynchronize with an IV. More...
 
virtual void GetNextIV (RandomNumberGenerator &rng, byte *iv)
 Retrieves a secure IV for the next message. More...
 
- Public Member Functions inherited from StreamTransformation
StreamTransformationRef ()
 Provides a reference to this object. More...
 
virtual unsigned int MandatoryBlockSize () const
 Provides the mandatory block size of the cipher. More...
 
virtual unsigned int OptimalBlockSize () const
 Provides the input block size most efficient for this cipher. More...
 
virtual unsigned int GetOptimalBlockSizeUsed () const
 Provides the number of bytes used in the current block when processing at optimal block size. More...
 
virtual unsigned int OptimalDataAlignment () const
 Provides input and output data alignment for optimal performance. More...
 
virtual void ProcessData (byte *outString, const byte *inString, size_t length)=0
 Encrypt or decrypt an array of bytes. More...
 
virtual size_t ProcessLastBlock (byte *outString, size_t outLength, const byte *inString, size_t inLength)
 Encrypt or decrypt the last block of data. More...
 
virtual unsigned int MinLastBlockSize () const
 Provides the size of the last block. More...
 
virtual bool IsLastBlockSpecial () const
 Determines if the last block receives special processing. More...
 
void ProcessString (byte *inoutString, size_t length)
 Encrypt or decrypt a string of bytes. More...
 
void ProcessString (byte *outString, const byte *inString, size_t length)
 Encrypt or decrypt a string of bytes. More...
 
byte ProcessByte (byte input)
 Encrypt or decrypt a byte. More...
 
virtual bool IsRandomAccess () const =0
 Determines whether the cipher supports random access. More...
 
virtual void Seek (lword pos)
 Seek to an absolute position. More...
 
virtual bool IsSelfInverting () const =0
 Determines whether the cipher is self-inverting. More...
 
virtual bool IsForwardTransformation () const =0
 Determines if the cipher is being operated in its forward direction. More...
 
- Public Member Functions inherited from Algorithm
 Algorithm (bool checkSelfTestStatus=true)
 Interface for all crypto algorithms. More...
 
virtual std::string AlgorithmName () const
 Provides the name of this algorithm. More...
 
virtual std::string AlgorithmProvider () const
 Retrieve the provider of this algorithm. More...
 
- Public Member Functions inherited from Clonable
virtual ClonableClone () const
 Copies this object. More...
 

Static Public Member Functions

static const char * StaticAlgorithmName ()
 The algorithm name. More...
 

Additional Inherited Members

- Public Types inherited from SimpleKeyingInterface
enum  IV_Requirement {
  UNIQUE_IV = 0 , RANDOM_IV , UNPREDICTABLE_RANDOM_IV , INTERNALLY_GENERATED_IV ,
  NOT_RESYNCHRONIZABLE
}
 Secure IVs requirements as enumerated values. More...
 

Detailed Description

XTS block cipher mode of operation default implementation.

Since
Crypto++ 8.3

Definition at line 49 of file xts.h.

Constructor & Destructor Documentation

◆ ~XTS_ModeBase()

virtual XTS_ModeBase::~XTS_ModeBase ( )
inlinevirtual

Definition at line 59 of file xts.h.

Member Function Documentation

◆ StaticAlgorithmName()

static const char * XTS_ModeBase::StaticAlgorithmName ( )
inlinestatic

The algorithm name.

Returns
the algorithm name

StaticAlgorithmName returns the algorithm's name as a static member function.

Definition at line 56 of file xts.h.

◆ AlgorithmName()

std::string XTS_ModeBase::AlgorithmName ( ) const
inlinevirtual

Provides the name of this algorithm.

Returns
the standard algorithm name

The standard algorithm name can be a name like AES or AES/GCM. Some algorithms do not have standard names yet. For example, there is no standard algorithm name for Shoup's ECIES.

Note
AlgorithmName is not universally implemented yet.

Reimplemented from Algorithm.

Definition at line 61 of file xts.h.

◆ AlgorithmProvider()

std::string XTS_ModeBase::AlgorithmProvider ( ) const
inlinevirtual

Retrieve the provider of this algorithm.

Returns
the algorithm provider

The algorithm provider can be a name like "C++", "SSE", "NEON", "AESNI", "ARMv8" and "Power8". C++ is standard C++ code. Other labels, like SSE, usually indicate a specialized implementation using instructions from a higher instruction set architecture (ISA). Future labels may include external hardware like a hardware security module (HSM).

Generally speaking Wei Dai's original IA-32 ASM code falls under "SSE2". Labels like "SSSE3" and "SSE4.1" follow after Wei's code and use intrinsics instead of ASM.

Algorithms which combine different instructions or ISAs provide the dominant one. For example on x86 AES/GCM returns "AESNI" rather than "CLMUL" or "AES+SSE4.1" or "AES+CLMUL" or "AES+SSE4.1+CLMUL".

Note
Provider is not universally implemented yet.
Since
Crypto++ 8.0

Reimplemented from CipherModeBase.

Definition at line 63 of file xts.h.

◆ MinKeyLength()

size_t XTS_ModeBase::MinKeyLength ( ) const
inlinevirtual

Returns smallest valid key length.

Returns
the minimum key length, in bytes

Reimplemented from CipherModeBase.

Definition at line 66 of file xts.h.

◆ MaxKeyLength()

size_t XTS_ModeBase::MaxKeyLength ( ) const
inlinevirtual

Returns largest valid key length.

Returns
the maximum key length, in bytes

Reimplemented from CipherModeBase.

Definition at line 68 of file xts.h.

◆ DefaultKeyLength()

size_t XTS_ModeBase::DefaultKeyLength ( ) const
inlinevirtual

Returns default key length.

Returns
the default key length, in bytes

Reimplemented from CipherModeBase.

Definition at line 70 of file xts.h.

◆ GetValidKeyLength()

size_t XTS_ModeBase::GetValidKeyLength ( size_t  keylength) const
inlinevirtual

Returns a valid key length for the algorithm.

Parameters
keylengththe size of the key, in bytes
Returns
the valid key length, in bytes

keylength is provided in bytes, not bits. If keylength is less than MIN_KEYLENGTH, then the function returns MIN_KEYLENGTH. If keylength is greater than MAX_KEYLENGTH, then the function returns MAX_KEYLENGTH. if If keylength is a multiple of KEYLENGTH_MULTIPLE, then keylength is returned. Otherwise, the function returns a lower multiple of KEYLENGTH_MULTIPLE.

Reimplemented from CipherModeBase.

Definition at line 72 of file xts.h.

◆ IsValidKeyLength()

bool XTS_ModeBase::IsValidKeyLength ( size_t  keylength) const
inlinevirtual

Returns whether keylength is a valid key length.

Parameters
keylengththe requested keylength
Returns
true if keylength is valid, false otherwise

Internally the function calls GetValidKeyLength()

Reimplemented from CipherModeBase.

Definition at line 74 of file xts.h.

◆ ThrowIfInvalidKeyLength()

void XTS_ModeBase::ThrowIfInvalidKeyLength ( size_t  length)

Validates the key length.

Parameters
lengththe size of the keying material, in bytes
Exceptions
InvalidKeyLengthif the key length is invalid

Definition at line 208 of file xts.cpp.

◆ BlockSize()

unsigned int XTS_ModeBase::BlockSize ( ) const
inline

Provides the block size of the cipher.

Returns
the block size of the cipher, in bytes

Definition at line 84 of file xts.h.

◆ GetOptimalBlockSize()

unsigned int XTS_ModeBase::GetOptimalBlockSize ( ) const
inline

Provides the input block size most efficient for this cipher.

Returns
The input block size that is most efficient for the cipher

The base class implementation returns MandatoryBlockSize().

Note
Optimal input length is n * OptimalBlockSize() - GetOptimalBlockSizeUsed() for any n > 0.

Definition at line 93 of file xts.h.

◆ MinLastBlockSize()

unsigned int XTS_ModeBase::MinLastBlockSize ( ) const
inlinevirtual

Provides the size of the last block.

Returns
the minimum size of the last block

MinLastBlockSize() returns the minimum size of the last block. 0 indicates the last block is not special.

MandatoryBlockSize() enlists one of two behaviors. First, if MandatoryBlockSize() returns 1, then the cipher can be streamed and ProcessData() is called with the tail bytes. Second, if MandatoryBlockSize() returns non-0, then the string of bytes is padded to MandatoryBlockSize() according to the padding mode. Then, ProcessData() is called with the padded string of bytes.

Some authenticated encryption modes are not expressed well with MandatoryBlockSize() and MinLastBlockSize(). For example, AES/OCB uses 16-byte blocks (MandatoryBlockSize = 16) and the last block requires special processing (MinLastBlockSize = 0). However, 0 is a valid last block size for OCB and the special processing is custom padding, and not standard PKCS padding. In response an unambiguous IsLastBlockSpecial() was added.

See also
ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial

Reimplemented from StreamTransformation.

Definition at line 95 of file xts.h.

◆ OptimalDataAlignment()

unsigned int XTS_ModeBase::OptimalDataAlignment ( ) const
inlinevirtual

Provides input and output data alignment for optimal performance.

Returns
the input data alignment that provides optimal performance
See also
GetAlignment() and OptimalBlockSize()

Reimplemented from CipherModeBase.

Definition at line 97 of file xts.h.

◆ ThrowIfInvalidBlockSize()

void XTS_ModeBase::ThrowIfInvalidBlockSize ( size_t  length)

Validates the block size.

Parameters
lengththe block size of the cipher, in bytes
Exceptions
InvalidArgumentif the block size is invalid

If CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS is 0, then CIPHER must be a 16-byte block cipher. If CRYPTOPP_XTS_WIDE_BLOCK_CIPHERS is non-zero then CIPHER can be 16, 32, 64, or 128-byte block cipher.

Definition at line 195 of file xts.cpp.

◆ SetKey()

void XTS_ModeBase::SetKey ( const byte key,
size_t  length,
const NameValuePairs params = g_nullNameValuePairs 
)
virtual

Sets or reset the key of this object.

Parameters
keythe key to use when keying the object
lengththe size of the key, in bytes
paramsadditional initialization parameters to configure this object

Reimplemented from SimpleKeyingInterface.

Definition at line 215 of file xts.cpp.

◆ IVRequirement()

IV_Requirement XTS_ModeBase::IVRequirement ( ) const
inlinevirtual

Minimal requirement for secure IVs.

Returns
the secure IV requirement of the algorithm

Implements CipherModeBase.

Definition at line 110 of file xts.h.

◆ Resynchronize() [1/2]

void XTS_ModeBase::Resynchronize ( const byte iv,
int  ivLength = -1 
)
virtual

Resynchronize with an IV.

Parameters
ivthe initialization vector
ivLengththe size of the initialization vector, in bytes

Resynchronize() resynchronizes with an IV provided by the caller. ivLength=-1 means use IVSize().

Exceptions
NotImplemented()if the object does not support resynchronization

Reimplemented from BlockOrientedCipherModeBase.

Definition at line 231 of file xts.cpp.

◆ ProcessData()

void XTS_ModeBase::ProcessData ( byte outString,
const byte inString,
size_t  length 
)
virtual

Encrypt or decrypt an array of bytes.

Parameters
outStringthe output byte buffer
inStringthe input byte buffer
lengththe size of the input and output byte buffers, in bytes

ProcessData is called with a string of bytes whose size depends on MandatoryBlockSize. Either inString == outString, or they must not overlap.

See also
ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial

Implements StreamTransformation.

Definition at line 261 of file xts.cpp.

◆ ProcessLastBlock()

size_t XTS_ModeBase::ProcessLastBlock ( byte outString,
size_t  outLength,
const byte inString,
size_t  inLength 
)
virtual

Encrypt or decrypt the last block of data.

Parameters
outStringthe output byte buffer
outLengththe size of the output byte buffer, in bytes
inStringthe input byte buffer
inLengththe size of the input byte buffer, in bytes
Returns
the number of bytes used in outString

ProcessLastBlock is used when the last block of data is special and requires handling by the cipher. The current implementation provides an output buffer with a size inLength+2*MandatoryBlockSize(). The return value allows the cipher to expand cipher text during encryption or shrink plain text during decryption.

This member function is used by CBC-CTS and OCB modes.

See also
ProcessData, ProcessLastBlock, MandatoryBlockSize, MinLastBlockSize, BlockPaddingSchemeDef, IsLastBlockSpecial

Reimplemented from StreamTransformation.

Definition at line 373 of file xts.cpp.

◆ Resynchronize() [2/2]

void XTS_ModeBase::Resynchronize ( word64  sector,
ByteOrder  order = BIG_ENDIAN_ORDER 
)

Resynchronize the cipher.

Parameters
sectora 64-bit sector number
orderthe endian order the word should be written

The Resynchronize() overload was provided for API compatibility with the IEEE P1619 paper.

Definition at line 238 of file xts.cpp.


The documentation for this class was generated from the following files: