Initial version

Author: lvbirgelen

security/security-design/shared-assets/kms-import-keys/LICENSE

@@ -0,0 +1,35 @@
+Copyright (c) 2024 Oracle and/or its affiliates.
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

security/security-design/shared-assets/kms-import-keys/README.md

@@ -0,0 +1,63 @@
+# Importing keys into OCI KMS Vaults
+
+Owner: Leon van Birgelen
+
+Key Management Service is an OCI service that stores and manages keys for secure access to resources.
+
+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.
+
+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.
+
+This example is for a RSA 2048 Asynchronous key to be imported.
+
+# Prerequisites
+
+- 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.
+
+- Get a RSA 2048 Key Pair to import and store in the file name **my_keypair.pem**, or generate one via this command:
+
+  ```openssl genrsa -out my_keypair.pem 2048```
+
+# Create the wrapped key material to be imported
+
+1. 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**
+
+2. Create a temporary AES key:
+
+   ```openssl rand -out temp_aes.key 32```
+
+3. Wrap the temporary AES Key:
+
+   ```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```
+
+4. Create a hexdump of the temporary AES key:
+
+   ```export temporary_AES_key_hexdump=$(hexdump -v -e '/1 "%02x"' < temp_aes.key)```
+
+5. Extract the private key from the to be imported RSA key:
+
+   ```openssl pkcs8 -topk8 -nocrypt -inform PEM -outform DER -in my_keypair.pem -out my_private_key.key```
+
+6. Encrypt the private key with the temporary AES key:
+
+   ```openssl enc -id-aes256-wrap-pad -iv A65959A6 -K $temporary_AES_key_hexdump -in my_private_key.key -out my_wrapped.key```
+
+7. Concatenate the wrapped temporary AES key with the wrapped private key into the to be imported key material:
+
+   ```cat wrapped_temp_aes.key my_wrapped.key > wrapped_key_material.key```
+
+# Import the wrapped key material
+
+- From the OCI Vault where the Public Wrapping Key was retrieved, create a Key and select the RSA as Key Shape Algorithm with the length 2048.
+- Have hte Import External key checkbox enabled.
+- The Wrapping Algorithm should be automatically set to "RSA_OAEP_AES_SHA256"
+- Upload the wrapped key material file **wrapped_key_material.key**
+- Click on the Create Key button.
+
+# License
+
+Copyright (c) 2024 Oracle and/or its affiliates.
+
+Licensed under the Universal Permissive License (UPL), Version 1.0.
+
+See [LICENSE](https://github.com/oracle-devrel/technology-engineering/blob/main/LICENSE) for more details.