Traga sua própria especificação de chave

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

Cenário

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

A seguir estão os requisitos:

• A chave a ser transferida nunca existe fora de um HSM no formato de texto sem formatação.
• Fora de um HSM, a chave a ser transferida é sempre protegida por uma chave mantida no HSM do Azure Key Vault

Terminologia

Chave do Key Exchange: uma chave com suporte de HSM que o cliente gera no cofre de chaves onde a chave BYOK é importada. A KEK deve ter as seguintes propriedades:

• É uma chave RSA-HSM (4096 bits ou 3072 bits ou 2048 bits)
• Ele tem um key_ops fixo (ONLY import), que permite que ele seja usado SOMENTE durante BYOK
• Deve estar no mesmo cofre em que a Chave de Destino será importada

Etapas do usuário

Para executar uma transferência de chave, o usuário deve seguir estas etapas:

1. Gerar KEK.
2. Recupere a chave pública do KEK.
3. Usando a ferramenta BYOK fornecida pelo fornecedor do HSM, importar a KEK para o HSM de destino e exportar a Chave de Destino protegida pela KEK.
4. Importe a chave de destino protegida para o Azure Key Vault.

Os clientes usam a ferramenta BYOK e a documentação fornecidas 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 gerenciada, como:

• O HSM pode precisar ser configurado para permitir a exportação baseada em encapsulamento de chave
• 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 encapsular chaves no HSM.

A configuração do HSM de origem está, em geral, fora do escopo dessa especificação. A Microsoft espera que o fornecedor de HSM produza documentação acompanhando sua ferramenta BYOK para incluir essas 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 desse comando.

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

Recuperar a chave pública do KEK

Baixe a parte da 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 chave usando a ferramenta BYOK fornecida pelo fornecedor de HSM

O cliente usa a ferramenta BYOK fornecida pelo Fornecedor de HSM para criar um blob de transferência de chave (armazenado como um arquivo ".byok"). A chave pública KEK (como um arquivo .pem) é uma das entradas para essa ferramenta.

Blob de Transferência de Chaves

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

O texto puro da chave de destino depende do tipo de chave:

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

Os bytes da chave de texto sem formatação sã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 claro codificada é criptografada com a chave AES utilizando o Envoltório 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 criptografado final.

O formato do blob de transferência utiliza a serialização compacta de Criptografia Web JSON (RFC7516) principalmente como meio de entregar os metadados necessários ao serviço para a correta descriptografia.

Caso o CKM_RSA_AES_KEY_WRAP_PAD seja utilizado, a serialização JSON do blob de transferência seria:

{
  "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 principal de KEK. Para chaves do Key Vault, ele tem esta aparência: 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. Essas informações destinam-se ao uso na solução de problemas e suporte.

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

Carregar o blob de transferência de chave para importar a chave do HSM

Os clientes transferem o Blob de Transferência de Chave (arquivo ".byok") para uma estação de trabalho online e, em seguida, executam um comando de importação de chave az keyvault para importar esse blob como uma nova chave com suporte de 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 de curva elíptica, você precisa 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 esse comando é 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 EC:

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

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

Referências

• Guia do Desenvolvedor do Cofre de Chaves

Próximas etapas

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