Provides asymmetric ciphers algorithms (PK). More...

#include <VirgilAsymmetricCipher.h>

Inheritance diagram for virgil::crypto::foundation::VirgilAsymmetricCipher:

Public Member Functions
Creation methods
	VirgilAsymmetricCipher ()
	Create object that is not initialized with specific algorithm yet. More...

Info
size_t	keySize () const
	Provides size in bits of the underlying key. More...

size_t	keyLength () const
	Provides the length in bytes of the underlying key. More...

Keys export
virgil::crypto::VirgilByteArray	exportPrivateKeyToDER (const virgil::crypto::VirgilByteArray &pwd=virgil::crypto::VirgilByteArray()) const
	Provides private key. More...

virgil::crypto::VirgilByteArray	exportPublicKeyToDER () const
	Provides public key. More...

virgil::crypto::VirgilByteArray	exportPrivateKeyToPEM (const virgil::crypto::VirgilByteArray &pwd=virgil::crypto::VirgilByteArray()) const
	Provides private key. More...

virgil::crypto::VirgilByteArray	exportPublicKeyToPEM () const
	Provides public key. More...

Keys low level management
Note Properly works only with Curve25519 keys. Warning Used for internal purposes only.
virgil::crypto::VirgilKeyPair::Type	getKeyType () const
	Return type of the underlying key. More...

void	setKeyType (virgil::crypto::VirgilKeyPair::Type keyType)
	Change type of the underlying key. More...

virgil::crypto::VirgilByteArray	getPublicKeyBits () const
	Return number of the underlying public key. More...

void	setPublicKeyBits (const virgil::crypto::VirgilByteArray &bits)
	Set number of the underlying public key. More...

Encryption / Decryption
virgil::crypto::VirgilByteArray	encrypt (const virgil::crypto::VirgilByteArray &in) const
	Encrypts given message. More...

virgil::crypto::VirgilByteArray	decrypt (const virgil::crypto::VirgilByteArray &in) const
	Decrypts given message. More...

Sign / Verify
virgil::crypto::VirgilByteArray	sign (const virgil::crypto::VirgilByteArray &digest, int hashType) const
	Sign given hash. More...

bool	verify (const virgil::crypto::VirgilByteArray &digest, const virgil::crypto::VirgilByteArray &sign, int hashType) const
	Verify given hash with given sign. More...

VirgilAsn1Compatible implementation
virtual size_t	asn1Write (virgil::crypto::foundation::asn1::VirgilAsn1Writer &asn1Writer, size_t childWrittenBytes=0) const override
	Write object state to the writer. More...

virtual void	asn1Read (virgil::crypto::foundation::asn1::VirgilAsn1Reader &asn1Reader) override
	Read object state from the reader. More...

Public Member Functions inherited from virgil::crypto::foundation::asn1::VirgilAsn1Compatible
virgil::crypto::VirgilByteArray	toAsn1 () const
	Save object state to the ASN.1 structure.

void	fromAsn1 (const virgil::crypto::VirgilByteArray &asn1)
	Restore object state from the ASN.1 structure.

virtual	~VirgilAsn1Compatible () noexcept
	Polymorphic destructor.

Static Public Member Functions
Keys validation
static bool	isKeyPairMatch (const virgil::crypto::VirgilByteArray &publicKey, const virgil::crypto::VirgilByteArray &privateKey, const virgil::crypto::VirgilByteArray &privateKeyPassword=virgil::crypto::VirgilByteArray())
	Check if a public-private pair of keys matches. More...

static bool	isPublicKeyValid (const virgil::crypto::VirgilByteArray &key)
	Check if given public key has a valid format. More...

static void	checkPublicKey (const virgil::crypto::VirgilByteArray &key)
	Check if given public key has a valid format. More...

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

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

Keys management
void	setPrivateKey (const virgil::crypto::VirgilByteArray &key, const virgil::crypto::VirgilByteArray &pwd=virgil::crypto::VirgilByteArray())
	Configures private key. More...

