XTR_DH Class Reference

XTR-DH with key validation. More...

Inheritance diagram for XTR_DH:
SimpleKeyAgreementDomain CryptoParameters KeyAgreementAlgorithm GeneratableCryptoMaterial AsymmetricAlgorithm CryptoMaterial Algorithm NameValuePairs Clonable

List of all members.

Public Member Functions

 XTR_DH (const Integer &p, const Integer &q, const GFP2Element &g)
 XTR_DH (RandomNumberGenerator &rng, unsigned int pbits, unsigned int qbits)
 XTR_DH (BufferedTransformation &domainParams)
void DEREncode (BufferedTransformation &domainParams) const
 for backwards compatibility, calls GetMaterial().Save(bt)
bool Validate (RandomNumberGenerator &rng, unsigned int level) const
 Check this object for errors.
bool GetVoidValue (const char *name, const std::type_info &valueType, void *pValue) const
 Get a named value.
void AssignFrom (const NameValuePairs &source)
 Assign values to this object.
CryptoParametersAccessCryptoParameters ()
unsigned int AgreedValueLength () const
 return length of agreed value produced
unsigned int PrivateKeyLength () const
 return length of private keys in this domain
unsigned int PublicKeyLength () const
 return length of public keys in this domain
void GeneratePrivateKey (RandomNumberGenerator &rng, byte *privateKey) const
 generate private key
