Security Scol plugin
Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
x25519 Class Reference

x25519 with key validation More...

#include <xed25519.h>

Inheritance diagram for x25519:
SimpleKeyAgreementDomain CryptoParameters PKCS8PrivateKey KeyAgreementAlgorithm GeneratableCryptoMaterial ASN1CryptoMaterial< PrivateKey > AsymmetricAlgorithm CryptoMaterial ASN1Object PrivateKey Algorithm NameValuePairs GeneratableCryptoMaterial Clonable CryptoMaterial NameValuePairs

Public Member Functions

 CRYPTOPP_CONSTANT (SECRET_KEYLENGTH=32)
 Size of the private key.
 
 CRYPTOPP_CONSTANT (PUBLIC_KEYLENGTH=32)
 Size of the public key.
 
 CRYPTOPP_CONSTANT (SHARED_KEYLENGTH=32)
 Size of the shared key.
 
 x25519 ()
 Create a x25519 object.
 
 x25519 (const byte y[PUBLIC_KEYLENGTH], const byte x[SECRET_KEYLENGTH])
 Create a x25519 object.
 
 x25519 (const byte x[SECRET_KEYLENGTH])
 Create a x25519 object.
 
 x25519 (const Integer &y, const Integer &x)
 Create a x25519 object.
 
 x25519 (const Integer &x)
 Create a x25519 object.
 
 x25519 (RandomNumberGenerator &rng)
 Create a x25519 object.
 
 x25519 (BufferedTransformation &params)
 Create a x25519 object.
 
 x25519 (const OID &oid)
 Create a x25519 object.
 
void ClampKey (byte x[SECRET_KEYLENGTH]) const
 Clamp a private key.
 
bool IsClamped (const byte x[SECRET_KEYLENGTH]) const
 Determine if private key is clamped.
 
bool IsSmallOrder (const byte y[PUBLIC_KEYLENGTH]) const
 Test if a key has small order.
 
OID GetAlgorithmID () const
 Get the Object Identifier.
 
void SetAlgorithmID (const OID &oid)
 Set the Object Identifier.
 
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 ()
 Retrieves a reference to Crypto Parameters.
 
void Save (BufferedTransformation &bt) const
 DER encode ASN.1 object.
 
void Save (BufferedTransformation &bt, bool v1) const
 DER encode ASN.1 object.
 
void Load (BufferedTransformation &bt)
 BER decode ASN.1 object.
 
void BERDecode (BufferedTransformation &bt)
 Decode this object from a BufferedTransformation.
 
void DEREncode (BufferedTransformation &bt) const
 Encode this object into a BufferedTransformation.
 
void BERDecodePrivateKey (BufferedTransformation &bt, bool parametersPresent, size_t size)
 Decode privateKey part of privateKeyInfo.
 
void DEREncodePrivateKey (BufferedTransformation &bt) const
 Encode privateKey part of privateKeyInfo.
 
void DEREncode (BufferedTransformation &bt, int version) const
 DER encode ASN.1 object.
 
void BERDecodeAndCheckAlgorithmID (BufferedTransformation &bt)
 Determine if OID is valid for this object.
 
void GenerateRandom (RandomNumberGenerator &rng, const NameValuePairs &params)
 Generate a random key or crypto parameters.
 
unsigned int AgreedValueLength () const
 Provides the size of the agreed value.
 
unsigned int PrivateKeyLength () const
 Provides the size of the private key.
 
unsigned int PublicKeyLength () const
 Provides the size of the public key.
 
void GeneratePrivateKey (RandomNumberGenerator &rng, byte *privateKey) const
 Generate private key in this domain.
 
void GeneratePublicKey (RandomNumberGenerator &rng, const byte *privateKey, byte *publicKey) const
 Generate a public key from a private key in this domain.
 
bool Agree (byte *agreedValue, const byte *privateKey, const byte *otherPublicKey, bool validateOtherPublicKey=true) const
 Derive agreed value.
 
- Public Member Functions inherited from SimpleKeyAgreementDomain
virtual void GenerateKeyPair (RandomNumberGenerator &rng, byte *privateKey, byte *publicKey) const
 Generate a private/public key pair.
 
- Public Member Functions inherited from KeyAgreementAlgorithm
CryptoMaterialAccessMaterial ()
 Retrieves a reference to Crypto Parameters.
 
const CryptoMaterialGetMaterial () const
 Retrieves a reference to Crypto Parameters.
 
virtual const CryptoParametersGetCryptoParameters () const
 Retrieves a reference to Crypto Parameters.
 
