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 (std::string intKeyString)
	Compute the hash code of an "internal" ECC public or private key string. 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 (std::string internalKey)
	Convert an internal EC private key string into an internal EC public key string. More...

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

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

static std::string	ReadPrivateKey (std::string keyFileOrString, 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 (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 (std::string outputFile, std::string internalKey, std::string password, PbeScheme pbes=PbeScheme::Default, std::string paramString="", Format fileFormat=Format::Binary)
	Save an internal EC private key string to an encrypted private key file. More...

static int	SaveKey (std::string outputFile, 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...

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 key in "legacy" PKCS#8 v1 format (default is v2 OneAsymmetricKey).

◆ 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 ( 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.

◆ 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 ( 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	(	std::string	internalKey,
		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	(	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	(	std::string	keyFileOrString,
		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 ( 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	(	std::string	outputFile,
		std::string	internalKey,
		std::string	password,
		PbeScheme	pbes = `PbeScheme::Default`,
		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	(	std::string	outputFile,
		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.

Public Types

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Curve

◆ Format

◆ KeyType

◆ PbeScheme

◆ Publicity

Member Function Documentation

◆ CurveNameAsString()

◆ DHSharedSecret()

◆ KeyHashCode()

◆ MakeKeys()

◆ PublicKeyFromPrivate()

◆ QueryKey()

◆ ReadKeyByCurve()

◆ ReadPrivateKey()

◆ ReadPublicKey()

◆ SaveEncKey()

◆ SaveKey()