Quickstart: Azure Key Vault Managed HSM client library for JavaScript

ابدأ مع مكتبة عملاء Azure Key Vault Managed HSM لجافا سكريبت. HSM المدارة هي خدمة سحابية مدارة بالكامل ومتاحة بشكل كبير ومستأجر واحد ومتوافقة مع المعايير تمكنك من حماية مفاتيح التشفير لتطبيقاتك السحابية، باستخدام وحدات HSM التي تم التحقق من صحتها من FIPS 140-3 المستوى 3 . لمزيد من المعلومات حول إدارة HSM، راجع النظرة العامة.

في هذه البداية السريعة، تتعلم كيفية الوصول إلى وتنفيذ العمليات التشفيرية على المفاتيح في إدارة HSM باستخدام مكتبة عملاء JavaScript.

موارد مكتبة عملاء HSM المدارة:

API الوثائق المرجعية | المكتبة مصدر المصدر | حزمة (npm)

المتطلبات المسبقه

إعداد البيئة المحلية

يستخدم هذا البدء السريع مكتبة Azure Identity مع Azure CLI للمصادقة على خدمات Azure. يمكن للمطورين أيضا استخدام تعليمة Visual Studio برمجية لمصادقة مكالماتهم. لمزيد من المعلومات، راجع مصادقة العميل باستخدام مكتبة عميل Azure Identity.

تسجيل الدخول إلى Azure

شغل az login الأمر لتسجيل الدخول:

az login

أنشئ مجلد مشروع وقم بتهيئة

  1. أنشئ مجلد مشروع وانتقل إليه:

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

  2. تهيئة المشروع:

    npm init -y

قم بتثبيت الحِزَم

تثبيت مكتبات عملاء Azure Identity و Key Vault Keys:

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

إنشاء نموذج التعليمات البرمجية

أنشئ ملفا باسم index.js الرمز التالي. استبدلها <hsm-name> باسمك HSM المدار، وباسم <key-name> مفتاح موجود.

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);
});

شغّل التطبيق

شغّل التطبيق:

node index.js

يجب أن تلاحظ مخرجات مشابهة لـ:

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!

فهم التعليمات البرمجية

المصادقة باستخدام DefaultAzureCredential

DefaultAzureCredential يختار تلقائيا الاعتماد المناسب بناء على بيئتك:

البيئة الاعتماد المستخدم
Azure VMs، خدمة التطبيقات، الوظائف هوية مدارة معينة من قبل النظام أو من قبل المستخدم
Azure Kubernetes Service هوية عبء العمل
التنمية المحلية Azure CLI، Visual Studio، أو VS Code credentials
البنية الأساسية لبرنامج ربط العمليات التجارية CI/CD اتحاد هوية أو مبدأ الخدمة في عبء العمل

تتحقق الشهادة من هذه المصادر بالترتيب:

  1. متغيرات البيئة
  2. هوية عبء العمل
  3. الهوية المُدارة
  4. Azure CLI
  5. Azure PowerShell
  6. بيانات Visual Studio / VS Code

بالنسبة لأعباء العمل الإنتاجية في Azure، ينصح بشدة باستخدام الهويات المدارة لأنها تلغي إدارة بيانات الاعتماد تماما.

العمليات الرئيسية

توفر الفئة KeyClient طرقا ل:

  • إنشاء والحصول على التحديثات وحذف المفاتيح
  • قائمة المفاتيح وإصدارات المفاتيح
  • مفاتيح النسخ الاحتياطي والاستعادة

توفر الفئة CryptographyClient عمليات تشفير:

  • تشفير وفك تشفير البيانات
  • توقيع وتحقق من التواقيع
  • مفاتيح اللف والفك

تعيين أدوار HSM المدارة

لكي يتمكن تطبيقك من الوصول إلى المفاتيح، قم بتعيين الدور المناسب ل HSM المحلي المناسب لهويتك المدارة. استبدل <vm-name>، <resource-group>، ومع <hsm-name> قيمك الفعلية.

# 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

لمزيد من المعلومات حول الأدوار والأذونات، راجع الأدوار المدمجة في RBAC المحلية لإدارة HSM.

تنظيف الموارد

عندما لا تعود الحاجة، احذف مجموعة الموارد وجميع الموارد ذات الصلة:

az group delete --name <resource-group>

التحذير

يؤدي حذف مجموعة الموارد إلى وضع HSM المُدار في حالة حذف مبدئي. يستمر نظام HSM المدار في المحاسبة حتى يتم تطهيره. راجع حماية الحذف المبدئي وإزالة HSM المُدار

الخطوات التالية

  • Last updated on