cryptlib.h File Reference

Abstract base classes that provide a uniform interface to this library. More...

Go to the source code of this file.

## Classes

struct | EnumToType< ENUM_TYPE, VALUE >
| Converts an enumeration to a type suitable for use as a template parameter. More...
class | Exception
| Base class for all exceptions thrown by the library. More...
class | InvalidArgument
| An invalid argument was detected. More...
class | InvalidDataFormat
| Input data was received that did not conform to expected format. More...
class | InvalidCiphertext
| A decryption filter encountered invalid ciphertext. More...
class | NotImplemented
| A method was called which was not implemented. More...
class | CannotFlush
| Flush(true) was called but it can't completely flush its buffers. More...
class | OS_Error
| The operating system reported an error. More...
struct | DecodingResult
| Returns a decoding results. More...
class | NameValuePairs
| Interface for retrieving values given their names. More...
class | NameValuePairs::ValueTypeMismatch
| Thrown when an unexpected type is encountered. More...
class | Clonable
| Interface for cloning objects. More...
class | Algorithm
| Interface for all crypto algorithms. More...
class | SimpleKeyingInterface
| Interface for algorithms that take byte strings as keys. More...
class | BlockTransformation
| Interface for the data processing part of block ciphers. More...
class | StreamTransformation
| Interface for the data processing portion of stream ciphers. More...
class | HashTransformation
| Interface for hash functions and data processing part of MACs. More...
class | BlockCipher
| Interface for one direction (encryption or decryption) of a block cipher. More...
class | SymmetricCipher
| Interface for one direction (encryption or decryption) of a stream cipher or cipher mode. More...
class | MessageAuthenticationCode
| Interface for message authentication codes. More...
class | AuthenticatedSymmetricCipher
| Interface for authenticated encryption modes of operation. More...
class | AuthenticatedSymmetricCipher::BadState
| Exception thrown when the object is in the wrong state for the operation. More...
class | RandomNumberGenerator
| Interface for random number generators. More...
class | KeyDerivationFunction
| Interface for key derivation functions. More...
struct | PasswordBasedKeyDerivationFunction
| Interface for password based key derivation functions. More...
class | Waitable
| Interface for objects that can be waited on. More...
class | BufferedTransformation
| Interface for buffered transformations. More...
struct | BufferedTransformation::BlockingInputOnly
| Exception thrown by objects that have not implemented nonblocking input processing. More...
struct | BufferedTransformation::NoChannelSupport
| Exception thrown when a filter does not support named channels. More...
struct | BufferedTransformation::InvalidChannelName
| Exception thrown when a filter does not recognize a named channel. More...
class | CryptoMaterial
| Interface for crypto material. More...
class | CryptoMaterial::InvalidMaterial
| Exception thrown when invalid crypto material is detected. More...
class | GeneratableCryptoMaterial
| Interface for crypto material. More...
class | PublicKey
| Interface for public keys. More...
class | PrivateKey
| Interface for private keys. More...
class | CryptoParameters
| Interface for crypto parameters. More...
class | Certificate
| Interface for certificates. More...
class | AsymmetricAlgorithm
| Interface for asymmetric algorithms. More...
class | PublicKeyAlgorithm
| Interface for asymmetric algorithms using public keys. More...
class | PrivateKeyAlgorithm
| Interface for asymmetric algorithms using private keys. More...
class | KeyAgreementAlgorithm
| Interface for key agreement algorithms. More...
class | PK_CryptoSystem
| Interface for public-key encryptors and decryptors. More...
class | PK_Encryptor
| Interface for public-key encryptors. More...
class | PK_Encryptor::InvalidPlaintextLength
| Exception thrown when trying to encrypt plaintext of invalid length. More...
class | PK_Decryptor
| Interface for public-key decryptors. More...
class | PK_SignatureScheme
| Interface for public-key signers and verifiers. More...
class | PK_SignatureScheme::InvalidKeyLength
| Exception throw when the private or public key has a length that can't be used. More...
class | PK_SignatureScheme::KeyTooShort
| Exception throw when the private or public key is too short to sign or verify. More...
class | PK_MessageAccumulator
| Interface for accumulating messages to be signed or verified. More...
class | PK_Signer
| Interface for public-key signers. More...
class | PK_Verifier
| Interface for public-key signature verifiers. More...
class | SimpleKeyAgreementDomain
| Interface for domains of simple key agreement protocols. More...
class | AuthenticatedKeyAgreementDomain
| Interface for domains of authenticated key agreement protocols. More...
class | BERDecodeErr
| Exception thrown when an ASN.1 BER decoing error is encountered. More...
class | ASN1Object
| Interface for encoding and decoding ASN1 objects. More...