void GeneratePublicKey (RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
 generate public key
bool Agree (byte *agreedValue, const byte *privateKey, const byte *otherPublicKey, bool validateOtherPublicKey=true) const
 derive agreed value from your private key and couterparty's public key, return false in case of failure
const IntegerGetModulus () const
const IntegerGetSubgroupOrder () const
const GFP2ElementGetSubgroupGenerator () const
void SetModulus (const Integer &p)
void SetSubgroupOrder (const Integer &q)
void SetSubgroupGenerator (const GFP2Element &g)
virtual void GenerateKeyPair (RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const
 generate private/public key pair
CryptoMaterialAccessMaterial ()
 returns a reference to the crypto material used by this object
const CryptoMaterialGetMaterial () const
 returns a const reference to the crypto material used by this object
virtual const CryptoParametersGetCryptoParameters () const
void BERDecode (BufferedTransformation &bt)
 for backwards compatibility, calls AccessMaterial().Load(bt)
virtual std::string AlgorithmName () const
 Provides the name of this algorithm.
virtual ClonableClone () const
 Copies this object.
virtual void GenerateRandom (RandomNumberGenerator &rng, const NameValuePairs &params=g_nullNameValuePairs)
 Generate a random key or crypto parameters.
void GenerateRandomWithKeySize (RandomNumberGenerator &rng, unsigned int keySize)
 Generate a random key or crypto parameters.
virtual void ThrowIfInvalid (RandomNumberGenerator &rng, unsigned int level) const
 Check this object for errors.
virtual void Save (BufferedTransformation &bt) const
 Saves a key to a BufferedTransformation.
virtual void Load (BufferedTransformation &bt)
 Loads a key from a BufferedTransformation.
virtual bool SupportsPrecomputation () const
 Determines whether the object supports precomputation.
virtual void Precompute (unsigned int precomputationStorage)
 Perform precomputation.
virtual void LoadPrecomputation (BufferedTransformation &storedPrecomputation)
 retrieve previously saved precomputation
virtual void SavePrecomputation (BufferedTransformation &storedPrecomputation) const
 save precomputation for later use
void DoQuickSanityCheck () const
template<class T >
bool GetThisObject (T &object) const
 Get a copy of this object or subobject.
template<class T >
bool GetThisPointer (T *&ptr) const
 Get a pointer to this object.
template<class T >
bool GetValue (const char *name, T &value) const
 Get a named value.
template<class T >
GetValueWithDefault (const char *name, T defaultValue) const
 Get a named value.
std::string GetValueNames () const
 Get a list of value names that can be retrieved.
bool GetIntValue (const char *name, int &value) const
 Get a named value with type int.
int GetIntValueWithDefault (const char *name, int defaultValue) const
 Get a named value with type int, with default.
template<class T >
void GetRequiredParameter (const char *className, const char *name, T &value) const
 Retrieves a required name/value pair.
void GetRequiredIntParameter (const char *className, const char *name, int &value) const
 Retrieves a required name/value pair.

Static Public Member Functions

static void ThrowIfTypeMismatch (const char *name, const std::type_info &stored, const std::type_info &retrieving)
 Ensures an expected name and type is present.

Detailed Description

XTR-DH with key validation.

Definition at line 16 of file xtrcrypt.h.


Member Function Documentation

bool XTR_DH::Validate ( RandomNumberGenerator rng,
unsigned int  level 
) const [virtual]

Check this object for errors.

Parameters:
rng a RandomNumberGenerator for objects which use randomized testing
level the level of thoroughness
Returns:
true if the tests succeed, false otherwise

There are four levels of thoroughness:

  • 0 - using this object won't cause a crash or exception
  • 1 - this object will probably function, and encrypt, sign, other operations correctly
  • 2 - ensure this object will function correctly, and perform reasonable security checks
  • 3 - perform reasonable security checks, and do checks that may take a long time

Level 0 does not require a RandomNumberGenerator. A NullRNG() can be used for level 0.

Level 1 may not check for weak keys and such.

Levels 2 and 3 are recommended.

Implements CryptoMaterial.

Definition at line 44 of file xtrcrypt.cpp.

References Integer::One(), and Integer::Squared().

bool XTR_DH::GetVoidValue ( const char *  name,
const std::type_info &  valueType,
void *  pValue 
) const [virtual]

Get a named value.

Parameters:
name the name of the object or value to retrieve
valueType reference to a variable that receives the value
pValue void pointer to a variable that receives the value
Returns:
true if the value was retrieved, false otherwise

GetVoidValue() retrives the value of name if it exists.

Note:
GetVoidValue() is an internal function and should be implemented by derived classes. Users should use one of the other functions instead.
See also:
GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), GetRequiredParameter() and GetRequiredIntParameter()

Implements NameValuePairs.

Definition at line 62 of file xtrcrypt.cpp.

References Modulus(), SubgroupGenerator(), and SubgroupOrder().

void XTR_DH::AssignFrom ( const NameValuePairs source  )  [virtual]

Assign values to this object.

This function can be used to create a public key from a private key.

Implements CryptoMaterial.

Definition at line 71 of file xtrcrypt.cpp.

References Modulus(), SubgroupGenerator(), and SubgroupOrder().

void XTR_DH::GeneratePrivateKey ( RandomNumberGenerator rng,
byte *  privateKey 
) const [virtual]

generate private key

Precondition:
size of privateKey == PrivateKeyLength()

Implements SimpleKeyAgreementDomain.

Definition at line 80 of file xtrcrypt.cpp.

References Integer::Encode(), PrivateKeyLength(), and Integer::Zero().

void XTR_DH::GeneratePublicKey ( RandomNumberGenerator rng,
const byte *  privateKey,
byte *  publicKey 
) const [virtual]

generate public key

re size of publicKey == PublicKeyLength()

Implements SimpleKeyAgreementDomain.

Definition at line 86 of file xtrcrypt.cpp.

References PrivateKeyLength(), and PublicKeyLength().

bool XTR_DH::Agree ( byte *  agreedValue,
const byte *  privateKey,
const byte *  otherPublicKey,
bool  validateOtherPublicKey = true 
) const [virtual]

derive agreed value from your private key and couterparty's public key, return false in case of failure

Note:
If you have previously validated the public key, use validateOtherPublicKey=false to save time. re size of agreedValue == AgreedValueLength()
Precondition:
length of privateKey == PrivateKeyLength()
length of otherPublicKey == PublicKeyLength()

Implements SimpleKeyAgreementDomain.

Definition at line 94 of file xtrcrypt.cpp.

References AgreedValueLength(), PrivateKeyLength(), and PublicKeyLength().

void SimpleKeyAgreementDomain::GenerateKeyPair ( RandomNumberGenerator rng,
byte *  privateKey,
byte *  publicKey 
) const [virtual, inherited]

generate private/public key pair

Note:
equivalent to calling GeneratePrivateKey() and then GeneratePublicKey()

Definition at line 921 of file cryptlib.cpp.

References SimpleKeyAgreementDomain::GeneratePrivateKey(), and SimpleKeyAgreementDomain::GeneratePublicKey().

virtual std::string Algorithm::AlgorithmName (  )  const [inline, virtual, inherited]

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 in Adler32, CCM_Base, CRC32, ClassNullRNG, AuthenticatedSymmetricCipher, DH_Domain< GROUP_PARAMETERS, COFACTOR_OPTION >, EAX_Base, StreamTransformationFilter, HashFilter, HashVerificationFilter, AuthenticatedDecryptionFilter, SignerFilter, SignatureVerificationFilter, GCM_Base, HMAC< T >, RDRAND, RDSEED, SHA3, BitBucket, and VMAC_Base.

Definition at line 488 of file cryptlib.h.

Referenced by BufferedTransformation::ChannelCreatePutSpace(), BufferedTransformation::ChannelFlush(), BufferedTransformation::ChannelMessageSeriesEnd(), BufferedTransformation::ChannelPut2(), TF_DecryptorBase::Decrypt(), TF_EncryptorBase::Encrypt(), StreamTransformation::ProcessLastBlock(), and PK_DefaultDecryptionFilter::Put2().

virtual Clonable* Clonable::Clone (  )  const [inline, virtual, inherited]

Copies this object.

Returns:
a copy of this object
Exceptions:
NotImplemented 
Note:
this is not implemented by most classes
See also:
NotCopyable

Definition at line 464 of file cryptlib.h.

virtual void GeneratableCryptoMaterial::GenerateRandom ( RandomNumberGenerator rng,
const NameValuePairs params = g_nullNameValuePairs 
) [inline, virtual, inherited]

Generate a random key or crypto parameters.

Parameters:
rng a RandomNumberGenerator to produce keying material
params additional initialization parameters
Exceptions:
KeyingErr if a key can't be generated or algorithm parameters are invalid

If a derived class does not override GenerateRandom, then the base class throws NotImplemented.

Reimplemented in DL_GroupParameters_EC< EC >, DL_GroupParameters_EC< EC >, InvertibleESIGNFunction, DL_GroupParameters_IntegerBased, DL_GroupParameters_DSA, InvertibleLUCFunction, DL_PrivateKeyImpl< GP >, InvertibleRabinFunction, InvertibleRSAFunction, InvertibleRWFunction, and DL_PrivateKeyImpl< DL_GroupParameters_EC< EC > >.

Definition at line 2019 of file cryptlib.h.

Referenced by GeneratableCryptoMaterial::GenerateRandomWithKeySize().

void GeneratableCryptoMaterial::GenerateRandomWithKeySize ( RandomNumberGenerator rng,
unsigned int  keySize 
) [inherited]

Generate a random key or crypto parameters.

Parameters:
rng a RandomNumberGenerator to produce keying material
keySize the size of the key, in bits
Exceptions:
KeyingErr if a key can't be generated or algorithm parameters are invalid

GenerateRandomWithKeySize calls GenerateRandom with a NameValuePairs object with only "KeySize"

Definition at line 771 of file cryptlib.cpp.

References GeneratableCryptoMaterial::GenerateRandom(), and MakeParameters().

virtual void CryptoMaterial::ThrowIfInvalid ( RandomNumberGenerator rng,
unsigned int  level 
) const [inline, virtual, inherited]

Check this object for errors.

Parameters:
rng a RandomNumberGenerator for objects which use randomized testing
level the level of thoroughness
Exceptions:
InvalidMaterial 

Internally, ThrowIfInvalid() calls Validate() and throws InvalidMaterial if validation fails.

Definition at line 1939 of file cryptlib.h.

virtual void CryptoMaterial::Save ( BufferedTransformation bt  )  const [inline, virtual, inherited]

Saves a key to a BufferedTransformation.

Parameters:
bt the destination BufferedTransformation
Exceptions:
NotImplemented 

Save writes the material to a BufferedTransformation.

If the material is a key, then the key is written with ASN.1 DER encoding. The key includes an object identifier with an algorthm id, like a subjectPublicKeyInfo.

A "raw" key without the "key info" can be saved using a key's DEREncode method.

If a derived class does not override Save, then the base class throws NotImplemented.

Reimplemented in InvertibleRSAFunction, RWFunction, and InvertibleRWFunction.

Definition at line 1951 of file cryptlib.h.

virtual void CryptoMaterial::Load ( BufferedTransformation bt  )  [inline, virtual, inherited]

Loads a key from a BufferedTransformation.

Parameters:
bt the source BufferedTransformation
Exceptions:
KeyingErr 

Load attempts to read material from a BufferedTransformation. If the material is a key that was generated outside the library, then the following usually applies:

  • the key should be ASN.1 BER encoded
  • the key should be a "key info"

"key info" means the key should have an object identifier with an algorthm id, like a subjectPublicKeyInfo.

To read a "raw" key without the "key info", then call the key's BERDecode method.

Note:
Load generally does not check that the key is valid. Call Validate(), if needed.

Reimplemented in InvertibleRSAFunction, RWFunction, and InvertibleRWFunction.

Definition at line 1968 of file cryptlib.h.

virtual bool CryptoMaterial::SupportsPrecomputation (  )  const [inline, virtual, inherited]

Determines whether the object supports precomputation.

Returns:
true if the object supports precomputation, false otherwise

Reimplemented in DL_GroupParameters< T >, DL_PrivateKeyImpl< GP >, DL_PublicKeyImpl< GP >, DL_GroupParameters< Integer >, DL_GroupParameters< typenameEcPrecomputation< EC >::Element >, DL_PrivateKeyImpl< DL_GroupParameters_EC< EC > >, and DL_PublicKeyImpl< DL_GroupParameters_EC< EC > >.

Definition at line 1973 of file cryptlib.h.

virtual void CryptoMaterial::Precompute ( unsigned int  precomputationStorage  )  [inline, virtual, inherited]

Perform precomputation.

Parameters:
precomputationStorage the suggested number of objects for the precompute table
Exceptions:
NotImplemented 

The exact semantics of Precompute() varies, but it typically means calculate a table of n objects that can be used later to speed up computation.

If a derived class does not override Precompute, then the base class throws NotImplemented.

Reimplemented in DL_GroupParameters< T >, DL_PrivateKeyImpl< GP >, DL_PublicKeyImpl< GP >, DL_GroupParameters< Integer >, DL_GroupParameters< typenameEcPrecomputation< EC >::Element >, DL_PrivateKeyImpl< DL_GroupParameters_EC< EC > >, and DL_PublicKeyImpl< DL_GroupParameters_EC< EC > >.

Definition at line 1982 of file cryptlib.h.

template<class T >
bool NameValuePairs::GetThisObject ( T &  object  )  const [inline, inherited]

Get a copy of this object or subobject.

Template Parameters:
T class or type
Parameters:
object reference to a variable that receives the value

Definition at line 297 of file cryptlib.h.

Referenced by DL_PrivateKeyImpl< DL_GroupParameters_EC< EC > >::GenerateRandom().

template<class T >
bool NameValuePairs::GetThisPointer ( T *&  ptr  )  const [inline, inherited]

Get a pointer to this object.

Template Parameters:
T class or type
Parameters:
ptr reference to a pointer to a variable that receives the value

Definition at line 306 of file cryptlib.h.

template<class T >
bool NameValuePairs::GetValue ( const char *  name,
T &  value 
) const [inline, inherited]

Get a named value.

Template Parameters:
T class or type
Parameters:
name the name of the object or value to retrieve
value reference to a variable that receives the value
Returns:
true if the value was retrieved, false otherwise
See also:
GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), GetRequiredParameter() and GetRequiredIntParameter()

