Externe KMS Lieferanten-API-Referenz

  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'