void	setPublicKey (const virgil::crypto::VirgilByteArray &key)
	Configures public key. More...

void	genKeyPair (VirgilKeyPair::Type type)
	Generates private and public keys. More...

void	genKeyPairFrom (const VirgilAsymmetricCipher &other)
	Generates private and public keys of the same type from the given context. More...

void	genKeyPairFromKeyMaterial (VirgilKeyPair::Type type, const VirgilByteArray &keyMaterial)
	Generates private and public keys from the given key material. More...

static VirgilByteArray	computeShared (const VirgilAsymmetricCipher &publicContext, const VirgilAsymmetricCipher &privateContext)
	Compute shared secret key on a given contexts. More...

Additional Inherited Members
Protected Member Functions inherited from virgil::crypto::foundation::asn1::VirgilAsn1Compatible
virtual void	checkRequiredField (const VirgilByteArray &param) const
	If given parameter is empty exception will be thrown. More...

Detailed Description

Provides asymmetric ciphers algorithms (PK).

Constructor & Destructor Documentation

virgil::crypto::foundation::VirgilAsymmetricCipher::VirgilAsymmetricCipher ( )

Create object that is not initialized with specific algorithm yet.

See Also: fromAsn1() method to initialize it.; genKeyPair() method to initialize it.; setPublicKey() method to initialize it.; setPrivateKey() method to initialize it.

Member Function Documentation

virtual void virgil::crypto::foundation::VirgilAsymmetricCipher::asn1Read ( virgil::crypto::foundation::asn1::VirgilAsn1Reader & asn1Reader )

overridevirtual

Read object state from the reader.

Parameters

asn1Reader reader payloaded with ASN.1 to be read.

Implements virgil::crypto::foundation::asn1::VirgilAsn1Compatible.

virtual size_t virgil::crypto::foundation::VirgilAsymmetricCipher::asn1Write	(	virgil::crypto::foundation::asn1::VirgilAsn1Writer &	asn1Writer,
		size_t	childWrittenBytes = `0`
	)		const

overridevirtual

Write object state to the writer.

Parameters

asn1Writer	writer that should be payloaded by subclasses.
childWrittenBytes	count of bytes that was written by subclasses.

Returns: Writen bytes count.

Implements virgil::crypto::foundation::asn1::VirgilAsn1Compatible.