Definition at line 319 of file cryptlib.h.

Referenced by DL_GroupParameters_EC< EC >::AssignFrom(), DL_GroupParameters_IntegerBased::GenerateRandom(), DL_GroupParameters_DSA::GenerateRandom(), InvertibleESIGNFunction::GenerateRandom(), Inflator::IsolatedInitialize(), StringSinkTemplate< T >::IsolatedInitialize(), ArraySink::IsolatedInitialize(), FileSink::IsolatedInitialize(), and Grouper::IsolatedInitialize().

template<class T >
T NameValuePairs::GetValueWithDefault ( const char *  name,
defaultValue 
) const [inline, inherited]
std::string NameValuePairs::GetValueNames (  )  const [inline, inherited]

Get a list of value names that can be retrieved.

Returns:
a list of names available to retrieve

the items in the list are delimited with a colon.

Definition at line 344 of file cryptlib.h.

bool NameValuePairs::GetIntValue ( const char *  name,
int &  value 
) const [inline, inherited]

Get a named value with type int.

Parameters:
name the name of the value to retrieve
value the value retrieved upon success
Returns:
true if an int value was retrieved, false otherwise

GetIntValue() is used to ensure we don't accidentally try to get an unsigned int or some other type when we mean int (which is the most common case)

See also:
GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), GetRequiredParameter() and GetRequiredIntParameter()