## Namespaces

namespace | Name
| Namespace containing value name definitions.
namespace | Weak
| Namespace containing weak and wounded algorithms.
namespace | NaCl
| Namespace containing NaCl library functions.
namespace | Test
| Namespace containing testing and benchmark classes.

## Typedefs

typedef EnumToType< ByteOrder, LITTLE_ENDIAN_ORDER > | LittleEndian
| Provides a constant for LittleEndian.
typedef EnumToType< ByteOrder, BIG_ENDIAN_ORDER > | BigEndian
| Provides a constant for BigEndian.

## Enumerations

enum | CipherDir { ENCRYPTION , DECRYPTION }
| Specifies a direction for a cipher to operate. More...
enum | ByteOrder { LITTLE_ENDIAN_ORDER = 0 , BIG_ENDIAN_ORDER = 1 }
| Provides the byte ordering. More...

## Functions

CRYPTOPP_DLL RandomNumberGenerator & | NullRNG ()
| Random Number Generator that does not produce random numbers.
CRYPTOPP_DLL BufferedTransformation & | TheBitBucket ()
| An input discarding BufferedTransformation.
int | LibraryVersion (...)
| Specifies the build-time version of the library.
int | HeaderVersion ()
| Specifies the runtime version of the library.

## Variables

const unsigned long | INFINITE_TIME = ULONG_MAX
| Represents infinite time.
const std::string | DEFAULT_CHANNEL
| Default channel for BufferedTransformation.
const std::string | AAD_CHANNEL
| Channel for additional authenticated data.
const NameValuePairs & | g_nullNameValuePairs
| An empty set of name-value pairs.

## Detailed Description

Abstract base classes that provide a uniform interface to this library.

Definition in file cryptlib.h.

## Typedef Documentation

## LittleEndian

typedef EnumToType<ByteOrder, LITTLE_ENDIAN_ORDER> LittleEndian

Provides a constant for LittleEndian.

Definition at line 155 of file cryptlib.h.

## BigEndian

typedef EnumToType<ByteOrder, BIG_ENDIAN_ORDER> BigEndian

Provides a constant for BigEndian.

Definition at line 157 of file cryptlib.h.

## Enumeration Type Documentation

## CipherDir

enum CipherDir

Specifies a direction for a cipher to operate.

See also
  BlockTransformation::IsForwardTransformation(), BlockTransformation::IsPermutation(), BlockTransformation::GetCipherDirection()

Enumerator
ENCRYPTION | the cipher is performing encryption
DECRYPTION | the cipher is performing decryption

Definition at line 128 of file cryptlib.h.

## ByteOrder

enum ByteOrder

Provides the byte ordering.

Big-endian and little-endian modes are supported. Bi-endian and PDP-endian modes are not supported.

Enumerator
LITTLE_ENDIAN_ORDER | byte order is little-endian
BIG_ENDIAN_ORDER | byte order is big-endian

Definition at line 148 of file cryptlib.h.

## Function Documentation

## NullRNG()

CRYPTOPP_DLL RandomNumberGenerator & NullRNG | ( |  | ) |

Random Number Generator that does not produce random numbers.

Returns
  reference that can be passed to functions that require a RandomNumberGenerator

NullRNG() returns a reference that can be passed to functions that require a RandomNumberGenerator but don't actually use it. The NullRNG() throws NotImplemented when a generation function is called.

See also
  ClassNullRNG, PK_SignatureScheme::IsProbabilistic()

## TheBitBucket()

CRYPTOPP_DLL BufferedTransformation & TheBitBucket | ( |  | ) |

An input discarding BufferedTransformation.

Returns
  a reference to a BufferedTransformation object that discards all input

