Especificação Traga a sua própria chave

Este documento descreve as especificações para importar chaves protegidas por HSM dos HSMs locais dos clientes para o Cofre de Chaves.

Cenário

Um cliente do Cofre de Chaves gostaria de transferir com segurança uma chave de seu HSM local fora do Azure para o HSM que dá suporte ao Cofre de Chaves do Azure. O processo de importação de uma chave gerada fora do Cofre de Chaves é conhecido como Bring Your Own Key (BYOK).

Os requisitos são os seguintes:

• A chave a ser transferida nunca existe fora de um HSM em formato de texto simples.
• Fora de um HSM, a chave a ser transferida é sempre protegida por uma chave mantida no HSM do Cofre de Chaves do Azure

Terminologia

Chave de troca de chaves: uma chave apoiada por HSM que o cliente gera no cofre de chaves onde a chave BYOK será importada. Este KEK deve ter as seguintes propriedades:

• É uma chave RSA-HSM (4096 bits ou 3072 bits ou 2048 bits)
• Terá key_ops fixo (APENAS 'importar'), que lhe permitirá ser utilizado APENAS durante o BYOK
• Deve estar no mesmo cofre onde a chave de destino será importada

Etapas do usuário

Para executar uma transferência de chave, um usuário executa as seguintes etapas:

1. Gere o KEK.
2. Recupere a chave pública do KEK.
3. Usando a ferramenta BYOK fornecida pelo fornecedor HSM - Importe o KEK para o HSM de destino e exporte a chave de destino protegida pelo KEK.
4. Importe a Chave de Destino protegida para o Cofre de Chaves do Azure.

Os clientes usam a ferramenta BYOK e a documentação fornecida pelo fornecedor do HSM para concluir as etapas 3. Ele produz um Blob de Transferência de Chave (um arquivo ".byok").

Restrições de HSM

O HSM existente pode aplicar restrições à chave que gerencia, incluindo:

• O HSM pode precisar ser configurado para permitir a exportação baseada em encapsulamento de chaves
• A chave de destino pode precisar ser marcada CKA_EXTRACTABLE para que o HSM permita a exportação controlada
• Em alguns casos, o KEK e a chave de encapsulamento podem precisar ser marcados como CKA_TRUSTED, o que permite que ele seja usado para envolver chaves no HSM.

A configuração do HSM de origem está, geralmente, fora do escopo desta especificação. A Microsoft espera que o fornecedor do HSM produza documentação que acompanhe sua ferramenta BYOK para incluir tais etapas de configuração.

Gerar KEK

Use o comando az keyvault key create para criar KEK com operações de chave definidas para importação. Anote o identificador de chave 'kid' retornado do comando abaixo.

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

Recuperar a chave pública do KEK

Faça o download da parte de chave pública do KEK e armazene-a em um arquivo PEM.

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

Gerar blob de transferência de chaves usando a ferramenta BYOK fornecida pelo fornecedor HSM

O cliente usará a ferramenta BYOK fornecida pelo fornecedor HSM para criar um blob de transferência de chaves (armazenado como um arquivo ".byok"). A chave pública KEK (como um ficheiro .pem) será uma das entradas para esta ferramenta.

Blob de transferência de chave

A longo prazo, a Microsoft gostaria de usar o mecanismo PKCS#11 CKM_RSA_AES_KEY_WRAP para transferir a chave de destino para o Azure Key Vault, uma vez que esse mecanismo produz um único blob e, mais importante, a chave AES intermediária é manipulada pelos dois HSMs e é garantidamente efêmera. Esse mecanismo não está atualmente disponível em alguns HSMs, mas a combinação de proteger a chave de destino com CKM_AES_KEY_WRAP_PAD usando uma chave AES e protegendo a chave AES com CKM_RSA_PKCS_OAEP produz um blob equivalente.

O texto sem formatação da chave de destino depende do tipo de chave:

• Para uma chave RSA, a chave privada ASN.1 DER codificação [RFC3447] encapsulada em PKCS#8 [RFC5208]
• Para uma chave EC, a chave privada ASN.1 codificação DER [RFC5915] encapsulada em PKCS#8 [RFC5208]
• Para uma chave de octeto, os bytes brutos da chave

Os bytes para a chave de texto simples são então transformados usando o mecanismo CKM_RSA_AES_KEY_WRAP:

• Uma chave AES efêmera é gerada e criptografada com a chave RSA de encapsulamento usando RSA-OAEP com SHA1.
• A chave de texto simples codificada é criptografada usando a chave AES usando o Wrap de Chave AES com Preenchimento.
• A chave AES criptografada e a chave de texto sem formatação criptografada são concatenadas para produzir o blob de texto cifrado final.

O formato do blob de transferência usa a serialização compacta (RFC7516) JSON Web Encryption principalmente como um veículo para entregar os metadados necessários ao serviço para a descriptografia correta.

Se CKM_RSA_AES_KEY_WRAP_PAD for usado, a serialização JSON do blob de transferência será:

{
  "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 = identificador de chave do KEK. Para chaves do Cofre da Chave, a aparência é a seguinte: https://ContosoKeyVaultHSM.vault.azure.net/keys/mykek/eba63d27e4e34e028839b53fac905621
• ALG = algoritmo.
• dir = Modo direto, ou seja, o kid referenciado é usado para proteger diretamente o texto cifrado que é uma representação precisa de CKM_RSA_AES_KEY_WRAP
• generator = um campo informativo que indica o nome e a versão da ferramenta BYOK e o fabricante e modelo do HSM de origem. Estas informações destinam-se a ser utilizadas na resolução de problemas e suporte.

O blob JSON é armazenado em um arquivo com uma extensão ".byok" para que os clientes do Azure PowerShell/CLI o tratem corretamente quando os comandos 'Add-AzKeyVaultKey' (PSH) ou 'az keyvault key import' (CLI) são usados.

Carregar blob de transferência de chave para importar chave HSM

O cliente transferirá o Blob de Transferência de Chaves (arquivo ".byok") para uma estação de trabalho online e, em seguida, executará um comando az keyvault key import para importar esse blob como uma nova chave apoiada por HSM para o Key Vault.

Para importar uma chave RSA, use este comando:

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

Para importar uma chave EC, você deve especificar o tipo de chave e o nome da curva.

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

Quando o comando acima é executado, ele resulta no envio de uma solicitação de API REST da seguinte maneira:

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

Corpo da solicitação ao importar uma chave RSA:

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

Corpo da solicitação ao importar uma chave CE:

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

O valor "key_hsm" é todo o conteúdo do KeyTransferPackage-ContosoFirstHSMkey.byok codificado no formato Base64.

Referências

• Guia do Programador do Key Vault

Próximos passos

• Instruções BYOK passo a passo: Importar chaves protegidas por HSM para o Key Vault (BYOK)