|
| 1 | +# Importing keys into OCI KMS Vaults |
| 2 | + |
| 3 | +Owner: Leon van Birgelen |
| 4 | + |
| 5 | +Key Management Service is an OCI service that stores and manages keys for secure access to resources. |
| 6 | + |
| 7 | +The Oracle Cloud Infrastructure (OCI) [Key Management Service](https://oracle.com/security/cloud-security/key-management/) (KMS) is a cloud-based service that provides centralized management and control of encryption keys for data stored in OCI. |
| 8 | + |
| 9 | +One of the capabilities of OCI KMS is to import Vault Keys and Key Versions, in case you want to "bring your own key" (BYOK). There is [detailed documentation](https://docs.public.oneportal.content.oci.oraclecloud.com/en-us/iaas/Content/KeyManagement/Tasks/importingkeys.htm) available on this process but in this example below you will find a brief guide on how to this as it is a tedious and detailed process. |
| 10 | + |
| 11 | + |
| 12 | +# Importing a RSA 2048 Asynchronous key |
| 13 | + |
| 14 | +This example is for an RSA 2048 Asynchronous Key to be imported in OCI Vault. There are also examples for Synchronous Keys and for importing key versions, see the documentation as mentioned above. |
| 15 | + |
| 16 | +## Prerequisites |
| 17 | + |
| 18 | +- Make sure to have a up-to-date version of OpenSSL installed that supports the RSA_OAEP_AES_SHA256 wrapping mechanism. OCI CloudShell is currently based on Oracle Linux 7, which does not have the minimum required version of OpenSSL installed. If you create an OCI Compute based on Oracle Linux 9, it should work immediately. Below commandline can be used to test if your openssl version is usable. |
| 19 | + ``` |
| 20 | + openssl enc -id-aes256-wrap-pad -iv A65959A6 -K AABBCCDDEEFFAABBCCDDEEFFAABBCCDDEEAABBCCDDEEAABBCCDDEEFFAABBCCDD -in /dev/null |
| 21 | + ``` |
| 22 | + If the command returns an Error, please use an Oracle Linux 9 compute image or follow this [documentation](https://docs.public.oneportal.content.oci.oraclecloud.com/en-us/iaas/Content/KeyManagement/Tasks/importing_assymetric_keys.htm). |
| 23 | + |
| 24 | +- Get a RSA 2048 Key Pair to import and store in the file name ```my_keypair.pem```, or generate one via this command: |
| 25 | + ``` |
| 26 | + openssl genrsa -out my_keypair.pem 2048 |
| 27 | + ``` |
| 28 | + |
| 29 | +- Create an OCI Vault and copy the Public Wrapping Key. You can find it when creating a new Key in the Vault and enabling the "Import External key" checkbox. For this example store the wrapping key in file called ```pub_wrapping_key.pem``` |
| 30 | + |
| 31 | +### Manually create the wrapped key material to be imported |
| 32 | + |
| 33 | +1. Create a temporary AES key: |
| 34 | + ``` |
| 35 | + openssl rand -out temp_aes.key 32 |
| 36 | + ``` |
| 37 | + |
| 38 | +2. Wrap the temporary AES key with the public wrapping key using RSA-OAEP with SHA-256: |
| 39 | + ``` |
| 40 | + openssl pkeyutl -encrypt -in temp_aes.key -inkey pub_wrapping_key.pem -pubin -out wrapped_temp_aes.key -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256 |
| 41 | + ``` |
| 42 | + |
| 43 | +3. Generate hexadecimal of the temporary AES key material: |
| 44 | + ``` |
| 45 | + export temporary_AES_key_hexdump=$(hexdump -v -e '/1 "%02x"' < temp_aes.key) |
| 46 | + ``` |
| 47 | + |
| 48 | +4. If the RSA private key you want to import is in PEM format, convert it to DER: |
| 49 | + ``` |
| 50 | + openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER -in my_keypair.pem -out my_private_key.key |
| 51 | + ``` |
| 52 | + |
| 53 | +5. Wrap your RSA private key with the temporary AES key: |
| 54 | + ``` |
| 55 | + openssl enc -id-aes256-wrap-pad -iv A65959A6 -K $temporary_AES_key_hexdump -in my_private_key.key -out my_wrapped.key |
| 56 | + ``` |
| 57 | + |
| 58 | +6. Create the wrapped key material by concatenating both wrapped keys: |
| 59 | + ``` |
| 60 | + cat wrapped_temp_aes.key my_wrapped.key > wrapped_key_material.key |
| 61 | + ``` |
| 62 | + |
| 63 | +### Use the provided script to generate the wrapped key material to be imported |
| 64 | + |
| 65 | +The script is provided in the OCI Documentation [here](https://docs.public.oneportal.content.oci.oraclecloud.com/en-us/iaas/Content/KeyManagement/Tasks/importing_asymmetric_keys_topic_script_to_import_rsa_key_material_as_a_new_external_key.htm) |
| 66 | + |
| 67 | +Just copy the script and place it on an environment where you have the correct version of openssl (see pre-requisites). Then modify the script to have the correct values to point to the required input files. The below example shows how to set the values when you use an OCI Compute with Oracle Linux 9: |
| 68 | + |
| 69 | +``` |
| 70 | +OPENSSL_PATH="/usr/bin/openssl" |
| 71 | +PRIVATE_KEY="my_keypair.pem" |
| 72 | +WRAPPING_KEY="pub_wrapping_key.pem" |
| 73 | +``` |
| 74 | + |
| 75 | +After the script has run, the wrapped key material files are available in a tmp folder as listed on screen and can be used to import the key as mentioned in the next step. |
| 76 | + |
| 77 | +If you want to automate the import to OCI as well, the script has already some example code in it that can be used as a starting point for this. Just also make sure that you setup OCI Permissions and grant these to the compute's instance principles via a dynamic group. See the OCI Documentation for more details on permissions [here](https://docs.public.oneportal.content.oci.oraclecloud.com/en-us/iaas/Content/KeyManagement/Tasks/importingkeys.htm#permissions). |
| 78 | + |
| 79 | +## Import the wrapped key material |
| 80 | + |
| 81 | +- In the OCI Console from the OCI Vault where the Public Wrapping Key was retrieved, click Create a Key and select the RSA as Key Shape Algorithm with the length 2048. |
| 82 | +- Have the Import External key checkbox enabled. |
| 83 | +- The Wrapping Algorithm should be automatically set to "RSA_OAEP_AES_SHA256" |
| 84 | +- Upload the wrapped key material file ```wrapped_key_material.key``` |
| 85 | +- Click on the Create Key button. |
| 86 | +- Make sure to cleanup the used files as private keys should never be left somewhere on a filesystem. |
| 87 | + |
| 88 | +# License |
| 89 | + |
| 90 | +Copyright (c) 2024 Oracle and/or its affiliates. |
| 91 | + |
| 92 | +Licensed under the Universal Permissive License (UPL), Version 1.0. |
| 93 | + |
| 94 | +See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details. |
0 commit comments