Elliptic curve cryptography. More...

Public Types
enum class	Curve
	Supported curves. More...

enum class	Format
	Format for output files. More...

enum class	KeyType
	Key type for unencrypted key file. More...

enum class	PbeScheme
	Password-based encryption scheme to encrypt the private key file. More...

enum class	Publicity
	State of key being public or private. More...

Static Public Member Functions
static std::string	CurveNameAsString (Curve curve)
	Get curve name as a string. More...

static bvec_t	DHSharedSecret (std::string &ourIntPrivateKey, std::string &theirIntPublicKey)
	Compute EC Diffie-Hellman (ECDH) shared secret. More...

static uint32_t	KeyHashCode (const std::string &intKeyString)
	Compute the hash code of an "internal" ECC public or private key string. More...

static bool	KeyMatch (const std::string &privateKey, const std::string &publicKey)
	Verify that a pair of "internal" ECC private and public key strings are matched. More...

static int	MakeKeys (const std::string &publicKeyFile, const std::string &privateKeyFile, Curve curve, const std::string &password, PbeScheme pbes=PbeScheme::Default, const std::string &paramString="", Format fileFormat=Format::Binary)
	Generate an EC public/private key pair and save as two key files. More...

static std::string	PublicKeyFromPrivate (const std::string &internalKey)
	Convert an internal EC private key string into an internal EC public key string. More...

static std::string	QueryKey (const std::string &internalKey, const std::string &query)
	Query an EC key string for selected information. More...

static std::string	ReadKeyByCurve (const std::string &hexKey, Curve curve, Publicity publicity=Publicity::PrivateKey)
	Read an EC key from its hexadecimal representation. More...

static std::string	ReadPrivateKey (const std::string &keyFileOrString, const std::string &password="")
	Read from a file or a string containing an EC private key into an "internal" private key string. More...

static std::string	ReadPublicKey (const std::string &keyFileOrString)
	Read from a file or a string containing an EC public key into an "internal" public key string. More...

static int	SaveEncKey (const std::string &outputFile, const std::string &internalKey, const std::string &password, PbeScheme pbes=PbeScheme::Default, const std::string &paramString="", Format fileFormat=Format::Binary)
	Save an internal EC private key string to an encrypted private key file. More...

static int	SaveKey (const std::string &outputFile, const std::string &internalKey, KeyType keyType=KeyType::Default, Format fileFormat=Format::Binary)
	Save an internal EC key string (public or private) to an unencrypted key file. More...

static std::string	WriteKey (const std::string &internalKey, KeyType keyType=KeyType::Default)
	Write an internal EC key to an output string in PEM format. More...

Detailed Description

Elliptic curve cryptography.

Member Enumeration Documentation

◆ Curve

enum dipki::Ecc::Curve

strong

Supported curves.

See also: CurveNameAsString

Enumerator
Secp192r1	NIST curve P-192.
Secp224r1	NIST curve P-224.
Secp256r1	NIST curve P-256.
Secp384r1	NIST curve P-384.
Secp521r1	NIST curve P-521.
Secp256k1	"Bitcoin" curve
P_192	NIST curve P-192 (synonym for `secp192r1`)
P_224	NIST curve P-256 (synonym for `secp256r1`)
P_256	NIST curve P-224 (synonym for `secp224r1`)
P_384	NIST curve P-384 (synonym for `secp384r1`)
P_521	NIST curve P-521 (synonym for `secp521r1`)
Prime192v1	Alternative name for NIST curve P-192.
Prime256v1	Alternative name for NIST curve P-256.
BrainpoolP256r1	ECC Brainpool 256-bit curve [RFC5639].
BrainpoolP384r1	ECC Brainpool 384-bit curve [RFC5639].
BrainpoolP512r1	ECC Brainpool 512-bit curve [RFC5639].
Ed25519	Safe curve for EdDSA [RFC7748].
Ed448	Safe curve for EdDSA [RFC7748].
X25519	Safe curve for ECDH [RFC7748].
X448	Safe curve for ECDH [RFC7748].

◆ Format

enum dipki::Ecc::Format

strong

Format for output files.

Enumerator
Binary	Binary DER-encoded (default)
PEM	PEM-encoded text file.

◆ KeyType

enum dipki::Ecc::KeyType

strong

Key type for unencrypted key file.

Enumerator
Default	Save key in the default format.
Pkcs8PrivateKeyInfo	Save a NIST/SEC curve private key in PKCS#8 `PrivateKeyInfo` format (ignored for a public key).
Legacy	Save a SAFE curve key in "legacy" PKCS#8 v1 format (default is v2 OneAsymmetricKey).
CompressKey	Save an ECDSA public key in compressed format (default is uncompressed)

◆ PbeScheme

enum dipki::Ecc::PbeScheme

strong

Password-based encryption scheme to encrypt the private key file.

