Virgil Security Crypto library  2.0.7
List of all members
virgil::crypto::foundation::VirgilAsymmetricCipher Class Reference

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

#include <VirgilAsymmetricCipher.h>

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

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...
 
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
asn1Readerreader 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
asn1Writerwriter that should be payloaded by subclasses.
childWrittenBytescount 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith VirgilCryptoError::NotInitialized, if public or private context are not initialized with specific algorithm.
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith VirgilCryptoError::NotInitialized, if donor context does not contain own key pair.
VirgilCryptoExceptionwith VirgilCryptoError::UnsupportedAlgorithm, if key pair can't be generated with given type.
virgil::crypto::VirgilKeyPair::Type virgil::crypto::foundation::VirgilAsymmetricCipher::getKeyType ( ) const

Return type of the underlying key.

Note
Properly works only with Curve25519 keys.
Exceptions
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith VirgilCryptoError::InvalidPrivateKey, if private key is invalid.
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith VirgilCryptoError::InvalidArgument, if given key size is unexpected.
VirgilCryptoExceptionwith 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
VirgilCryptoExceptionwith 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: