Spécification Bring Your Own KeyBring your own key specification

Ce document décrit les spécifications relatives à l'importation dans Key Vault de clés protégées par HSM depuis les modules HSM locaux des clients.This document describes specifications for importing HSM-protected keys from customers' on-premises HSMs into Key Vault.

ScénarioScenario

Un client Key Vault souhaite transférer en toute sécurité une clé de son module HSM local (en dehors d'Azure) vers le module HSM qui soutient Azure Key Vault.A Key Vault customer would like to securely transfer a key from their on-premises HSM outside Azure, into the HSM backing Azure Key Vault. Le processus d'importation d'une clé générée en dehors de Key Vault est généralement appelé Bring Your Own Key (BYOK).The process of importing a key generated outside Key Vault is generally referred to as Bring Your Own Key (BYOK).

Les conditions requises sont les suivantes :The following are the requirements:

  • La clé à transférer n'existe jamais en dehors d'un module HSM en clair.The key to be transferred never exists outside an HSM in plain text form.
  • En dehors d'un module HSM, la clé à transférer est toujours protégée par une clé conservée dans le module HSM Azure Key Vault.Outside an HSM, the key to be transferred is always protected by a key held in the Azure Key Vault HSM

TerminologieTerminology

Nom de la cléKey Name Type de cléKey Type OrigineOrigin DescriptionDescription
Key Exchange Key (KEK)Key Exchange Key (KEK) RSARSA HSM Azure Key VaultAzure Key Vault HSM Paire de clés RSA-HSM générée dans Azure Key VaultAn HSM backed RSA key pair generated in Azure Key Vault
Clé d'enveloppementWrapping Key AESAES HSM du fournisseurVendor HSM Clé AES [éphémère] générée localement par HSMAn [ephemeral] AES key generated by HSM on-prem
Clé cibleTarget Key RSA, EC, AESRSA, EC, AES HSM du fournisseurVendor HSM Clé à transférer au HSM d’Azure Key VaultThe key to be transferred to the Azure Key Vault HSM

Key Exchange Key (KEK)  : clé HSM que le client génère dans le coffre de clés où la clé BYOK sera importée.Key Exchange Key: An HSM-backed key that customer generates in the key vault where the BYOK key will be imported. Les propriétés de cette KEK doivent être les suivantes :This KEK must have following properties:

  • Il s'agit d'une clé RSA-HSM (4096, 3072 ou 2048 bits)It’s an RSA-HSM key (4096-bit or 3072-bit or 2048-bit)
  • Elle disposera de key_ops fixes (« import » UNIQUEMENT) qui lui permettront d'être utilisée EXCLUSIVEMENT dans le cadre du processus BYOKIt will have fixed key_ops (ONLY ‘import’), that will allow it to be used ONLY during BYOK
  • Elle doit se trouver dans le coffre où la clé cible sera importéeMust be in the same vault where the Target Key will be imported

Procédure à suivre par l'utilisateurUser steps

Pour effectuer un transfert de clé, en tant qu'utilisateur, vous devez procéder comme suit :To perform a key transfer, a user performs following steps:

  1. Générez la KEK.Generate KEK.
  2. Récupérez la clé publique de la KEK.Retrieve the public key of the KEK.
  3. À 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.Using HSM vendor provided BYOK tool - Import the KEK into the target HSM and exports the Target Key protected by the KEK.
  4. Importez la clé cible protégée dans Azure Key Vault.Import the protected Target Key to Azure Key Vault.

À l'étape 3, les clients utilisent l'outil BYOK et la documentation du fournisseur du module HSM.Customers use the BYOK tool and documentation provided by HSM vendor to complete Steps 3. Un objet blob de transfert de clé est généré (fichier « .byok »).It produces a Key Transfer Blob (a ".byok" file).

Contraintes HSMHSM constraints

Les modules HSM existants peuvent imposer des contraintes à la clé qu'ils gèrent, notamment :Existing HSM may apply constraints on key that they manage, including:

  • Il peut être nécessaire de configurer le module HSM afin qu'il autorise l'exportation basée sur l'enveloppement de la clé.The HSM may need to be configured to allow key wrap-based export
  • Il peut être nécessaire de marquer la clé cible comme CKA_EXTRACTABLE pour que le module HSM autorise une exportation contrôlée.The target key may need to be marked CKA_EXTRACTABLE for the HSM to allow controlled export
  • Dans certains cas, il peut être nécessaire de marquer la KEK et la clé d'enveloppement comme CKA_TRUSTED.In some cases, the KEK and wrapping key may need to be marked as CKA_TRUSTED. Cela permet de l'utiliser pour envelopper les clés dans le module HSM.This allows it to be used to wrap keys in the HSM.

La configuration du module HSM source est généralement en dehors du champ d'application de cette spécification.The configuration of source HSM is, generally, outside the scope of this specification. Microsoft attend du fournisseur du module HSM qu'il produise une documentation pour accompagner son outil BYOK afin d'y inclure ces étapes de configuration.Microsoft expects the HSM vendor to produce documentation accompanying their BYOK tool to include any such configuration steps.

Nota

Les étapes 1, 2 et 4 décrites ci-dessous peuvent être effectuées à l'aide d'autres interfaces telles qu'Azure PowerShell et le portail Azure.Steps 1, 2, and 4 described below can be performed using other interfaces such as Azure PowerShell and Azure Portal. Elles peuvent également être exécutées par programmation à l'aide de fonctions équivalentes du kit de développement logiciel Key Vault SDK.They can also be performed programmatically using equivalent functions in Key Vault SDK.

Étape 1 : Générer la KEKStep 1: Generate KEK

Pour créer une clé KEK avec les opérations de clé définies sur import, utilisez la commande az keyvault key create.Use the az keyvault key create command to create KEK with key operations set to import. Notez l’identificateur de clé « kid » retourné à partir de la commande ci-dessous.Note down the key identifier 'kid' returned from the below command.

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

Étape 2 : Récupérer la clé publique de la KEKStep 2: Retrieve the public key of the KEK

Téléchargez la partie clé publique de la KEK et stockez-la dans un fichier PEM.Download the public key portion of the KEK and store it into a PEM file.

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

Étape 3 : Générer un objet blob de transfert de clé à l'aide de l'outil BYOK du fournisseur du module HSMSteps 3: Generate key transfer blob using HSM vendor provided BYOK tool

Le client utilisera l'outil BYOK proposé par le fournisseur du module HSM pour créer un objet blob de transfert de clé (stocké dans un fichier « .byok »).Customer will use HSM Vendor provided BYOK tool to create a key transfer blob (stored as a ".byok" file). La clé publique KEK (sous forme de fichier .pem) sera l'une des entrées de cet outil.KEK public key (as a .pem file) will be one of the inputs to this tool.

Objet blob de transfert de cléKey Transfer Blob

À long terme, Microsoft souhaite utiliser le mécanisme CKM_RSA_AES_KEY_WRAP PKCS#11 pour transférer la clé cible vers Azure Key Vault car ce mécanisme produit un seul objet blob et, plus important encore, la clé AES intermédiaire est gérée par les deux modules HSM et est garantie éphémère.Long term, Microsoft would like to use PKCS#11 CKM_RSA_AES_KEY_WRAP mechanism to transfer the target key to Azure Key Vault since this mechanism produces a single blob and, more importantly, the intermediate AES key is handled by the two HSMs and is guaranteed to be ephemeral. 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.This mechanism is not presently available in some HSMs but the combination of protecting the target key with CKM_AES_KEY_WRAP_PAD using an AES key and protecting the AES key with CKM_RSA_PKCS_OAEP produces an equivalent blob.

Le texte en clair de la clé cible dépend du type de clé :The target key plaintext depends on the key type:

  • Pour une clé RSA, l'encodage DER ASN.1 de clé privée [RFC3447] enveloppé dans PKCS#8 [RFC5208]For an RSA key, the private key ASN.1 DER encoding [RFC3447] wrapped in PKCS#8 [RFC5208]
  • Pour une clé EC, l'encodage DER ASN.1 de clé privée [RFC5915] enveloppé dans PKCS#8 [RFC5208]For an EC key, the private key ASN.1 DER encoding [RFC5915] wrapped in PKCS#8 [RFC5208]
  • Pour une clé d'octet, les octets bruts de la cléFor an octet key, the raw bytes of the key

Les octets de la clé en clair sont ensuite transformés à l'aide du mécanisme CKM_RSA_AES_KEY_WRAP :The bytes for the plaintext key are then transformed using the CKM_RSA_AES_KEY_WRAP mechanism:

  • Une clé AES éphémère est générée et chiffrée avec la clé RSA d'enveloppement en utilisant RSA-OAEP avec SHA1.An ephemeral AES key is generated and encrypted with the wrapping RSA key using RSA-OAEP with SHA1.
  • La clé en clair encodée est chiffrée à l'aide de la clé AES en utilisant AES Key Wrap avec remplissage.The encoded plaintext key is encrypted using the AES key using AES Key Wrap with Padding.
  • La clé AES chiffrée et la clé en clair chiffrée sont concaténées pour produire l'objet blob de texte chiffré final.The encrypted AES key and the encrypted plaintext key are concatenated to produce the final ciphertext blob.

Le format de l'objet blob de transfert utilise la sérialisation compacte JSON Web Encryption (RFC7516) principalement comme moyen de fournir les métadonnées requises au service pour un déchiffrement adéquat.The format of the transfer blob uses JSON Web Encryption compact serialization (RFC7516) primarily as a vehicle for delivering the required metadata to the service for correct decryption.

Si CKM_RSA_AES_KEY_WRAP_PAD est utilisé, la sérialisation JSON de l'objet blob de transfert sera :If CKM_RSA_AES_KEY_WRAP_PAD is used, the JSON serialization of the transfer blob would be:

{
  "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 = identificateur de clé de la KEK.kid = key identifier of KEK. Pour les clés Key Vault, il se présente comme suit : https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621For Key Vault keys it looks like this: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
  • alg = algorithme.alg = algorithm.
  • dir = mode direct, c'est-à-dire que le kid référencé est utilisé pour protéger directement le texte chiffré qui est une représentation précise de CKM_RSA_AES_KEY_WRAPdir = Direct mode, i.e. the referenced kid is used to directly protect the ciphertext which is an accurate representation of CKM_RSA_AES_KEY_WRAP
  • generator = champ d'informations qui indique le nom et la version de l'outil BYOK ainsi que le fabricant et le modèle du module HSM source.generator = an informational field that denotes the name and version of BYOK tool and the source HSM manufacturer and model. Ces informations sont destinées à être utilisées pour la résolution des problèmes et le support.This information is intended for use in troubleshooting and support.

L'objet blob JSON est stocké dans un fichier « .byok » afin que les clients Azure PowerShell/CLI le traitent correctement lorsque les commandes « Add-AzKeyVaultKey » (PSH) ou « az keyvault key import » (CLI) sont utilisées.The JSON blob is stored in a file with a ".byok" extension so that the Azure PowerShell/CLI clients treats it correctly when ‘Add-AzKeyVaultKey’ (PSH) or ‘az keyvault key import’ (CLI) commands are used.

Étape 4 : Charger l'objet blob de transfert de clé pour importer la clé du module HSMStep 4: Upload key transfer blob to import HSM-key

Le client transférera l'objet blob de transfert de clé (fichier « .byok ») vers une station de travail en ligne, puis exécutera une commande az keyvault key import pour importer cet objet blob en tant que nouvelle clé HSM dans Key Vault.Customer will transfer the Key Transfer Blob (".byok" file) to an online workstation and then run a az keyvault key import command to import this blob as a new HSM-backed key into Key Vault.

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

Lorsque la commande ci-dessus est exécutée, elle se traduit par l'envoi d'une requête d'API REST :When the above command is executed, it results in sending a REST API request as follows:

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

Corps de la requête :Request body:

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

la valeur « key_hsm » est le contenu entier du fichier KeyTransferPackage-ContosoFirstHSMkey.byok encodé au format Base64.“key_hsm” value is the entire contents of the KeyTransferPackage-ContosoFirstHSMkey.byok encoded in the Base64 format.

ReferencesReferences

Étapes suivantesNext steps