- Public Member Functions inherited from Algorithm
 Algorithm (bool checkSelfTestStatus=true)
 Interface for all crypto algorithms.
 
virtual std::string AlgorithmName () const
 Provides the name of this algorithm.
 
virtual std::string AlgorithmProvider () const
 Retrieve the provider of this algorithm.
 
- Public Member Functions inherited from Clonable
virtual ClonableClone () const
 Copies this object.
 
- Public Member Functions inherited from GeneratableCryptoMaterial
void GenerateRandomWithKeySize (RandomNumberGenerator &rng, unsigned int keySize)
 Generate a random key or crypto parameters.
 
- Public Member Functions inherited from CryptoMaterial
virtual void ThrowIfInvalid (RandomNumberGenerator &rng, unsigned int level) const
 Check this object for errors.
 
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
 Perform a quick sanity check.
 
- Public Member Functions inherited from NameValuePairs
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.
 
CRYPTOPP_DLL std::string GetValueNames () const
 Get a list of value names that can be retrieved.
 
CRYPTOPP_DLL bool GetIntValue (const char *name, int &value) const
 Get a named value with type int.
 
CRYPTOPP_DLL int GetIntValueWithDefault (const char *name, int defaultValue) const
 Get a named value with type int, with default.
 
CRYPTOPP_DLL bool GetWord64Value (const char *name, word64 &value) const
 Get a named value with type word64.
 
CRYPTOPP_DLL word64 GetWord64ValueWithDefault (const char *name, word64 defaultValue) const
 Get a named value with type word64, with default.
 
template<class T >
void GetRequiredParameter (const char *className, const char *name, T &value) const
 Retrieves a required name/value pair.
 
CRYPTOPP_DLL void GetRequiredIntParameter (const char *className, const char *name, int &value) const
 Retrieves a required name/value pair.
 
- Public Member Functions inherited from PKCS8PrivateKey
virtual bool BERDecodeAlgorithmParameters (BufferedTransformation &bt)
 Decode optional parameters.
 
virtual bool DEREncodeAlgorithmParameters (BufferedTransformation &bt) const
 Encode optional parameters.
 
virtual void BERDecodeOptionalAttributes (BufferedTransformation &bt)
 Decode optional attributes.
 
virtual void DEREncodeOptionalAttributes (BufferedTransformation &bt) const
 Encode optional attributes.
 
- Public Member Functions inherited from ASN1Object
virtual void BEREncode (BufferedTransformation &bt) const
 Encode this object into a BufferedTransformation.
 

Protected Member Functions

void SecretToPublicKey (byte y[PUBLIC_KEYLENGTH], const byte x[SECRET_KEYLENGTH]) const
 

Protected Attributes

FixedSizeSecBlock< byte, SECRET_KEYLENGTH > m_sk
 
FixedSizeSecBlock< byte, PUBLIC_KEYLENGTH > m_pk
 
OID m_oid
 
- Protected Attributes inherited from PKCS8PrivateKey
ByteQueue m_optionalAttributes
 

Additional Inherited Members

- Static Public Member Functions inherited from NameValuePairs
static CRYPTOPP_DLL void CRYPTOPP_API ThrowIfTypeMismatch (const char *name, const std::type_info &stored, const std::type_info &retrieving)
 Ensures an expected name and type is present.
 

Detailed Description

x25519 with key validation

Since
Crypto++ 8.0

Definition at line 54 of file xed25519.h.

Constructor & Destructor Documentation

◆ ~x25519()

virtual x25519::~x25519 ( )
inlinevirtual

Definition at line 67 of file xed25519.h.

◆ x25519() [1/8]

x25519::x25519 ( )
inline

Create a x25519 object.

This constructor creates an empty x25519 object. It is intended for use in loading existing parameters, like CryptoBox parameters. If you are performing key agreement you should use a constructor that generates random parameters on construction.

Definition at line 74 of file xed25519.h.

◆ x25519() [2/8]

ANONYMOUS_NAMESPACE_END x25519::x25519 ( const byte  y[PUBLIC_KEYLENGTH],
const byte  x[SECRET_KEYLENGTH] 
)

Create a x25519 object.

Parameters
ypublic key
xprivate key

This constructor creates a x25519 object using existing parameters.

Note
The public key is not validated.

Definition at line 74 of file xed25519.cpp.

◆ x25519() [3/8]

x25519::x25519 ( const byte  x[SECRET_KEYLENGTH])

Create a x25519 object.

Parameters
xprivate key

This constructor creates a x25519 object using existing parameters. The public key is calculated from the private key.

