Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Este tópico descreve como formatar as chaves para que possam ser importadas pelo
Cloud KMS como novas versões.
O formato correto para o material da chave varia de acordo com o tipo de importação: chave simétrica ou assimétrica. Para mais informações sobre a diferença entre essas chaves, consulte Finalidades de chaves e algoritmos.
Formatos de chave compatíveis
Chaves simétricas para criptografia:
Importadas, as chaves simétricas precisam ter 16 bytes (apenas para
criptografia simétrica bruta) ou 32 bytes de dados binários e não precisam ser codificadas.
Se a chave tiver codificação hexadecimal ou codificada em base64, você precisará decodificá-la antes de tentar importá-la.
Chaves simétricas para assinatura (chaves MAC): as chaves de assinatura HMAC importadas
precisam ter um comprimento igual ao comprimento de saída da função hash criptográfica
usada. Por exemplo, as chaves HMAC-SHA256 precisam ter um comprimento de 32
bytes e não podem ser codificadas. Se a chave tiver codificação hexadecimal ou
codificação base64, você precisará decodificá-la antes de tentar importá-la.
Chaves assimétricas para criptografia ou assinatura: as chaves assimétricas importadas
precisam estar no formato PKCS #8 e ser codificadas em DER. O formato PCKS #8 é definido
no RFC 5208 (em inglês). A codificação DER
é definida em International
Telecommunications Union X.680 (em inglês). As chaves assimétricas precisam usar uma das combinações de comprimento e algoritmo compatíveis com o Cloud KMS.
Alguns aspectos de uma chave, como o comprimento dela, não podem ser alterados após a chave ser criada. Nesses casos, a chave não pode ser importada para o Cloud KMS.
Como verificar uma chave simétrica
Use o comando wc para verificar o comprimento de uma chave simétrica.
wc -c /path/to/unwrapped-key
Você não pode importar uma chave de criptografia simétrica com um comprimento diferente de 32.
As chaves de assinatura simétricas (chaves MAC) precisam ter um comprimento igual ao comprimento de saída da função de hash criptográfica sendo usada, por exemplo, as chaves HMAC-SHA256 precisam ter um comprimento de 32 bytes.
Use o comando file para verificar o formato de uma chave.
file /path/to/unwrapped-key
Se a saída for data, a chave estará no formato correto a ser importado.
Se o resultado for ASCII text, use o comando cat para exibir o conteúdo do arquivo.
Se for uma string de letras e números terminando em um sinal =, pode ser codificada em base64. Use o comando base64 (Base64.exe no Windows) para decodificá-la. Veja a seguir um exemplo de chave codificada em base64:
THzArjassB+giKeNeT1Zr74OgV24t+Ep+37Ec6ojB3Y=
Se ela contiver uma ou mais linhas de números hexadecimais, poderá ser codificada em hexadecimal. Use o comando xxd (ou o
comando Format-Hex do PowerShell
no Windows) para decodificá-la. Confira a seguir um exemplo de chave codificada em
hexadecimal:
Se ela contiver qualquer outro texto, talvez não seja uma chave simétrica válida.
Como formatar chaves assimétricas
Chaves assimétricas que usam qualquer um dos algoritmos compatíveis podem ser importadas. Na prática, é difícil determinar retroativamente o algoritmo usado para criar uma chave assimétrica. Por esse motivo, recomendamos que você execute os seguintes comandos em cada chave assimétrica antes de tentar importá-la para o Cloud KMS.
Use o comando file para verificar o formato de uma chave.
file /path/to/unwrapped-key
Se a saída for PEM, a chave estará no formato PEM. Se for ASCII text, provavelmente está no formato PEM. Em ambos os casos, execute o seguinte comando para convertê-lo no formato PCKS#8 DER:
Se a saída for data, provavelmente a chave estará no formato DER, mas talvez não esteja no formato PKCS #8. Execute o seguinte comando para garantir que a chave esteja no formato correto. O comando não terá efeito se a chave já estiver no formato correto. Nesse caso, use o comando diff para verificar se os arquivos de entrada e saída são idênticos.
openssl pkcs8 -topk8 -nocrypt -inform DER -outform DER \
-in /path/to/asymmetric-key-der \
-out /path/to/formatted-key
Solução de problemas
Se você executar os comandos acima e achar que a chave está em um formato
adequado, mas a importação ainda falhar, verifique se há erros no console Google Cloud e
consulte Solução de problemas de importações
falhadas.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-18 UTC."],[],[],null,["# Formatting keys for import\n\nThis topic describes how to format your keys so that they can be imported by\nCloud KMS as new key versions.\n\nThe correct format for your key material varies based on whether the key\nmaterial is being imported into a symmetric key, or into an asymmetric key. For\nmore information about the difference between symmetric and asymmetric keys, see\n[Key purposes and algorithms](/kms/docs/algorithms).\n\nSupported key formats\n---------------------\n\n- **Symmetric keys for encryption** : Imported symmetric keys must be 16 bytes (for [raw symmetric encryption](/kms/docs/raw-encryption) only) or 32 bytes of binary data, and must *not* be encoded. If your key is hex-encoded or base64-encoded, then you must decode it before attempting to import it.\n- **Symmetric keys for signing (MAC keys)** : Imported HMAC signing keys must have a length equal to the output length of the cryptographic hash function being used (for example, HMAC-SHA256 keys must have a length of 32 bytes), and must *not* be encoded. If your key is hex-encoded or base64-encoded, then you must decode it before attempting to import it.\n- **Asymmetric keys for encryption or signing** : Imported asymmetric keys must be in PKCS #8 format and must be DER-encoded. PCKS #8 format is defined in [RFC 5208](https://tools.ietf.org/html/rfc5208). DER encoding is defined in [International\n Telecommunications Union X.680](https://www.itu.int/rec/T-REC-X.680/en). Asymmetric keys must use one of the [length and algorithm combinations](/kms/docs/algorithms) supported by Cloud KMS.\n\n| **Important:** An RSA key's public exponent must be 65,537 or higher. This is a Digital Signature Standard (DSS) requirement noted in the Criteria for IFC Key Pairs section of [FIPS PUB 186-4](https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf), Section B.3.1\n\nSome aspects of a key, such as the key's length, cannot be changed after the key\nis created. In these cases, the key cannot be imported into Cloud KMS.\n\nChecking a symmetric key\n------------------------\n\nUse the `wc` command to check a symmetric key's length. \n\n```\nwc -c /path/to/unwrapped-key\n```\n\n- You cannot import a symmetric encryption key with a length other than 32.\n\n- Symmetric signing keys (MAC keys) must have a length equal to the output\n length of the cryptographic hash function being used (e.g. HMAC-SHA256 keys\n must have a length of 32 bytes).\n\nUse the `file` command to check a key's format. \n\n```\nfile /path/to/unwrapped-key\n```\n\n- If the output is `data`, the key is in the correct format to be imported.\n\n- If the output is `ASCII text`, use the `cat` command to display the contents\n of the file.\n\n - If it is a string of letters and numbers ending in an `=` sign, it might\n be base64-encoded. Use the `base64` command (`Base64.exe` on Windows) to\n decode it. The following is an example of a base64-encoded key:\n\n ```\n THzArjassB+giKeNeT1Zr74OgV24t+Ep+37Ec6ojB3Y=\n ```\n - If it contains one or more lines of hexadecimal numbers, it might be\n hex-encoded. Use the `xxd` command (or the\n [`Format-Hex` PowerShell command](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/format-hex)\n on Windows) to decode it. The following is an example of a hex-encoded\n key:\n\n ```\n 00000000: 4c7c c0ae 36ac b01f a088 a78d 793d 59af L|..6.......y=Y.\n 00000010: be0e 815d b8b7 e129 fb7e c473 aa23 0776 ...]...).~.s.#.v\n ```\n - If it contains any other text, it may not be a valid symmetric key.\n\nFormatting asymmetric keys\n--------------------------\n\nAsymmetric keys using any of the supported [algorithms](/kms/docs/algorithms)\ncan be imported. In practice, it is difficult to retroactively determine the\nalgorithm used to create an asymmetric key. For that reason, we recommend that\nyou run the following commands on each asymmetric key before attempting to\nimport it into Cloud KMS.\n\n1. Use the `file` command to check a key's format.\n\n ```\n file /path/to/unwrapped-key\n ```\n - If the output is `PEM`, the key is in PEM format. If it is `ASCII text`,\n it is probably in PEM format. In either case, run the following command\n to convert it to PCKS#8 DER format:\n\n ```\n openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER \\\n -in /path/to/asymmetric-key-pem \\\n -out /path/to/formatted-key\n ```\n - If the output is `data`, the key is likely to be in DER format, but it\n may not be in PKCS #8 format. Run the following command to ensure that\n the key is in the correct format. The command has no effect if the key\n is already in the correct format. In that case, you can use the `diff`\n command to verify that the input and output file are identical.\n\n ```\n openssl pkcs8 -topk8 -nocrypt -inform DER -outform DER \\\n -in /path/to/asymmetric-key-der \\\n -out /path/to/formatted-key\n ```\n\nTroubleshooting\n---------------\n\nIf you run the commands above and you believe the key is in an appropriate\nformat, but the import still fails, check for errors in Google Cloud console, and\nthen see [Troubleshooting failed\nimports](/kms/docs/troubleshooting-failed-imports).\n\nWhat's next\n-----------\n\n- Continue to [Import a key version](/kms/docs/importing-a-key)\n- Learn about [key import](/kms/docs/key-import)"]]
