This class handles information about Virgil Security key pair. More...

#include <VirgilKeyPair.h>

Public Types
enum	Type { Type::RSA_256, Type::RSA_512, Type::RSA_1024, Type::RSA_2048, Type::RSA_3072, Type::RSA_4096, Type::RSA_8192, Type::EC_SECP192R1, Type::EC_SECP224R1, Type::EC_SECP256R1, Type::EC_SECP384R1, Type::EC_SECP521R1, Type::EC_BP256R1, Type::EC_BP384R1, Type::EC_BP512R1, Type::EC_SECP192K1, Type::EC_SECP224K1, Type::EC_SECP256K1, Type::EC_CURVE25519, Type::FAST_EC_X25519, Type::FAST_EC_ED25519 }
	Specific key algorithm type. More...

using	Algorithm = Type
	Key algorithm.

Public Member Functions
	VirgilKeyPair (const VirgilByteArray &publicKey, const VirgilByteArray &privateKey)
	Initialize key pair with given public and private key.

VirgilByteArray	publicKey () const
	Provide access to the public key.

VirgilByteArray	privateKey () const
	Provide access to the private key.

Static Public Member Functions
static VirgilKeyPair	generate (VirgilKeyPair::Type type, const VirgilByteArray &pwd=VirgilByteArray())
	Generate new key pair given type. More...

static VirgilKeyPair	generateRecommended (const VirgilByteArray &pwd=VirgilByteArray())
	Generate new key pair with recommended most safe type. More...

static VirgilKeyPair	generateFrom (const VirgilKeyPair &donorKeyPair, const VirgilByteArray &donorPrivateKeyPassword=VirgilByteArray(), const VirgilByteArray &newKeyPairPassword=VirgilByteArray())
	Generate new key pair of the same type based on the donor key pair. More...

static VirgilKeyPair	generateFromKeyMaterial (VirgilKeyPair::Type type, const VirgilByteArray &keyMaterial, const VirgilByteArray &pwd=VirgilByteArray())
	Generates private and public keys from the given key material. More...

static VirgilKeyPair	generateRecommendedFromKeyMaterial (const VirgilByteArray &keyMaterial, const VirgilByteArray &pwd=VirgilByteArray())
	Generates recommended private and public keys from the given key material. More...

Keys validation
static bool	isKeyPairMatch (const VirgilByteArray &publicKey, const VirgilByteArray &privateKey, const VirgilByteArray &privateKeyPassword=VirgilByteArray())
	Check if a public-private pair of keys matches. More...

static bool	checkPrivateKeyPassword (const VirgilByteArray &key, const VirgilByteArray &pwd)
	Check if given private key and it's password matches. More...

static bool	isPrivateKeyEncrypted (const VirgilByteArray &privateKey)
	Check if given private key is encrypted. More...

Keys
static VirgilByteArray	resetPrivateKeyPassword (const VirgilByteArray &privateKey, const VirgilByteArray &oldPassword, const VirgilByteArray &newPassword)
	Reset password for the given private key. More...

static VirgilByteArray	encryptPrivateKey (const VirgilByteArray &privateKey, const VirgilByteArray &privateKeyPassword)
	Return encrypted private key in PKCS#8 format. More...

static VirgilByteArray	decryptPrivateKey (const VirgilByteArray &privateKey, const VirgilByteArray &privateKeyPassword)
	Return plain (non encrypted) private key. More...

static VirgilByteArray	extractPublicKey (const VirgilByteArray &privateKey, const VirgilByteArray &privateKeyPassword)
	Extract public key from the private key. More...

static VirgilByteArray	publicKeyToPEM (const VirgilByteArray &publicKey)
	Convert given public key to the PEM format. More...

static VirgilByteArray	publicKeyToDER (const VirgilByteArray &publicKey)
	Convert given public key to the DER format. More...

static VirgilByteArray	privateKeyToPEM (const VirgilByteArray &privateKey, const VirgilByteArray &privateKeyPassword=VirgilByteArray())
	Convert given private key to the PEM format. More...

static VirgilByteArray	privateKeyToDER (const VirgilByteArray &privateKey, const VirgilByteArray &privateKeyPassword=VirgilByteArray())
	Convert given private key to the DER format. More...

Detailed Description

This class handles information about Virgil Security key pair.

Member Enumeration Documentation

enum virgil::crypto::VirgilKeyPair::Type

strong

Specific key algorithm type.

Note: This type is deprecated. Use Algorithm instead.

