Mulai cepat: pustaka klien Azure Key Vault Managed HSM untuk JavaScript

Mulai menggunakan pustaka klien Azure Key Vault Managed HSM untuk JavaScript. Managed HSM adalah layanan cloud yang dikelola sepenuhnya, tersedia tinggi, berpenyewa tunggal, sesuai standar yang memungkinkan Anda untuk melindungi kunci kriptografi aplikasi cloud Anda dengan menggunakan HSM yang tervalidasi FIPS 140-3 Level 3. Untuk informasi selengkapnya tentang HSM Terkelola, tinjau Gambaran Umum.

Dalam panduan cepat ini, Anda mempelajari cara mengakses dan melakukan operasi kriptografi pada kunci di Managed HSM menggunakan pustaka klien JavaScript.

Sumber daya pustaka klien HSM terkelola:

dokumentasi referensi API | Kode sumber pustaka | Paket (npm)

Prasyarat

Siapkan lingkungan lokal Anda

Panduan mulai cepat ini menggunakan pustaka Identitas Azure, dengan Azure CLI, untuk mengautentikasi ke layanan Azure. Pengembang juga dapat menggunakan Visual Studio Code untuk mengautentikasi panggilan mereka. Untuk informasi selengkapnya, lihat Authenticate klien dengan pustaka klien Azure Identity.

Masuk ke Azure

Jalankan az login perintah untuk masuk:

az login

Membuat folder proyek dan menginisialisasi

  1. Buat folder proyek dan navigasikan ke folder tersebut:

    mkdir mhsm-js-app && cd mhsm-js-app

  2. Inisialisasi proyek:

    npm init -y

Instal paket-paket tersebut

Instal pustaka klien Azure Identity dan Key Vault Keys:

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

Membuat kode sampel

Buat file bernama index.js dengan kode berikut. Ganti <hsm-name> dengan nama HSM Terkelola Anda, dan <key-name> dengan nama kunci yang ada.

const { DefaultAzureCredential } = require("@azure/identity");
const { KeyClient, CryptographyClient } = require("@azure/keyvault-keys");

async function main() {
    // Use DefaultAzureCredential for automatic credential selection
    const credential = new DefaultAzureCredential();

    // Connect to Managed HSM - replace with your HSM URI
    const hsmUri = "https://<hsm-name>.managedhsm.azure.net";
    const keyClient = new KeyClient(hsmUri, credential);

    // Get a key reference
    const keyName = "<key-name>";
    console.log(`Retrieving key '${keyName}' from Managed HSM...`);
    const key = await keyClient.getKey(keyName);
    console.log(`Key retrieved. Key type: ${key.keyType}`);

    // Perform cryptographic operations
    const cryptoClient = new CryptographyClient(key, credential);

    // Encrypt data
    const plaintext = Buffer.from("Hello, Managed HSM!");
    console.log(`\nOriginal text: ${plaintext.toString()}`);

    const encryptResult = await cryptoClient.encrypt("RSA-OAEP-256", plaintext);
    console.log(`Encrypted (base64): ${encryptResult.result.toString("base64").substring(0, 64)}...`);

    // Decrypt data
    const decryptResult = await cryptoClient.decrypt("RSA-OAEP-256", encryptResult.result);
    console.log(`Decrypted text: ${decryptResult.result.toString()}`);

    console.log("\nDone!");
}

main().catch((error) => {
    console.error("An error occurred:", error);
    process.exit(1);
});

Jalankan aplikasi

Jalankan aplikasi:

node index.js

Anda akan melihat output yang mirip dengan:

Retrieving key 'myrsakey' from Managed HSM...
Key retrieved. Key type: RSA-HSM

Original text: Hello, Managed HSM!
Encrypted (base64): NWE4ZjNiMmMxZDRlNWY2YTdiOGM5ZDBlMWYyYTNiNGM...
Decrypted text: Hello, Managed HSM!

Done!

Memahami kode

Autentikasi dengan DefaultAzureCredential

DefaultAzureCredential secara otomatis memilih kredensial yang sesuai berdasarkan lingkungan Anda:

Lingkungan Kredensial yang digunakan
Azure VM, App Service, Functions Identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna
Azure Kubernetes Service Identitas beban kerja
Pengembangan lokal kredensial Azure CLI, Visual Studio, atau VS Code
Jalur CI/CD Federasi identitas beban kerja atau perwakilan layanan

Pemeriksaan kredensial memeriksa sumber-sumber ini secara berurutan:

  1. Variabel lingkungan
  2. Identitas beban kerja
  3. Identitas yang dikelola
  4. Azure CLI
  5. Azure PowerShell
  6. Kredensial untuk Visual Studio / VS Code

Untuk beban kerja produksi dalam Azure, identitas terkelola sangat disarankan karena menghilangkan manajemen kredensial sepenuhnya.

Operasi utama

Kelas ini KeyClient menyediakan metode untuk:

  • Membuat, mendapatkan, memperbarui, dan menghapus kunci
  • Mencantumkan kunci dan versi kunci
  • Kunci untuk cadangan dan pemulihan

Kelas ini CryptographyClient menyediakan operasi kriptografi:

  • Mengenkripsi dan mendekripsi data
  • Menandatangani dan memverifikasi tanda tangan
  • Membungkus dan membongkar kunci

Menetapkan peran HSM Terkelola

Agar aplikasi Anda dapat mengakses kunci, tetapkan peran RBAC lokal HSM Terkelola yang sesuai untuk identitas terkelola Anda. Ganti <vm-name>, <resource-group>, dan <hsm-name> dengan nilai aktual Anda.

# Get the principal ID of your managed identity
principalId=$(az vm identity show --name <vm-name> --resource-group <resource-group> --query principalId -o tsv)

# Assign the Crypto User role for key operations
az keyvault role assignment create \
    --hsm-name <hsm-name> \
    --role "Managed HSM Crypto User" \
    --assignee $principalId \
    --scope /keys

Untuk informasi selengkapnya tentang peran dan izin, lihat Peran bawaan lokal RBAC Managed HSM.

Membersihkan sumber daya

Jika tidak lagi diperlukan, hapus grup sumber daya dan semua sumber daya terkait:

az group delete --name <resource-group>

Peringatan

Menghapus grup sumber daya akan menempatkan HSM Terkelola dalam status dihapus sementara. HSM Terkelola terus ditagih hingga dihapus secara permanen. Lihat Penghapusan lunak dan perlindungan penghapusan HSM Terkelola

Langkah berikutnya

  • Last updated on