CryptoSys PKI  23.0.0
Public Types | Static Public Member Functions | List of all members
dipki::Ecc Class Reference

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
curveCurve
Returns
Curve name as a string, e.g. "secp256r1".
// secp256r1
@ Secp256r1
NIST curve P-256.
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
ourIntPrivateKeyOur own private key in ephemeral "internal" form.
theirIntPublicKeyOther 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
intKeyStringKey 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
publicKeyFileOutput filename for public key.
privateKeyFileOutput filename for (encrypted) private key.
curveElliptic curve
passwordPassword for encrypted private key (required).
pbesEncryption scheme to encrypt private key.
paramStringOptional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks).
fileFormatFormat 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
internalKeyPrivate 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
internalKeyKey as an internal key string.
queryQuery 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_errorException 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
hexKeyHexadecimal representation of the key, private or public.
curveElliptic curve.
publicityRequired 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
keyFileOrStringName of private key file or a PEM String containing the key.
passwordPassword 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
keyFileOrStringName 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
outputFileName of key file to be created.
internalKeyThe private EC key as an internal key string.
passwordPassword to be used for the encrypted key file
pbesPassword-based encryption scheme to encrypt private key.
paramStringOptional parameters. A set of attribute name=value pairs separated by a semicolon ";" (see remarks). Set as "" for defaults.
fileFormatFormat 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
outputFileName of key file to be created.
internalKeyThe private or public EC key as an internal key string.
keyTypeKey structure for private key (ignored for public).
fileFormatFormat to save file (default = DER binary)
Returns
Zero if successful.
Copyright © 2004-24 D.I. Management Services Pty Limited t/a CryptoSys ABN 78 083 210 584 Australia. All rights reserved. <www.di-mgt.com.au> <www.cryptosys.net>. Generated on Mon Sep 23 2024 15:37:33 by Doxygen 1.9.1.