Oracle Cloud Infrastructureドキュメント

外部KMSベンダーAPIリファレンス

OCI External Key ManagementのベンダーAPIに関する情報を検索します。

重要

このAPIリファレンス情報は、ハードウェア・セキュリティ・モジュール(HSM)ベンダー向けであり、OCI外部キー管理サービスの通常ユーザー向けにはありません。OCIキー管理用の顧客APIの詳細は、キーおよびシークレット管理を使用した開発を参照してください。

OCI外部キー管理リソース・モデル

この項では、外部キー管理リソース・モデルのOCIおよびサード・パーティ・リソースについて詳しく説明します。OCIでの外部キー管理の詳細は、キーおよびシークレット管理の概念および外部キー管理サービスを参照してください。

OCIのKey Management Service (KMS)は、ユーザーが外部ハードウェア・セキュリティ・モジュール(HSM)でキーを格納および管理するときに、次のリソースを使用します。

ボールト

OCIボールトは、Key Management Serviceがボールト・キーまたはキー参照を作成し、永続的に格納する顧客のOCI環境の論理エンティティです。外部キー管理を使用している顧客は、外部HSMにあるキーへの参照を格納するために「外部」タイプのボールトを作成します。ボールトは、キーを管理する際の顧客の最上位リソースです。ボールト内には、OCIキー参照およびキー参照バージョンがあります。

サードパーティ・キー

OCI External Key Managementを使用するお客様は、サードパーティのHSMインタフェースにキーを作成して格納します。OCI外部キー管理では、これらはOracleによって生成または格納されず、OCI顧客環境内のリソースではないため、サード・パーティ・キーとみなされます。ただし、OCI外部キー管理は、暗号化操作リクエストを処理するためにこれらのキーへの参照をマップするため、これらはリソース・モデルの一部です。

各サード・パーティ・キーには、外部システムによって作成されたキーID (GUID)があります。お客様は、キーIDとキーの詳細(キー・タイプとシェイプ)を使用して、OCI外部キー管理でキー参照を作成します。サードパーティ・キーには、1つ以上のキー・バージョンが含まれます。

サードパーティ・キーのキー参照

OCI Key Managementでは、お客様は、キーIDとキーの詳細(キー・タイプとシェイプ)を使用してサードパーティ・キーへの参照を作成します。OCI Key Managementには、実際のキー・マテリアルではなく、キー・マッピングの詳細とキー・メタデータが格納されます。お客様は、OCI環境でこれらの主要なリファレンスと対話します。

OCIでのキー参照の作成では、サード・パーティのHSMにキーは作成されません。同様に、OCIでキー参照を削除しても、HSMのサード・パーティ・キーは削除されません。OCI KMSは、暗号化操作リクエストの処理にキー参照を使用し、外部HSMで暗号化操作が発生します。キー参照には、現在および廃止されているキー参照バージョンに関する情報が格納されます。

サードパーティ・キーのキー参照バージョン

各サード・パーティ・キーには、HSMでキー・バージョンが自動的に割り当てられます。顧客がサード・パーティ・キーをローテーションすると、HSMによって新しいキー・バージョンが生成されます。お客様は、ローテーションされたキーのバージョンIDを取得し、それを使用してOCI Key Managementのキー参照をローテーションし、OCI Key Managementが正しいサードパーティ・キー・バージョンに暗号化操作リクエストを送信できるようにします。

ベンダーAPI操作

HSMベンダーは、外部KMS機能をサポートするために、OCI外部キー管理(外部KMS)ベンダーAPIを実装しています。このAPIは、次の操作を提供します。

操作 API名 説明
ボールト・メタデータの取得 GetVaultMetadata ボールトのメタデータを取得します。
データの暗号化 Encrypt 指定された外部キー・バージョンを使用してデータを暗号化するか、バージョンが指定されていない場合は、指定されたキーの最新バージョンを暗号化します。
データの復号化 Decrypt 指定された外部キー・バージョンを使用してデータを暗号化するか、バージョンが指定されていない場合は、指定されたキーの最新バージョンを暗号化します。
キー・メタデータの取得 GetKeyMetadata 指定したキーの最新バージョンに関連付けられたメタデータを取得します。
キー・バージョン・メタデータの取得 GetKeyVersionMetadata 指定したキー・バージョンに関連付けられたメタデータを取得します。
ランダム・バイトの生成 GenerateRandomBytes ランダム・バイトを生成します。

ベンダーAPIリファレンス

APIの詳細は、この項のベンダーAPIリファレンスを展開します。

ベンダーAPIリファレンス

  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": "<vendor_name>"
      }
  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'

エラー・コード・リファレンス

入力エラー ベンダーAPI 外部HSMベンダーからの予想応答
顧客が自分のキー(hyok)のボールトIDを間違ったホールドを提供 vaults/{vaultId}/metadata {"code":"404","message":"Error in getting OCI vault"}
外部キー・マネージャでhyokボールトが無効です vaults/{vaultId}/metadata {"code":"403","message":"xxxxxxxx"}
顧客が間違ったhyokキーを提供 keys/{keyId}/metadata {"code":"404","message":"Invalid key details provided"}
hyokキーは無効です keys/{keyId}/metadata {"code":"403","message":"xxxxxxxx"}
顧客が間違ったhyokキー・バージョンを提供 /keyVersions/{keyVersionId}/metadata {"code":"404","message":"Invalid Key details"}
顧客は外部キー・マネージャでhyokキーが無効になっているときに暗号化または復号化を試行します

keys/{keyId}/encrypt

keys/{keyId}/decrypt

{"code":"403","message":"OCI key is not in Active state to perform the operation."}
顧客は外部キー・マネージャでhyokキーが削除されたときに暗号化または復号化を試行します

keys/{keyId}/encrypt

keys/{keyId}/decrypt

{"code":"404","message":"Invalid key details provided"}
顧客が復号化コール中に改ざんされた暗号テキストまたは無効な暗号テキストを提供しようとしました keys/{keyId}/decrypt {"code":"400","message":"Bad Request: illegal base64 data at input byte 4"}
顧客は、別のhyokキーを使用して暗号化された暗号テキストを提供します keys/{keyId}/decrypt {"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"}
復号化コール中に無効な初期化ベクトル(IV)またはタグを提供する顧客タイヤ keys/{keyId}/decrypt {"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"}
顧客がペイロードに無効な追加の認証済データ(AAD)を提供しようとしました /keys/{keyId}/generateRandomBytes {"code":"400","message":"Bad Request: illegal base64 data at input byte 8"}
顧客は外部キー・マネージャでhyokキーが無効になっているときにランダム・バイトを生成しようとします /keys/{keyId}/generateRandomBytes {"code":"403","message":"Key is in disabled state."}