Back to Details

azure-keyvault-keys-ts

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Azure Key Vault Keys SDK for TypeScript

适用于TypeScript的Azure Key Vault Keys SDK

Manage cryptographic keys with Azure Key Vault.
使用Azure Key Vault管理加密密钥。

Installation

安装

bash
undefined
bash
undefined

Keys SDK

Keys SDK

npm install @azure/keyvault-keys @azure/identity
undefined
npm install @azure/keyvault-keys @azure/identity
undefined

Environment Variables

环境变量

bash
KEY_VAULT_URL=https://<vault-name>.vault.azure.net
bash
KEY_VAULT_URL=https://<vault-name>.vault.azure.net

Or

Or

AZURE_KEYVAULT_NAME=<vault-name>
undefined
AZURE_KEYVAULT_NAME=<vault-name>
undefined

Authentication

身份验证

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

const credential = new DefaultAzureCredential();
const vaultUrl = `https://${process.env.AZURE_KEYVAULT_NAME}.vault.azure.net`;

const keyClient = new KeyClient(vaultUrl, credential);
const secretClient = new SecretClient(vaultUrl, credential);
typescript
import { DefaultAzureCredential } from "@azure/identity";
import { KeyClient, CryptographyClient } from "@azure/keyvault-keys";

const credential = new DefaultAzureCredential();
const vaultUrl = `https://${process.env.AZURE_KEYVAULT_NAME}.vault.azure.net`;

const keyClient = new KeyClient(vaultUrl, credential);
const secretClient = new SecretClient(vaultUrl, credential);

Secrets Operations

机密操作

Create/Set Secret

创建/设置机密

typescript
const secret = await secretClient.setSecret("MySecret", "secret-value");

// With attributes
const secretWithAttrs = await secretClient.setSecret("MySecret", "value", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  contentType: "application/json",
  tags: { environment: "production" }
});
typescript
const secret = await secretClient.setSecret("MySecret", "secret-value");

// With attributes
const secretWithAttrs = await secretClient.setSecret("MySecret", "value", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  contentType: "application/json",
  tags: { environment: "production" }
});

Get Secret

获取机密

typescript
// Get latest version
const secret = await secretClient.getSecret("MySecret");
console.log(secret.value);

// Get specific version
const specificSecret = await secretClient.getSecret("MySecret", {
  version: secret.properties.version
});
typescript
// 获取最新版本
const secret = await secretClient.getSecret("MySecret");
console.log(secret.value);

// 获取指定版本
const specificSecret = await secretClient.getSecret("MySecret", {
  version: secret.properties.version
});

List Secrets

列出机密

typescript
for await (const secretProperties of secretClient.listPropertiesOfSecrets()) {
  console.log(secretProperties.name);
}

// List versions
for await (const version of secretClient.listPropertiesOfSecretVersions("MySecret")) {
  console.log(version.version);
}
typescript
for await (const secretProperties of secretClient.listPropertiesOfSecrets()) {
  console.log(secretProperties.name);
}

// 列出版本
for await (const version of secretClient.listPropertiesOfSecretVersions("MySecret")) {
  console.log(version.version);
}

Delete Secret

删除机密

typescript
// Soft delete
const deletePoller = await secretClient.beginDeleteSecret("MySecret");
await deletePoller.pollUntilDone();

// Purge (permanent)
await secretClient.purgeDeletedSecret("MySecret");

// Recover
const recoverPoller = await secretClient.beginRecoverDeletedSecret("MySecret");
await recoverPoller.pollUntilDone();
typescript
// 软删除
const deletePoller = await secretClient.beginDeleteSecret("MySecret");
await deletePoller.pollUntilDone();

// 彻底清除
await secretClient.purgeDeletedSecret("MySecret");

// 恢复
const recoverPoller = await secretClient.beginRecoverDeletedSecret("MySecret");
await recoverPoller.pollUntilDone();

Keys Operations

密钥操作

Create Keys

创建密钥

typescript
// Generic key
const key = await keyClient.createKey("MyKey", "RSA");

// RSA key with size
const rsaKey = await keyClient.createRsaKey("MyRsaKey", { keySize: 2048 });

// Elliptic Curve key
const ecKey = await keyClient.createEcKey("MyEcKey", { curve: "P-256" });

// With attributes
const keyWithAttrs = await keyClient.createKey("MyKey", "RSA", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  tags: { purpose: "encryption" },
  keyOps: ["encrypt", "decrypt", "sign", "verify"]
});
typescript
// 通用密钥
const key = await keyClient.createKey("MyKey", "RSA");

// 指定大小的RSA密钥
const rsaKey = await keyClient.createRsaKey("MyRsaKey", { keySize: 2048 });

// 椭圆曲线密钥
const ecKey = await keyClient.createEcKey("MyEcKey", { curve: "P-256" });

// 带属性的密钥
const keyWithAttrs = await keyClient.createKey("MyKey", "RSA", {
  enabled: true,
  expiresOn: new Date("2025-12-31"),
  tags: { purpose: "encryption" },
  keyOps: ["encrypt", "decrypt", "sign", "verify"]
});

Get Key

获取密钥

typescript
const key = await keyClient.getKey("MyKey");
console.log(key.name, key.keyType);
typescript
const key = await keyClient.getKey("MyKey");
console.log(key.name, key.keyType);

List Keys

列出密钥

typescript
for await (const keyProperties of keyClient.listPropertiesOfKeys()) {
  console.log(keyProperties.name);
}
typescript
for await (const keyProperties of keyClient.listPropertiesOfKeys()) {
  console.log(keyProperties.name);
}

Rotate Key

轮换密钥

typescript
// Manual rotation
const rotatedKey = await keyClient.rotateKey("MyKey");

// Set rotation policy
await keyClient.updateKeyRotationPolicy("MyKey", {
  lifetimeActions: [{ action: "Rotate", timeBeforeExpiry: "P30D" }],
  expiresIn: "P90D"
});
typescript
// 手动轮换
const rotatedKey = await keyClient.rotateKey("MyKey");

// 设置轮换策略
await keyClient.updateKeyRotationPolicy("MyKey", {
  lifetimeActions: [{ action: "Rotate", timeBeforeExpiry: "P30D" }],
  expiresIn: "P90D"
});

Delete Key

删除密钥

typescript
const deletePoller = await keyClient.beginDeleteKey("MyKey");
await deletePoller.pollUntilDone();

// Purge
await keyClient.purgeDeletedKey("MyKey");
typescript
const deletePoller = await keyClient.beginDeleteKey("MyKey");
await deletePoller.pollUntilDone();

// 彻底清除
await keyClient.purgeDeletedKey("MyKey");

Cryptographic Operations

加密操作

Create CryptographyClient

创建CryptographyClient

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

// From key object
const cryptoClient = new CryptographyClient(key, credential);

// From key ID
const cryptoClient = new CryptographyClient(key.id!, credential);
typescript
import { CryptographyClient } from "@azure/keyvault-keys";

// 通过密钥对象创建
const cryptoClient = new CryptographyClient(key, credential);

// 通过密钥ID创建
const cryptoClient = new CryptographyClient(key.id!, credential);

Encrypt/Decrypt

加密/解密

typescript
// Encrypt
const encryptResult = await cryptoClient.encrypt({
  algorithm: "RSA-OAEP",
  plaintext: Buffer.from("My secret message")
});

// Decrypt
const decryptResult = await cryptoClient.decrypt({
  algorithm: "RSA-OAEP",
  ciphertext: encryptResult.result
});

console.log(decryptResult.result.toString());
typescript
// 加密
const encryptResult = await cryptoClient.encrypt({
  algorithm: "RSA-OAEP",
  plaintext: Buffer.from("My secret message")
});

// 解密
const decryptResult = await cryptoClient.decrypt({
  algorithm: "RSA-OAEP",
  ciphertext: encryptResult.result
});

console.log(decryptResult.result.toString());

Sign/Verify

签名/验签

typescript
import { createHash } from "node:crypto";

// Create digest
const hash = createHash("sha256").update("My message").digest();

// Sign
const signResult = await cryptoClient.sign("RS256", hash);

