Using Keys

Note

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

This topic describes what you can do with keys in terms of cryptographic operations. For information about managing keys, see Managing Keys. For information about managing the vaults in which you store keys, see Managing Vaults.

Cryptographic operations include the following:

  • Encrypting data
  • Decrypting data
  • Generating data encryption keys
  • Exporting master encryption keys (protected by software)

You can use either the command line interface (CLI) or API to perform cryptographic operations.

Required IAM Policy

Warning

Keys associated with volumes, buckets, file systems, clusters, and stream pools will not work unless you authorize Block Volume, Object Storage, File Storage, Container Engine for Kubernetes, and Streaming to use keys on your behalf. Additionally, you must also authorize users to delegate key usage to these services in the first place. For more information, see Let a user group delegate key usage in a compartment and Let Block Volume, Object Storage, File Storage, Container Engine for Kubernetes, and Streaming services encrypt and decrypt volumes, volume backups, buckets, file systems, Kubernetes secrets, and stream pools in Common Policies.

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

For administrators: for typical policies that give access to vaults, keys, and secrets, see Let security admins manage vaults, keys, and secrets. For more information about permissions or if you need to write more restrictive policies, see Details for the Vault Service.

If you're new to policies, see Getting Started with Policies and Common Policies.

Monitoring Resources

You can monitor the health, capacity, and performance of your Oracle Cloud Infrastructure resources by using metrics, alarms, and notifications. For more information, see Monitoring Overview and Notifications Overview.

For information about monitoring the traffic associated with your master encryption keys, see Vault Metrics.

Using the Command Line Interface (CLI)

For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the Command Line Reference.

Tip

Each vault has a unique endpoint for create, update, and list operations for keys. This endpoint is referred to as the control plane URL or management endpoint. Each vault also has a unique endpoint for cryptographic operations. This endpoint is known as the data plane URL or the cryptographic endpoint. When using the CLI for key operations, you must provide the appropriate endpoint for the type of operation. To retrieve a vault's endpoints, see instructions in To view vault configuration details.
To encrypt data by using your Vault master encryption key

Open a command prompt and run oci kms crypto encrypt to encrypt data:

oci kms crypto encrypt --key-id <key_OCID> --plaintext <base64_string> --endpoint <data_plane_url>

For example:


oci kms crypto encrypt --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --plaintext VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4= --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com

Optionally, you can include the associated-data option to provide an encryption context that might contain useful, but non-secret, information about the encrypted data. That information is associated with the encrypted data such that the data cannot be decrypted without it, providing an additional layer of protection. Associated data must be properly formatted JSON.


oci kms crypto encrypt --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --plaintext VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4= --associated-data '{"CustomerId":"12345", "Custom Data":"custom data"}' --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com
To decrypt data by using your Vault master encryption key

Open a command prompt and run oci kms crypto decrypt to decrypt data:

oci kms crypto decrypt --key-id <key_OCID> --ciphertext <base64_string> --endpoint <data_plane_url>

For example:


oci kms crypto decrypt --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --ciphertext VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4= --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com

If the data you want to decrypt had an encryption context associated with it at the time of encryption, the same encryption context is required to decrypt the data. For example, the --associated-data in the following sample matches what was provided in the preceding sample command for encrypting data.


oci kms crypto decrypt --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --ciphertext VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4= --associated-data '{"CustomerId":"12345", "Custom Data":"custom data"}' --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com
To generate a data encryption key from your Vault master encryption key

Open a command prompt and run oci kms crypto generate-data-encryption-key to generate a data encryption key that you can then use to encrypt and decrypt data:

oci kms crypto generate-data-encryption-key --key-id <key_OCID> --key-shape <key_encryption_information> --include-plaintext-key <Boolean_value> --endpoint <data_plane_url>

For example:


oci kms crypto generate-data-encryption-key --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --key-shape file://path/to/json/file --include-plaintext-key true --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com
To export a software-protected master encryption key

You can export a software-protected master encryption key if you want to use it to perform cryptographic operations in the application running on the client instead of performing those same operations in the cloud with the Vault service. You can use the key locally, and then discard the key from local memory to protect the key contents.

Open a command prompt and run oci kms crypto key export to export a software-protected master encryption key:

oci kms crypto key export --key-id <key_OCID> --algorithm <encryption_algorithm> --public-key <public_RSA_wrapping_key> --endpoint <data_plane_url>

For example:


oci kms crypto key export --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --algorithm RSA_OAEP_AES_SHA256 --public-key "key.pem" --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com

In the preceding example, the specified algorithm invokes the RSA AES key wrap mechanism. Specifically, it results in the generation of a temporary AES key that wraps the exportable key material. The temporary AES key is itself transformed through Optimal Asymmetric Encryption Padding (OAEP). Applying OAEP with the RSA encryption algorithm (RSA-OAEP) with a SHA-256 hash to wrap the temporary AES key with the provided RSA public wrapping key generates a wrapped temporary AES key. The wrapped temporary AES key and the wrapped exportable key material are concatenated to produce blob output that jointly represents them and which only the possessor of the RSA private wrapping key can decrypt.