Difficulty: beginner
Estimated Time: 35 minutes

The Vault service lets you create vaults in your tenancy as containers for encryption keys and secrets. Vaults are logical entities where the Vault service creates and durably stores keys and secrets. The type of vault you have determines features and functionality such as degrees of storage isolation, access to management and encryption, and scalability. The type of vault you have also affects pricing.

If needed, a virtual private vault provides you with a dedicated partition in a hardware security module (HSM), offering a level of storage isolation for encryption keys that’s effectively equivalent to a virtual independent HSM. Keys are stored on highly available and durable hardware security modules (HSM) that meet Federal Information Processing Standards (FIPS) 140-2 Security Level 3 security certification. The Vault service uses the Advanced Encryption Standard (AES) as its encryption algorithm and its keys are AES symmetric keys. Note that the virtual private vault has a substantial price tag (several $ per hour) compared to many other services.

Before the introduction of secrets as a resource, Oracle Cloud Infrastructure Vault was known as Oracle Cloud Infrastructure Key Management.

Keys

Keys are logical entities that represent one or more key versions that contain the cryptographic material used to encrypt and decrypt data, protecting the data where it is stored. When processed as part of an encryption algorithm, a key specifies how to transform plaintext into ciphertext during encryption and how to transform ciphertext into plaintext during decryption.

After you create your first master encryption key, you can then use the API to generate data encryption keys that the Vault service returns to you. Some services can also use a master encryption key to generate their own data encryption keys.

The OCI API for the Vault Service gives the ability to encrypt contents using one of the generated keys - resulting in unreadable contents - and to decrypt contents that has previously been encrypted using that same key. In encrypted state, the data can freely be shared without fear of revealing the original content.

Secrets

Secrets are credentials such as passwords, certificates, SSH keys, or authentication tokens for third-party cloud services that you use with Oracle Cloud Infrastructure services. These secrets are stored in a vault, which is a software container backed by a FIPS 140-2 Level 3 HSM. Storing secrets in a vault provides greater security than you might achieve by storing them elsewhere, such as in code or configuration files. You can retrieve secrets from the vault when you need them to access resources or other services. You (an application) can cache a secret and use it as long as you need it. All tenancies have access to and can store secrets in Oracle Cloud Infrastructure Vault at no cost. This service was launched in April 2020.

The following diagram illustrates the most fundamental secrets use case. You create secret (credentials) and store them in Oracle Cloud Infrastructure vault. The application can use/read the secret as needed (4) and then connect (5) to the target service. source: https://www.ateam-oracle.com/secure-way-of-managing-secrets-in-oci

Advantages of managing secrets in Oracle Cloud Infrastructure vault

  • You can centralize secrets management and only administrators will have Create, Update, and Delete permissions on secrets
  • You can rotate/update secrets/credentials without any changes in the consumer application
  • Secrets are encrypted at rest to improve security posture
  • secrets management proliferates machine to machine communication or serverless computing by making it secure

Scenario steps

In this scenario, you will:

  • create a Vault
  • generate a Key in the Vault and use the key for Encryption and Decyption
  • create and retrieve Secrets
  • read Secrets from a Node application
  • read Secrets from a Function

Resources

Oracle Blog - Announcing Secrets Service

OCI Vault, Keys and Secrets - technical documentation

Summary

This completes your introduction to Vaults, Keys and Secrets.

You have created a Vault, generated a Key in that Vault and created a Secret in the Vault.

You have used to Key to encrypt contents. The encrypted contents was later decrypted as well.

The secret was stored in the Vault and later retrieved using the OCI CLI and in a Node application using the Node SDK for OCI. The last step you took was the creation of a Function that retrieves the secret - using its Resource Principal status.

Finally, the function, the dynamic group and the policy were removed and the Secret, Key and Vault where scheduled for deletion. Note that the pending deletion for the Vault, Key and Secret can still be canceled, although for Key and Secret only when the deletion of the Vault is canceled first.

Managing a Vault with Keys and Secrets

Step 1 of 7

Step 1 - Preparing the lab environment

Some of the steps in this scenario require the use of the OCI Command Line Interface.

Execute the following command to install the OCI CLI:

curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh > install-oci-cli.sh
chmod +777 install-oci-cli.sh
sudo ./install-oci-cli.sh --accept-all-defaults