Definition at line 83 of file xed25519.cpp.

◆ x25519() [4/8]

x25519::x25519 ( const Integer y,
const Integer x 
)

Create a x25519 object.

Parameters
ypublic key
xprivate key

This constructor creates a x25519 object using existing parameters.

Note
The public key is not validated.

Definition at line 92 of file xed25519.cpp.

◆ x25519() [5/8]

x25519::x25519 ( const Integer x)

Create a x25519 object.

Parameters
xprivate key

This constructor creates a x25519 object using existing parameters. The public key is calculated from the private key.

Definition at line 104 of file xed25519.cpp.

◆ x25519() [6/8]

x25519::x25519 ( RandomNumberGenerator rng)

Create a x25519 object.

Parameters
rngRandomNumberGenerator derived class

This constructor creates a new x25519 using the random number generator.

Definition at line 116 of file xed25519.cpp.

◆ x25519() [7/8]

x25519::x25519 ( BufferedTransformation params)

Create a x25519 object.

Parameters
paramspublic and private key

This constructor creates a x25519 object using existing parameters. The params can be created with Save.

Note
The public key is not validated.

Definition at line 123 of file xed25519.cpp.

◆ x25519() [8/8]

x25519::x25519 ( const OID oid)

Create a x25519 object.

Parameters
oidan object identifier

This constructor creates a new x25519 using the specified OID. The public and private points are uninitialized.

Member Function Documentation

◆ AccessCryptoParameters()

CryptoParameters & x25519::AccessCryptoParameters ( )
inlinevirtual

Retrieves a reference to Crypto Parameters.

Returns
a reference the crypto parameters

Implements KeyAgreementAlgorithm.

Definition at line 154 of file xed25519.h.

◆ Agree()

bool x25519::Agree ( byte agreedValue,
const byte privateKey,
const byte otherPublicKey,
bool  validateOtherPublicKey = true 
) const
virtual

Derive agreed value.

Parameters
agreedValuea byte buffer for the shared secret
privateKeya byte buffer with your private key in this domain
otherPublicKeya byte buffer with the other party's public key in this domain
validateOtherPublicKeya flag indicating if the other party's public key should be validated
Returns
true upon success, false in case of failure

Agree() derives an agreed value from your private keys and couterparty's public keys.

The other party's public key is validated by default. If you have previously validated the static public key, use validateStaticOtherPublicKey=false to save time.

Precondition
COUNTOF(agreedValue) == AgreedValueLength()
COUNTOF(privateKey) == PrivateKeyLength()
COUNTOF(otherPublicKey) == PublicKeyLength()

Implements SimpleKeyAgreementDomain.

Definition at line 366 of file xed25519.cpp.

◆ AgreedValueLength()

unsigned int x25519::AgreedValueLength ( ) const
inlinevirtual

Provides the size of the agreed value.

Returns
size of agreed value produced in this domain

Implements SimpleKeyAgreementDomain.

Definition at line 236 of file xed25519.h.

◆ AssignFrom()

void x25519::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 319 of file xed25519.cpp.

◆ BERDecode()

void x25519::BERDecode ( BufferedTransformation bt)
virtual

Decode this object from a BufferedTransformation.

Parameters
btBufferedTransformation object

Uses Basic Encoding Rules (BER)

Reimplemented from PKCS8PrivateKey.

Definition at line 166 of file xed25519.cpp.

◆ BERDecodeAndCheckAlgorithmID()

void x25519::BERDecodeAndCheckAlgorithmID ( BufferedTransformation bt)

Determine if OID is valid for this object.

BERDecodeAndCheckAlgorithmID() parses the OID from bt and determines if it valid for this object. The problem in practice is there are multiple OIDs available to denote curve25519 operations. The OIDs include an old GNU OID used by SSH, OIDs specified in draft-josefsson-pkix-newcurves, and OIDs specified in draft-ietf-curdle-pkix.

By default BERDecodeAndCheckAlgorithmID() accepts an OID set by the user, ASN1::curve25519() and ASN1::X25519(). ASN1::curve25519() is generic and says "this key is valid for curve25519 operations". ASN1::X25519() is specific and says "this key is valid for x25519 key exchange."

Definition at line 148 of file xed25519.cpp.

◆ BERDecodePrivateKey()

void x25519::BERDecodePrivateKey ( BufferedTransformation bt,
bool  parametersPresent,
size_t  size 
)
virtual

Decode privateKey part of privateKeyInfo.

