Crypto++ 8.6 Free C++ class library of cryptographic schemes

Public Types | Public Member Functions | List of all members
HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH > Class Template Reference

Hashed Menezes-Qu-Vanstone in GF(p) More...

Inheritance diagram for HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >:

## Public Types
typedef GROUP_PARAMETERS | GroupParameters
typedef GroupParameters::Element | Element
typedef HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH > | Domain

## Public Member Functions
| HMQV_Domain (bool clientRole=true)
| Construct a HMQV domain. More...
| HMQV_Domain (const GroupParameters &params, bool clientRole=true)
| Construct a HMQV domain. More...
| HMQV_Domain (BufferedTransformation &bt, bool clientRole=true)
| Construct a HMQV domain. More...
template<class T1 >
| HMQV_Domain (T1 v1, bool clientRole=true)
| Construct a HMQV domain. More...
template<class T1 , class T2 >
| HMQV_Domain (T1 v1, T2 v2, bool clientRole=true)
| Construct a HMQV domain. More...
template<class T1 , class T2 , class T3 >
| HMQV_Domain (T1 v1, T2 v2, T3 v3, bool clientRole=true)
| Construct a HMQV domain. More...
template<class T1 , class T2 , class T3 , class T4 >
| HMQV_Domain (T1 v1, T2 v2, T3 v3, T4 v4, bool clientRole=true)
| Construct a HMQV domain. More...
const GroupParameters & | GetGroupParameters () const
| Retrieves the group parameters for this domain. More...
GroupParameters & | AccessGroupParameters ()
| Retrieves the group parameters for this domain. More...
CryptoParameters & | AccessCryptoParameters ()
| Retrieves the crypto parameters for this domain. More...
unsigned int | AgreedValueLength () const
| Provides the size of the agreed value. More...
unsigned int | StaticPrivateKeyLength () const
| Provides the size of the static private key. More...
unsigned int | StaticPublicKeyLength () const
| Provides the size of the static public key. More...
void | GenerateStaticPrivateKey (RandomNumberGenerator &rng, byte *privateKey) const
| Generate static private key in this domain. More...
void | GenerateStaticPublicKey (RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
| Generate a static public key from a private key in this domain. More...
unsigned int | EphemeralPrivateKeyLength () const
| Provides the size of the ephemeral private key. More...
unsigned int | EphemeralPublicKeyLength () const
| Provides the size of the ephemeral public key. More...
void | GenerateEphemeralPrivateKey (RandomNumberGenerator &rng, byte *privateKey) const
| Generate ephemeral private key in this domain. More...
void | GenerateEphemeralPublicKey (RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
| Generate ephemeral public key from a private key in this domain. More...
bool | Agree (byte *agreedValue, const byte *staticPrivateKey, const byte *ephemeralPrivateKey, const byte *staticOtherPublicKey, const byte *ephemeralOtherPublicKey, bool validateStaticOtherPublicKey=true) const
| Derive agreed value or shared secret. More...
Public Member Functions inherited from AuthenticatedKeyAgreementDomain
virtual void | GenerateStaticKeyPair (RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const
| Generate a static private/public key pair. More...
virtual void | GenerateEphemeralKeyPair (RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const
| Generate private/public key pair. More...
Public Member Functions inherited from KeyAgreementAlgorithm
CryptoMaterial & | AccessMaterial ()
| Retrieves a reference to Crypto Parameters. More...
const CryptoMaterial & | GetMaterial () const
| Retrieves a reference to Crypto Parameters. More...
virtual const CryptoParameters & | GetCryptoParameters () const
| Retrieves a reference to Crypto Parameters. 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 Clonable * | Clone () const
| Copies this object. More...

## Detailed Description

### template<class GROUP_PARAMETERS, class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>
class HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >

Hashed Menezes-Qu-Vanstone in GF(p)

This implementation follows Hugo Krawczyk's HMQV: A High-Performance Secure Diffie-Hellman Protocol. Note: this implements HMQV only. HMQV-C with Key Confirmation is not provided.

See also
  MQV, HMQV, FHMQV, and AuthenticatedKeyAgreementDomain

Since
  Crypto++ 5.6.4

Definition at line 23 of file hmqv.h.

## Constructor & Destructor Documentation

## ◆ HMQV_Domain() [1/7]

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::HMQV_Domain | ( | bool | clientRole = `true` | ) |
| inline

Construct a HMQV domain.

Parameters

  clientRole | flag indicating initiator or recipient

`clientRole = true` indicates initiator, and `clientRole = false` indicates recipient or server.

Definition at line 36 of file hmqv.h.

## ◆ HMQV_Domain() [2/7]

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::HMQV_Domain | ( | const GroupParameters & | params,
|  | bool | clientRole = `true`
| ) |  |
| inline

Construct a HMQV domain.

Parameters

  params | group parameters and options
  clientRole | flag indicating initiator or recipient

`clientRole = true` indicates initiator, and `clientRole = false` indicates recipient or server.

Definition at line 44 of file hmqv.h.

## ◆ HMQV_Domain() [3/7]

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::HMQV_Domain | ( | BufferedTransformation & | bt,
|  | bool | clientRole = `true`
| ) |  |
| inline

Construct a HMQV domain.

Parameters

  bt | BufferedTransformation with group parameters and options
  clientRole | flag indicating initiator or recipient

`clientRole = true` indicates initiator, and `clientRole = false` indicates recipient or server.

Definition at line 52 of file hmqv.h.

## ◆ HMQV_Domain() [4/7]

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>
template<class T1 >

HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::HMQV_Domain | ( | T1 | v1,
|  | bool | clientRole = `true`
| ) |  |
| inline

Construct a HMQV domain.

Template Parameters

  T1 | template parameter used as a constructor parameter

Parameters

  v1 | first parameter
  clientRole | flag indicating initiator or recipient

v1 is passed directly to the GROUP_PARAMETERS object.

`clientRole = true` indicates initiator, and `clientRole = false` indicates recipient or server.

Definition at line 64 of file hmqv.h.

## ◆ HMQV_Domain() [5/7]

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>
template<class T1 , class T2 >

HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::HMQV_Domain | ( | T1 | v1,
|  | T2 | v2,
|  | bool | clientRole = `true`
| ) |  |
| inline

Construct a HMQV domain.

Template Parameters

  T1 | template parameter used as a constructor parameter
  T2 | template parameter used as a constructor parameter

Parameters

  v1 | first parameter
  v2 | second parameter
  clientRole | flag indicating initiator or recipient

v1 and v2 are passed directly to the GROUP_PARAMETERS object.

`clientRole = true` indicates initiator, and `clientRole = false` indicates recipient or server.

Definition at line 78 of file hmqv.h.

## ◆ HMQV_Domain() [6/7]

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>
template<class T1 , class T2 , class T3 >

HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::HMQV_Domain | ( | T1 | v1,
|  | T2 | v2,
|  | T3 | v3,
|  | bool | clientRole = `true`
| ) |  |
| inline

Construct a HMQV domain.

Template Parameters

  T1 | template parameter used as a constructor parameter
  T2 | template parameter used as a constructor parameter
  T3 | template parameter used as a constructor parameter

Parameters

  v1 | first parameter
  v2 | second parameter
  v3 | third parameter
  clientRole | flag indicating initiator or recipient

v1, v2 and v3 are passed directly to the GROUP_PARAMETERS object.

`clientRole = true` indicates initiator, and `clientRole = false` indicates recipient or server.

Definition at line 94 of file hmqv.h.

## ◆ HMQV_Domain() [7/7]

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>
template<class T1 , class T2 , class T3 , class T4 >

HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::HMQV_Domain | ( | T1 | v1,
|  | T2 | v2,
|  | T3 | v3,
|  | T4 | v4,
|  | bool | clientRole = `true`
| ) |  |
| inline

Construct a HMQV domain.

Template Parameters

  T1 | template parameter used as a constructor parameter
  T2 | template parameter used as a constructor parameter
  T3 | template parameter used as a constructor parameter
  T4 | template parameter used as a constructor parameter

Parameters

  v1 | first parameter
  v2 | second parameter
  v3 | third parameter
  v4 | third parameter
  clientRole | flag indicating initiator or recipient

v1, v2, v3 and v4 are passed directly to the GROUP_PARAMETERS object.

`clientRole = true` indicates initiator, and `clientRole = false` indicates recipient or server.

Definition at line 112 of file hmqv.h.

## Member Function Documentation

## ◆ GetGroupParameters()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

const GroupParameters& HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::GetGroupParameters | ( |  | ) | const
| inline

Retrieves the group parameters for this domain.

Returns
  the group parameters for this domain as a const reference

Definition at line 120 of file hmqv.h.

## ◆ AccessGroupParameters()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

GroupParameters& HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::AccessGroupParameters | ( |  | ) |
| inline

Retrieves the group parameters for this domain.

Returns
  the group parameters for this domain as a non-const reference

Definition at line 124 of file hmqv.h.

## ◆ AccessCryptoParameters()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

CryptoParameters& HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::AccessCryptoParameters | ( |  | ) |
| inline virtual

Retrieves the crypto parameters for this domain.

Returns
  the crypto parameters for this domain as a non-const reference

Implements KeyAgreementAlgorithm.

Definition at line 128 of file hmqv.h.

## ◆ AgreedValueLength()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

unsigned int HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::AgreedValueLength | ( |  | ) | const
| inline virtual

Provides the size of the agreed value.

Returns
  size of agreed value produced in this domain

The length is calculated using `GetEncodedElementSize(false)`, which means the element is encoded in a non-reversible format. A non-reversible format means its a raw byte array, and it lacks presentation format like an ASN.1 BIT_STRING or OCTET_STRING.

Implements AuthenticatedKeyAgreementDomain.

Definition at line 136 of file hmqv.h.

## ◆ StaticPrivateKeyLength()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

unsigned int HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::StaticPrivateKeyLength | ( |  | ) | const
| inline virtual

Provides the size of the static private key.

Returns
  size of static private keys in this domain

The length is calculated using the byte count of the subgroup order.

Implements AuthenticatedKeyAgreementDomain.

Definition at line 142 of file hmqv.h.

## ◆ StaticPublicKeyLength()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

unsigned int HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::StaticPublicKeyLength | ( |  | ) | const
| inline virtual

Provides the size of the static public key.

Returns
  size of static public keys in this domain

The length is calculated using `GetEncodedElementSize(true)`, which means the element is encoded in a reversible format. A reversible format means it has a presentation format, and its an ANS.1 encoded element or point.

Implements AuthenticatedKeyAgreementDomain.

Definition at line 151 of file hmqv.h.

## ◆ GenerateStaticPrivateKey()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

void HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::GenerateStaticPrivateKey | ( | RandomNumberGenerator & | rng,
|  | byte * | privateKey
| ) |  | const
| inline virtual

Generate static private key in this domain.

Parameters

  rng | a RandomNumberGenerator derived class
  privateKey | a byte buffer for the generated private key in this domain

The private key is a random scalar used as an exponent in the range `[1,MaxExponent()]`.

Precondition
  `COUNTOF(privateKey) == PrivateStaticKeyLength()`

Implements AuthenticatedKeyAgreementDomain.

Definition at line 160 of file hmqv.h.

## ◆ GenerateStaticPublicKey()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

void HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::GenerateStaticPublicKey | ( | RandomNumberGenerator & | rng,
|  | const byte * | privateKey,
|  | byte * | publicKey
| ) |  | const
| inline virtual

Generate a static public key from a private key in this domain.

Parameters

  rng | a RandomNumberGenerator derived class
  privateKey | a byte buffer with the previously generated private key
  publicKey | a byte buffer for the generated public key in this domain

The public key is an element or point on the curve, and its stored in a revrsible format. A reversible format means it has a presentation format, and its an ANS.1 encoded element or point.

Precondition
  `COUNTOF(publicKey) == PublicStaticKeyLength()`

Implements AuthenticatedKeyAgreementDomain.

Definition at line 174 of file hmqv.h.

## ◆ EphemeralPrivateKeyLength()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

unsigned int HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::EphemeralPrivateKeyLength | ( |  | ) | const
| inline virtual

Provides the size of the ephemeral private key.

Returns
  size of ephemeral private keys in this domain

An ephemeral private key is a private key and public key. The serialized size is different than a static private key.

Implements AuthenticatedKeyAgreementDomain.

Definition at line 187 of file hmqv.h.

## ◆ EphemeralPublicKeyLength()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

unsigned int HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::EphemeralPublicKeyLength | ( |  | ) | const
| inline virtual

Provides the size of the ephemeral public key.

Returns
  size of ephemeral public keys in this domain

An ephemeral public key is a public key. The serialized size is the same as a static public key.

Implements AuthenticatedKeyAgreementDomain.

Definition at line 193 of file hmqv.h.

## ◆ GenerateEphemeralPrivateKey()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

void HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::GenerateEphemeralPrivateKey | ( | RandomNumberGenerator & | rng,
|  | byte * | privateKey
| ) |  | const
| inline virtual

Generate ephemeral private key in this domain.

Parameters

  rng | a RandomNumberGenerator derived class
  privateKey | a byte buffer for the generated private key in this domain

Precondition
  `COUNTOF(privateKey) == EphemeralPrivateKeyLength()`

Implements AuthenticatedKeyAgreementDomain.

Definition at line 199 of file hmqv.h.

## ◆ GenerateEphemeralPublicKey()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

void HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::GenerateEphemeralPublicKey | ( | RandomNumberGenerator & | rng,
|  | const byte * | privateKey,
|  | byte * | publicKey
| ) |  | const
| inline virtual

Generate ephemeral public key from a private key in this domain.

Parameters

  rng | a RandomNumberGenerator derived class
  privateKey | a byte buffer with the previously generated private key
  publicKey | a byte buffer for the generated public key in this domain

Precondition
  `COUNTOF(publicKey) == EphemeralPublicKeyLength()`

Implements AuthenticatedKeyAgreementDomain.

Definition at line 213 of file hmqv.h.

## ◆ Agree()

template<class GROUP_PARAMETERS , class COFACTOR_OPTION = typename GROUP_PARAMETERS::DefaultCofactorOption, class HASH = SHA512>

bool HMQV_Domain< GROUP_PARAMETERS, COFACTOR_OPTION, HASH >::Agree | ( | byte * | agreedValue,
|  | const byte * | staticPrivateKey,
|  | const byte * | ephemeralPrivateKey,
|  | const byte * | staticOtherPublicKey,
|  | const byte * | ephemeralOtherPublicKey,
|  | bool | validateStaticOtherPublicKey = `true`
| ) |  | const
| inline virtual

Derive agreed value or shared secret.

Parameters

  agreedValue | the shared secret
  staticPrivateKey | your long term private key
  ephemeralPrivateKey | your ephemeral private key
  staticOtherPublicKey | couterparty's long term public key
  ephemeralOtherPublicKey | couterparty's ephemeral public key
  validateStaticOtherPublicKey | flag indicating validation

Returns
  true upon success, false in case of failure

Agree() performs the authenticated key agreement. Agree() derives a shared secret from your private keys and couterparty's public keys. Each instance or run of the protocol should use a new ephemeral key pair.

The other's ephemeral public key will always be validated at Level 1 to ensure it is a point on the curve. `validateStaticOtherPublicKey` determines how thoroughly other's static public key is validated. If you have previously validated the couterparty's static public key, then use `validateStaticOtherPublicKey=false` to save time.

Precondition
  `COUNTOF(agreedValue) == AgreedValueLength()`
  `COUNTOF(staticPrivateKey) == StaticPrivateKeyLength()`
  `COUNTOF(ephemeralPrivateKey) == EphemeralPrivateKeyLength()`
  `COUNTOF(staticOtherPublicKey) == StaticPublicKeyLength()`
  `COUNTOF(ephemeralOtherPublicKey) == EphemeralPublicKeyLength()`

Implements AuthenticatedKeyAgreementDomain.

Definition at line 242 of file hmqv.h.

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

- hmqv.h