Definition at line 355 of file cryptlib.h.

Referenced by InvertibleRWFunction::GenerateRandom(), InvertibleRSAFunction::GenerateRandom(), InvertibleRabinFunction::GenerateRandom(), InvertibleLUCFunction::GenerateRandom(), DL_GroupParameters_IntegerBased::GenerateRandom(), DL_GroupParameters_DSA::GenerateRandom(), and InvertibleESIGNFunction::GenerateRandom().

int NameValuePairs::GetIntValueWithDefault ( const char *  name,
int  defaultValue 
) const [inline, inherited]

Get a named value with type int, with default.

Parameters:
name the name of the value to retrieve
defaultValue the default value if the name does not exist
Returns:
the value retrieved on success or the default value
See also:
GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), GetRequiredParameter() and GetRequiredIntParameter()

Definition at line 364 of file cryptlib.h.

Referenced by DL_GroupParameters_IntegerBased::GenerateRandom(), Redirector::Initialize(), Deflator::IsolatedInitialize(), ByteQueue::IsolatedInitialize(), HashFilter::IsolatedInitialize(), Grouper::IsolatedInitialize(), Base64URLEncoder::IsolatedInitialize(), VMAC_Base::UncheckedSetKey(), SAFER::Base::UncheckedSetKey(), and Weak1::ARC4_Base::UncheckedSetKey().

