Azure SDK for JavaScript - Key Vault API Documentation

Key Vault SDK for JavaScript - API Reference

KeyClient

The KeyClient provides operations to manage cryptographic keys in Azure Key Vault. This client is for managing keys (create, delete, update, retrieve, etc.).

`createKey(name: string, keyType: KeyType, options?: CreateKeyOptions)`

Creates a new key in the specified Key Vault.

Parameters:

name (string): The name of the key to create. Must be unique within the Key Vault.
keyType (KeyType): The type of key to create (e.g., RSA, EC).
options (optional CreateKeyOptions): Additional options for key creation.

Returns:

A Promise that resolves with a KeyVaultKey object representing the created key.

// Example usage:
const { KeyClient, KeyType } = require("@azure/keyvault-keys");
const { DefaultAzureCredential } = require("@azure/identity");

const vaultUrl = "https://your-keyvault-name.vault.azure.net";
const credential = new DefaultAzureCredential();
const client = new KeyClient(vaultUrl, credential);

async function createRsaKey() {
    const keyName = "myNewRsaKey";
    const key = await client.createKey(keyName, KeyType.RSA);
    console.log(`Created key: ${key.name}`);
}
createRsaKey();

`getKey(name: string, options?: GetKeyOptions)`

Retrieves a specific key from the Key Vault.

Parameters:

name (string): The name of the key to retrieve.
options (optional GetKeyOptions): Additional options for retrieving the key.

Returns:

A Promise that resolves with a KeyVaultKey object representing the retrieved key.

`deleteKey(name: string, options?: DeleteKeyOptions)`

Deletes a key from the Key Vault. If the Key Vault is soft-delete enabled, the key is marked for deletion but can be recovered.

Parameters:

name (string): The name of the key to delete.
options (optional DeleteKeyOptions): Additional options for deleting the key.

Returns:

A Promise that resolves with a DeletedKeyVaultKey object representing the deleted key.

`listPropertiesOfKeys(options?: ListPropertiesOfKeysOptions)`

Lists the properties of all keys in the Key Vault.

Parameters:

options (optional ListPropertiesOfKeysOptions): Options for pagination and filtering.

Returns:

An async iterator that yields KeyProperties objects.

SecretClient

The SecretClient provides operations to manage secrets in Azure Key Vault. This client is for managing secrets (create, delete, update, retrieve, etc.).

`setSecret(name: string, value: string, options?: SetSecretOptions)`

Creates a new secret or updates an existing secret in the specified Key Vault.

Parameters:

name (string): The name of the secret to set.
value (string): The value of the secret.
options (optional SetSecretOptions): Additional options for setting the secret.

Returns:

A Promise that resolves with a KeyVaultSecret object representing the created or updated secret.

`getSecret(name: string, options?: GetSecretOptions)`

Retrieves a specific secret from the Key Vault.

Parameters:

name (string): The name of the secret to retrieve.
options (optional GetSecretOptions): Additional options for retrieving the secret.

Returns:

A Promise that resolves with a KeyVaultSecret object representing the retrieved secret.

`deleteSecret(name: string, options?: DeleteSecretOptions)`

Deletes a secret from the Key Vault. If the Key Vault is soft-delete enabled, the secret is marked for deletion but can be recovered.

Parameters:

name (string): The name of the secret to delete.
options (optional DeleteSecretOptions): Additional options for deleting the secret.

Returns:

A Promise that resolves with a DeletedKeyVaultSecret object representing the deleted secret.

CertificateClient

The CertificateClient provides operations to manage certificates in Azure Key Vault. This client is for managing certificates (create, delete, update, retrieve, etc.).

`importCertificate(name: string, pem: Uint8Array, options?: ImportCertificateOptions)`

Imports an existing certificate to the specified Key Vault.

Parameters:

name (string): The name of the certificate to import.
pem (Uint8Array): The certificate content in PEM format.
options (optional ImportCertificateOptions): Additional options for importing the certificate.

Returns:

A Promise that resolves with a KeyVaultCertificate object representing the imported certificate.

`getCertificate(name: string, options?: GetCertificateOptions)`

Retrieves a specific certificate from the Key Vault.

Parameters:

name (string): The name of the certificate to retrieve.
options (optional GetCertificateOptions): Additional options for retrieving the certificate.

Returns:

A Promise that resolves with a KeyVaultCertificate object representing the retrieved certificate.

`deleteCertificate(name: string, options?: DeleteCertificateOptions)`

Deletes a certificate from the Key Vault. If the Key Vault is soft-delete enabled, the certificate is marked for deletion but can be recovered.

Parameters:

name (string): The name of the certificate to delete.
options (optional DeleteCertificateOptions): Additional options for deleting the certificate.

Returns:

A Promise that resolves with a DeletedKeyVaultCertificate object representing the deleted certificate.

KeyClient (Management)

This section details operations for managing keys at the Key Vault level, typically for administrative tasks. These operations might require broader permissions.

`purgeDeletedKey(name: string, options?: PurgeDeletedKeyOptions)`

Performs a purge deletion of the specified key. This operation is restricted and only available for specific regions and when soft-delete is enabled.

Parameters:

name (string): The name of the key to purge.
options (optional PurgeDeletedKeyOptions): Additional options for purging the key.

Returns:

A Promise that resolves when the operation is complete.

SecretClient (Management)

This section details operations for managing secrets at the Key Vault level, typically for administrative tasks.

`purgeDeletedSecret(name: string, options?: PurgeDeletedSecretOptions)`

Performs a purge deletion of the specified secret. This operation is restricted and only available for specific regions and when soft-delete is enabled.

Parameters:

name (string): The name of the secret to purge.
options (optional PurgeDeletedSecretOptions): Additional options for purging the secret.

Returns:

A Promise that resolves when the operation is complete.

CertificateClient (Management)

This section details operations for managing certificates at the Key Vault level, typically for administrative tasks.

`purgeDeletedCertificate(name: string, options?: PurgeDeletedCertificateOptions)`

Performs a purge deletion of the specified certificate. This operation is restricted and only available for specific regions and when soft-delete is enabled.

Parameters:

name (string): The name of the certificate to purge.
options (optional PurgeDeletedCertificateOptions): Additional options for purging the certificate.

Returns:

A Promise that resolves when the operation is complete.

CryptoClient

The CryptoClient provides operations to perform cryptographic operations using keys stored in Azure Key Vault. This client is for performing actual encryption, decryption, signing, and verification.

`wrapKey(keyName: string, keyVersion: string, algorithm: KeyWrapAlgorithm, plainText: Uint8Array, options?: WrapKeyOptions)`

Wraps (encrypts) a symmetric key using a Key Vault key.

Parameters:

keyName (string): The name of the Key Vault key to use for wrapping.
keyVersion (string): The version of the Key Vault key.
algorithm (KeyWrapAlgorithm): The algorithm to use for wrapping (e.g., RSA-OAEP).
plainText (Uint8Array): The symmetric key to wrap.
options (optional WrapKeyOptions): Additional options for wrapping.

Returns:

A Promise that resolves with the wrapped key (encrypted symmetric key) as a Uint8Array.

`unwrapKey(keyName: string, keyVersion: string, algorithm: KeyWrapAlgorithm, cipherText: Uint8Array, options?: UnwrapKeyOptions)`

Unwraps (decrypts) a symmetric key using a Key Vault key.

Parameters:

keyName (string): The name of the Key Vault key to use for unwrapping.
keyVersion (string): The version of the Key Vault key.
algorithm (KeyWrapAlgorithm): The algorithm used for wrapping (e.g., RSA-OAEP).
cipherText (Uint8Array): The wrapped (encrypted) symmetric key.
options (optional UnwrapKeyOptions): Additional options for unwrapping.

Returns:

A Promise that resolves with the unwrapped key (decrypted symmetric key) as a Uint8Array.

