Skip to main content

Export a key

Use the Pangea Vault to export key materials

note

Only Vault keys that have been designated as "exportable" in the Advanced settings during key creation can be exported.

There are three export options available using the Vault APIs.

  • Exporting a key without encryption (not secure)
  • Encrypting and exporting a key
  • Encrypting and exporting a key using Key Encapsulation Mechanism, or KEM

The Vault Export API uses a set of required and optional API parameters to provide the three export options.

Required Parameters:

  • id - The ID of the Vault key material to be exported.

Optional Parameters:

  • asymmetric_algorithm - Encryption option for exporting the key material. Use RSA-OAEP-4096-SHA512 for traditional public key encryption and RSA-NO-PADDING-4096-KEM for KEM.
  • asymmetric_public_key - A RSA-4096 public key in PEM format that will be used to encrypt a salt value returned in result.encrypted_salt or to encrypt the exported key materials, depending on the selection for the asymmetric_algorithm.
  • kem_password - Used along with the salt (returned in result.encrypted_salt) to derive the symmetric key (AES256 GCM algorithm) that is used to encrypt and decrypt the exported key material.
  • version - Version of the key material to export. Defaults to current version.

Exporting key material without encryption​

You can export key material without using encryption for both symmetric and asymmetric key materials, and for both public and private keys. However, asymmetric keys exported in this method are returned in PEM format plain text, and symmetric keys are returned in base64 encoded binary. This is not considered secure.

To export key material without encryption, complete the following:

  1. Provide the ID of the key to export in the id field of the API.
  2. Input the version of the key to export, if it is not the current version.
  3. Submit the POST request.
  4. The key is returned in PEM or base64 encoded format in the following fields:
    • For symmetric keys: result.key
    • For asymmetric private keys: result.private_key
    • For asymmetric public key: result.public_key

Encrypting and exporting​

Encrypting and exporting key material is possible for keys that are smaller than 382 bytes in length. Longer key material for both symmetric and asymmetric key material must be exported using the KEM method.

RSA-OAEP-4096-SHA512 exportable keys​

All supported symmetric keys, and the following asymmetric keys can be exported using the RSA-OEAP-4096-SHA512 option:

  • ECDSA-SHA256 (227 bytes)
  • ECDSA-SHA384 (288 bytes)
  • ECDSA-SHA512 (365 bytes)
  • ED25519 (119 bytes)
  • ES256 (227 bytes)
  • ES256K (223 bytes)
  • ES384 (288 bytes)
  • ES512 (365 bytes)
  • SPHINCSPLUS-128F-SHA256-ROBUST-BETA (237 bytes)
  • SPHINCSPLUS-128F-SHA256-SIMPLE-BETA (237 bytes)
  • SPHINCSPLUS-128F-SHAKE256-ROBUST-BETA (237 bytes)
  • SPHINCSPLUS-128F-SHAKE256-SIMPLE-BETA (237 bytes)
  • SPHINCSPLUS-192F-SHA256-ROBUST-BETA (302 bytes)
  • SPHINCSPLUS-192F-SHA256-SIMPLE-BETA (302 bytes)
  • SPHINCSPLUS-192F-SHAKE256-ROBUST-BETA (302 bytes)
  • SPHINCSPLUS-192F-SHAKE256-SIMPLE-BETA (302 bytes)
  • SPHINCSPLUS-256F-SHA256-ROBUST-BETA (371 bytes)
  • SPHINCSPLUS-256F-SHA256-SIMPLE-BETA (371 bytes)
  • SPHINCSPLUS-256F-SHAKE256-ROBUST-BETA (371 bytes)
  • SPHINCSPLUS-256F-SHAKE256-SIMPLE-BETA (371 bytes)

To use the RSA-OAEP-4096-SHA512 option for encrypting the exported key material directly with the asymmetric_public_key, complete the following:

  1. Provide the ID of the key material to export in the id field of the API (key material must be less than 382 bytes in length).
  2. Input a public key for use with a RSA-4096 algorithm in the asymmetric_public_key field.
  3. Set the asymmetric_algorithm option to RSA-OAEP-4096-SHA512.
  4. Submit the POST request.
  5. If symmetric key meterial is being exported, the encrypted symmetric key is returned in result.key. If asymmetric key material is being exported, the asymmetric key is returned in two fields:
    • result.private_key - The encrypted private key of the exported key material.
    • result.public_key - The public key of the exported key material in PEM plaintext.