Enumerator
Default	Default option: `pbeWithSHAAnd3-KeyTripleDES-CBC` from PKCS#12.
Pbkdf2_Desede3	PBKDF2 using `des-EDE3-CBC`
Pbkdf2_Aes128	PBKDF2 using `aes128-CBC`
Pbkdf2_Aes192	PBKDF2 using `aes192-CBC`
Pbkdf2_Aes256	PBKDF2 using `aes256-CBC`

◆ Publicity

enum dipki::Ecc::Publicity

strong

State of key being public or private.

Enumerator
PrivateKey	Key value represents a private key.
PublicKey	Key value represents a public key.

Member Function Documentation

◆ CurveNameAsString()

static std::string dipki::Ecc::CurveNameAsString ( Curve curve )

static

Get curve name as a string.

Parameters

curve Curve

Returns: Curve name as a string, e.g. "secp256r1".
cout << dipki::Ecc::CurveNameAsString(dipki::Ecc::Curve::Secp256r1) << endl;

// secp256r1

dipki::Ecc::Curve::Secp256r1
@ Secp256r1
NIST curve P-256.

dipki::Ecc::CurveNameAsString
static std::string CurveNameAsString(Curve curve)
Get curve name as a string.

◆ DHSharedSecret()

static bvec_t dipki::Ecc::DHSharedSecret	(	std::string &	ourIntPrivateKey,
		std::string &	theirIntPublicKey
	)

static

Compute EC Diffie-Hellman (ECDH) shared secret.

Parameters

ourIntPrivateKey	Our own private key in ephemeral "internal" form.
theirIntPublicKey	Other party's public key in "internal" form.

Returns: The Diffie-Hellman shared secret as a byte array.

Remarks: The output is the Diffie-Hellman shared secret. This may require further processing to be used in an application; for example, as input to a key derivation function. The keys are expected in ephemeral "internal" format read into a string using Ecc::ReadPrivateKey, Ecc::ReadPublicKey or Ecc::ReadKeyByCurve. All supported NIST/SEC curves can be used as well as the safe curve X25519 (but not Ed25519, which is for signatures only).

◆ KeyHashCode()

static uint32_t dipki::Ecc::KeyHashCode ( const std::string & intKeyString )

static

Compute the hash code of an "internal" ECC public or private key string.

Parameters

intKeyString Key as an internal key string.

Returns: A 32-bit hash code for the key.

Remarks: Should be the same for a matching private and public key.

◆ KeyMatch()

static bool dipki::Ecc::KeyMatch	(	const std::string &	privateKey,
		const std::string &	publicKey
	)

static

Verify that a pair of "internal" ECC private and public key strings are matched.

Parameters

privateKey	Internal ECC private key string.
publicKey	Internal ECC public key string.

Returns: true if the keystrings are valid and matched, or false if the keystrings are valid but not matched.

Exceptions

std::runtime_error Exception with error code if an internal key string is invalid.

◆ MakeKeys()

static int dipki::Ecc::MakeKeys	(	const std::string &	publicKeyFile,
		const std::string &	privateKeyFile,
		Curve	curve,
		const std::string &	password,
		PbeScheme	pbes = `PbeScheme::Default`,
		const std::string &	paramString = `""`,
		Format	fileFormat = `Format::Binary`
	)

static

Generate an EC public/private key pair and save as two key files.

Parameters

publicKeyFile	Output filename for public key.
privateKeyFile	Output filename for (encrypted) private key.
curve	Elliptic curve
password	Password for encrypted private key (required).
pbes	Encryption scheme to encrypt private key.
paramString	Optional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks).
fileFormat	Format to save file (default = DER binary).

Returns: Zero if successful.

Remarks

Valid name-value pair parameters for paramString are:

Parameter	Result
count=integer	To set the iteration count used in the PBKDF2 method, e.g. `"count=5000;"` [default=2048].
prf=hmac-name	To change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacWithSHA1`].

Valid values for hmac-name are {hmacWithSHA1,hmacWithSHA224,hmacWithSHA256,hmacWithSHA384,hmacWithSHA512}.

◆ PublicKeyFromPrivate()

static std::string dipki::Ecc::PublicKeyFromPrivate ( const std::string & internalKey )

static

Convert an internal EC private key string into an internal EC public key string.

Parameters

internalKey Private key as an internal key string.

Returns: The public key in ephemeral "internal" representation.

◆ QueryKey()

static std::string dipki::Ecc::QueryKey	(	const std::string &	internalKey,
		const std::string &	query
	)

static

Query an EC key string for selected information.

Parameters

internalKey	Key as an internal key string.
query	Query string (case insensitive).

Returns: String containing the result or an empty string if not found.

Remarks

Valid queries are:

Query String	Returns
`curveName`	Name of the curve.
`keyBits`	Number of bits in the key.
`isPrivate`	"1" if key is a private key; "0" if not.
`isValid`	"1" if key is validated; "0" if not.
`privateKey`	Value of the private key encoded in hex.
`publicKey`	Value of the public key encoded in hex.

Exceptions

std::runtime_error Exception with error code if internal key string or query is invalid.

◆ ReadKeyByCurve()

static std::string dipki::Ecc::ReadKeyByCurve	(	const std::string &	hexKey,
		Curve	curve,
		Publicity	publicity = `Publicity::PrivateKey`
	)

static

Read an EC key from its hexadecimal representation.

Parameters

hexKey	Hexadecimal representation of the key, private or public.
curve	Elliptic curve.
publicity	Required to read a safe curve key, otherwise ignored [default=`PrivateKey`].

Returns: The key in ephemeral "internal" representation.

Remarks: For NIST/SEC curves, an EC private key w is represented as HEX(w) and a public key (x,y) in the uncompressed X9.63 form 04||HEX(x)||HEX(y). The key type is detected automatically and the publicity argument is ignored.
For the safe curves, X25519 and Ed25519, both private and public keys are expected as the hexadecimal representation of a 32-byte value in little-endian format. The publicity argument must be used to must specify whether the key is a private or public key.

◆ ReadPrivateKey()

static std::string dipki::Ecc::ReadPrivateKey	(	const std::string &	keyFileOrString,
		const std::string &	password = `""`
	)

static

Read from a file or a string containing an EC private key into an "internal" private key string.

Parameters

keyFileOrString	Name of private key file or a PEM String containing the key.
password	Password for private key, if encrypted.

Returns: The key in ephemeral "internal" representation.

Remarks: The output string is an ephemeral internal key string valid only for the current session.

◆ ReadPublicKey()

static std::string dipki::Ecc::ReadPublicKey ( const std::string & keyFileOrString )

static

Read from a file or a string containing an EC public key into an "internal" public key string.

Parameters

keyFileOrString Name of public key file or a PEM String containing the key.

Returns: The key in ephemeral "internal" representation.

◆ SaveEncKey()

static int dipki::Ecc::SaveEncKey	(	const std::string &	outputFile,
		const std::string &	internalKey,
		const std::string &	password,
		PbeScheme	pbes = `PbeScheme::Default`,
		const std::string &	paramString = `""`,
		Format	fileFormat = `Format::Binary`
	)

static

Save an internal EC private key string to an encrypted private key file.

Parameters

outputFile	Name of key file to be created.
internalKey	The private EC key as an internal key string.
password	Password to be used for the encrypted key file
pbes	Password-based encryption scheme to encrypt private key.
paramString	Optional parameters. A set of attribute name=value pairs separated by a semicolon `";"` (see remarks). Set as `""` for defaults.
fileFormat	Format to save file (default = DER binary)

Returns: Zero if successful.

Remarks

Valid name-value pair parameters for paramString are:

Parameter	Result
count=integer	To set the iteration count used in the PBKDF2 method, e.g. `"count=5000;"` [default=2048].
prf=hmac-name	To change the HMAC algorithm used in the PBKDF2 method, e.g. `"prf=hmacWithSHA256;"` [default=`hmacWithSHA1`].

Valid values for hmac-name are {hmacWithSHA1,hmacWithSHA224,hmacWithSHA256,hmacWithSHA384,hmacWithSHA512}.

◆ SaveKey()

static int dipki::Ecc::SaveKey	(	const std::string &	outputFile,
		const std::string &	internalKey,
		KeyType	keyType = `KeyType::Default`,
		Format	fileFormat = `Format::Binary`
	)

static

Save an internal EC key string (public or private) to an unencrypted key file.

Parameters

outputFile	Name of key file to be created.
internalKey	The private or public EC key as an internal key string.
keyType	Key structure for private key (ignored for public).
fileFormat	Format to save file (default = DER binary)

Returns: Zero if successful.

◆ WriteKey()

static std::string dipki::Ecc::WriteKey	(	const std::string &	internalKey,
		KeyType	keyType = `KeyType::Default`
	)

static

Write an internal EC key to an output string in PEM format.

Parameters

internalKey	The private or public EC key as an internal key string.
keyType	Key structure options.

Returns: String containing the key in textual PEM format or the empty string if error.

Remarks: This works the same as Ecc::SaveKey() except it outputs to a PEM string instead of a file.

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Curve

◆ Format

◆ KeyType

◆ PbeScheme

◆ Publicity

Member Function Documentation

◆ CurveNameAsString()

◆ DHSharedSecret()

◆ KeyHashCode()

◆ KeyMatch()

◆ MakeKeys()

◆ PublicKeyFromPrivate()

◆ QueryKey()

◆ ReadKeyByCurve()

◆ ReadPrivateKey()

◆ ReadPublicKey()

◆ SaveEncKey()

◆ SaveKey()

◆ WriteKey()