|
| 1 | +# OCI Vault software key backup |
| 2 | + |
| 3 | +Owner: Inge Os |
| 4 | + |
| 5 | +OCI Vault supports several types of keys: HSM-based and software-based. |
| 6 | + |
| 7 | +Most services in Oracle OCI with encryption offer two types of encryption key management, Oracle-managed keys or Customer-managed keys. |
| 8 | + |
| 9 | +Some common main requirements most often seen in various cyber security frameworks typically are: |
| 10 | +- Separation of Duty, key administration is separated from service management. Typical for Oracle Databases with Transparent Data Encryption the DBA function does not have access to manage the keys, only to read and use them. |
| 11 | +- The Master key shall not be stored in any filesystem shared with the encrypted resource. Again, for using the Oracle Database with TDE as an example, the default key management with TDE is to use an Oracle Wallet stored in the same filesystem as the Oracle software installation. |
| 12 | +- To meet these requirements and to have a robust operations model for key management, Oracle offers Oracle Key Vault. |
| 13 | + |
| 14 | +Oracle Key Vault offers two main categories of key management: |
| 15 | +- HSM-based, with a FIPS compliant Hardware Security Module |
| 16 | +- Software-based, where the key is not stored in an HSM, but still protected with the strong tenant isolation and ops isolation that is the cornerstone of Oracle OCI. |
| 17 | + |
| 18 | +The main difference between HSM-based Vaults and Software-based is that the HSM-based prohibits explicit export of the master key. HSM-based key storage offers HA and DR, including cross-region replication, slightly dependent on the type of HSM service deployed. |
| 19 | + |
| 20 | +Software-based Key Vault does not offer cross-region replication. |
| 21 | +The main purpose of this asset is to provide an example Python script that demonstrates the usage of the Python KMS SDK, an example of OCI Vault software key backup/restore between two regions. |
| 22 | + |
| 23 | +## Prerequisites |
| 24 | + |
| 25 | +- The script may be run from the Cloud Shell, or from a Linux/Windows environment |
| 26 | +- Python 3.0 |
| 27 | +- Create a virtual environment |
| 28 | + |
| 29 | +``` |
| 30 | +[user]$ python -m venv ocienv |
| 31 | +[user]$ source ocienv/bin/activate |
| 32 | +``` |
| 33 | +- Install Oracle OCI CLI, if not run off Cloud Shell |
| 34 | + |
| 35 | +Please refer to the OCI install guide. |
| 36 | + |
| 37 | +[CLI Installation Guide](https://docs.oracle.com/en-us/iaas/Content/API/Concepts/cliconcepts.htm) |
| 38 | + |
| 39 | + |
| 40 | +- Install Python SDK into your virtual environment |
| 41 | + |
| 42 | +``` |
| 43 | +[user]$ pip install oci |
| 44 | +``` |
| 45 | + |
| 46 | +- Configure OCI profiles and verify the OCI SDK |
| 47 | +Configure the OCI CLI with an API key (may be the same) for source and target. Please refer to the OCI CLI documentation for creating an OCI environment file. |
| 48 | + |
| 49 | + |
| 50 | +[OCI File Configuration]( https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliconfigure.htm) |
| 51 | + |
| 52 | + |
| 53 | +The OCI CLI configuration may be verified with the following command: |
| 54 | + |
| 55 | +``` |
| 56 | +[user]$ oci os ns get --profile myprofile |
| 57 | +{ |
| 58 | + "data": "<your namespace>" |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +- A valid public key for export only |
| 63 | + |
| 64 | +- Create and/or Check IAM Policies to permit key reading, inspection, and creation. |
| 65 | + |
| 66 | +Permission to `manage` the following types of resources in your Oracle Cloud Infrastructure tenancy: `vaults`, `keys`, `secret-family` |
| 67 | +Example policies: |
| 68 | +``` |
| 69 | +Allow group SecurityAdmins to manage vaults in tenancy |
| 70 | +
|
| 71 | +Allow group SecurityAdmins to manage keys in tenancy |
| 72 | +
|
| 73 | +Allow group SecurityAdmins to manage secret-family in tenancy |
| 74 | +``` |
| 75 | +[Policy Reference, Vault](https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/commonpolicies.htm#sec-admins-manage-vaults-keys) |
| 76 | + |
| 77 | + |
| 78 | +If you don't have the required permissions and quota, contact your tenancy administrator. See [Policy Reference](https://docs.cloud.oracle.com/en-us/iaas/Content/Identity/Reference/policyreference.htm), [Service Limits](https://docs.cloud.oracle.com/en-us/iaas/Content/General/Concepts/servicelimits.htm), [Compartment Quotas](https://docs.cloud.oracle.com/iaas/Content/General/Concepts/resourcequotas.htm). |
| 79 | + |
| 80 | +## Script execution |
| 81 | + |
| 82 | +The script requires a number of arguments. The arguments vary depending on the script execution. All or some arguments can be submitted as a configuration file in JSON format or at the command line. Any command-line argument overwrites any arguments from the configuration file, |
| 83 | + |
| 84 | +The script has two modes of operation: |
| 85 | +1) Export a key, save it to a file, and print the fingerprint, used for verification of a key |
| 86 | +2) Copy the key between two locations where tenant OCID, region, and API Key are required. |
| 87 | + |
| 88 | +A key in the vault may have several versions, and you may specify the OCID of a given version for both export and copy of the key. If no key version is specified, the most recent key is exported. |
| 89 | + |
| 90 | +The script checks if the key is Enabled and is of type SOFTWARE before any export is attempted. |
| 91 | + |
| 92 | +## Configuration parameters/arguments |
| 93 | + |
| 94 | +ociconfig path to OCI configuration file |
| 95 | +source_ociprofile Source profile in oci config |
| 96 | +source_region Source Region |
| 97 | +source_compartment Source Compartment |
| 98 | +source_vault Source vault OCI |
| 99 | +source_keyname Source Key Name, if search for key |
| 100 | +source_key_ocid Source key OCID if search for OCID |
| 101 | +source_key_version OCID of a specific key version, if not set pick latest version |
| 102 | + |
| 103 | +target_region Target Region |
| 104 | +target_compartment Target Compartment |
| 105 | +target_vault Target Vault OCID |
| 106 | +target_ociprofile Target profile in oci config |
| 107 | +target_keyname Target keyname, the copy will be created with this name |
| 108 | + |
| 109 | +exportonly only save to file or print key, don't backup |
| 110 | +wrapping_pubkey_file If it supplied filepointer external key for wrapping |
| 111 | +outputfile File for the exported key |
| 112 | + |
| 113 | +## Example execution |
| 114 | +Example export |
| 115 | +``` |
| 116 | +python kms_key_backup.py --configfile kms_backup.json --target_keyname test1 --source_key_ocid ocid1.key.oc1.eu-frankfurt-1.xxxxxx --exportonly --wrapping_pubkey_file export_pub.pem --source_key_version ocid1.keyversion.oc1.eu-frankfurt-1.qwertyqwerty |
| 117 | +``` |
| 118 | +with configfile: |
| 119 | +``` |
| 120 | +{ |
| 121 | + "ociconfig":"/home/myhome/.oci/config", |
| 122 | + "source_ociprofile":"my-config-fra", |
| 123 | + "source_region" : "eu-frankfurt-1", |
| 124 | + "source_compartment" : "ocid1.compartment.oc1..aaaaaaaa", |
| 125 | + "source_vault" : "ocid1.vault.oc1.eu-frankfurt-1.aaaeeeqqqlllaleaeqlr", |
| 126 | + "wrapping_algorithm" : "RSA_OAEP_AES_SHA256" |
| 127 | +} |
| 128 | +``` |
| 129 | +Example backup |
| 130 | +``` |
| 131 | +python kms_key_backup.py --configfile kms_backup.json --target_keyname test2 --source_key_ocid ocid1.key.oc1.eu-frankfurt-1.eeeeaaaaaaa --source_key_version ocid1.keyversion.oc1.eu-frankfurt-1.qfqfqfqfqfaeaea |
| 132 | +``` |
| 133 | +with configfile: |
| 134 | +``` |
| 135 | +{ |
| 136 | + "ociconfig":"/home/myhome/.oci/config", |
| 137 | + "source_ociprofile":"my-config-fra", |
| 138 | + "source_region" : "eu-frankfurt-1", |
| 139 | + "source_compartment" : "ocid1.compartment.oc1..aaaaaaaa", |
| 140 | + "source_vault" : "ocid1.vault.oc1.eu-frankfurt-1.aaaeeeqqqlllaleaeqlr", |
| 141 | + "source_key_ocid" : "ocid1.key.oc1.eu-frankfurt-1.sxesxesxesxe", |
| 142 | + "target_region" : "eu-stockholm-1", |
| 143 | + "target_compartment" : "ocid1.compartment.oc1..aaaaaaaa", |
| 144 | + "target_vault" : "ocid1.vault.oc1.eu-stockholm-1.qewuroewrre", |
| 145 | + "target_ociprofile":"my-config-ams", |
| 146 | + "wrapping_algorithm" : "RSA_OAEP_AES_SHA256" |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | + |
| 151 | + |
| 152 | + |
| 153 | +# License |
| 154 | + |
| 155 | +Copyright (c) 2024 Oracle and/or its affiliates. |
| 156 | + |
| 157 | +Licensed under the Universal Permissive License (UPL), Version 1.0. |
| 158 | + |
| 159 | +See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details. |
| 160 | + |
| 161 | + |
0 commit comments