Oracle Cloud Infrastructure Documentation

Creating Key References

Learn how to create key references for OCI External Key Management that refer to keys stored in an external key management system.

To create a key reference, you will need the following details:
  • The key ID (generated on CipherTrust Cloud Key Manager)
  • Key algorithm (AES)
  • Key length
    1. Open the navigation menu , select Identity & Security, and then select External Key Management.
    2. In the External key Management home page, select a vault from the list.
    3. In the Vault Details page, select Key Reference
    4. In the Create Key Reference page, provide the following details:
      • Name: Enter a name for the key reference
      • Create in Compartment: Select a compartment for the key reference.
      • Key Shape: Algorithm: Select a key encryption algorithm. By default, KMS supports only AES.
      • Key Shape: Length: The AES key can be of three different key lengths (16, 24, 32 bytes).
      • External Key ID: Enter the external key ID (GUID) generated by Thales CipherTrust Manager for the external key.
    5. Select Create.

      After you create a key reference, the OCI Key Management service stores the mapping of key references (and not the actual key material) with the GUIDs of keys. The actual key material is always retained in the external key management system.

  • Open a command prompt and run oci kms management key create to create a new key reference:

    oci kms management key create --external-key-reference

    Avoid entering confidential information.

    For a complete list of flags and variable options for Vault CLI commands, see Command Line Reference.

  • Use the CreateKey API with the Management Endpoint to create a key reference for the external key management system.

    Note

    The Management Endpoint is used for management operations including Create, Update, List, Get, and Delete. The Management Endpoint is also called the control plane URL or the KMSMANAGMENT endpoint.

    The Cryptographic Endpoint is used for cryptographic operations including Encrypt, Decrypt, Generate Data Encryption Key, Sign, and Verify. The Cryptographic Endpoint is also called the data plane URL or the KMSCRYPTO endpoint.

    You can find the management and cryptographic endpoints in a vault's details metadata. See Getting a Vault's Details for instructions.

    For regional endpoints for the Key Management, Secret Management, and Secret Retrieval APIs, see API Reference and Endpoints.

    For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.