Parameters
btBufferedTransformation object
parametersPresentflag indicating if algorithm parameters are present
sizenumber of octets to read for the parameters, in bytes

BERDecodePrivateKey() the decodes privateKey part of privateKeyInfo, without the OCTET STRING header.

When parametersPresent = true then BERDecodePrivateKey() calls BERDecodeAlgorithmParameters() to parse algorithm parameters.

See also
BERDecodeAlgorithmParameters

Implements PKCS8PrivateKey.

Definition at line 238 of file xed25519.cpp.

◆ ClampKey()

void x25519::ClampKey ( byte  x[SECRET_KEYLENGTH]) const

Clamp a private key.

Parameters
xprivate key

ClampKeys() clamps a private key and then regenerates the public key from the private key.

Definition at line 128 of file xed25519.cpp.

◆ CRYPTOPP_CONSTANT() [1/3]

x25519::CRYPTOPP_CONSTANT ( PUBLIC_KEYLENGTH  = 32)

Size of the public key.

PUBLIC_KEYLENGTH is the size of the public key, in bytes.

◆ CRYPTOPP_CONSTANT() [2/3]

x25519::CRYPTOPP_CONSTANT ( SECRET_KEYLENGTH  = 32)

Size of the private key.

SECRET_KEYLENGTH is the size of the private key, in bytes.

◆ CRYPTOPP_CONSTANT() [3/3]

x25519::CRYPTOPP_CONSTANT ( SHARED_KEYLENGTH  = 32)

Size of the shared key.

SHARED_KEYLENGTH is the size of the shared key, in bytes.

◆ DEREncode() [1/2]

void x25519::DEREncode ( BufferedTransformation bt) const
inlinevirtual

Encode this object into a BufferedTransformation.

Parameters
btBufferedTransformation object

Uses Distinguished Encoding Rules (DER)

Reimplemented from PKCS8PrivateKey.

Definition at line 200 of file xed25519.h.

◆ DEREncode() [2/2]

void x25519::DEREncode ( BufferedTransformation bt,
int  version 
) const

DER encode ASN.1 object.

Parameters
btBufferedTransformation object
versionindicates version

DEREncode() will write the OID associated with algorithm or scheme. In the case of public and private keys, this function writes the subjectPublicKeyInfo parts.

The default OID is from RFC 8410 using id-X25519. The default private key format is RFC 5208.

The value of version is written as the INTEGER. INTEGER 0 means RFC 5208 format, which is the old format. The old format provides the best interop, and keys will work with OpenSSL. The INTEGER 1 means RFC 5958 format, which is the new format.

Definition at line 211 of file xed25519.cpp.

◆ DEREncodePrivateKey()

void x25519::DEREncodePrivateKey ( BufferedTransformation bt) const
virtual

Encode privateKey part of privateKeyInfo.

Parameters
btBufferedTransformation object

DEREncodePrivateKey() encodes the privateKey part of privateKeyInfo, without the OCTET STRING header.

See also
DEREncodeAlgorithmParameters

Implements PKCS8PrivateKey.

Definition at line 259 of file xed25519.cpp.

◆ GeneratePrivateKey()

void x25519::GeneratePrivateKey ( RandomNumberGenerator rng,
byte privateKey 
) const
virtual

Generate private key in this domain.

Parameters
rnga RandomNumberGenerator derived class
privateKeya byte buffer for the generated private key in this domain
Precondition
COUNTOF(privateKey) == PrivateKeyLength()

Implements SimpleKeyAgreementDomain.

Definition at line 354 of file xed25519.cpp.

◆ GeneratePublicKey()

void x25519::GeneratePublicKey ( RandomNumberGenerator rng,
const byte privateKey,
byte publicKey 
) const
virtual

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

Parameters
rnga RandomNumberGenerator derived class
privateKeya byte buffer with the previously generated private key
publicKeya byte buffer for the generated public key in this domain
Precondition
COUNTOF(publicKey) == PublicKeyLength()

Implements SimpleKeyAgreementDomain.

Definition at line 360 of file xed25519.cpp.

◆ GenerateRandom()

void x25519::GenerateRandom ( RandomNumberGenerator rng,
const NameValuePairs params 
)
virtual

Generate a random key or crypto parameters.

Parameters
rnga RandomNumberGenerator to produce keying material
paramsadditional initialization parameters
Exceptions
KeyingErrif 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 from GeneratableCryptoMaterial.

Definition at line 343 of file xed25519.cpp.

◆ GetAlgorithmID()

OID x25519::GetAlgorithmID ( ) const
inlinevirtual

