Oracle Cloud Infrastructure Documentation

External KMS Vendor API Reference

Find information about the vendor API for OCI External Key Management.

Important

This API reference information is for hardware security module (HSM) vendors, and is not for regular users of the OCI External Key Management service. See Developing with Key and Secret Management for information on the customer APIs for OCI Key Management.

The OCI External Key Management Resource Model

This section details the OCI and third-party resources in the External Key Management resource model. For more details on External Key Management in OCI, see Key and Secret Management Concepts and External Key Management Service.

OCI's Key Management Service (KMS) uses the following resources when users store and manage keys in an external hardware security module (HSM).

Vaults

OCI vaults are logical entities in the customer's OCI environment where the Key Management Service creates and durably stores vault keys or key references. Customers using External Key Management create vaults of the type "external" to store references to keys located in an external HSM. The vault is the top-level resource for the customer when managing keys. Inside the vault are OCI Key References and Key Reference Versions.

Third-party Keys

Customers using OCI External Key Management create and store keys in an third-party HSM interface. OCI External Key Management considers these to be "third-party keys," because they're not generated or stored by Oracle, and therefore aren't resources within the OCI customer environment. But they're a part of the resource model because OCI External Key Management maps references to these keys to handle cryptographic operation requests.

Each third-party key has a key ID (GUID) created by the external system. Customers use the key ID and key details (key type and shape) to create a key reference in OCI External Key Management. Third-party keys contain one or more key versions.

Key References for Third-party Keys

In OCI Key Management, customers create references to third-party keys using the key ID and key details (key type and shape). OCI Key Management stores the key mapping details and key metadata, and not the actual key material. Customers interact with these key references in their OCI environment.

Creation of a key reference in OCI doesn't create a key in the third-party HSM. Similarly, the deletion of a key reference in OCI doesn't delete the third-party key in the HSM. OCI KMS uses the key reference for handling cryptographic operation requests, and cryptographic operations happen in the external HSM. Key references store information about current and retired key reference versions.

Key Reference Versions for Third-party Keys

Each third-party key is automatically assigned a key version in the HSM. When a customer rotates an third-party key, the HSM generates a new key version. Customers take the version ID of the rotated key and use it to rotate the key reference in OCI Key Management so that OCI Key Management can send cryptographic operation requests to the correct third-party key version.

Vendor API Operations

HSM vendors implement the OCI External Key Management (External KMS) vendor API to support External KMS features. The API offers the following operations:

Operation API name Description
Get vault metadata GetVaultMetadata Gets the metadata of a vault.
Encrypt data Encrypt Encrypts data using a specified external key version, or if no version is specified, the latest version of a specified key.
Decrypt data Decrypt Encrypts data using a specified external key version, or if no version is specified, the latest version of a specified key.
Get key metadata GetKeyMetadata Gets the metadata associated with the latest version of a specified key.
Get key version metadata GetKeyVersionMetadata Gets the metadata associated with a specified key version.
Generate random byes GenerateRandomBytes Generates random bytes.

Vendor API Reference

Expand the Vendor API reference in this section for complete API details.

Vendor API Reference

  description: |
    This API spec details the contract that the external key manager vendors need to implement 
    to support External Key Manager feature in OCI KMS
    BasePath includes dynamic prefixes that should be added by vendor implementation.
  license:
    name: Oracle Corporation
  title: External Key Manager Vendor API
  version: 'v1'
  basePath: "/<path-prefix>/ekm/v1"

schemes:
  - https
consumes:
  - application/json
produces:
  - application/json

#==========[ Parameters ]====================================================================================================
parameters:
  VaultIdPathParam:
    name: vaultId
    in: path
    description: Vault ID on the External Key Manager system. A vault is a consturct to group all keys together
    type: string
    required: true
  KeyIdPathParam:
    name: keyId
    in: path
    description: Key ID on the External Key Manager system
    type: string
    required: true
  KeyVersionIdPathParam:
    name: keyVersionId
    required: true
    in: path
    type: string
    description: Key Version ID on the External Key Manager system
    minLength: 1
    maxLength: 255
  RequestIdHeader:
    name: opc-request-id
    required: false
    in: header
    type: string
    description: |
      Unique identifier for the request. If provided, the returned request ID
      will include this value. Otherwise, a random request ID will be
      generated by the service.
  AuthorizationHeader:
      name: authorization
      in: header
      description: |
          A HTTP header carrying the OAuth token with format:
          `Bearer {token}`
      required: true
      type: string