// Verify
const verifyResult = await cryptoClient.verify("RS256", hash, signResult.result);
console.log("Valid:", verifyResult.result);
typescript
import { createHash } from "node:crypto";

// 创建摘要
const hash = createHash("sha256").update("My message").digest();

// 签名
const signResult = await cryptoClient.sign("RS256", hash);

// 验签
const verifyResult = await cryptoClient.verify("RS256", hash, signResult.result);
console.log("Valid:", verifyResult.result);

Wrap/Unwrap Keys

包装/解包密钥

typescript
// Wrap a key (encrypt it for storage)
const wrapResult = await cryptoClient.wrapKey("RSA-OAEP", Buffer.from("key-material"));

// Unwrap
const unwrapResult = await cryptoClient.unwrapKey("RSA-OAEP", wrapResult.result);
typescript
// 包装密钥（加密后存储）
const wrapResult = await cryptoClient.wrapKey("RSA-OAEP", Buffer.from("key-material"));

// 解包
const unwrapResult = await cryptoClient.unwrapKey("RSA-OAEP", wrapResult.result);

Backup and Restore

备份与恢复

typescript
// Backup
const keyBackup = await keyClient.backupKey("MyKey");
const secretBackup = await secretClient.backupSecret("MySecret");

// Restore (can restore to different vault)
const restoredKey = await keyClient.restoreKeyBackup(keyBackup!);
const restoredSecret = await secretClient.restoreSecretBackup(secretBackup!);
typescript
// 备份
const keyBackup = await keyClient.backupKey("MyKey");
const secretBackup = await secretClient.backupSecret("MySecret");

// 恢复（可恢复到不同的密钥保管库）
const restoredKey = await keyClient.restoreKeyBackup(keyBackup!);
const restoredSecret = await secretClient.restoreSecretBackup(secretBackup!);

Key Types

密钥类型

typescript
import {
  KeyClient,
  KeyVaultKey,
  KeyProperties,
  DeletedKey,
  CryptographyClient,
  KnownEncryptionAlgorithms,
  KnownSignatureAlgorithms
} from "@azure/keyvault-keys";

import {
  SecretClient,
  KeyVaultSecret,
  SecretProperties,
  DeletedSecret
} from "@azure/keyvault-secrets";
typescript
import {
  KeyClient,
  KeyVaultKey,
  KeyProperties,
  DeletedKey,
  CryptographyClient,
  KnownEncryptionAlgorithms,
  KnownSignatureAlgorithms
} from "@azure/keyvault-keys";

import {
  SecretClient,
  KeyVaultSecret,
  SecretProperties,
  DeletedSecret
} from "@azure/keyvault-secrets";

Error Handling

错误处理

typescript
try {
  const secret = await secretClient.getSecret("NonExistent");
} catch (error: any) {
  if (error.code === "SecretNotFound") {
    console.log("Secret does not exist");
  } else {
    throw error;
  }
}
typescript
try {
  const secret = await secretClient.getSecret("NonExistent");
} catch (error: any) {
  if (error.code === "SecretNotFound") {
    console.log("Secret does not exist");
  } else {
    throw error;
  }
}

Best Practices

最佳实践

  1. Use DefaultAzureCredential - Works across dev and production
  2. Enable soft-delete - Required for production vaults
  3. Set expiration dates - On both keys and secrets
  4. Use key rotation policies - Automate key rotation
  5. Limit key operations - Only grant needed operations (encrypt, sign, etc.)
  6. Browser not supported - These SDKs are Node.js only
  1. 使用DefaultAzureCredential - 在开发和生产环境中均适用
  2. 启用软删除 - 生产环境密钥保管库的必需配置
  3. 设置过期日期 - 为密钥和机密都设置过期时间
  4. 使用密钥轮换策略 - 自动执行密钥轮换
  5. 限制密钥操作权限 - 仅授予所需的操作权限（如加密、签名等）
  6. 不支持浏览器 - 这些SDK仅适用于Node.js环境

When to Use

适用场景

This skill is applicable to execute the workflow or actions described in the overview.
此技能适用于执行概述中描述的工作流或操作场景。