Formatting keys for import

Cloud Key Management Service allows you to import user-provided cryptographic keys. This topic describes how to properly format your keys, so that they can be imported by Cloud KMS.

The correct format for your key material varies based on whether the key material is being imported into a symmetric key, or into an asymmetric key. For more information about the difference between symmetric and asymmetric keys, see Key purposes and algorithms.

Supported key formats

  • Symmetric keys for encryption must be 32 bytes of binary data, and must not be encoded. If your key is hex-encoded or base-64 encoded, you must decode it before attempting to import it.

  • Asymmetric keys for encryption or signing must be in PKCS #8 format and must be DER-encoded. PCKS #8 format is defined in RFC 5208. DER encoding is defined in International Telecommunications Union X.680. Asymmetric keys must use one of the length and algorithm combinations supported by Cloud KMS.

Some aspects of a key, such as the key's length, cannot be changed after the key is created. In these cases, the key cannot be imported into Cloud KMS.

Checking a symmetric key

Use the wc command to check a symmetric key's length.

wc -c /path/to/unwrapped-key

You cannot import a symmetric key with a length other than 32.

Use the file command to check a key's format.

file /path/to/unwrapped-key
  • If the output is data, the key is in the correct format to be imported.
  • If the output is ASCII text, use the cat command to display the contents of the file.
    • If it is a string of letters and numbers ending in an = sign, it might be base64-encoded. Use the base64 command (Base64.exe on Windows) to decode it. The following is an example of a base64-encoded key:
      THzArjassB+giKeNeT1Zr74OgV24t+Ep+37Ec6ojB3Y=
      
    • If it contains one or more lines of hexadecimal numbers, it might be hex-encoded. Use the xxd command (or the Format-Hex PowerShell command on Windows) to decode it. The following is an example of a hex-encoded key:
      00000000: 4c7c c0ae 36ac b01f a088 a78d 793d 59af  L|..6.......y=Y.
      00000010: be0e 815d b8b7 e129 fb7e c473 aa23 0776  ...]...).~.s.#.v
      
    • If it contains any other text, it may not be a valid symmetric key.

Formatting asymmetric keys

Asymmetric keys using any of the supported algorithms can be imported. In practice, it is difficult to retroactively determine the algorithm used to create an asymmetric key. For that reason, we recommend that you run the following commands on each asymmetric key before attempting to import it into Cloud KMS.

  1. Use the file command to check a key's format.

    file /path/to/unwrapped-key
    
    • If the output is PEM, the key is in PEM format. If it is ASCII text, it is probably in PEM format. In either case, run the following command to convert it to PCKS#8 DER format:

      openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER \
      -in /path/to/asymmetric-key-pem \
      -out /path/to/formatted-key
      
    • If the output is data, the key is likely to be in DER format, but it may not be in PKCS #8 format. Run the following command to ensure that the key is in the correct format. The command has no effect if the key is already in the correct format. In that case, you can use the diff command to verify that the input and output file are identical.

      openssl pkcs8 -topk8 -nocrypt -inform DER -outform DER \
        -in /path/to/asymmetric-key-der \
        -out /path/to/formatted-key
      

Troubleshooting

If you run the commands above and you believe the key is in an appropriate format, but the import still fails, check for errors in Google Cloud Console, and refer to Troubleshooting failed imports.

What's next?