Security Scol plugin
Public Member Functions | Protected Types | Protected Member Functions | Protected Attributes | 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:
BlockOrientedCipherModeBase CipherModeBase SymmetricCipher SimpleKeyingInterface StreamTransformation Algorithm Clonable XTS_Final< CIPHER >

Public Member Functions

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

Protected Types

enum  { ParallelBlocks = 12 }
 

Protected Member Functions

virtual void ResizeBuffers ()
 
size_t ProcessLastPlainBlock (byte *outString, size_t outLength, const byte *inString, size_t inLength)
 
size_t ProcessLastCipherBlock (byte *outString, size_t outLength, const byte *inString, size_t inLength)
 
virtual BlockCipherAccessBlockCipher ()=0
 
virtual BlockCipherAccessTweakCipher ()=0
 
const BlockCipherGetBlockCipher () const
 
const BlockCipherGetTweakCipher () const
 
- Protected Member Functions inherited from BlockOrientedCipherModeBase
bool RequireAlignedInput () const
 
- Protected Member Functions inherited from CipherModeBase
unsigned int BlockSize () const
 
virtual void SetFeedbackSize (unsigned int feedbackSize)
 
- Protected Member Functions inherited from SymmetricCipher
const AlgorithmGetAlgorithm () const
 Returns the base class Algorithm.
 
- Protected Member Functions inherited from SimpleKeyingInterface
void ThrowIfInvalidKeyLength (size_t length)
 Validates the key length.
 
void ThrowIfResynchronizable ()
 Validates the object.
 
void ThrowIfInvalidIV (const byte *iv)
 Validates the IV.
 
size_t ThrowIfInvalidIVLength (int length)
 Validates the IV length.
 
const byteGetIVAndThrowIfInvalid (const NameValuePairs &params, size_t &size)
 Retrieves and validates the IV.
 
void AssertValidKeyLength (size_t length) const
 Validates the key length.
 

Protected Attributes

AlignedSecByteBlock m_xregister
 
AlignedSecByteBlock m_xworkspace
 
- Protected Attributes inherited from BlockOrientedCipherModeBase
SecByteBlock m_buffer
 
- Protected Attributes inherited from CipherModeBase
BlockCipherm_cipher
 
SecByteBlock m_register
 

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.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum
protected

Definition at line 145 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

◆ 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.

◆ 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.

◆ 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.

◆ GetBlockCipher()

const BlockCipher & XTS_ModeBase::GetBlockCipher ( ) const
inlineprotected

Definition at line 131 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.

◆ GetTweakCipher()

const BlockCipher & XTS_ModeBase::GetTweakCipher ( ) const
inlineprotected

Definition at line 133 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.

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ 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.

◆ ProcessLastCipherBlock()

size_t XTS_ModeBase::ProcessLastCipherBlock ( byte outString,
size_t  outLength,
const byte inString,
size_t  inLength 
)
inlineprotected

Definition at line 452 of file xts.cpp.

◆ ProcessLastPlainBlock()

size_t XTS_ModeBase::ProcessLastPlainBlock ( byte outString,
size_t  outLength,
const byte inString,
size_t  inLength 
)
inlineprotected

Definition at line 387 of file xts.cpp.

◆ ResizeBuffers()

void XTS_ModeBase::ResizeBuffers ( )
protectedvirtual

Reimplemented from BlockOrientedCipherModeBase.

Definition at line 249 of file xts.cpp.

◆ 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.

◆ 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.

◆ 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.

◆ StaticAlgorithmName()

CRYPTOPP_STATIC_CONSTEXPR const char * XTS_ModeBase::StaticAlgorithmName ( )
inline

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.

◆ ThrowIfInvalidBlockSize()

ANONYMOUS_NAMESPACE_END 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.

◆ 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.

Member Data Documentation

◆ m_xregister

AlignedSecByteBlock XTS_ModeBase::m_xregister
protected

Definition at line 137 of file xts.h.

◆ m_xworkspace

AlignedSecByteBlock XTS_ModeBase::m_xworkspace
protected

Definition at line 138 of file xts.h.


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