Using Keys

This topic describes what you can do with keys in terms of cryptographic operations and signing operations. For information about managing keys, see Managing Keys. For information about exporting keys, see Exporting Keys and Key Versions. 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
  • Signing data
  • Verifying signed data

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

Required IAM Policy

Caution

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. Keys associated with databases will not work unless you authorize a dynamic group that includes all nodes in the DB system to manage keys in the tenancy. For more information, see Required IAM Policy in Creating and Managing Exadata Databases.

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have 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 Console

To view the public key of an asymmetric key
  1. Open the navigation menu. Under the Governance and Administration group, go to Security and click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment where the key exists.
  3. From the list of vaults in the compartment, click the name of the vault that contains the key.
  4. Under Master Encryption Keys, click the name of the key.
  5. Under Resources, click Versions.
  6. In the list of key versions, find the key for which you want to view the public key, click the Actions menu, and then click View Public Key.
  7. Do one of the following:
    • To copy the contents of the public key, click Copy. The contents of the public key are copied to your clipboard.
    • To download the public key, click Download. The file is automatically downloaded to your local computer.
  8. When you are finished, click Close.

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
Note

You can use either AES symmetric keys or RSA asymmetric keys to encrypt or decrypt data. ECDSA keys do not support the cryptography required to encrypt or decrypt data. If you want to encrypt data by using an RSA asymmetric key, then you must also provide the --key-version-id of the key. To decrypt the data, you need to provide the same --key-version-id. The need to track key versions exists because, unlike symmetric keys, an asymmetric key's ciphertext does not contain the information that the service needs for decryption purposes.

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 extra layer of protection. Associated data must be properly formatted JSON.

If using an RSA asymmetric key, provide the public key.


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
Note

You can use AES symmetric keys or RSA asymmetric keys to encrypt or decrypt data. ECDSA keys do not support the cryptography required to encrypt or decrypt data.

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 you want to decrypt data previously encrypted by an RSA asymmetric key, then you must also provide the --key-version-id of the key that encrypted the data. The need to track key versions exists because, unlike symmetric keys, an asymmetric key's ciphertext does not contain the information that the service needs for decryption purposes. 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
Note

You can only use AES symmetric keys to generate data encryption keys. You cannot generate data encryption keys from RSA and ECDSA asymmetric keys.

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 view the public key of an asymmetric key

Open a command prompt and run oci kms management key-version get to view the public key of an asymmetric key:

oci kms management key-version get --key-id <key_OCID> --key-version-id <keyversion_OCID> --endpoint <control_plane_url>

For example:


oci kms management key-version get --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --key-version-id ocid1.keyversion.region1.sea.example5aacuu.aumjmafauxaaa.abuwcljt2lolvy722lpaefa53mbl2fyrtcvb3desouxwygdhqxgryexample --endpoint https://exampleaaacu2-management.kms.us-ashburn-1.oraclecloud.com
To sign data by using your Vault master encryption key
Note

You can only use RSA or ECDSA asymmetric keys to digitally sign data and verify signed data. AES keys do not support the asymmetric cryptography required to sign data or to verify signed data.

Open a command prompt and run oci kms crypto signed-data sign to sign a message:

oci kms crypto signed-data sign --key-id <key_OCID> --key-version-id <keyversion_OCID> --message <base64_string> --signing-algorithm <key_algorithm> --endpoint <data_plane_url>

For example:


oci kms crypto signed-data sign --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --key-version-id ocid1.keyversion.region1.sea.example5aacuu.aumjmafauxaaa.abuwcljt2lolvy722lpaefa53mbl2fyrtcvb3desouxwygdhqxgryexample --message VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4= --signing-algorithm SHA_224_RSA_PKCS_PSS --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com
To verify signed data by using your Vault master encryption key
Note

You can only use RSA or ECDSA asymmetric keys to digitally sign data and verify signed data. AES keys do not support the asymmetric cryptography required to sign data or to verify signed data.

Open a command prompt and run oci kms crypto verified-data verify to verify the integrity of signed data:

oci kms crypto verified-data verify --key-id <key_OCID> --key-version-id <keyversion_OCID> --message <base64_string> --signature <base64_string> --signing-algorithm <key_algorithm> --endpoint <data_plane_url>

For example:


oci kms crypto verified-data verify --key-id ocid1.key.region1.sea.exampleaaacu2.examplesmtpsuqmoy4m5cvblugmizcoeu2nfc6b3zfaux2lmqz245gezevsq --key-version-id ocid1.keyversion.region1.sea.example5aacuu.aumjmafauxaaa.abuwcljt2lolvy722lpaefa53mbl2fyrtcvb3desouxwygdhqxgryexample --message VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wcyBvdmVyIHRoZSBsYXp5IGRvZy4= --signature VGhpcyBpcyBhIHNpZ25hdHVyZS4= --signing-algorithm SHA_224_RSA_PKCS_PSS --endpoint https://exampleaaacu3-crypto.kms.us-ashburn-1.oraclecloud.com