#==========[ Definitions ]====================================================================================================
definitions:
  VaultMetadata:
    type: object
    description: The response to the vault metadata request.
    required:
      - state
      - vendor
    properties:
      state:
        type: string
        description: The state of the vault on external key manager
        enum:
          - ACTIVE
          - DISABLED
      vendor:
        type: string
        description: The vendor of the external key manager
        minLength: 1
        maxLength: 255
    example: |
      {
      "state": "ACTIVE",
      "vendor": "Thales CTM"
      }
  KeyMetadata:
    description: The response to a request to get metadata of a key
    type: object
    required:
      - state
    properties:
      state:
        description: The state of the key
        type: string
        enum:
          - ACTIVE
          - DISABLED
      keyId:
        type: string
        description: The id of the key
        minLength: 1
        maxLength: 255
      currentKeyVersionId:
        type: string
        description: The id of the current key version for the key.
        minLength: 1
        maxLength: 255
      keyShape:
        $ref: '#/definitions/KeyShape'
      keyOps:
        type: array
        description: The operations allowed to be performed using the key
        items:
          type: string
          enum:
            - ENCRYPT
            - DECRYPT
    example: |
      {
        "keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
        "currentKeyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
        "keyShape":
          {
            "algorithm": AES
            "length": 256
          }
        "state": "ACTIVE",
        "keyOps": [
          "ENCRYPT",
          "DECRYPT"
        ]
      }
  KeyVersionMetadata:
    description: The response to a request to get metadata of a key version
    type: object
    required:
      - state
    properties:
      state:
        description: The state of the key version
        type: string
        enum:
          - ACTIVE
          - DISABLED
      keyId:
        type: string
        description: The id of the master key for the key version
        minLength: 1
        maxLength: 255
      keyVersionId:
        type: string
        description: The id of the key version
        minLength: 1
        maxLength: 255
      keyVersionOps:
        type: array
        description: The operations allowed to be performed using the key version
        items:
          type: string
          enum:
            - ENCRYPT
            - DECRYPT
    example: |
      {
        "keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
        "keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf"
        "state": "ACTIVE",
        "keyVersionOps": [
          "ENCRYPT",
          "DECRYPT"
        ]
      }
  DecryptDetails:
    type: object
    description: Contains input data and associated metadata for a decyrpt request
    required:
      - ciphertext
      - mode
      - keyVersionId
    properties:
      ciphertext:
        type: string
        description: Ciphertext that appears as a base64 encoded string in the JSON blob.
      aad:
        type: string
        description: AAD that appears as a base64 encoded string in the JSON blob.
          The length of the string representation of the associated data must be fewer than 4096
          characters.
      iv:
        type: string
        description: IV that appears as a base64 encoded string in the JSON blob.
      mode:
        type: string
        default: AES_GCM
        enum:
          - AES_GCM
          - AES_CBC
        description: |
          The encryption algorithm to use to decrypt data
          `AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
          that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
      pad:
        type: string
        description: Pad Scheme used in encryption
        default: PKCS7
        enum:
          - PKCS7
          - NONE
      tag:
        type: string
        description: Tag that appears as a base64 encoded string in the JSON blob.
      keyVersionId:
        type: string
        description: The id of the key version used to decrypt the ciphertext.
        minLength: 1
        maxLength: 255
    example: |
      {
        "ciphertext": "RpeAO2op/+bQD3FioKbuVi54yysO79e0SjY=",
        "iv": "EYMbIM/MOv5q7Km1",
        "mode": "AES_GCM",
        "tag": "dk958fIs5D+kRE8rKKqtgA==",
        "aad": "fIs5D+kRE8r",
        "keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf"
      }
  DecryptedData:
    description: The response to a request to decrypt the encrypted data.
    type: object
    required:
      - plaintext
      - mode
      - keyId
      - keyVersionId
    properties:
      plaintext:
        type: string
        description: The decrypted data, expressed as a base64-encoded value.
        minLength: 1
        maxLength: 4096
      keyId:
        type: string
        description: The id of the key used to decrypt the ciphertext.
        minLength: 1
        maxLength: 255
      keyVersionId:
        type: string
        description: The id of the key version used to decrypt the ciphertext.
        minLength: 1
        maxLength: 255
      aad:
        type: string
        description: AAD that appears as a base64 encoded string in the JSON blob.
          The length of the string representation of the associated data must be fewer than 4096
          characters.
      pad:
        type: string
        description: Pad Scheme used in encryption
        default: PKCS7
        enum:
          - PKCS7
          - NONE
      iv:
        type: string
        description: IV that appears as a base64 encoded string in the JSON blob.
      mode:
        type: string
        default: AES_GCM
        enum:
          - AES_GCM
          - AES_CBC
        description: |
          The encryption algorithm to use to decrypt data
          `AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
          that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
      tag:
        type: string
        description: Tag that appears as a base64 encoded string in the JSON blob.
    example: |
      {
        "plaintext": "aGVsbG8sIHdvcmxk",
        "keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
        "keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
        "iv": "EYMbIM/MOv5q7Km1",
        "mode": "AES_GCM",
        "tag": "dk958fIs5D+kRE8rKKqtgA==",
        "aad": "fIs5D+kRE8r"    
      }
  EncryptDetails:
    type: object
    description: Contains input data and associated metadata for encrypt request
    required:
      - plaintext
      - mode
    properties:
      plaintext:
        type: string
        description: A byte array data to be encrypted. JSON encodes byte arrays to base64 strings. Therefore, the string in the JSON object should be a valid base64 string.
      aad:
        type: string
        description: AAD that appears as a base64 encoded string in the JSON blob.
          The length of the string representation of the associated data must be fewer than 4096
          characters. (Only applicable when mode is AES_GCM)
      iv:
        type: string
        description: IV that appears as a base64 encoded string in the JSON blob.
      mode:
        type: string
        default: AES_GCM
        enum:
          - AES_GCM
          - AES_CBC
        description: |
          The encryption algorithm to use to encrypt data
          `AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
          that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
      pad:
        type: string
        description: Pad Scheme used in encryption
        default: PKCS7
        enum:
          - PKCS7
          - NONE
      tagLen:
        type: integer
        description: Tag length in bytes expressed as integer (Only applicable when mode is AES_GCM)
        minLength: 12
        maxLength: 16
        default: 16
      keyVersionId:
        type: string
        description: Key version ID
    example: |
      {
        "plaintext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
        "iv": "EYMbIM/MOv5q7Km1",
        "mode": "AES_GCM",
        "aad": "fIs5D+kRE8r",
        "tagLen" : 16,
        "keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
        "pad" : "PKCS7"
      }
  EncryptedData:
    description: The response to a request to encrypt the plaintext data.
    type: object
    required:
      - ciphertext
      - keyId
      - keyVersionId
      - mode
    properties:
      ciphertext:
        type: string
        description: The encrypted data.
        minLength: 1
        maxLength: 65536
      keyId:
        type: string
        description: The id of the key used to encrypt the plaintext.
        minLength: 1
        maxLength: 255
      keyVersionId:
        type: string
        description: The id of the key version used to encrypt the plaintext.
        minLength: 1
        maxLength: 255
      aad:
        type: string
        description: AAD that appears as a base64 encoded string in the JSON blob.
          The length of the string representation of the associated data must be fewer than 4096
          characters.
      iv:
        type: string
        description:  IV that appears as a base64 encoded string in the JSON blob.
      tag:
        type: string
        description: Tag
      pad:
        type: string
        description: Pad Scheme used in encryption
        default: PKCS7
        enum:
          - PKCS7
          - NONE
      mode:
        type: string
        default: AES_GCM
        enum:
          - AES_GCM
          - AES_CBC
        description: |
          The encryption algorithm to use to encrypt data
          `AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
          that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
    example: |
      {
        "ciphertext": "RpeAO2op/+bQD3FioKbuVi54yysO79e0SjY=",
        "keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
        "keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
        "iv": "EYMbIM/MOv5q7Km1",
        "mode": "AES_GCM",
        "tag": "dk958fIs5D+kRE8rKKqtgA==",
        "pad": "PKCS7",
        "aad": "fIs5D+kRE8r"
      }
  GenerateRandomBytesDetails:
    description: The details used to generate random bytes.
    type: object
    required:
      - length
    properties:
      length:
        type: integer
        description: Length of the bytes to be generated
        enum:
          - 16
          - 24
          - 32
    example: |
      {
        "length": 16
      }
  RandomBytes:
    description: The reponse to the reqeuest to generate random bytes
    type: object
    required:
      - randomBytes
      - length
    properties:
      randomBytes:
        type: string
        description: The base64 encoded random bytes
        minLength: 1
        maxLength: 65536
      length:
        type: integer
        description: Length of the bytes to be generated
        enum:
          - 16
          - 24
          - 32
    example: |
      {
        "randomBytes": "AAwRhavVBkAAAJNF0nE7tBz/CQDanO33toIAWpw/lCn9GuadiyNNZ2QCmeUksvor8HD00o0TiUHzj6IsDJ5z1j/AEXZrhBtEcz4=",
        "length": 32
      }
  KeyShape:
    type: object
    description: The cryptographic properties of a key.
    required:
      - algorithm
      - length
    properties:
      algorithm:
        type: string
        description: The algorithm used by a key/key versions to encrypt or decrypt.
        enum:
          - AES
      length:
        type: integer
        description: The length of the key in bytes, expressed as an integer.
        enum:
          - 14
          - 24
          - 32
    example: |
      {
        "algorithm": "AES",
        "length": 16
      }
  Error:
    description: |
      The error object.
    required:
      - code
      - message
    properties:
      code:
        type: string
        description: |
          The unique code of an error.
      message:
        type: string
        description: |
          The description of an error.      


#==========[ Paths ]====================================================================================================
paths:
  /vaults/{vaultId}/metadata:
    get:
      operationId: GetVaultMetadata
      summary: Get Vault metadata
      description: Get metadata of the Vault
      tags:
        - ekmVaultMetadata
      parameters:
        - $ref: '#/parameters/VaultIdPathParam'
        - $ref: '#/parameters/RequestIdHeader'
        - $ref: '#/parameters/AuthorizationHeader'
      responses:
        200:
          description: OK
          headers:
            opc-request-id:
              description: |
                Unique Oracle-assigned identifier for the request.
              type: string
          schema:
            $ref: '#/definitions/VaultMetadata'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        403:
          $ref: '#/responses/403'
        404:
          $ref: '#/responses/404'
        409:
          $ref: '#/responses/409'
        412:
          $ref: '#/responses/412'
        422:
          $ref: '#/responses/422'
        429:
          $ref: '#/responses/429'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/DefaultError'
      x-example: |
      GET <path-prefix>/ekm/v1/vaults/<vaultId>>/metadata
        Host: <ip-address>:<port>
        <authorization and other headers>

  /vaults/{vaultId}/keys/{keyId}/encrypt:
    post:
      operationId: Encrypt
      summary: Encrypt plaintext
      description: To encrypt the data using a specific version of the external key, specify the version ID of the key as an input parameter. If not specified, the latest version of the key with id keyId under vault with id vaultId is used to encrypt the data.
      tags:
        - ekmCrypto
      parameters:
        - $ref: '#/parameters/VaultIdPathParam'
        - $ref: '#/parameters/KeyIdPathParam'
        - $ref: '#/parameters/RequestIdHeader'
        - $ref: '#/parameters/AuthorizationHeader'
        - description: The input containing plaintext to encrypt and metadata
          in: body
          name: EncryptDetails
          required: true
          schema:
            $ref: '#/definitions/EncryptDetails'
      responses:
        '200':
          description: The encrypted data, presented as ciphertext.
          headers:
            opc-request-id:
              description: |
                Unique Oracle-assigned identifier for the request.
              type: string
          schema:
            $ref: '#/definitions/EncryptedData'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        403:
          $ref: '#/responses/403'
        404:
          $ref: '#/responses/404'
        409:
          $ref: '#/responses/409'
        412:
          $ref: '#/responses/412'
        422:
          $ref: '#/responses/422'
        429:
          $ref: '#/responses/429'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/DefaultError'
      x-example: |
      POST <path-prefix>/ekm/v1/vaults/<vaultId>/keys/<keyId>/encrypt
        Host: <ip-address>:<port>
        <authorization and other headers>
          {
            "plaintext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
            "iv": "EYMbIM/MOv5q7Km1",
            "mode": "AES_GCM",
            "aad": "fIs5D+kRE8r",
            "tagLen" : 16,
            "keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
            "pad" : "PKCS7"
          }
  /vaults/{vaultId}/keys/{keyId}/decrypt:
    post:
      operationId: Decrypt
      summary: Decrypt Ciphertext
      description: To decrypt the data using a specific version of the external key included in the ciphertext input.
      tags:
        - ekmCrypto
      parameters:
        - $ref: '#/parameters/VaultIdPathParam'
        - $ref: '#/parameters/KeyIdPathParam'
        - $ref: '#/parameters/RequestIdHeader'
        - $ref: '#/parameters/AuthorizationHeader'
        - description: The input containing ciphertext to decrypt and metadata
          in: body
          name: DecryptDetails
          required: true
          schema:
            $ref: '#/definitions/DecryptDetails'
      responses:
        200:
          description: |
            The decrypted data in plaintext.
          headers:
            opc-request-id:
              description: |
                Unique Oracle-assigned identifier for the request.
              type: string
          schema:
            $ref: '#/definitions/DecryptedData'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        403:
          $ref: '#/responses/403'
        404:
          $ref: '#/responses/404'
        409:
          $ref: '#/responses/409'
        412:
          $ref: '#/responses/412'
        422:
          $ref: '#/responses/422'
        429:
          $ref: '#/responses/429'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/DefaultError'
      x-example: |
      POST <path-prefix>/ekm/v1/vaults/<vaultId>/keys/<keyId>/decrypt
        Host: <ip-address>:<port>
        <authorization and other headers>
          {
            "ciphertext": "RpeAO2op/+bQD3FioKbuVi54yysO79e0SjY=",
            "iv": "EYMbIM/MOv5q7Km1",
            "mode": "AES_GCM",
            "tag": "dk958fIs5D+kRE8rKKqtgA==",
            "aad": "fIs5D+kRE8r",
            "keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf"
          }
  /vaults/{vaultId}/keys/{keyId}/metadata:
    get:
      operationId: GetKeyMetadata
      summary: Key Metadata
      description: To fetch the metadata associated with the latest version of the key
      tags:
        - ekmKeyMetaData
      parameters:
        - $ref: '#/parameters/VaultIdPathParam'
        - $ref: '#/parameters/KeyIdPathParam'
        - $ref: '#/parameters/RequestIdHeader'
        - $ref: '#/parameters/AuthorizationHeader'
      responses:
        200:
          description: OK
          headers:
            opc-request-id:
              description: |
                Unique Oracle-assigned identifier for the request.
              type: string
          schema:
            $ref: '#/definitions/KeyMetadata'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        403:
          $ref: '#/responses/403'
        404:
          $ref: '#/responses/404'
        409:
          $ref: '#/responses/409'
        412:
          $ref: '#/responses/412'
        422:
          $ref: '#/responses/422'
        429:
          $ref: '#/responses/429'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/DefaultError'
      x-example: |
      GET <path-prefix>/ekm/v1/vaults/<vaultId>/keys/<keyId>/metadata
        Host: <ip-address>:<port>
        <authorization and other headers>

  /vaults/{vaultId}/keys/{keyId}/keyVersions/{keyVersionId}/metadata:
    get:
      operationId: GetKeyVersionMetadata
      summary: KeyVersion Metadata
      description: To fetch the metadata associated with a specific version of the key.
      tags:
        - ekmKeyVersionMetaData
      parameters:
        - $ref: '#/parameters/VaultIdPathParam'
        - $ref: '#/parameters/KeyIdPathParam'
        - $ref: '#/parameters/RequestIdHeader'
        - $ref: '#/parameters/KeyVersionIdPathParam'
        - $ref: '#/parameters/AuthorizationHeader'
      responses:
        200:
          description: OK
          headers:
            opc-request-id:
              description: |
                Unique Oracle-assigned identifier for the request.
              type: string
          schema:
            $ref: '#/definitions/KeyVersionMetadata'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        403:
          $ref: '#/responses/403'
        404:
          $ref: '#/responses/404'
        409:
          $ref: '#/responses/409'
        412:
          $ref: '#/responses/412'
        422:
          $ref: '#/responses/422'
        429:
          $ref: '#/responses/429'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/DefaultError'
    x-example: |
    GET <path-prefix>/ekm/v1/vaults/<vaultId>>/keys/<keyVersionId>/metadata
        Host: <ip-address>:<port>
        <authorization and other headers>

  /vaults/{vaultId}/generateRandomBytes:
    post:
      operationId: GenerateRandomBytes
      summary: Generate Random Bytes
      description: Generates random bytes.
      tags:
        - ekmCrypto
      parameters:
        - $ref: '#/parameters/VaultIdPathParam'
        - $ref: '#/parameters/RequestIdHeader'
        - $ref: '#/parameters/AuthorizationHeader'
        - description: The input contains metadata to create random bytes from
          in: body
          name: GenerateRandomBytesDetails
          required: true
          schema:
            $ref: '#/definitions/GenerateRandomBytesDetails'
      responses:
        201:
          description: Created
          headers:
            opc-request-id:
              description: |
                Unique Oracle-assigned identifier for the request. If you need to contact Oracle about
                a particular request, please provide the request ID.
              type: string
          schema:
            $ref: '#/definitions/RandomBytes'
        400:
          $ref: '#/responses/400'
        401:
          $ref: '#/responses/401'
        403:
          $ref: '#/responses/403'
        404:
          $ref: '#/responses/404'
        409:
          $ref: '#/responses/409'
        412:
          $ref: '#/responses/412'
        422:
          $ref: '#/responses/422'
        429:
          $ref: '#/responses/429'
        500:
          $ref: '#/responses/500'
        default:
          $ref: '#/responses/DefaultError'
      x-example: |
      POST <path-prefix>/ekm/v1/vaults/<vaultId>/generateRandomBytes
        Host: <ip-address>:<port>
        <authorization and other headers>
          {
            "length": 16
          }
