Apportez votre propre spécification de clé

2025-06-18

Ce document décrit les spécifications pour l’importation de clés protégées par HSM à partir de HSM locaux des clients dans Key Vault.

Scénario

Un client Key Vault souhaite transférer en toute sécurité une clé à partir de son HSM local en dehors d’Azure, dans le stockage HSM d’Azure Key Vault. Le processus d’importation d’une clé générée en dehors du coffre de clés est appelé BYOK (Bring Your Own Key).

Voici les conditions requises :

La clé à transférer n’existe jamais en dehors d’un HSM sous forme de texte brut.
En dehors d’un HSM, la clé à transférer est toujours protégée par une clé conservée dans le HSM Azure Key Vault

Terminologie

Nom de la clé	Type de clé	Origine	Descriptif
Clé d’échange de clés (KEK)	RSA	HSM Azure Key Vault	Paire de clés RSA sauvegardée par HSM générée dans Azure Key Vault
Clé d'encapsulation	Norme de chiffrement avancée (AES)	Fournisseur HSM	Clé AES [éphémère] générée par un HSM local
Clé cible	RSA, EC, AES (HSM managé uniquement)	Fournisseur HSM	La clé à transférer vers le Key Vault HSM d'Azure

Clé d'échange de clés : une clé gérée par HSM générée par le client dans le coffre de clés où la clé BYOK est importée. Les propriétés de cette KEK doivent être les suivantes :

Il s’agit d’une clé RSA-HSM (4096 bits ou 3072 bits ou 2048 bits)
Il a un key_ops fixe (ONLY import), qui lui permet d’être utilisé UNIQUEMENT pendant BYOK
Elle doit se trouver dans le coffre où la clé cible est importée

Étapes de l’utilisateur

Pour effectuer un transfert de clé, en tant qu'utilisateur, vous devez procéder comme suit :

Générez KEK.
Récupérez la clé publique du KEK.
À l'aide de l'outil BYOK du fournisseur du module HSM, importez la KEK dans le module HSM cible et exportez la clé cible protégée par la KEK.
Importez la clé cible protégée dans Azure Key Vault.

Les clients utilisent l’outil BYOK et la documentation fournies par le fournisseur HSM pour effectuer les étapes 3. Il produit un objet blob de transfert de clés (un fichier ".byok").

Contraintes HSM

Les modules HSM existants peuvent imposer des contraintes à la clé qu'ils gèrent, notamment :

Le HSM peut avoir besoin d’être configuré pour autoriser l’exportation basée sur l'enveloppement de clé.
La clé cible peut avoir besoin d’être marquée CKA_EXTRACTABLE pour que le module HSM autorise l’exportation contrôlée
Dans certains cas, la clé KEK et la clé d’habillage doivent être marquées comme CKA_TRUSTED, ce qui lui permet d’être utilisée pour encapsuler les clés dans le HSM.

La configuration du HSM source est généralement en dehors de l’étendue de cette spécification. Microsoft s’attend à ce que le fournisseur HSM produise de la documentation qui accompagne son outil BYOK pour inclure toutes ces étapes de configuration.

Remarque

Plusieurs de ces étapes peuvent être effectuées à l’aide d’autres interfaces telles qu’Azure PowerShell et le portail Azure. Elles peuvent également être effectuées par programmation à l’aide de fonctions équivalentes dans le Kit de développement logiciel (SDK) Key Vault.

Générer une clé KEK

Utilisez la commande az keyvault key create pour créer un KEK avec les opérations de clé définies sur l'importation. Notez l’identificateur de clé « kid » retourné à partir de cette commande.

az keyvault key create --kty RSA-HSM --size 4096 --name KEKforBYOK --ops import --vault-name ContosoKeyVaultHSM

Remarque

Les services prennent en charge différentes longueurs KEK ; Azure SQL, par exemple, prend uniquement en charge les longueurs de clé de 2048 ou 3072 octets. Pour plus d’informations, consultez la documentation de votre service.

Récupérer la clé publique du KEK

Téléchargez la partie clé publique du KEK et stockez-la dans un fichier PEM.

az keyvault key download --name KEKforBYOK --vault-name ContosoKeyVaultHSM --file KEKforBYOK.publickey.pem

Générer un blob de transfert de clé en utilisant l’outil BYOK fourni par le fournisseur HSM.

Le client utilise l’outil BYOK proposé par le fournisseur de module HSM pour créer un objet blob de transfert de clé (stocké comme fichier « .byok »). La clé publique KEK (en tant que fichier .pem) est l’une des entrées de cet outil.

Blob de transfert de clé

À long terme, Microsoft souhaite utiliser le mécanisme de CKM_RSA_AES_KEY_WRAP PKCS#11 pour transférer la clé cible vers Azure Key Vault, car ce mécanisme produit un objet blob unique et, plus important encore, la clé AES intermédiaire est gérée par les deux modules HSM et est garantie d’être éphémère. Ce mécanisme n’est actuellement pas disponible dans certains modules HSM, mais la combinaison de la protection de la clé cible avec CKM_AES_KEY_WRAP_PAD à l’aide d’une clé AES et de la protection de la clé AES avec CKM_RSA_PKCS_OAEP produit un objet blob équivalent.

Le texte en clair de la clé cible dépend du type de clé :

Pour une clé RSA, l’encodage DER ASN.1 de la clé privée [RFC3447] encapsulé dans PKCS#8 [RFC5208]
Pour une clé EC, l’encodage DER ASN.1 de clé privée [RFC5915] encapsulé dans PKCS#8 [RFC5208]
Pour une clé d’octet, octets bruts de la clé

Les octets de la clé en texte clair sont ensuite transformés à l’aide du mécanisme de CKM_RSA_AES_KEY_WRAP :

Une clé AES éphémère est générée et chiffrée avec la clé RSA encapsulée à l’aide de RSA-OAEP avec SHA1.
La clé en texte clair encodée est chiffrée avec la clé AES en utilisant AES Key Wrap avec remplissage.
La clé AES chiffrée et la clé en texte clair chiffrée sont concaténées pour produire l’objet blob de texte chiffré final.

Le format de l’objet blob de transfert utilise la sérialisation compacte JSON Web Encryption (RFC7516) principalement comme moyen de remettre les métadonnées requises au service pour le déchiffrement correct.

Si CKM_RSA_AES_KEY_WRAP_PAD est utilisé, la sérialisation JSON de l’objet blob de transfert est la suivante :

{
  "schema_version": "1.0.0",
  "header":
  {
    "kid": "<key identifier of the KEK>",
    "alg": "dir",
    "enc": "CKM_RSA_AES_KEY_WRAP"
  },
  "ciphertext":"BASE64URL(<ciphertext contents>)",
  "generator": "BYOK tool name and version; source HSM name and firmware version"
}

kid = ID de clé de la KEK. Pour les clés Key Vault, il se présente comme suit : https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
alg = algorithme.
dir = Mode direct, autrement dit, l’enfant référencé est utilisé pour protéger directement le texte chiffré qui est une représentation précise de CKM_RSA_AES_KEY_WRAP
générateur = champ d’information qui désigne le nom et la version de l’outil BYOK et le fabricant et le modèle HSM source. Ces informations sont destinées à être utilisées dans le dépannage et le support.

L’objet blob JSON est stocké dans un fichier avec une extension « .byok » afin que le client Azure PowerShell ou CLI le traite correctement lorsque les commandes « Add-AzKeyVaultKey » (PSH) ou « az keyvault key import » (CLI) sont utilisées.

Charger l'objet blob de transfert de clé pour importer la clé du module HSM

Les clients transfèrent le fichier Blob de transfert de clés (« .byok ») vers une station de travail en ligne, puis exécutent une commande az keyvault key import pour importer cet objet blob en tant que nouvelle clé sauvegardée par HSM dans Key Vault.

Pour importer une clé RSA, utilisez cette commande :

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file KeyTransferPackage-ContosoFirstHSMkey.byok --ops encrypt decrypt

Pour importer une clé EC, vous devez spécifier le type de clé et le nom de la courbe.

az keyvault key import --vault-name ContosoKeyVaultHSM --name ContosoFirstHSMkey --byok-file --kty EC-HSM --curve-name "P-256" KeyTransferPackage-ContosoFirstHSMkey.byok --ops sign verify

Lorsque cette commande est exécutée, elle envoie une demande d’API REST comme suit :

PUT https://contosokeyvaulthsm.vault.azure.net/keys/ContosoFirstHSMKey?api-version=7.0

Corps de la demande lors de l’importation d’une clé RSA :

{
  "key": {
    "kty": "RSA-HSM",
    "key_ops": [
      "decrypt",
      "encrypt"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

Corps de la demande lors de l’importation d’une clé EC :

{
  "key": {
    "kty": "EC-HSM",
    "crv": "P-256",
    "key_ops": [
      "sign",
      "verify"
    ],
    "key_hsm": "<Base64 encoded BYOK_BLOB>"
  },
  "attributes": {
    "enabled": true
  }
}

La valeur « key_hsm » est l’intégralité du contenu de KeyTransferPackage-ContosoFirstHSMkey.byok encodé au format Base64.

références

Guide du développeur Key Vault

Étapes suivantes

Instructions BYOK pas à pas : Importer des clés protégées par HSM dans Key Vault (BYOK)