Documentation Oracle Cloud Infrastructure

Référence d'API de fournisseur KMS externe

Recherchez des informations sur l'API du fournisseur pour OCI External Key Management.

Important

Ces informations de référence d'API sont destinées aux fournisseurs de modules de sécurité matériels (HSM) et ne sont pas destinées aux utilisateurs standard du service OCI External Key Management. Pour plus d'informations sur les API client pour OCI Key Management, reportez-vous à Développement avec la gestion des clés et des clés secrètes.

Modèle de ressource OCI External Key Management

Cette section détaille OCI et les ressources tierces dans le modèle de ressource External Key Management. Pour plus d'informations sur la gestion des clés externes dans OCI, reportez-vous à Concepts de gestion des clés et des clés secrètes et à Service de gestion des clés externes.

Le service de gestion des clés (KMS) d'OCI utilise les ressources suivantes lorsque les utilisateurs stockent et gèrent des clés dans un module de sécurité HSM externe.

Coffres

Les coffres OCI sont des entités logiques dans l'environnement OCI du client dans lequel Key Management Service crée et stocke de manière durable des clés de coffre ou des références de clé. Les clients qui utilisent la gestion des clés externes créent des coffres de type "externe" pour stocker les références aux clés situées dans un HSM externe. Le coffre est la ressource de niveau supérieur du client lors de la gestion des clés. Dans le coffre se trouvent les références de clé OCI et les versions de référence de clé.

Clés tierces

Les clients qui utilisent OCI External Key Management créent et stockent des clés dans une interface HSM tierce. OCI External Key Management considère qu'il s'agit de "clés tierces", car elles ne sont pas générées ou stockées par Oracle et ne sont donc pas des ressources dans l'environnement client OCI. Mais ils font partie du modèle de ressource car OCI External Key Management met en correspondance les références à ces clés pour gérer les demandes d'opération cryptographique.

Chaque clé tierce possède un code clé (GUID) créé par le système externe. Les clients utilisent l'ID et les détails de la clé (type et forme de clé) pour créer une référence de clé dans OCI External Key Management. Les clés tierces contiennent une ou plusieurs versions de clé.

Références clés pour les clés tierces

Dans OCI Key Management, les clients créent des références à des clés tierces à l'aide de l'ID de clé et des détails de clé (type et forme de clé). OCI Key Management stocke les détails de mise en correspondance des clés et les métadonnées des clés, et non le matériel de clé réel. Les clients interagissent avec ces références clés dans leur environnement OCI.

La création d'une référence de clé dans OCI ne crée pas de clé dans le module HSM tiers. De même, la suppression d'une référence de clé dans OCI ne supprime pas la clé tierce dans le module HSM. OCI KMS utilise la référence de clé pour gérer les demandes d'opération cryptographique et les opérations cryptographiques se produisent dans le HSM externe. Les références de clé stockent des informations sur les versions de référence de clé en cours et supprimées.

Versions de référence de clé pour les clés tierces

Une version de clé est automatiquement affectée à chaque clé tierce dans le HSM. Lorsqu'un client fait pivoter une clé tierce, le module HSM génère une nouvelle version de clé. Les clients utilisent l'ID de version de la clé pivotée pour effectuer la rotation de la référence de clé dans OCI Key Management afin qu'OCI Key Management puisse envoyer des demandes d'opération cryptographique à la version de clé tierce appropriée.

Opérations d'API fournisseur

Les fournisseurs HSM implémentent l'API du fournisseur OCI External Key Management (External KMS) pour prendre en charge les fonctionnalités KMS externes. L'API offre les opérations suivantes :

Opération Nom d'API Description
Obtenir des métadonnées de coffre GetVaultMetadata Obtient les métadonnées d'un coffre.
crypter les données Encrypt Chiffre les données à l'aide d'une version de clé externe spécifiée ou, si aucune version n'est spécifiée, de la dernière version d'une clé spécifiée.
Décryptage de données Decrypt Chiffre les données à l'aide d'une version de clé externe spécifiée ou, si aucune version n'est spécifiée, de la dernière version d'une clé spécifiée.
Obtenir des métadonnées de clé GetKeyMetadata Obtient les métadonnées associées à la dernière version d'une clé spécifiée.
Obtenir les métadonnées de version de clé GetKeyVersionMetadata Obtient les métadonnées associées à une version de clé spécifiée.
Générer des byes aléatoires GenerateRandomBytes Génère des octets aléatoires.

Référence d'API fournisseur

Développez la référence d'API du fournisseur dans cette section pour obtenir des détails complets sur l'API.

Référence d'API fournisseur

  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'

Référence de code erreur

Erreur d'entrée API fournisseur Réponse attendue du fournisseur HSM externe
le client fournit un ID de coffre de clé (hyok) incorrect vaults/{vaultId}/metadata {"code":"404","message":"Error in getting OCI vault"}
hyok Vault est désactivé dans le gestionnaire de clés externe vaults/{vaultId}/metadata {"code":"403","message":"xxxxxxxx"}
le client fournit une clé hyok incorrecte keys/{keyId}/metadata {"code":"404","message":"Invalid key details provided"}
La clé hyok est désactivée keys/{keyId}/metadata {"code":"403","message":"xxxxxxxx"}
le client fournit une version de clé hyok incorrecte /keyVersions/{keyVersionId}/metadata {"code":"404","message":"Invalid Key details"}
le client tente de crypter ou de décrypter lorsque la clé hyok est désactivée dans le gestionnaire de clés externe

keys/{keyId}/encrypt

keys/{keyId}/decrypt

{"code":"403","message":"OCI key is not in Active state to perform the operation."}
le client tente de crypter ou de décrypter lorsque la clé hyok est supprimée dans le gestionnaire de clés externe

keys/{keyId}/encrypt

keys/{keyId}/decrypt

{"code":"404","message":"Invalid key details provided"}
le client tente de fournir du texte de cryptage altéré ou non valide lors du déchiffrement de l'appel keys/{keyId}/decrypt {"code":"400","message":"Bad Request: illegal base64 data at input byte 4"}
le client fournit du texte chiffré qui a été chiffré à l'aide d'une autre clé hyok keys/{keyId}/decrypt {"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"}
pneus client pour fournir un vecteur d'initialisation (IV) ou une balise non valide lors de l'appel de décryptage keys/{keyId}/decrypt {"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"}
le client tente de fournir des données authentifiées supplémentaires (AAD) non valides dans la charge utile /keys/{keyId}/generateRandomBytes {"code":"400","message":"Bad Request: illegal base64 data at input byte 8"}
le client tente de générer des octets aléatoires lorsque la clé hyok est désactivée dans le gestionnaire de clés externe /keys/{keyId}/generateRandomBytes {"code":"403","message":"Key is in disabled state."}