static bool virgil::crypto::foundation::VirgilAsymmetricCipher::checkPrivateKeyPassword	(	const virgil::crypto::VirgilByteArray &	key,
		const virgil::crypto::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.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidPrivateKey, if private key is invalid.

static void virgil::crypto::foundation::VirgilAsymmetricCipher::checkPublicKey ( const virgil::crypto::VirgilByteArray & key )

static

Check if given public key has a valid format.

Ensure that given public key has the valid format PEM or DER.

Parameters

key	- public key to be checked.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidPublicKey, if public key is invalid.

static VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::computeShared	(	const VirgilAsymmetricCipher &	publicContext,
		const VirgilAsymmetricCipher &	privateContext
	)

static

Compute shared secret key on a given contexts.

Prerequisites:

Public context MUST handle public key.
Private context MUST handle private key.
Both contexts MUST handle Elliptic Curve keys of the same group.

Parameters

publicContext	- public context.
privateContext	- private context.

Exceptions

VirgilCryptoException	with VirgilCryptoError::NotInitialized, if public or private context are not initialized with specific algorithm.
VirgilCryptoException	with VirgilCryptoError::InvalidArgument, if prerequisites broken.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::decrypt ( const virgil::crypto::VirgilByteArray & in ) const

Decrypts given message.

Decrypt given message with known private key, configured with setPrivateKey method, or genKeyPair method.

Parameters

in	- message to be decrypted.

Returns: Decrypted message.

Exceptions

VirgilCryptoException with VirgilCryptoError::UnsupportedAlgorithm, if current context does not support decryption.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::encrypt ( const virgil::crypto::VirgilByteArray & in ) const

Encrypts given message.

Encrypt given message with known public key, configured with setPublicKey method, or genKeyPair method.

Parameters

in	- message to be encrypted.

Returns: Encrypted message.

Exceptions

VirgilCryptoException with VirgilCryptoError::UnsupportedAlgorithm, if current context does not support encryption.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::exportPrivateKeyToDER ( const virgil::crypto::VirgilByteArray & pwd = virgil::crypto::VirgilByteArray() ) const

Provides private key.

Parameters

pwd	- private key password (max length is 31 byte).

Returns: Private key in a PKCS#1, SEC1 DER or PKCS#8 structure format.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidState, if private key can not be exported.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::exportPrivateKeyToPEM ( const virgil::crypto::VirgilByteArray & pwd = virgil::crypto::VirgilByteArray() ) const

Provides private key.

Parameters

pwd	- private key password (max length is 31 byte).

Returns: Private key in a PKCS#1, SEC1 PEM or PKCS#8 structure format.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidState, if private key can not be exported.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::exportPublicKeyToDER ( ) const

Provides public key.

Returns: Public key in the SubjectPublicKeyInfo DER structure format.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidState, if public key can not be exported.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::exportPublicKeyToPEM ( ) const

Provides public key.

Returns: Public key in a SubjectPublicKeyInfo PEM structure format.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidState, if public key can not be exported.

void virgil::crypto::foundation::VirgilAsymmetricCipher::genKeyPair ( VirgilKeyPair::Type type )

Generates private and public keys.

Generate private and public keys in the current context.

Parameters

type	- keypair type.

Exceptions

VirgilCryptoException with VirgilCryptoError::UnsupportedAlgorithm, if key pair can't be generated with given type.

void virgil::crypto::foundation::VirgilAsymmetricCipher::genKeyPairFrom ( const VirgilAsymmetricCipher & other )

Generates private and public keys of the same type from the given context.

Parameters

other - donor context.

Exceptions

VirgilCryptoException	with VirgilCryptoError::NotInitialized, if donor context does not contain own key pair.
VirgilCryptoException	with VirgilCryptoError::UnsupportedAlgorithm, if key pair can't be generated with given type.

void virgil::crypto::foundation::VirgilAsymmetricCipher::genKeyPairFromKeyMaterial	(	VirgilKeyPair::Type	type,
		const VirgilByteArray &	keyMaterial
	)

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	- keypair type.
keyMaterial	- the only data to be used for key generation, must be strong enough.

Exceptions

VirgilCryptoException	with VirgilCryptoError::UnsupportedAlgorithm, if key pair can't be generated with given type.
VirgilCryptoException	with VirgilCryptoError::NotSecure, if Key Material is weak.

virgil::crypto::VirgilKeyPair::Type virgil::crypto::foundation::VirgilAsymmetricCipher::getKeyType ( ) const

Return type of the underlying key.

Note: Properly works only with Curve25519 keys.

Exceptions

VirgilCryptoException with VirgilCryptoError::NotInitialized, if key type is unknown.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::getPublicKeyBits ( ) const

Return number of the underlying public key.

Legend:

number - Fast EC point if underlying key belongs to the Elliptic Curve group

Note: Properly works only with X25519 and ED25519 keys.

Exceptions

VirgilCryptoException with VirgilCryptoError::UnsupportedAlgorithm, if given key type not allowed for this operation.

static bool virgil::crypto::foundation::VirgilAsymmetricCipher::isKeyPairMatch	(	const virgil::crypto::VirgilByteArray &	publicKey,
		const virgil::crypto::VirgilByteArray &	privateKey,
		const virgil::crypto::VirgilByteArray &	privateKeyPassword = `virgil::crypto::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::foundation::VirgilAsymmetricCipher::isPrivateKeyEncrypted ( const virgil::crypto::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.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidPrivateKey, if private key is invalid.

static bool virgil::crypto::foundation::VirgilAsymmetricCipher::isPublicKeyValid ( const virgil::crypto::VirgilByteArray & key )

static

Check if given public key has a valid format.

Ensure that given public key has the valid format PEM or DER.

Parameters

key	- public key to be checked.

Returns: true - if public key is valid, false - otherwise.

size_t virgil::crypto::foundation::VirgilAsymmetricCipher::keyLength ( ) const

Provides the length in bytes of the underlying key.

Returns: Length in bytes of the underlying key.

size_t virgil::crypto::foundation::VirgilAsymmetricCipher::keySize ( ) const

Provides size in bits of the underlying key.

Returns: Size in bits of the underlying key.

void virgil::crypto::foundation::VirgilAsymmetricCipher::setKeyType ( virgil::crypto::VirgilKeyPair::Type keyType )

Change type of the underlying key.

Note: Properly works only with Curve25519 keys.

Exceptions

VirgilCryptoException with VirgilCryptoError::UnsupportedAlgorithm, if given key type not allowed for this operation.

void virgil::crypto::foundation::VirgilAsymmetricCipher::setPrivateKey	(	const virgil::crypto::VirgilByteArray &	key,
		const virgil::crypto::VirgilByteArray &	pwd = `virgil::crypto::VirgilByteArray()`
	)

Configures private key.

Parse given private key and set it to the current context.

Parameters

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

Exceptions

VirgilCryptoException	with VirgilCryptoError::InvalidPrivateKey, if private key is invalid.
VirgilCryptoException	with VirgilCryptoError::InvalidPrivateKeyPassword, if private key password mismatch.

void virgil::crypto::foundation::VirgilAsymmetricCipher::setPublicKey ( const virgil::crypto::VirgilByteArray & key )

Configures public key.

Parse given public key and set it to the current context.

Parameters

key	- public key in DER or PEM format.

Exceptions

VirgilCryptoException with VirgilCryptoError::InvalidPublicKey, if public key is invalid.

void virgil::crypto::foundation::VirgilAsymmetricCipher::setPublicKeyBits ( const virgil::crypto::VirgilByteArray & bits )

Set number of the underlying public key.

Legend:

number - Fast EC point if underlying key belongs to the Elliptic Curve group

Note: Properly works only with X25519 and ED25519 keys.

Exceptions

VirgilCryptoException	with VirgilCryptoError::InvalidArgument, if given key size is unexpected.
VirgilCryptoException	with VirgilCryptoError::UnsupportedAlgorithm, if given key type not allowed for this operation.

virgil::crypto::VirgilByteArray virgil::crypto::foundation::VirgilAsymmetricCipher::sign	(	const virgil::crypto::VirgilByteArray &	digest,
		int	hashType
	)		const

Sign given hash.

Sign given hash with known private key, configured with setPrivateKey method, or genKeyPair method.

Parameters

digest	- digest to be signed.
hashType	- type of the hash algorithm that was used to get digest

Returns: Signed digest.

Exceptions

VirgilCryptoException with VirgilCryptoError::UnsupportedAlgorithm, if current context does not support sign or connected algorithms (Hash, RNG, etc).

bool virgil::crypto::foundation::VirgilAsymmetricCipher::verify	(	const virgil::crypto::VirgilByteArray &	digest,
		const virgil::crypto::VirgilByteArray &	sign,
		int	hashType
	)		const

Verify given hash with given sign.

Verify given hash with known public key, configured with setPrivateKey method, or genKeyPair method, and with given sign.

Parameters

digest	- digest to be verified.
sign	- signed digest to be used during verification.
hashType	- type of the hash algorithm that was used to get digest

Returns: true if given digest corresponds to the given digest sign, otherwise - false.

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

include/virgil/crypto/foundation/VirgilAsymmetricCipher.h

Public Member Functions

Static Public Member Functions

Keys management

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation