CryptographyClient class

Package:

@azure/keyvault-keys

A client used to perform cryptographic operations on an Azure Key vault key or a local JsonWebKey.

Constructors

CryptographyClient(JsonWebKey_2)

Constructs a new instance of the Cryptography client for the given key in local mode. Example usage: import { CryptographyClient } from "@azure/keyvault-keys"; const jsonWebKey: JsonWebKey = { // ... }; const client = new CryptographyClient(jsonWebKey);

CryptographyClient(string | KeyVaultKey, TokenCredential, CryptographyClientOptions)

Constructs a new instance of the Cryptography client for the given key Example usage: import { KeyClient, CryptographyClient } from "@azure/keyvault-keys"; import { DefaultAzureCredential } from "@azure/identity"; let vaultUrl = `https://<MY KEYVAULT HERE>.vault.azure.net`; let credentials = new DefaultAzureCredential(); let keyClient = new KeyClient(vaultUrl, credentials); let keyVaultKey = await keyClient.getKey("MyKey"); let client = new CryptographyClient(keyVaultKey.id, credentials); // or let client = new CryptographyClient(keyVaultKey, credentials);

Properties

keyID	The ID of the key used to perform cryptographic operations for the client.
vaultUrl	The base URL to the vault. If a local JsonWebKey is used vaultUrl will be empty.

Methods

decrypt(DecryptParameters, DecryptOptions)	Decrypts the given ciphertext with the specified decryption parameters. Depending on the algorithm used in the decryption parameters, the set of possible decryption parameters will change. Microsoft recommends you not use CBC without first ensuring the integrity of the ciphertext using, for example, an HMAC. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information. Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.decrypt({ algorithm: "RSA1_5", ciphertext: encryptedBuffer }); let result = await client.decrypt({ algorithm: "A256GCM", iv: ivFromEncryptResult, authenticationTag: tagFromEncryptResult });
decrypt(string, Uint8Array, DecryptOptions)	Decrypts the given ciphertext with the specified cryptography algorithm Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.decrypt("RSA1_5", encryptedBuffer); Microsoft recommends you not use CBC without first ensuring the integrity of the ciphertext using, for example, an HMAC. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information.
encrypt(EncryptParameters, EncryptOptions)	Encrypts the given plaintext with the specified encryption parameters. Depending on the algorithm set in the encryption parameters, the set of possible encryption parameters will change. Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.encrypt({ algorithm: "RSA1_5", plaintext: Buffer.from("My Message")}); let result = await client.encrypt({ algorithm: "A256GCM", plaintext: Buffer.from("My Message"), additionalAuthenticatedData: Buffer.from("My authenticated data")});
encrypt(string, Uint8Array, EncryptOptions)	Encrypts the given plaintext with the specified cryptography algorithm Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.encrypt("RSA1_5", Buffer.from("My Message"));
sign(string, Uint8Array, SignOptions)	Cryptographically sign the digest of a message Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.sign("RS256", digest);
signData(string, Uint8Array, SignOptions)	Cryptographically sign a block of data Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.signData("RS256", message);
unwrapKey(KeyWrapAlgorithm, Uint8Array, UnwrapKeyOptions)	Unwraps the given wrapped key using the specified cryptography algorithm Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.unwrapKey("RSA1_5", keyToUnwrap);
verify(string, Uint8Array, Uint8Array, VerifyOptions)	Verify the signed message digest Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.verify("RS256", signedDigest, signature);
verifyData(string, Uint8Array, Uint8Array, VerifyOptions)	Verify the signed block of data Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.verifyData("RS256", signedMessage, signature);
wrapKey(KeyWrapAlgorithm, Uint8Array, WrapKeyOptions)	Wraps the given key using the specified cryptography algorithm Example usage: let client = new CryptographyClient(keyVaultKey, credentials); let result = await client.wrapKey("RSA1_5", keyToWrap);

Constructor Details

CryptographyClient(JsonWebKey_2)

Constructs a new instance of the Cryptography client for the given key in local mode.

Example usage:

import { CryptographyClient } from "@azure/keyvault-keys";

const jsonWebKey: JsonWebKey = {
  // ...
};
const client = new CryptographyClient(jsonWebKey);

new CryptographyClient(key: JsonWebKey_2)

Parameters

key

JsonWebKey

The JsonWebKey to use during cryptography operations.

CryptographyClient(string | KeyVaultKey, TokenCredential, CryptographyClientOptions)

Constructs a new instance of the Cryptography client for the given key

Example usage:

import { KeyClient, CryptographyClient } from "@azure/keyvault-keys";
import { DefaultAzureCredential } from "@azure/identity";

let vaultUrl = `https://<MY KEYVAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();

let keyClient = new KeyClient(vaultUrl, credentials);
let keyVaultKey = await keyClient.getKey("MyKey");

let client = new CryptographyClient(keyVaultKey.id, credentials);
// or
let client = new CryptographyClient(keyVaultKey, credentials);

new CryptographyClient(key: string | KeyVaultKey, credential: TokenCredential, pipelineOptions?: CryptographyClientOptions)

Parameters

key

string | KeyVaultKey

The key to use during cryptography tasks. You can also pass the identifier of the key i.e its url here.

credential

TokenCredential

An object that implements the TokenCredential interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs.

pipelineOptions

CryptographyClientOptions

Pipeline options used to configure Key Vault API requests. Omit this parameter to use the default pipeline configuration.

Property Details

keyID

The ID of the key used to perform cryptographic operations for the client.

undefined | string keyID

Property Value

undefined | string

vaultUrl

The base URL to the vault. If a local JsonWebKey is used vaultUrl will be empty.

string vaultUrl

Property Value

string

Method Details

decrypt(DecryptParameters, DecryptOptions)

Decrypts the given ciphertext with the specified decryption parameters. Depending on the algorithm used in the decryption parameters, the set of possible decryption parameters will change.

Microsoft recommends you not use CBC without first ensuring the integrity of the ciphertext using, for example, an HMAC. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information.

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.decrypt({ algorithm: "RSA1_5", ciphertext: encryptedBuffer });
let result = await client.decrypt({ algorithm: "A256GCM", iv: ivFromEncryptResult, authenticationTag: tagFromEncryptResult });

function decrypt(decryptParameters: DecryptParameters, options?: DecryptOptions): Promise<DecryptResult>

Parameters

decryptParameters

DecryptParameters

The decryption parameters.

options

DecryptOptions

Additional options.

Returns

Promise<DecryptResult>

decrypt(string, Uint8Array, DecryptOptions)

Warning

This API is now deprecated.

Use decrypt({ algorithm, ciphertext }, options) instead.

Decrypts the given ciphertext with the specified cryptography algorithm

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.decrypt("RSA1_5", encryptedBuffer);

Microsoft recommends you not use CBC without first ensuring the integrity of the ciphertext using, for example, an HMAC. See https://docs.microsoft.com/dotnet/standard/security/vulnerabilities-cbc-mode for more information.

function decrypt(algorithm: string, ciphertext: Uint8Array, options?: DecryptOptions): Promise<DecryptResult>

Parameters

algorithm

string

The algorithm to use.

ciphertext

Uint8Array

The text to decrypt.

options

DecryptOptions

Additional options.

Returns

Promise<DecryptResult>

encrypt(EncryptParameters, EncryptOptions)

Encrypts the given plaintext with the specified encryption parameters. Depending on the algorithm set in the encryption parameters, the set of possible encryption parameters will change.

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.encrypt({ algorithm: "RSA1_5", plaintext: Buffer.from("My Message")});
let result = await client.encrypt({ algorithm: "A256GCM", plaintext: Buffer.from("My Message"), additionalAuthenticatedData: Buffer.from("My authenticated data")});

function encrypt(encryptParameters: EncryptParameters, options?: EncryptOptions): Promise<EncryptResult>

Parameters

encryptParameters

EncryptParameters

The encryption parameters, keyed on the encryption algorithm chosen.

options

EncryptOptions

Additional options.

Returns

Promise<EncryptResult>

encrypt(string, Uint8Array, EncryptOptions)

Warning

This API is now deprecated.

Use encrypt({ algorithm, plaintext }, options) instead.

Encrypts the given plaintext with the specified cryptography algorithm

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.encrypt("RSA1_5", Buffer.from("My Message"));

function encrypt(algorithm: string, plaintext: Uint8Array, options?: EncryptOptions): Promise<EncryptResult>

Parameters

algorithm

string

The algorithm to use.

plaintext

Uint8Array

The text to encrypt.

options

EncryptOptions

Additional options.

Returns

Promise<EncryptResult>

sign(string, Uint8Array, SignOptions)

Cryptographically sign the digest of a message

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.sign("RS256", digest);

function sign(algorithm: string, digest: Uint8Array, options?: SignOptions): Promise<SignResult>

Parameters

algorithm

string

The signing algorithm to use.

digest

Uint8Array

The digest of the data to sign.

options

SignOptions

Additional options.

Returns

Promise<SignResult>

signData(string, Uint8Array, SignOptions)

Cryptographically sign a block of data

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.signData("RS256", message);

function signData(algorithm: string, data: Uint8Array, options?: SignOptions): Promise<SignResult>

Parameters

algorithm

string

The signing algorithm to use.

data

Uint8Array

The data to sign.

options

SignOptions

Additional options.

Returns

Promise<SignResult>

unwrapKey(KeyWrapAlgorithm, Uint8Array, UnwrapKeyOptions)

Unwraps the given wrapped key using the specified cryptography algorithm

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.unwrapKey("RSA1_5", keyToUnwrap);

function unwrapKey(algorithm: KeyWrapAlgorithm, encryptedKey: Uint8Array, options?: UnwrapKeyOptions): Promise<UnwrapResult>

Parameters

algorithm

KeyWrapAlgorithm

The decryption algorithm to use to unwrap the key.

encryptedKey

Uint8Array

The encrypted key to unwrap.

options

UnwrapKeyOptions

Additional options.

Returns

Promise<UnwrapResult>

verify(string, Uint8Array, Uint8Array, VerifyOptions)

Verify the signed message digest

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.verify("RS256", signedDigest, signature);

function verify(algorithm: string, digest: Uint8Array, signature: Uint8Array, options?: VerifyOptions): Promise<VerifyResult>

Parameters

algorithm

string

The signing algorithm to use to verify with.

digest

Uint8Array

The digest to verify.

signature

Uint8Array

The signature to verify the digest against.

options

VerifyOptions

Additional options.

Returns

Promise<VerifyResult>

verifyData(string, Uint8Array, Uint8Array, VerifyOptions)

Verify the signed block of data

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.verifyData("RS256", signedMessage, signature);

function verifyData(algorithm: string, data: Uint8Array, signature: Uint8Array, options?: VerifyOptions): Promise<VerifyResult>

Parameters

algorithm

string

The algorithm to use to verify with.

data

Uint8Array

The signed block of data to verify.

signature

Uint8Array

The signature to verify the block against.

options

VerifyOptions

Additional options.

Returns

Promise<VerifyResult>

wrapKey(KeyWrapAlgorithm, Uint8Array, WrapKeyOptions)

Wraps the given key using the specified cryptography algorithm

Example usage:

let client = new CryptographyClient(keyVaultKey, credentials);
let result = await client.wrapKey("RSA1_5", keyToWrap);

function wrapKey(algorithm: KeyWrapAlgorithm, key: Uint8Array, options?: WrapKeyOptions): Promise<WrapResult>

Parameters

algorithm

KeyWrapAlgorithm

The encryption algorithm to use to wrap the given key.

key

Uint8Array

The key to wrap.

options

WrapKeyOptions

Additional options.

Returns

Promise<WrapResult>