## LibraryVersion()

int LibraryVersion | ( |  | ... | ) |

Specifies the build-time version of the library.

Returns
  integer representing the build-time version

LibraryVersion can help detect inadvertent mixing and matching of library versions. When using Crypto++ distributed by a third party, LibraryVersion() records the version of the shared object that was built by the third party. The LibraryVersion() record resides in cryptlib.o on Unix compatibles and cryptlib.obj on Windows. It does not change when an app links to the library.

LibraryVersion() is declared with C linkage (extern "C") within the CryptoPP namespace to help programs locate the symbol. If the symbol is present, then the library version is 5.7 or above. If it is missing, then the library version is 5.6.5 or below.

The function could be used as shown below.

      if (LibraryVersion() != HeaderVersion())
      {
         cout << "Potential version mismatch" << endl;

         const int lmaj = (LibraryVersion() / 100U) % 10;
         const int lmin = (LibraryVersion() / 10U) % 10;
         const int hmaj = (HeaderVersion() / 100U) % 10;
         const int hmin = (HeaderVersion() / 10U) % 10;

         if(lmaj != hmaj)
            cout << "Major version mismatch" << endl;
         else if(lmin != hmin)
            cout << "Minor version mismatch" << endl;
      }

See also
  HeaderVersion(), GitHub Issue 371.

Since
  Crypto++ 6.0

## HeaderVersion()

int HeaderVersion | ( |  | ) |

inline

Specifies the runtime version of the library.

Returns
  integer representing the runtime version

HeaderVersion() can help detect inadvertent mixing and matching of library versions. When using Crypto++ distributed by a third party, HeaderVersion() records the version of the headers used by the app when the app is compiled.

HeaderVersion() is declared with C linkage (extern "C") within the CryptoPP namespace to help programs locate the symbol. If the symbol is present, then the library version is 5.7 or above. If it is missing, then the library version is 5.6.5 or below.

The function could be used as shown below.

      if (LibraryVersion() != HeaderVersion())
      {
         cout << "Potential version mismatch" << endl;

         const int lmaj = (LibraryVersion() / 100U) % 10;
         const int lmin = (LibraryVersion() / 10U) % 10;
         const int hmaj = (HeaderVersion() / 100U) % 10;
         const int hmin = (HeaderVersion() / 10U) % 10;

         if(lmaj != hmaj)
            cout << "Major version mismatch" << endl;
         else if(lmin != hmin)
            cout << "Minor version mismatch" << endl;
      }

See also
  LibraryVersion(), GitHub Issue 371.

Since
  Crypto++ 6.0

Definition at line 3372 of file cryptlib.h.

## Variable Documentation

## INFINITE_TIME

const unsigned long INFINITE_TIME = ULONG_MAX

Represents infinite time.

Definition at line 135 of file cryptlib.h.

## DEFAULT_CHANNEL

const std::string DEFAULT_CHANNEL

Default channel for BufferedTransformation.

DEFAULT_CHANNEL is equal to an empty string

The definition for DEFAULT_CHANNEL is in cryptlib.cpp. It can be subject to Static Initialization Order Fiasco. If you experience a crash in DEFAULT_CHANNEL where the string object is NULL, then you probably have a global object using DEFAULT_CHANNEL before it has been constructed.

Definition at line 516 of file cryptlib.h.

## AAD_CHANNEL

const std::string AAD_CHANNEL

Channel for additional authenticated data.

AAD_CHANNEL is equal to "AAD"

The definition for AAD_CHANNEL is in cryptlib.cpp. It can be subject to Static Initialization Order Fiasco. If you experience a crash in AAD_CHANNEL where the string object is NULL, then you probably have a global object using AAD_CHANNEL before it has been constructed.

Definition at line 525 of file cryptlib.h.

## g_nullNameValuePairs

const NameValuePairs& g_nullNameValuePairs

An empty set of name-value pairs.

The definition for g_nullNameValuePairs is in cryptlib.cpp. It can be subject to Static Initialization Order Fiasco. If you experience a crash in g_nullNameValuePairs where the string object is NULL, then you probably have a global object using g_nullNameValuePairs before it has been constructed.

Definition at line 534 of file cryptlib.h.