Encrypting and exporting a key using KEM​

Vault uses KEM to securely export both asymmetric and symmetric keys of any length.

Keys that require KEM for encrypted export​

  • ED25519-DILITHIUM2-BETA (5404 bytes)
  • ED448-DILITHIUM3-BETA (8334 bytes)
  • FALCON-1024-BETA (3076 bytes)
  • RSA-2048-SHA256 (1675 bytes)
  • RSA-3072-SHA256 (2455 bytes)
  • RSA-4096-SHA256 (3243 bytes)
  • RSA-OAEP-2048-SHA1 (1679 bytes)
  • RSA-OAEP-2048-SHA256 (1679 bytes)
  • RSA-OAEP-2048-SHA512 (1679 bytes)
  • RSA-OAEP-3072-SHA1 (2455 bytes)
  • RSA-OAEP-3072-SHA256 (2455 bytes)
  • RSA-OAEP-3072-SHA512 (2459 bytes)
  • RSA-OAEP-4096-SHA1 (3243 bytes)
  • RSA-OAEP-4096-SHA256 (3243 bytes)
  • RSA-OAEP-4096-SHA512 (3243 bytes)
  • RSA-PKCS1V15-2048-SHA256 (1679 bytes)
  • RSA-PSS-2048-SHA256 (1679 bytes)
  • RSA-PSS-3072-SHA256 (2459 bytes)
  • RSA-PSS-4096-SHA256 (3243 bytes)
  • RSA-PSS-4096-SHA512 (3247 bytes)

The KEM process involves derivation of a symmetric key (AES256 GCM) that will be used to encrypt and decrypt the exported key materials. Both the Vault export API implementation and the caller will need to derive the same symmetric key: export will use it to encrypt, and the caller will use it to decrypt the exported key materials.

The derivation of the symmetric key is driven by a kem password and a salt. The caller chooses and provides a kem_password and Vault's export API chooses the salt. The export API uses kem_password and its chosen salt to derive the symmetric key and uses it to encrypt the key materials that are returned.

The caller of the export API has to use the kem_password and salt to derive the same symmetric key so that the caller can use it to decrypt the returned encrypted and exported key materials. The caller already has the kem_password because they passed it in. The salt that the export API used in the symmetric key derivation is encrypted using the asymmetric_public_key parameter and is returned in result.encrypted_salt.

  1. Add the ID of the key to export in the id field of the API.
  2. Create a password for the kem_password parameter.
  3. Input a public key created for use with a RSA-4096 algorithm in the asymmetric_public_key field.
  4. Set the asymmetric_algorithm option to RSA-NO-PADDING-4096-KEM.
  5. Submit the POST request.
  6. Symmetric key materials are encrypted with the derived symmetric key (AES256 GCM) and returned in result.key. Asymmetric key materials are returned as:
    • result.private_key - The private key of the exported key material encrypted with the derived symmetric key (AES256 GCM).
    • result.public_key - The public key of the exported key material in plaintext PEM format.

Recover the exported key​

After exporting the key, you can recover the key material by completing the following actions.

It is strongly recommended that you use the Pangea SDK to handle recovery of keys exported using KEM to avoid errors and for ease of use. For details on the process, see RFC 5990 Appendix A and/or the source code for the Pangea SDK .

Here is a description of the KEM exported key recovery process.

  1. Use the asymmetric private key corresponding to the asymmetric_public_key parameter value to decrypt the salt returned in the result.encrypted_salt field within the response.
  2. Use the PBKDF2 key derivation function with the decrypted salt, the result.iterations, and the kem_password to re-derive the symmetric key that was used to encrypt the key material and is needed to decrypt it.
  3. Use the result of the derived-symmetric-key retrieval to decrypt the result.key or result.private_key, based on the type of key that was encrypted.