Get the Object Identifier.

Returns
the Object Identifier

The default OID is from RFC 8410 using id-X25519. The default private key format is RFC 5208.

Implements PKCS8PrivateKey.

Definition at line 138 of file xed25519.h.

◆ GetVoidValue()

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

Get a named value.

Parameters
namethe name of the object or value to retrieve
valueTypereference to a variable that receives the value
pValuevoid pointer to a variable that receives the value
Returns
true if the value was retrieved, false otherwise

GetVoidValue() retrieves 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 290 of file xed25519.cpp.

◆ IsClamped()

bool x25519::IsClamped ( const byte  x[SECRET_KEYLENGTH]) const

Determine if private key is clamped.

Parameters
xprivate key

Definition at line 133 of file xed25519.cpp.

◆ IsSmallOrder()

bool x25519::IsSmallOrder ( const byte  y[PUBLIC_KEYLENGTH]) const

Test if a key has small order.

Parameters
ypublic key

Definition at line 138 of file xed25519.cpp.

◆ Load()

void x25519::Load ( BufferedTransformation bt)
inlinevirtual

BER decode ASN.1 object.

Parameters
btBufferedTransformation object
See also
RFC 5958, Asymmetric Key Packages

Reimplemented from CryptoMaterial.

Definition at line 194 of file xed25519.h.

◆ PrivateKeyLength()

unsigned int x25519::PrivateKeyLength ( ) const
inlinevirtual

Provides the size of the private key.

Returns
size of private keys in this domain

Implements SimpleKeyAgreementDomain.

Definition at line 237 of file xed25519.h.

◆ PublicKeyLength()

unsigned int x25519::PublicKeyLength ( ) const
inlinevirtual

Provides the size of the public key.

Returns
size of public keys in this domain

Implements SimpleKeyAgreementDomain.

Definition at line 238 of file xed25519.h.

◆ Save() [1/2]

void x25519::Save ( BufferedTransformation bt) const
inlinevirtual

DER encode ASN.1 object.

Parameters
btBufferedTransformation object

Save() will write the OID associated with algorithm or scheme. In the case of public and private keys, this function writes the subjectPublicKeyInfo parts.

The default OID is from RFC 8410 using id-X25519. The default private key format is RFC 5208, which is the old format. The old format provides the best interop, and keys will work with OpenSSL.

See also
RFC 5958, Asymmetric Key Packages

Reimplemented from CryptoMaterial.

Definition at line 167 of file xed25519.h.

◆ Save() [2/2]

void x25519::Save ( BufferedTransformation bt,
bool  v1 
) const
inline

DER encode ASN.1 object.

Parameters
btBufferedTransformation object
v1flag indicating v1

Save() will write the OID associated with algorithm or scheme. In the case of public and private keys, this function writes the subjectPublicKeyInfo parts.

The default OID is from RFC 8410 using id-X25519. The default private key format is RFC 5208.

v1 means INTEGER 0 is written. INTEGER 0 means RFC 5208 format, which is the old format. The old format provides the best interop, and keys will work with OpenSSL. The other option uses INTEGER 1. INTEGER 1 means RFC 5958 format, which is the new format.

See also
RFC 5958, Asymmetric Key Packages

Definition at line 186 of file xed25519.h.

◆ SecretToPublicKey()

void x25519::SecretToPublicKey ( byte  y[PUBLIC_KEYLENGTH],
const byte  x[SECRET_KEYLENGTH] 
) const
protected

Definition at line 143 of file xed25519.cpp.

◆ SetAlgorithmID()

void x25519::SetAlgorithmID ( const OID oid)
inline

Set the Object Identifier.

Parameters
oidthe new Object Identifier

Definition at line 144 of file xed25519.h.

◆ Validate()

bool x25519::Validate ( RandomNumberGenerator rng,
unsigned int  level 
) const
virtual

Check this object for errors.

Parameters
rnga RandomNumberGenerator for objects which use randomized testing
levelthe 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.

See also
ThrowIfInvalid()

Implements CryptoMaterial.

Definition at line 267 of file xed25519.cpp.

Member Data Documentation

◆ m_oid

OID x25519::m_oid
protected

Definition at line 252 of file xed25519.h.

◆ m_pk

FixedSizeSecBlock<byte, PUBLIC_KEYLENGTH> x25519::m_pk
protected

Definition at line 251 of file xed25519.h.

◆ m_sk

FixedSizeSecBlock<byte, SECRET_KEYLENGTH> x25519::m_sk
protected

Definition at line 250 of file xed25519.h.


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