External KMS Vendor API Reference
Find information about the vendor API for OCI External Key Management.
Important
This API reference information is for hardware security module (HSM) vendors, and is not for regular users of the OCI External Key Management service. See Developing with Key and Secret Management for information on the customer APIs for OCI Key Management.
The OCI External Key Management Resource Model
This section details the OCI and third-party resources in the External Key Management resource model. For more details on External Key Management in OCI, see Key and Secret Management Concepts and External Key Management Service.
OCI's Key Management Service (KMS) uses the following resources when users store and manage keys in an external hardware security module (HSM).
Vaults
OCI vaults are logical entities in the customer's OCI environment where the Key Management Service creates and durably stores vault keys or key references. Customers using External Key Management create vaults of the type "external" to store references to keys located in an external HSM. The vault is the top-level resource for the customer when managing keys. Inside the vault are OCI Key References and Key Reference Versions.
Third-party Keys
Customers using OCI External Key Management create and store keys in an third-party HSM interface. OCI External Key Management considers these to be "third-party keys," because they're not generated or stored by Oracle, and therefore aren't resources within the OCI customer environment. But they're a part of the resource model because OCI External Key Management maps references to these keys to handle cryptographic operation requests.
Each third-party key has a key ID (GUID) created by the external system. Customers use the key ID and key details (key type and shape) to create a key reference in OCI External Key Management. Third-party keys contain one or more key versions.
Key References for Third-party Keys
In OCI Key Management, customers create references to third-party keys using the key ID and key details (key type and shape). OCI Key Management stores the key mapping details and key metadata, and not the actual key material. Customers interact with these key references in their OCI environment.
Creation of a key reference in OCI doesn't create a key in the third-party HSM. Similarly, the deletion of a key reference in OCI doesn't delete the third-party key in the HSM. OCI KMS uses the key reference for handling cryptographic operation requests, and cryptographic operations happen in the external HSM. Key references store information about current and retired key reference versions.
Key Reference Versions for Third-party Keys
Each third-party key is automatically assigned a key version in the HSM. When a customer rotates an third-party key, the HSM generates a new key version. Customers take the version ID of the rotated key and use it to rotate the key reference in OCI Key Management so that OCI Key Management can send cryptographic operation requests to the correct third-party key version.
Vendor API Operations
HSM vendors implement the OCI External Key Management (External KMS) vendor API to support External KMS features. The API offers the following operations:
| Operation | API name | Description |
|---|---|---|
| Get vault metadata | GetVaultMetadata |
Gets the metadata of a vault. |
| Encrypt data | Encrypt |
Encrypts data using a specified external key version, or if no version is specified, the latest version of a specified key. |
| Decrypt data | Decrypt |
Encrypts data using a specified external key version, or if no version is specified, the latest version of a specified key. |
| Get key metadata | GetKeyMetadata |
Gets the metadata associated with the latest version of a specified key. |
| Get key version metadata | GetKeyVersionMetadata |
Gets the metadata associated with a specified key version. |
| Generate random byes | GenerateRandomBytes |
Generates random bytes. |
Vendor API Reference
Expand the Vendor API reference in this section for complete API details.
Vendor API Reference
description: |
This API spec details the contract that the external key manager vendors need to implement
to support External Key Manager feature in OCI KMS
BasePath includes dynamic prefixes that should be added by vendor implementation.
license:
name: Oracle Corporation
title: External Key Manager Vendor API
version: 'v1'
basePath: "/<path-prefix>/ekm/v1"
schemes:
- https
consumes:
- application/json
produces:
- application/json
#==========[ Parameters ]====================================================================================================
parameters:
VaultIdPathParam:
name: vaultId
in: path
description: Vault ID on the External Key Manager system. A vault is a consturct to group all keys together
type: string
required: true
KeyIdPathParam:
name: keyId
in: path
description: Key ID on the External Key Manager system
type: string
required: true
KeyVersionIdPathParam:
name: keyVersionId
required: true
in: path
type: string
description: Key Version ID on the External Key Manager system
minLength: 1
maxLength: 255
RequestIdHeader:
name: opc-request-id
required: false
in: header
type: string
description: |
Unique identifier for the request. If provided, the returned request ID
will include this value. Otherwise, a random request ID will be
generated by the service.
AuthorizationHeader:
name: authorization
in: header
description: |
A HTTP header carrying the OAuth token with format:
`Bearer {token}`
required: true
type: string
#==========[ Definitions ]====================================================================================================
definitions:
VaultMetadata:
type: object
description: The response to the vault metadata request.
required:
- state
- vendor
properties:
state:
type: string
description: The state of the vault on external key manager
enum:
- ACTIVE
- DISABLED
vendor:
type: string
description: The vendor of the external key manager
minLength: 1
maxLength: 255
example: |
{
"state": "ACTIVE",
"vendor": "Thales CTM"
}
KeyMetadata:
description: The response to a request to get metadata of a key
type: object
required:
- state
properties:
state:
description: The state of the key
type: string
enum:
- ACTIVE
- DISABLED
keyId:
type: string
description: The id of the key
minLength: 1
maxLength: 255
currentKeyVersionId:
type: string
description: The id of the current key version for the key.
minLength: 1
maxLength: 255
keyShape:
$ref: '#/definitions/KeyShape'
keyOps:
type: array
description: The operations allowed to be performed using the key
items:
type: string
enum:
- ENCRYPT
- DECRYPT
example: |
{
"keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
"currentKeyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
"keyShape":
{
"algorithm": AES
"length": 256
}
"state": "ACTIVE",
"keyOps": [
"ENCRYPT",
"DECRYPT"
]
}
KeyVersionMetadata:
description: The response to a request to get metadata of a key version
type: object
required:
- state
properties:
state:
description: The state of the key version
type: string
enum:
- ACTIVE
- DISABLED
keyId:
type: string
description: The id of the master key for the key version
minLength: 1
maxLength: 255
keyVersionId:
type: string
description: The id of the key version
minLength: 1
maxLength: 255
keyVersionOps:
type: array
description: The operations allowed to be performed using the key version
items:
type: string
enum:
- ENCRYPT
- DECRYPT
example: |
{
"keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf"
"state": "ACTIVE",
"keyVersionOps": [
"ENCRYPT",
"DECRYPT"
]
}
DecryptDetails:
type: object
description: Contains input data and associated metadata for a decyrpt request
required:
- ciphertext
- mode
- keyVersionId
properties:
ciphertext:
type: string
description: Ciphertext that appears as a base64 encoded string in the JSON blob.
aad:
type: string
description: AAD that appears as a base64 encoded string in the JSON blob.
The length of the string representation of the associated data must be fewer than 4096
characters.
iv:
type: string
description: IV that appears as a base64 encoded string in the JSON blob.
mode:
type: string
default: AES_GCM
enum:
- AES_GCM
- AES_CBC
description: |
The encryption algorithm to use to decrypt data
`AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
pad:
type: string
description: Pad Scheme used in encryption
default: PKCS7
enum:
- PKCS7
- NONE
tag:
type: string
description: Tag that appears as a base64 encoded string in the JSON blob.
keyVersionId:
type: string
description: The id of the key version used to decrypt the ciphertext.
minLength: 1
maxLength: 255
example: |
{
"ciphertext": "RpeAO2op/+bQD3FioKbuVi54yysO79e0SjY=",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"tag": "dk958fIs5D+kRE8rKKqtgA==",
"aad": "fIs5D+kRE8r",
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf"
}
DecryptedData:
description: The response to a request to decrypt the encrypted data.
type: object
required:
- plaintext
- mode
- keyId
- keyVersionId
properties:
plaintext:
type: string
description: The decrypted data, expressed as a base64-encoded value.
minLength: 1
maxLength: 4096
keyId:
type: string
description: The id of the key used to decrypt the ciphertext.
minLength: 1
maxLength: 255
keyVersionId:
type: string
description: The id of the key version used to decrypt the ciphertext.
minLength: 1
maxLength: 255
aad:
type: string
description: AAD that appears as a base64 encoded string in the JSON blob.
The length of the string representation of the associated data must be fewer than 4096
characters.
pad:
type: string
description: Pad Scheme used in encryption
default: PKCS7
enum:
- PKCS7
- NONE
iv:
type: string
description: IV that appears as a base64 encoded string in the JSON blob.
mode:
type: string
default: AES_GCM
enum:
- AES_GCM
- AES_CBC
description: |
The encryption algorithm to use to decrypt data
`AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
tag:
type: string
description: Tag that appears as a base64 encoded string in the JSON blob.
example: |
{
"plaintext": "aGVsbG8sIHdvcmxk",
"keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"tag": "dk958fIs5D+kRE8rKKqtgA==",
"aad": "fIs5D+kRE8r"
}
EncryptDetails:
type: object
description: Contains input data and associated metadata for encrypt request
required:
- plaintext
- mode
properties:
plaintext:
type: string
description: A byte array data to be encrypted. JSON encodes byte arrays to base64 strings. Therefore, the string in the JSON object should be a valid base64 string.
aad:
type: string
description: AAD that appears as a base64 encoded string in the JSON blob.
The length of the string representation of the associated data must be fewer than 4096
characters. (Only applicable when mode is AES_GCM)
iv:
type: string
description: IV that appears as a base64 encoded string in the JSON blob.
mode:
type: string
default: AES_GCM
enum:
- AES_GCM
- AES_CBC
description: |
The encryption algorithm to use to encrypt data
`AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
pad:
type: string
description: Pad Scheme used in encryption
default: PKCS7
enum:
- PKCS7
- NONE
tagLen:
type: integer
description: Tag length in bytes expressed as integer (Only applicable when mode is AES_GCM)
minLength: 12
maxLength: 16
default: 16
keyVersionId:
type: string
description: Key version ID
example: |
{
"plaintext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"aad": "fIs5D+kRE8r",
"tagLen" : 16,
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
"pad" : "PKCS7"
}
EncryptedData:
description: The response to a request to encrypt the plaintext data.
type: object
required:
- ciphertext
- keyId
- keyVersionId
- mode
properties:
ciphertext:
type: string
description: The encrypted data.
minLength: 1
maxLength: 65536
keyId:
type: string
description: The id of the key used to encrypt the plaintext.
minLength: 1
maxLength: 255
keyVersionId:
type: string
description: The id of the key version used to encrypt the plaintext.
minLength: 1
maxLength: 255
aad:
type: string
description: AAD that appears as a base64 encoded string in the JSON blob.
The length of the string representation of the associated data must be fewer than 4096
characters.
iv:
type: string
description: IV that appears as a base64 encoded string in the JSON blob.
tag:
type: string
description: Tag
pad:
type: string
description: Pad Scheme used in encryption
default: PKCS7
enum:
- PKCS7
- NONE
mode:
type: string
default: AES_GCM
enum:
- AES_GCM
- AES_CBC
description: |
The encryption algorithm to use to encrypt data
`AES_GCM` indicates that the key is a symmetric key that uses the Advanced Encryption Standard (AES) algorithm and
that the mode of encryption is the Galois/Counter Mode (GCM)/ Cipher block chaining(CBC).
example: |
{
"ciphertext": "RpeAO2op/+bQD3FioKbuVi54yysO79e0SjY=",
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
"keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"tag": "dk958fIs5D+kRE8rKKqtgA==",
"pad": "PKCS7",
"aad": "fIs5D+kRE8r"
}
GenerateRandomBytesDetails:
description: The details used to generate random bytes.
type: object
required:
- length
properties:
length:
type: integer
description: Length of the bytes to be generated
enum:
- 16
- 24
- 32
example: |
{
"length": 16
}
RandomBytes:
description: The reponse to the reqeuest to generate random bytes
type: object
required:
- randomBytes
- length
properties:
randomBytes:
type: string
description: The base64 encoded random bytes
minLength: 1
maxLength: 65536
length:
type: integer
description: Length of the bytes to be generated
enum:
- 16
- 24
- 32
example: |
{
"randomBytes": "AAwRhavVBkAAAJNF0nE7tBz/CQDanO33toIAWpw/lCn9GuadiyNNZ2QCmeUksvor8HD00o0TiUHzj6IsDJ5z1j/AEXZrhBtEcz4=",
"length": 32
}
KeyShape:
type: object
description: The cryptographic properties of a key.
required:
- algorithm
- length
properties:
algorithm:
type: string
description: The algorithm used by a key/key versions to encrypt or decrypt.
enum:
- AES
length:
type: integer
description: The length of the key in bytes, expressed as an integer.
enum:
- 14
- 24
- 32
example: |
{
"algorithm": "AES",
"length": 16
}
Error:
description: |
The error object.
required:
- code
- message
properties:
code:
type: string
description: |
The unique code of an error.
message:
type: string
description: |
The description of an error.
#==========[ Paths ]====================================================================================================
paths:
/vaults/{vaultId}/metadata:
get:
operationId: GetVaultMetadata
summary: Get Vault metadata
description: Get metadata of the Vault
tags:
- ekmVaultMetadata
parameters:
- $ref: '#/parameters/VaultIdPathParam'
- $ref: '#/parameters/RequestIdHeader'
- $ref: '#/parameters/AuthorizationHeader'
responses:
200:
description: OK
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/VaultMetadata'
400:
$ref: '#/responses/400'
401:
$ref: '#/responses/401'
403:
$ref: '#/responses/403'
404:
$ref: '#/responses/404'
409:
$ref: '#/responses/409'
412:
$ref: '#/responses/412'
422:
$ref: '#/responses/422'
429:
$ref: '#/responses/429'
500:
$ref: '#/responses/500'
default:
$ref: '#/responses/DefaultError'
x-example: |
GET <path-prefix>/ekm/v1/vaults/<vaultId>>/metadata
Host: <ip-address>:<port>
<authorization and other headers>
/vaults/{vaultId}/keys/{keyId}/encrypt:
post:
operationId: Encrypt
summary: Encrypt plaintext
description: To encrypt the data using a specific version of the external key, specify the version ID of the key as an input parameter. If not specified, the latest version of the key with id keyId under vault with id vaultId is used to encrypt the data.
tags:
- ekmCrypto
parameters:
- $ref: '#/parameters/VaultIdPathParam'
- $ref: '#/parameters/KeyIdPathParam'
- $ref: '#/parameters/RequestIdHeader'
- $ref: '#/parameters/AuthorizationHeader'
- description: The input containing plaintext to encrypt and metadata
in: body
name: EncryptDetails
required: true
schema:
$ref: '#/definitions/EncryptDetails'
responses:
'200':
description: The encrypted data, presented as ciphertext.
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/EncryptedData'
400:
$ref: '#/responses/400'
401:
$ref: '#/responses/401'
403:
$ref: '#/responses/403'
404:
$ref: '#/responses/404'
409:
$ref: '#/responses/409'
412:
$ref: '#/responses/412'
422:
$ref: '#/responses/422'
429:
$ref: '#/responses/429'
500:
$ref: '#/responses/500'
default:
$ref: '#/responses/DefaultError'
x-example: |
POST <path-prefix>/ekm/v1/vaults/<vaultId>/keys/<keyId>/encrypt
Host: <ip-address>:<port>
<authorization and other headers>
{
"plaintext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"aad": "fIs5D+kRE8r",
"tagLen" : 16,
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
"pad" : "PKCS7"
}
/vaults/{vaultId}/keys/{keyId}/decrypt:
post:
operationId: Decrypt
summary: Decrypt Ciphertext
description: To decrypt the data using a specific version of the external key included in the ciphertext input.
tags:
- ekmCrypto
parameters:
- $ref: '#/parameters/VaultIdPathParam'
- $ref: '#/parameters/KeyIdPathParam'
- $ref: '#/parameters/RequestIdHeader'
- $ref: '#/parameters/AuthorizationHeader'
- description: The input containing ciphertext to decrypt and metadata
in: body
name: DecryptDetails
required: true
schema:
$ref: '#/definitions/DecryptDetails'
responses:
200:
description: |
The decrypted data in plaintext.
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/DecryptedData'
400:
$ref: '#/responses/400'
401:
$ref: '#/responses/401'
403:
$ref: '#/responses/403'
404:
$ref: '#/responses/404'
409:
$ref: '#/responses/409'
412:
$ref: '#/responses/412'
422:
$ref: '#/responses/422'
429:
$ref: '#/responses/429'
500:
$ref: '#/responses/500'
default:
$ref: '#/responses/DefaultError'
x-example: |
POST <path-prefix>/ekm/v1/vaults/<vaultId>/keys/<keyId>/decrypt
Host: <ip-address>:<port>
<authorization and other headers>
{
"ciphertext": "RpeAO2op/+bQD3FioKbuVi54yysO79e0SjY=",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"tag": "dk958fIs5D+kRE8rKKqtgA==",
"aad": "fIs5D+kRE8r",
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf"
}
/vaults/{vaultId}/keys/{keyId}/metadata:
get:
operationId: GetKeyMetadata
summary: Key Metadata
description: To fetch the metadata associated with the latest version of the key
tags:
- ekmKeyMetaData
parameters:
- $ref: '#/parameters/VaultIdPathParam'
- $ref: '#/parameters/KeyIdPathParam'
- $ref: '#/parameters/RequestIdHeader'
- $ref: '#/parameters/AuthorizationHeader'
responses:
200:
description: OK
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/KeyMetadata'
400:
$ref: '#/responses/400'
401:
$ref: '#/responses/401'
403:
$ref: '#/responses/403'
404:
$ref: '#/responses/404'
409:
$ref: '#/responses/409'
412:
$ref: '#/responses/412'
422:
$ref: '#/responses/422'
429:
$ref: '#/responses/429'
500:
$ref: '#/responses/500'
default:
$ref: '#/responses/DefaultError'
x-example: |
GET <path-prefix>/ekm/v1/vaults/<vaultId>/keys/<keyId>/metadata
Host: <ip-address>:<port>
<authorization and other headers>
/vaults/{vaultId}/keys/{keyId}/keyVersions/{keyVersionId}/metadata:
get:
operationId: GetKeyVersionMetadata
summary: KeyVersion Metadata
description: To fetch the metadata associated with a specific version of the key.
tags:
- ekmKeyVersionMetaData
parameters:
- $ref: '#/parameters/VaultIdPathParam'
- $ref: '#/parameters/KeyIdPathParam'
- $ref: '#/parameters/RequestIdHeader'
- $ref: '#/parameters/KeyVersionIdPathParam'
- $ref: '#/parameters/AuthorizationHeader'
responses:
200:
description: OK
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/KeyVersionMetadata'
400:
$ref: '#/responses/400'
401:
$ref: '#/responses/401'
403:
$ref: '#/responses/403'
404:
$ref: '#/responses/404'
409:
$ref: '#/responses/409'
412:
$ref: '#/responses/412'
422:
$ref: '#/responses/422'
429:
$ref: '#/responses/429'
500:
$ref: '#/responses/500'
default:
$ref: '#/responses/DefaultError'
x-example: |
GET <path-prefix>/ekm/v1/vaults/<vaultId>>/keys/<keyVersionId>/metadata
Host: <ip-address>:<port>
<authorization and other headers>
/vaults/{vaultId}/generateRandomBytes:
post:
operationId: GenerateRandomBytes
summary: Generate Random Bytes
description: Generates random bytes.
tags:
- ekmCrypto
parameters:
- $ref: '#/parameters/VaultIdPathParam'
- $ref: '#/parameters/RequestIdHeader'
- $ref: '#/parameters/AuthorizationHeader'
- description: The input contains metadata to create random bytes from
in: body
name: GenerateRandomBytesDetails
required: true
schema:
$ref: '#/definitions/GenerateRandomBytesDetails'
responses:
201:
description: Created
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request. If you need to contact Oracle about
a particular request, please provide the request ID.
type: string
schema:
$ref: '#/definitions/RandomBytes'
400:
$ref: '#/responses/400'
401:
$ref: '#/responses/401'
403:
$ref: '#/responses/403'
404:
$ref: '#/responses/404'
409:
$ref: '#/responses/409'
412:
$ref: '#/responses/412'
422:
$ref: '#/responses/422'
429:
$ref: '#/responses/429'
500:
$ref: '#/responses/500'
default:
$ref: '#/responses/DefaultError'
x-example: |
POST <path-prefix>/ekm/v1/vaults/<vaultId>/generateRandomBytes
Host: <ip-address>:<port>
<authorization and other headers>
{
"length": 16
}
#==========[ Responses ]================================================================================================
responses:
400:
description: Bad Request
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
401:
description: Unauthorized
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
403:
description: Forbidden
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
404:
description: Not Found
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
409:
description: Conflict
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
412:
description: Precondition Failed
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
422:
description: Unprocessable Entity
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
429:
description: Too many requests. User-rate limit exceeded.
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
retry-after:
description: |
If the request gets throttled, time in seconds to retry the request.
type: integer
schema:
$ref: '#/definitions/Error'
500:
description: Internal Server Error
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
DefaultError:
description: Unknown Error
headers:
opc-request-id:
description: |
Unique Oracle-assigned identifier for the request.
type: string
schema:
$ref: '#/definitions/Error'
Error Code Reference
| Input Error | Vendor API | Expected response from external HSM vendor |
|---|---|---|
| customer provides wrong hold your own key (hyok) vault ID | vaults/{vaultId}/metadata |
{"code":"404","message":"Error in getting OCI vault"} |
| hyok vault is disabled in external key manager | vaults/{vaultId}/metadata |
{"code":"403","message":"xxxxxxxx"} |
| customer provides wrong hyok key | keys/{keyId}/metadata |
{"code":"404","message":"Invalid key details provided"} |
| hyok key is disabled | keys/{keyId}/metadata |
{"code":"403","message":"xxxxxxxx"} |
| customer provides wrong hyok key version | /keyVersions/{keyVersionId}/metadata |
{"code":"404","message":"Invalid Key details"} |
| customer tries to encrypt or decrypt when hyok key is disabled in external key manager |
|
{"code":"403","message":"OCI key is not in Active state to perform the operation."} |
| customer tries to encrypt or decrypt when hyok key is deleted in external key manager |
|
{"code":"404","message":"Invalid key details provided"} |
| customer tries to provide tampered or invalid cipher text during decrypt call | keys/{keyId}/decrypt |
{"code":"400","message":"Bad Request: illegal base64 data at input byte 4"} |
| customer provides cipher text that was encrypted using a different hyok key | keys/{keyId}/decrypt |
{"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"} |
| customer tires to provide invalid initialization vector (IV) or tag during decrypt call | keys/{keyId}/decrypt |
{"code":"400","message":"Error in decryption: [NCERRCryptoOperationFailed: Cryptographic operation failed in cipher operation]: AEAD decrypt final failed"} |
| customer tries to provide invalid additional authenticated data (AAD) in the payload | /keys/{keyId}/generateRandomBytes |
{"code":"400","message":"Bad Request: illegal base64 data at input byte 8"} |
| customer tries to generate random bytes when hyok key is disabled in external key manager | /keys/{keyId}/generateRandomBytes |
{"code":"403","message":"Key is in disabled state."} |