Quickstart: Azure Key Vault Managed HSM client library for Python

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

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

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

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

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

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

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

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

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

az login

إنشاء مجلد مشروع وبيئة افتراضية

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

    mkdir mhsm-python-app && cd mhsm-python-app

  2. أنشئ وفعل بيئة افتراضية:

    python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

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

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

pip install azure-identity azure-keyvault-keys

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

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

from azure.identity import DefaultAzureCredential
from azure.keyvault.keys import KeyClient
from azure.keyvault.keys.crypto import CryptographyClient, EncryptionAlgorithm

# Use DefaultAzureCredential for automatic credential selection
credential = DefaultAzureCredential()

# Connect to Managed HSM - replace with your HSM URI
hsm_uri = "https://<hsm-name>.managedhsm.azure.net"
key_client = KeyClient(vault_url=hsm_uri, credential=credential)

# Get a key reference
key_name = "<key-name>"
print(f"Retrieving key '{key_name}' from Managed HSM...")
key = key_client.get_key(key_name)
print(f"Key retrieved. Key type: {key.key_type}")

# Perform cryptographic operations
crypto_client = CryptographyClient(key, credential)

# Encrypt data
plaintext = b"Hello, Managed HSM!"
print(f"\nOriginal text: {plaintext.decode()}")

encrypt_result = crypto_client.encrypt(EncryptionAlgorithm.rsa_oaep_256, plaintext)
print(f"Encrypted (hex): {encrypt_result.ciphertext.hex()[:64]}...")

# Decrypt data
decrypt_result = crypto_client.decrypt(EncryptionAlgorithm.rsa_oaep_256, encrypt_result.ciphertext)
print(f"Decrypted text: {decrypt_result.plaintext.decode()}")

print("\nDone!")

شغّل التطبيق

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

python mhsm_keys.py

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

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

Original text: Hello, Managed HSM!
Encrypted (hex): 5a8f3b2c1d4e5f6a7b8c9d0e1f2a3b4c...
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