# add this line to ~/.profile - to make oci a recognized shell command
echo 'oci() { /root/bin/oci "[email protected]"; }' >> ~/.profile
# reload ~/.profile
. /root/.profile

You need to provide details on the OCI tenancy you will work in and the OCI user you will work as. Please open the IDE tab and edit these two files:

  • ~/.oci/config
  • ~/.oci/oci_api_key.pem

Paste the contents that you prepared in the OCI Tenancy preparation scenario.

Finalizing the Environment

Set the environment variable LAB_ID to 1 - unless you are in a workshop with multiple participants and each uses their own number.

export LAB_ID=1

Try out the following command to get a list of all namespaces you currently have access to - based on the OCI Configuration defined above.

oci os ns get

If you get a proper response, the OCI is configured correctly and you can proceed. If you run into an error, ask for help from your instructor.

You need to perform one more edit action on file ~/.oci/config. Open this file in the editor. Copy the entire contents and paste it below the current contents. Now change [DEFAULT] to [FN] in the duplicate block. The file will now look something like:

[DEFAULT]
user=ocid1.user.oc1..aaaaaaaazr7eselv5q
fingerprint=fd:db:13:bd:31
tenancy=ocid1.tenancy.oc1..aaaaaaaaggg6okq
region=us-ashburn-1
key_file=/root/.oci/oci_api_key.pem
[FN]
user=ocid1.user.oc1..aaaaaaaazr7eselv5q
fingerprint=fd:db:13:bd:31
tenancy=ocid1.tenancy.oc1..aaaaaaaaggg6okq
region=us-ashburn-1
key_file=/root/.oci/oci_api_key.pem

Environment Preparation

Check the installed version of Fn CLI. Note: we do not need the Fn server at this stage.

fn version

Configure and set remote context

List the currently available Fn contexts

fn list contexts

Create an appropriate Fn context for working with OCI as provider (see OCI Docs on Functions).

fn create context lab-fn-context --provider oracle

fn use context lab-fn-context

Prepare a number of environment variables. Note: the assumptions here are that you are working in a tenancy in the Ashburn region and a compartment called lab-compartment exists as well as an API Gateway lab-apigw in that same compartment as well as an API Deployment called MY_API_DEPL# on the API Gateway. We need to get references to these resources in order to create new resources in the right place.

export REGION=$(oci iam region-subscription list | jq -r '.data[0]."region-name"')
export REGION_KEY=$(oci iam region-subscription list | jq -r '.data[0]."region-key"')
export USER_OCID=$(oci iam user list --all | jq -r  '.data |sort_by(."time-created")| .[0]."id"')
export TENANCY_OCID=$(oci iam user list --all | jq -r  '.data[0]."compartment-id"') 
cs=$(oci iam compartment list)
export compartmentId=$(echo $cs | jq -r --arg display_name "lab-compartment" '.data | map(select(."name" == $display_name)) | .[0] | .id')

# get namespace
nss=$(oci os ns get)
export ns=$(echo $nss | jq -r '.data')

Update the context with the settings relevant for this workshop.

fn update context oracle.compartment-id $compartmentId

fn update context api-url https://functions.$REGION.oci.oraclecloud.com

fn update context registry ${REGION_KEY,,}.ocir.io/$ns/cloudlab-repo

fn update context oracle.profile FN

You can list the currently available Fn contexts again and see whether your changes had an effect (of course they did)

fn list contexts

Login Docker to OCI Container Registry

Next and finally, login to the private Docker Registry that is prepared for you on OCI.

The username you have to provide is composed of <tenancy-namespace>/<username>.

NAMESPACE=$ns
USER_USERNAME=$(oci iam user list --all | jq -r  '.data |sort_by(."time-created")| .[0]."name"')
echo "Username for logging in into Container Registry is $NAMESPACE/$USER_USERNAME"

The password is an Authentication Token generated for the specified user, in the OCI Tenancy preparation scenario. If you do not remember the authentication token, you can generate another one in the OCI Console: https://console.REGION.oraclecloud.com/identity/users//swift-credentials or using the instructions in the preparation scenario.

echo "Open the console at https://console.${REGION,,}.oraclecloud.com/identity/users/$USER_OCID/swift-credentials"

Now you can perform the login. Type the username and press enter, then type or paste the authentication token and press enter again.

docker login ${REGION_KEY,,}.ocir.io