ocikms KMS

The OCI KMS configures Boundary to use OCI KMS for key management.

The OCI KMS is activated by the presence of a kms "ocikms" block in Boundary’s configuration file.

ocikms Example

This example shows configuring the OCI KMS through the Boundary configuration file by providing all the required values:

  1. kms "ocikms" {
  2.   purpose              = "root"
  3.   key_id               = "ocid1.key.oc1.iad.afnxza26aag4s.abzwkljsbapzb2nrha5nt3s7s7p42ctcrcj72vn3kq5qx"
  4.   crypto_endpoint      = "https://afnxza26aag4s-crypto.kms.us-ashburn-1.oraclecloud.com"
  5.   management_endpoint  = "https://afnxza26aag4s-management.kms.us-ashburn-1.oraclecloud.com"
  6.   auth_type_api_key    = "true"
  7. }
  1. kms "ocikms" {  purpose              = "root"  key_id               = "ocid1.key.oc1.iad.afnxza26aag4s.abzwkljsbapzb2nrha5nt3s7s7p42ctcrcj72vn3kq5qx"  crypto_endpoint      = "https://afnxza26aag4s-crypto.kms.us-ashburn-1.oraclecloud.com"  management_endpoint  = "https://afnxza26aag4s-management.kms.us-ashburn-1.oraclecloud.com"  auth_type_api_key    = "true"}

ocikms Parameters

These parameters apply to the kms stanza in the Boundary configuration file:

  • purpose - Purpose of this KMS, acceptable values are: worker-auth, root, recovery, or config.
  • key_id (string: <required>): The OCI KMS key ID to use.
  • crypto_endpoint (string: <required>): The OCI KMS cryptographic endpoint (or data plane endpoint) to be used to make OCI KMS encryption/decryption requests.
  • management_endpoint (string: <required>): The OCI KMS management endpoint (or control plane endpoint) to be used to make OCI KMS key management requests.
  • auth_type_api_key (boolean: false): Specifies if using API key to authenticate to OCI KMS service. If it is false, Boundary authenticates using the instance principal from the compute instance. See Authentication section for details. Default is false.

Authentication

Authentication-related values must be provided, either as environment variables or as configuration parameters.

If you want to use Instance Principal, add section configuration below and add further configuration settings as detailed in the configuration docs.

  1. kms "ocikms" {
  2.   purpose             = "root"
  3.   crypto_endpoint     = "<kms-crypto-endpoint>"
  4.   management_endpoint = "<kms-management-endpoint>"
  5.   key_id              = "<kms-key-id>"
  6. }
  1. kms "ocikms" {  purpose             = "root"  crypto_endpoint     = "<kms-crypto-endpoint>"  management_endpoint = "<kms-management-endpoint>"  key_id              = "<kms-key-id>"}

If you want to use User Principal, the plugin will take the API key you defined for OCI SDK, often under ~/.oci/config.

  1. kms "ocikms" {
  2.   purpose             = "root"
  3.   auth_type_api_key   = true
  4.   crypto_endpoint     = "<kms-crypto-endpoint>"
  5.   management_endpoint = "<kms-management-endpoint>"
  6.   key_id              = "<kms-key-id>"
  7. }
  1. kms "ocikms" {  purpose             = "root"  auth_type_api_key   = true  crypto_endpoint     = "<kms-crypto-endpoint>"  management_endpoint = "<kms-management-endpoint>"  key_id              = "<kms-key-id>"}

To grant permission for a compute instance to use OCI KMS service, write policies for KMS access.

  • Create a Dynamic Group in your OCI tenancy.
  • Create a policy that allows the Dynamic Group to use or manage keys from OCI KMS. There are multiple ways to write these policies. The OCI Identity Policy can be used as a reference or starting point.

The most common policy allows a dynamic group of tenant A to use KMS’s keys in tenant B:

  1. define tenancy tenantB as <tenantB-ocid>
  3. endorse dynamic-group <dynamic-group-name> to use keys in tenancy tenantB
  1. define tenancy tenantB as <tenantB-ocid>
  2. endorse dynamic-group <dynamic-group-name> to use keys in tenancy tenantB
  1. define tenancy tenantA as <tenantA-ocid>
  3. define dynamic-group <dynamic-group-name> as <dynamic-group-ocid>
  5. admit dynamic-group <dynamic-group-name> of tenancy tenantA to use keys in compartment <key-compartment>
  1. define tenancy tenantA as <tenantA-ocid>
  2. define dynamic-group <dynamic-group-name> as <dynamic-group-ocid>
  3. admit dynamic-group <dynamic-group-name> of tenancy tenantA to use keys in compartment <key-compartment>

ocikms Rotate OCI KMS Key

For the OCI KMS key rotation feature, OCI KMS will create a new version of key internally. This process is independent from Boundary, and boundary still uses the same key_id without any interruption.