static void NameValuePairs::ThrowIfTypeMismatch ( const char *  name,
const std::type_info &  stored,
const std::type_info &  retrieving 
) [inline, static, inherited]

Ensures an expected name and type is present.

Parameters:
name the name of the value
stored the type that was stored for the name
retrieving the type that is being retrieved for the name
Exceptions:
ValueTypeMismatch 

ThrowIfTypeMismatch() effectively performs a type safety check. stored and retrieving are C++ mangled names for the type.

See also:
GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), GetRequiredParameter() and GetRequiredIntParameter()

Definition at line 376 of file cryptlib.h.

Referenced by DL_GroupParameters_EC< EC >::GetVoidValue().

template<class T >
void NameValuePairs::GetRequiredParameter ( const char *  className,
const char *  name,
T &  value 
) const [inline, inherited]

Retrieves a required name/value pair.

Template Parameters:
T class or type
Parameters:
className the name of the class
name the name of the value
value reference to a variable to receive the value
Exceptions:
InvalidArgument 

GetRequiredParameter() throws InvalidArgument if the name is not present or not of the expected type T.

See also:
GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), GetRequiredParameter() and GetRequiredIntParameter()

Definition at line 390 of file cryptlib.h.

Referenced by DL_GroupParameters_EC< EC >::AssignFrom(), RandomNumberSink::IsolatedInitialize(), Grouper::IsolatedInitialize(), and BaseN_Decoder::IsolatedInitialize().

void NameValuePairs::GetRequiredIntParameter ( const char *  className,
const char *  name,
int &  value 
) const [inline, inherited]

Retrieves a required name/value pair.

Parameters:
className the name of the class
name the name of the value
value reference to a variable to receive the value
Exceptions:
InvalidArgument 

GetRequiredParameter() throws InvalidArgument if the name is not present or not of the expected type T.

See also:
GetValue(), GetValueWithDefault(), GetIntValue(), GetIntValueWithDefault(), GetRequiredParameter() and GetRequiredIntParameter()

Definition at line 405 of file cryptlib.h.

Referenced by BaseN_Decoder::IsolatedInitialize().


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

Generated on 24 Mar 2016 for Crypto++ by  doxygen 1.6.1