Example Export using KEM​

A cURL request for exporting a symmetric key would look similar to this:

POST
curl -sSLX POST 'https://vault.dev.aws.pangea.cloud/v2beta/export' \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{"kem_password":"abcd1234","id":"pvi_hcubkazywdrkcv53af2uawrsoxbe2lbu","asymmetric_algorithm":"RSA-NO-PADDING-4096-KEM","asymmetric_public_key":"-----BEGIN RSA PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAr26sUIdzRO80Rla+J3TZ\n5Jt/AzJENwet1aGoxxm6rTT6CJBaiELYRGaSKroA7kJhiKFEU3DDeHDUvNMlM8PG\neaLTxlpDHMWeMhD0vUKvjwNpKsqYUO/da/rvHK8tk8XrLaHFkbARjCuSPNdINDhJ\nSZ/UW76xvTB3sxo13ln7UP/HQe0kYAz2vU0CS74GJwwzpeuYjbGWOdfgc4+BRQ7W\nx1qOzB4dSW76kjjjDRYrfj6o+FqaIta3MVxR2qpH/s+Zf1N2Rg/jjUjJ+1gKwNdZ\nkth6yKUBTJxyeynq28iJGfjzJPmNUiq8aqcNV15/gA7MDRXpi0aA0PmkGMSIIQZp\nKRAaWoBrLD+oC05tRFCzxzsEXpwAmWuAEO7Ujyfiz5d8L1FZLkaH9k5F/f+QMwQt\nIdwy8YhiEYMLsigO7W4SkVL/5Nciy/bPn4HKW6TmPY3Q1hKgAQEvAGZ6mbbkr8/2\nzFo+tS446Us0pASyaEdpS9Yz4f5pcMFXagGJS0WfswPv1kD4x7q1xUQ2IcU0hLdd\nSSzEz6t8kwodkxABEjBqi+o/OpoRRNsHc5Bidmha1QWjYV1bo2VIjTIi9OTjCKVG\nI+NjynsmCtv+wSue+5nU1h1PiGl2jKKA1r/1yHBzIvL7mhIP5SEaV1EzRHyZoVmx\n+CVewsSYUhQ7/Zuloa1nW1cCAwEAAQ==\n-----END RSA PUBLIC KEY-----"}'

And a successful response would export the key material and look something like this:

/v2/export response
{
"status":"Success"
"summary":"Symmetric key exported"
  "result":{
    "algorithm":"AES-CFB-128"
    "asymmetric_algorithm":"RSA-NO-PADDING-4096-KEM"
    "enabled":true
    "encrypted_salt":"a5RnZdGqI8HZkqBgIlGPV5rCU+u7qxBrUXsDpq0NNjF80p4JGWKvY8DVmRh/8ch3UJYy4yA+57ud+42Kl8gWhjDReHk1MhJw+k2iJZQv+rOE/47tqwwIzfBBQu1s4awmVDN6Ef9OmQbYkUV53oY5gF6BxXIyZqtkwKeyFasn476P0+2ew0HXthSd87KB7A+JJgDo/v8/1UdDRcCerMuJ42+vfURK7lavF9OF/IScfsTll+itMgNF1qZltDmq51wdV02tStrg732GMW6sQAteMU9gPUg144mHddht+82JAYesrQOy3++28i5k/ir7yp3bjnzD9WfLbTtFtsFKvaYauw=="
    "encryption_type":"kem"
    "hash_algorithm":"sha512"
    "id":"pvi_hcubkazywdrkcv53af2uawrsoxbe2lbu"
    "iteration_count":1000000
    "kdf":"pbkdf2"
    "key":"2nydzxWGnipSBj/ueORYFlb9k2OB4Avvz5F4Z9wE29buFlxA4WyN/rkKV3qUGNX4eEwT7Q=="
    "symmetric_algorithm":"AES-GCM-256"
    "type":"symmetric_key"
    "version":1
    }
}

You can then recover the key using your preferred method. We strongly suggest you use the SDK for this task as previously mentioned.

Was this article helpful?

Contact us