Options
All
  • Public
  • Public/Protected
  • All
Menu

Provides implementation of high-level cryptographic operations using Virgil Crypto Library.

Hierarchy

  • VirgilCrypto

Index

Constructors

constructor

  • new VirgilCrypto(__namedParameters?: object): VirgilCrypto

Properties

defaultKeyPairType

defaultKeyPairType: KeyPairType

Type of keys to generate by default.

useSha256Identifiers

useSha256Identifiers: boolean

Indicates whether to use old algorithm to calculate keypair identifiers.

Current algorithm: first 8 bytes of SHA512 hash of public key in DER format.

Old algorithm: SHA256 hash of public key in DER format.

Use SHA256 identifiers only if you need to be compatible with version 2 of this library (i.e. decrypt data that were encrypted using the version 2).

Default is false (new algorithm)

Methods

calculateHash

  • Calculates the hash of the given data.

    Parameters

    • data: Data

      The data to calculate the hash of. If data is a string, utf-8 encoding is assumed.

    • Default value algorithm: HashAlgorithm = HashAlgorithm.SHA256

    Returns Buffer

    • The hash.

calculateSignature

  • Calculates the signature of the data using the private key.

    NOTE: Returned value contains only digital signature, not data itself.

    NOTE: Data inside this function is guaranteed to be hashed with SHA512 at least one time.

    It's secure to pass raw data here.

    Parameters

    • data: Data

      The data to be signed. If data is a string, utf-8 encoding is assumed.

    • privateKey: VirgilPrivateKey

      The private key object.

    Returns Buffer

    • The signature.

createStreamCipher

createStreamDecipher

createStreamSigner

createStreamVerifier

  • Creates an instance of VirgilStreamVerifier to be used to verify the signature for the data in coming in chunks.

    Parameters

    • signature: Data

      The signature to be verified.

    • encoding: StringEncoding

      If signature is a string, specifies its encoding, otherwise is ignored. Default is 'utf8'.

    Returns VirgilStreamVerifier

decrypt

  • Decrypts the data with the given private key following the algorithm below:

    1. Uses Diffie-Hellman to obtain shared secret with sender ephemeral public key & the privateKey
    2. Computes KDF to obtain AES-256 KEY2 from shared secret
    3. Decrypts KEY1 using AES-256-CBC and KEY2
    4. Decrypts data using KEY1 and AES-256-GCM

    Parameters

    • encryptedData: Data

      The data to be decrypted. If encryptedData is a string, base64 encoding is assumed.

    • privateKey: VirgilPrivateKey

      The private key to decrypt with.

    Returns Buffer

    • Decrypted data

decryptThenVerify

  • Decrypts the data using the private key, then verifies decrypted data using the attached signature and the given public key.

    1. Uses Diffie-Hellman to obtain shared secret with sender ephemeral public key & recipient's private key
    2. Computes KDF to obtain AES-256 key - KEY2 - from shared secret
    3. Decrypts KEY1 using AES-256-CBC and KEY2
    4. Decrypts both data and signature using KEY1 and AES-256-GCM
    5. Verifies signature

    Parameters

    • encryptedData: Data

      The data to be decrypted and verified. If encryptedData is a string, base64 encoding is assumed.

    • privateKey: VirgilPrivateKey

      The private key object to use for decryption.

    • publicKey: VirgilPublicKey | VirgilPublicKey[]

      The public key object or an array of public key objects to use to verify data integrity. If publicKey is an array, the attached signature must be valid for any one of them.

    Returns Buffer

decryptThenVerifyDetached

  • Same as {@link IVirgilCrypto.decryptThenVerify} but expects the Virgil Cryptogram (the content info) to be passed as contentInfo parameter instead of be embedded in the encryptedData.

    Parameters

    • encryptedData: Data

      The data to be decrypted and verified. If encryptedData is a string, base64 encoding is assumed.

    • metadata: Data

      The metadata (i.e. public algorithm parameters used for encryption) required for decryption.

    • privateKey: VirgilPrivateKey

      The private key object to use for decryption.

    • publicKey: VirgilPublicKey | VirgilPublicKey[]

      The public key object or an array of public key objects to use to verify data integrity. If the public key identifier specified in metadata does not correspond to the publicKey argument (or any of the keys in the publicKey array), an error is thrown.

    Returns Buffer