Key Algorithm	Description	Notes
RSA_256	RSA 1024 bit	weak, not recommended
RSA_512	RSA 1024 bit	weak, not recommended
RSA_1024	RSA 1024 bit	weak, not recommended
RSA_2048	RSA 2048 bit	weak, not recommended
RSA_3072	RSA 3072 bit
RSA_4096	RSA 4096 bit
RSA_8192	RSA 8192 bit
EC_SECP192R1	192-bits NIST curve
EC_SECP224R1	224-bits NIST curve
EC_SECP256R1	256-bits NIST curve
EC_SECP384R1	384-bits NIST curve
EC_SECP521R1	521-bits NIST curve
EC_BP256R1	256-bits Brainpool curve
EC_BP384R1	384-bits Brainpool curve
EC_BP512R1	512-bits Brainpool curve
EC_SECP192K1	192-bits "Koblitz" curve
EC_SECP224K1	224-bits "Koblitz" curve
EC_SECP256K1	256-bits "Koblitz" curve
EC_CURVE25519	Curve25519 (deprecated format)	deprecated
FAST_EC_X25519	Curve25519	only encrypt / decrypt
FAST_EC_ED25519	Ed25519	recommended, default

Enumerator
RSA_256	RSA 1024 bit.
RSA_512	RSA 1024 bit.
RSA_1024	RSA 1024 bit.
RSA_2048	RSA 2048 bit.
RSA_3072	RSA 3072 bit.
RSA_4096	RSA 4096 bit.
RSA_8192	RSA 8192 bit.
EC_SECP192R1	192-bits NIST curve
EC_SECP224R1	224-bits NIST curve
EC_SECP256R1	256-bits NIST curve
EC_SECP384R1	384-bits NIST curve
EC_SECP521R1	521-bits NIST curve
EC_BP256R1	256-bits Brainpool curve
EC_BP384R1	384-bits Brainpool curve
EC_BP512R1	512-bits Brainpool curve
EC_SECP192K1	192-bits "Koblitz" curve
EC_SECP224K1	224-bits "Koblitz" curve
EC_SECP256K1	256-bits "Koblitz" curve
EC_CURVE25519	Curve25519 as ECP deprecated format.
FAST_EC_X25519	Curve25519.
FAST_EC_ED25519	Ed25519.

Member Function Documentation

static bool virgil::crypto::VirgilKeyPair::checkPrivateKeyPassword	(	const VirgilByteArray &	key,
		const VirgilByteArray &	pwd
	)

static

Check if given private key and it's password matches.

Parameters

key	- private key in DER or PEM format.
pwd	- private key password.

Returns: true - if private key and it's password matches.

static VirgilByteArray virgil::crypto::VirgilKeyPair::decryptPrivateKey	(	const VirgilByteArray &	privateKey,
		const VirgilByteArray &	privateKeyPassword
	)

static

Return plain (non encrypted) private key.

Decrypt the given private key and return result.

Parameters

privateKey	- Encrypted Private Key.
privateKeyPassword	- current Private Key password.

Exceptions

VirgilCryptoException,with	VirgilCryptoError::InvalidPrivateKeyPassword if password is wrong.
VirgilCryptoException,with	VirgilCryptoError::InvalidFormat if key has invalid format.

Note: It is unsafe to store Private Key in the plain text.

Returns: Plain Private Key.

static VirgilByteArray virgil::crypto::VirgilKeyPair::encryptPrivateKey	(	const VirgilByteArray &	privateKey,
		const VirgilByteArray &	privateKeyPassword
	)

static

Return encrypted private key in PKCS#8 format.

Encrypt the given private key and return result.

Parameters

privateKey	- Private Key in the plain text.
privateKeyPassword	- new Private Key password.

Exceptions

VirgilCryptoException,with	VirgilCryptoError::InvalidArgument if key is empty.
VirgilCryptoException,with	VirgilCryptoError::InvalidPrivateKeyPassword if key is already encrypted.
VirgilCryptoException,with	VirgilCryptoError::InvalidFormat if key has invalid format.

Returns: Encrypted Private Key.

static VirgilByteArray virgil::crypto::VirgilKeyPair::extractPublicKey	(	const VirgilByteArray &	privateKey,
		const VirgilByteArray &	privateKeyPassword
	)

static

Extract public key from the private key.

Parameters

privateKey	- Private Key.
privateKeyPassword	- Private Key password.

Returns: Public Key.

static VirgilKeyPair virgil::crypto::VirgilKeyPair::generate	(	VirgilKeyPair::Type	type,
		const VirgilByteArray &	pwd = `VirgilByteArray()`
	)

static

Generate new key pair given type.

Parameters

type	- private key type to be generated.
pwd	- private key password.

static VirgilKeyPair virgil::crypto::VirgilKeyPair::generateFrom	(	const VirgilKeyPair &	donorKeyPair,
		const VirgilByteArray &	donorPrivateKeyPassword = `VirgilByteArray()`,
		const VirgilByteArray &	newKeyPairPassword = `VirgilByteArray()`
	)

static

Generate new key pair of the same type based on the donor key pair.

Parameters

donorKeyPair	- public key or private key is used to determine the new key pair type.
donorPrivateKeyPassword	- donor private key password, optional if public key is defined.
newKeyPairPassword	- private key password of the new key pair.

static VirgilKeyPair virgil::crypto::VirgilKeyPair::generateFromKeyMaterial	(	VirgilKeyPair::Type	type,
		const VirgilByteArray &	keyMaterial,
		const VirgilByteArray &	pwd = `VirgilByteArray()`
	)

static

Generates private and public keys from the given key material.

This is a deterministic key generation algorithm that allows create private key from any secret data, i.e. password.

Parameters

type	- private key type to be generated.
keyMaterial	- the only data to be used for key generation, must be strong enough.
pwd	- private key password.

static VirgilKeyPair virgil::crypto::VirgilKeyPair::generateRecommended ( const VirgilByteArray & pwd = VirgilByteArray() )

static

Generate new key pair with recommended most safe type.

Parameters

pwd	- private key password.

static VirgilKeyPair virgil::crypto::VirgilKeyPair::generateRecommendedFromKeyMaterial	(	const VirgilByteArray &	keyMaterial,
		const VirgilByteArray &	pwd = `VirgilByteArray()`
	)

static

Generates recommended private and public keys from the given key material.

This is a deterministic key generation algorithm that allows create private key from any secret data, i.e. password.

Parameters

keyMaterial	- the only data to be used for key generation, must be strong enough.
pwd	- private key password.

Exceptions

VirgilCryptoException with VirgilCryptoError::NotSecure, if Key Material is weak.

static bool virgil::crypto::VirgilKeyPair::isKeyPairMatch	(	const VirgilByteArray &	publicKey,
		const VirgilByteArray &	privateKey,
		const VirgilByteArray &	privateKeyPassword = `VirgilByteArray()`
	)

static

Check if a public-private pair of keys matches.

Parameters

publicKey	- public key in DER or PEM format.
privateKey	- private key in DER or PEM format.
privateKeyPassword	- private key password if exists.

Returns: true - if public-private pair of keys matches.

static bool virgil::crypto::VirgilKeyPair::isPrivateKeyEncrypted ( const VirgilByteArray & privateKey )

static

Check if given private key is encrypted.

Parameters

privateKey - private key in DER or PEM format.

Returns: true - if private key is encrypted.

static VirgilByteArray virgil::crypto::VirgilKeyPair::privateKeyToDER	(	const VirgilByteArray &	privateKey,
		const VirgilByteArray &	privateKeyPassword = `VirgilByteArray()`
	)

static

Convert given private key to the DER format.

Parameters

privateKey	- Private Key to be converted.
privateKeyPassword	- password for the Private Key.

Returns: Private Key in the DER fromat.

Exceptions

VirgilCryptoException,with	VirgilCryptoError::InvalidPrivateKeyPassword if password is wrong.
VirgilCryptoException,with	VirgilCryptoError::InvalidFormat if key has invalid format.

static VirgilByteArray virgil::crypto::VirgilKeyPair::privateKeyToPEM	(	const VirgilByteArray &	privateKey,
		const VirgilByteArray &	privateKeyPassword = `VirgilByteArray()`
	)

static

Convert given private key to the PEM format.

Parameters

privateKey	- Private Key to be converted.
privateKeyPassword	- password for the Private Key.

Returns: Private Key in the PEM fromat.

Exceptions

VirgilCryptoException,with	VirgilCryptoError::InvalidPrivateKeyPassword if password is wrong.
VirgilCryptoException,with	VirgilCryptoError::InvalidFormat if key has invalid format.

static VirgilByteArray virgil::crypto::VirgilKeyPair::publicKeyToDER ( const VirgilByteArray & publicKey )

static

Convert given public key to the DER format.

Parameters

publicKey - Public Key to be converted.

Returns: Public Key in the DER fromat.

Exceptions

VirgilCryptoException,with VirgilCryptoError::InvalidFormat if key has invalid format.

static VirgilByteArray virgil::crypto::VirgilKeyPair::publicKeyToPEM ( const VirgilByteArray & publicKey )

static

Convert given public key to the PEM format.

Parameters

publicKey - Public Key to be converted.

Returns: Public Key in the PEM fromat.

Exceptions

VirgilCryptoException,with VirgilCryptoError::InvalidFormat if key has invalid format.

static VirgilByteArray virgil::crypto::VirgilKeyPair::resetPrivateKeyPassword	(	const VirgilByteArray &	privateKey,
		const VirgilByteArray &	oldPassword,
		const VirgilByteArray &	newPassword
	)

static

Reset password for the given private key.

Re-encrypt given Private Key with a new password.

Parameters

privateKey	- Private Key that is encrypted with old password.
oldPassword	- current Private Key password.
newPassword	- new Private Key password.

Returns: Private Key that is encrypted with the new password.

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

include/virgil/crypto/VirgilKeyPair.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Member Function Documentation