Documentation sur Oracle Cloud Infrastructure

Informations de référence sur l'API du fournisseur KMS externe

Recherchez des informations sur l'API du fournisseur pour le service de gestion des clés externes pour OCI.

Important

Ces informations de référence sur les API s'adressent aux fournisseurs de module de sécurité matériel et ne sont pas destinées aux utilisateurs réguliers du service de gestion des clés externes OCI. Voir Développement avec la gestion des clés et des clés secrètes pour plus d'informations sur les API de client pour OCI Key Management.

Modèle de ressource OCI pour la gestion des clés externes

Cette section détaille les ressources OCI et tierces dans le modèle de ressource External Key Management. Pour plus de détails sur la gestion des clés externes dans OCI, voir Concepts relatifs à la 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é matériel externe (HSM).

Chambres fortes

Les chambres fortes OCI sont des entités logiques dans l'environnement OCI du client, où le service de gestion des clés crée et stocke durablement les clés de chambre forte ou les références de clé. Les clients qui utilisent la gestion des clés externes créent des chambres fortes de type "externe" pour stocker les références aux clés situées dans un module de sécurité matériel externe. La chambre forte est la ressource de niveau supérieur pour le client lors de la gestion des clés. Dans la chambre forte se trouvent les références de clé OCI et les versions de référence de clé.

Clés de tierce partie

Les clients qui utilisent OCI External Key Management créent et stockent des clés dans une interface de module de sécurité matériel de tierce partie. Le service de gestion de clés externes pour OCI considère ces clés comme des "clés de tierce partie", car elles ne sont pas générées ou stockées par Oracle et ne sont donc pas des ressources dans l'environnement du client OCI. Mais ils font partie du modèle de ressource, car le service de gestion des clés externes OCI mappe les références à ces clés pour traiter les demandes d'opération cryptographique.

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

Références clés pour les clés de tierce partie

Dans le service de gestion des clés OCI, les clients créent des références aux clés de tierce partie à l'aide de l'ID clé et des détails de clé (type et forme de clé). Le service de gestion des clés OCI stocke les détails du mappage de clés et les métadonnées de clé, 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 de sécurité matériel de tierce partie. De même, la suppression d'une référence de clé dans OCI ne supprime pas la clé de tierce partie dans le module de sécurité matériel. Le service de gestion des clés pour OCI utilise la référence de clé pour traiter les demandes d'opération cryptographique, et les opérations cryptographiques se produisent dans le module de sécurité matériel externe. Les références de clé stockent des informations sur les versions de référence de clé courantes et mises hors service.

Versions de référence de clé pour les clés de tierce partie

Une version de clé est affectée automatiquement à chaque clé de tierce partie dans le module de sécurité matériel. Lorsqu'un client effectue la rotation d'une clé de tierce partie, le module de sécurité matériel génère une nouvelle version de clé. Les clients utilisent l'ID version de la clé pivotée et l'utilisent pour effectuer la rotation de la référence de clé dans le service de gestion des clés OCI afin que le service de gestion des clés OCI puisse envoyer des demandes d'opération cryptographique à la version de clé de tierce partie correcte.

Opérations d'API de fournisseur

Les fournisseurs de module de sécurité matériel mettent en oeuvre l'API de fournisseur de gestion de clés externes (SGC externe) OCI pour prendre en charge les fonctions du SGC externe. L'API offre les opérations suivantes :

Opération Nom de l'API Description
Obtenir les métadonnées de la chambre forte GetVaultMetadata Obtient les métadonnées d'une chambre forte.
Chiffrer des 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, la dernière version d'une clé spécifiée.
Déchiffrer les 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, la dernière version d'une clé spécifiée.
Obtenir les 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 de fournisseur

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

Référence d'API de 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 au code d'erreur

Erreur entrée API de fournisseur Réponse attendue du fournisseur externe de module de sécurité matériel
le client fournit un ID chambre forte de clé (hyok) erroné vaults/{vaultId}/metadata {"code":"404","message":"Error in getting OCI vault"}
La chambre forte hyok est désactivée dans le gestionnaire de clés externes vaults/{vaultId}/metadata {"code":"403","message":"xxxxxxxx"}
le client fournit une mauvaise clé hyok 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 chiffrer ou de déchiffrer lorsque la clé hyok est désactivée dans le gestionnaire de clés externes

keys/{keyId}/encrypt

keys/{keyId}/decrypt

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

keys/{keyId}/encrypt

keys/{keyId}/decrypt

{"code":"404","message":"Invalid key details provided"}
le client tente de fournir un texte de chiffrement altéré ou non valide lors de l'appel de déchiffrement keys/{keyId}/decrypt {"code":"400","message":"Bad Request: illegal base64 data at input byte 4"}
le client fournit un texte 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 un marqueur non valide lors du déchiffrement de l'appel 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 les données utiles /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 externes /keys/{keyId}/generateRandomBytes {"code":"403","message":"Key is in disabled state."}