encrypt

  • Encrypts the data for the given public key(s) following the algorithm below:

    1. Generates random AES-256 key - KEY1
    2. Encrypts the data with KEY1 using AES-256-GCM
    3. Generates ephemeral keypair for each recipient public key
    4. Uses Diffie-Hellman to obtain shared secret with each recipient public key & ephemeral private key
    5. Computes KDF to obtain AES-256 key - KEY2 - from shared secret for each recipient
    6. Encrypts KEY1 with KEY2 using AES-256-CBC for each recipient

    Parameters

    • data: Data

      The data to be encrypted. If data is a string, utf-8 encoding is assumed.

    • publicKey: VirgilPublicKey | VirgilPublicKey[]

      Public key or an array of public keys of the intended recipients.

    Returns Buffer

    • Encrypted data.

exportPrivateKey

  • exportPrivateKey(privateKey: VirgilPrivateKey, password?: undefined | string): Buffer
  • Exports private key material in DER format from the given private key object.

    Parameters

    • privateKey: VirgilPrivateKey

      The private key object.

    • Optional password: undefined | string

    Returns Buffer

    • The private key material in DER format.

exportPublicKey

  • Exports public key material in DER format from the given public key object.

    Parameters

    Returns Buffer

    • The public key bytes.

extractPublicKey

generateKeys

generateKeysFromKeyMaterial

  • Generates a new key pair from the given key material.

    Parameters

    • keyMaterial: Data

      The data to be used for key generation, must be strong enough (have high entropy). If keyMaterial is a string, base64 encoding is assumed.

    • Optional type: KeyPairType

    Returns VirgilKeyPair

getRandomBytes

  • getRandomBytes(length: number): Buffer
  • Generates a pseudo-random sequence of bytes of the given length.

    Parameters

    • length: number

      The number of bytes to generate.

    Returns Buffer

importPrivateKey

  • Creates a VirgilPrivateKey object from private key bytes in PEM or DER format.

    Parameters

    • rawPrivateKey: Data

      The private key bytes. If rawPrivateKey is a string, base64 encoding is assumed.

    • Optional password: undefined | string

    Returns VirgilPrivateKey

    • The private key object.

importPublicKey

  • Creates a VirgilPublicKey object from public key material in PEM or DER format.

    Parameters

    • rawPublicKey: Data

      The public key bytes. If rawPublicKey is a string, base64 encoding is assumed.

    Returns VirgilPublicKey

    • The imported key handle.

signThenEncrypt

  • Calculates the signature on the data using the private key, then encrypts the data along with the signature using the public key(s).

    1. Generates signature depending on the type of private key
    2. Generates random AES-256 key - KEY1
    3. Encrypts both data and signature with KEY1 using AES-256-GCM
    4. Generates ephemeral key pair for each recipient
    5. Uses Diffie-Hellman to obtain shared secret with each recipient's public key & each ephemeral private key
    6. Computes KDF to obtain AES-256 key - KEY2 - from shared secret for each recipient
    7. Encrypts KEY1 with KEY2 using AES-256-CBC for each recipient

    Parameters

    • data: Data

      The data to sign and encrypt. If data is a string, utf-8 encoding is assumed.

    • privateKey: VirgilPrivateKey

      The private key to use to calculate signature.

    • publicKey: VirgilPublicKey | VirgilPublicKey[]

      The public key of the intended recipient or an array of public keys of multiple recipients.

    Returns Buffer

    • Encrypted data with attached signature.

signThenEncryptDetached

  • Same as {@link IVirgilCrypto.signThenEncrypt} but returns the metadata (i.e. public algorithm parameters used for encryption) as a separate property on the response object rather than embedded in the encrypted data as regular signThenEncrypt does.

    Parameters

    • data: Data

      The data to sign and encrypt. If data is a string, utf-8 encoding is assumed.

    • privateKey: VirgilPrivateKey

      The private key to use to calculate signature.

    • publicKey: VirgilPublicKey | VirgilPublicKey[]

      The public key of the intended recipient or an array of public keys of multiple recipients.

    Returns object

    • Encrypted data and metadata.

verifySignature

  • Verifies the provided data using the given signature and public key. Note: Verification algorithm depends on PublicKey type. Default: EdDSA

    Parameters

    • data: Data

      The data to be verified. If data is a string, utf-8 encoding is assumed.

    • signature: Data

      The signature to verify. If signature is a string, base64 encoding is assumed.

    • publicKey: VirgilPublicKey

      The public key object.

    Returns boolean

    • True or False depending on the validity of the signature for the data and public key.