#==========[ Responses ]================================================================================================
responses:
  400:
    description: Bad Request
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  401:
    description: Unauthorized
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  403:
    description: Forbidden
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  404:
    description: Not Found
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  409:
    description: Conflict
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  412:
    description: Precondition Failed
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  422:
    description: Unprocessable Entity
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  429:
    description: Too many requests. User-rate limit exceeded.
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
      retry-after:
        description: |
          If the request gets throttled, time in seconds to retry the request.
        type: integer
    schema:
      $ref: '#/definitions/Error'
  500:
    description: Internal Server Error
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'
  DefaultError:
    description: Unknown Error
    headers:
      opc-request-id:
        description: |
          Unique Oracle-assigned identifier for the request.
        type: string
    schema:
      $ref: '#/definitions/Error'

Error Code Reference

Input Error Vendor API Expected response from external HSM vendor
customer provides wrong hold your own key (hyok) vault ID vaults/{vaultId}/metadata {"code":"404","message":"Error in getting OCI vault"}
hyok vault is disabled in external key manager vaults/{vaultId}/metadata {"code":"403","message":"xxxxxxxx"}
customer provides wrong hyok key keys/{keyId}/metadata {"code":"404","message":"Invalid key details provided"}
hyok key is disabled keys/{keyId}/metadata {"code":"403","message":"xxxxxxxx"}
customer provides wrong hyok key version /keyVersions/{keyVersionId}/metadata {"code":"404","message":"Invalid Key details"}
customer tries to encrypt or decrypt when hyok key is disabled in external key manager

keys/{keyId}/encrypt

keys/{keyId}/decrypt

 {"code":"403","message":"OCI key is not in Active state to perform the operation."}
customer tries to encrypt or decrypt when hyok key is deleted in external key manager

keys/{keyId}/encrypt

keys/{keyId}/decrypt

 {"code":"404","message":"Invalid key details provided"}
customer tries to provide tampered or invalid cipher text during decrypt call keys/{keyId}/decrypt {"code":"400","message":"Bad Request: illegal base64 data at input byte 4"}
customer provides cipher text that was encrypted using a different hyok key keys/{keyId}/decrypt {"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"}
customer tires to provide invalid initialization vector (IV) or tag during decrypt call keys/{keyId}/decrypt {"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"}
customer tries to provide invalid additional authenticated data (AAD) in the payload /keys/{keyId}/generateRandomBytes {"code":"400","message":"Bad Request: illegal base64 data at input byte 8"}
customer tries to generate random bytes when hyok key is disabled in external key manager /keys/{keyId}/generateRandomBytes {"code":"403","message":"Key is in disabled state."}