CryptographyClient class
A client used to perform cryptographic operations on an Azure Key vault key or a local JsonWebKey.
Constructors
| Cryptography |
Constructs a new instance of the Cryptography client for the given key in local mode. Example usage: |
| Cryptography |
Constructs a new instance of the Cryptography client for the given key Example usage: |
Properties
| keyID | The ID of the key used to perform cryptographic operations for the client. |
| vault |
The base URL to the vault. If a local JsonWebKey is used vaultUrl will be empty. |
Methods
| decrypt(Decrypt |
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: |
| decrypt(string, Uint8Array, Decrypt |
Decrypts the given ciphertext with the specified cryptography algorithm Example usage: 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(Encrypt |
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: |
| encrypt(string, Uint8Array, Encrypt |
Encrypts the given plaintext with the specified cryptography algorithm Example usage: |
| sign(string, Uint8Array, Sign |
Cryptographically sign the digest of a message Example usage: |
| sign |
Cryptographically sign a block of data Example usage: |
| unwrap |
Unwraps the given wrapped key using the specified cryptography algorithm Example usage: |
| verify(string, Uint8Array, Uint8Array, Verify |
Verify the signed message digest Example usage: |
| verify |
Verify the signed block of data Example usage: |
| wrap |
Wraps the given key using the specified cryptography algorithm Example usage: |
Constructor Details
CryptographyClient(JsonWebKey)
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)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 keyIDProperty Value
undefined | string
vaultUrl
The base URL to the vault. If a local JsonWebKey is used vaultUrl will be empty.
string vaultUrlProperty 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>