`signData(keyName: string, keyVersion: string, algorithm: string, digest: Uint8Array, options?: SignDataOptions)`

Signs data using a Key Vault key.

Parameters:

keyName (string): The name of the Key Vault key to use for signing.
keyVersion (string): The version of the Key Vault key.
algorithm (string): The signing algorithm to use (e.g., RS256).
digest (Uint8Array): The digest of the data to sign.
options (optional SignDataOptions): Additional options for signing.

Returns:

A Promise that resolves with the signature as a Uint8Array.

Enumerations and Types

`KeyType`

Specifies the type of cryptographic key.

RSA: Asymmetric RSA key.
EC: Asymmetric Elliptic Curve key.

`KeyWrapAlgorithm`

Specifies the algorithm for wrapping/unwrapping keys.

RSA_OAEP: RSA Optimal Asymmetric Encryption Padding.
RSA_1_5: RSA encryption with PKCS #1.5 padding.

Options Types

`CreateKeyOptions`

Optional parameters for the createKey operation.

tags?: { [key: string]: string }: Optional tags for the key.
keySize?: number: The size of the RSA key in bits (e.g., 2048, 3072, 4096).
curve?: EllipticCurveName: The elliptic curve name for EC keys (e.g., P256, P384, P521, SECP256K1).
reuseKeyOn?: ReuseKeyOnOption: Specifies if the key can be reused for cryptographic operations.

`GetKeyOptions`

Optional parameters for the getKey operation.

version?: string: The specific version of the key to retrieve. If omitted, the latest version is retrieved.

`DeleteKeyOptions`

Optional parameters for the deleteKey operation.

ifUnchanged?: string: Specifies a content hash value. The operation will only proceed if the key's content matches this hash.

`ListPropertiesOfKeysOptions`

Optional parameters for the listPropertiesOfKeys operation.

maxPageSize?: number: The maximum number of keys to return in a single page.
includeManaged?: boolean: Whether to include managed keys.

`SetSecretOptions`

Optional parameters for the setSecret operation.

contentType?: string: The content type of the secret.
tags?: { [key: string]: string }: Optional tags for the secret.
contentType?: string: The content type of the secret.
tags?: { [key: string]: string }: Optional tags for the secret.

`GetSecretOptions`

Optional parameters for the getSecret operation.

version?: string: The specific version of the secret to retrieve. If omitted, the latest version is retrieved.

`DeleteSecretOptions`

Optional parameters for the deleteSecret operation.

ifUnchanged?: string: Specifies a content hash value. The operation will only proceed if the secret's content matches this hash.

`ImportCertificateOptions`

Optional parameters for the importCertificate operation.

tags?: { [key: string]: string }: Optional tags for the certificate.
password?: string: The password for the PFX data, if applicable.

`GetCertificateOptions`

Optional parameters for the getCertificate operation.

version?: string: The specific version of the certificate to retrieve. If omitted, the latest version is retrieved.

`DeleteCertificateOptions`

Optional parameters for the deleteCertificate operation.

ifUnchanged?: string: Specifies a content hash value. The operation will only proceed if the certificate's content matches this hash.

`PurgeDeletedKeyOptions`

Optional parameters for the purgeDeletedKey operation.

options?: {}: Placeholder for future options.

`PurgeDeletedSecretOptions`

Optional parameters for the purgeDeletedSecret operation.

options?: {}: Placeholder for future options.

`PurgeDeletedCertificateOptions`

Optional parameters for the purgeDeletedCertificate operation.

options?: {}: Placeholder for future options.

`WrapKeyOptions`

Optional parameters for the wrapKey operation.

algorithm?: KeyWrapAlgorithm: The key wrap algorithm to use.

`UnwrapKeyOptions`

Optional parameters for the unwrapKey operation.

algorithm?: KeyWrapAlgorithm: The key wrap algorithm to use.

`SignDataOptions`

Optional parameters for the signData operation.

algorithm?: string: The signing algorithm to use.