{ "openapi": "3.0.0", "info": { "title": "IBM Key Protect API", "description": "## Introduction\n\nIBM® Key Protect for IBM Cloud® helps you provision encrypted\nkeys for apps across IBM Cloud. As you manage the\nlifecycle of your keys, you can benefit from knowing that your keys are secured\nby cloud-based FIPS 140-2 Level 3 hardware security modules (HSMs) that protect\nagainst the theft of information.\n\nKey Protect provides a REST API that you can\nuse with any programming language to store, retrieve, and generate encryption\nkeys. For details about using Key Protect,\nsee the IBM Cloud\n[docs](https://cloud.ibm.com/docs/key-protect/).\n\nAPI endpoint\n\n```bash\nhttps://.kms.cloud.ibm.com\n```\n\nReplace `` with the prefix that represents the geographic area where\nyour Key Protect service instance resides.\nFor more information, see\n[Regions and locations](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions).\n\nThe code examples on this tab use the client library that is provided for Go.\n\n```bash\ngo get -u github.com/IBM/keyprotect-go-client\n```\n\nGitHub:\n\n[https://github.com/IBM/keyprotect-go-client](https://github.com/IBM/keyprotect-go-client)\n\nThe code examples on this tab use the client library that is provided for NodeJS.\n\n```bash\nnpm install @ibm-cloud/ibm-key-protect\n```\n\nGitHub:\n\n[https://github.com/IBM/keyprotect-nodejs-client](https://github.com/IBM/keyprotect-nodejs-client)\n\nThe code examples on this tab use the client library that is provided for Python.\n\n```bash\npip install -U keyprotect\n```\n\nGitHub:\n\n[https://github.com/IBM/keyprotect-python-client](https://github.com/IBM/keyprotect-python-client)\n\nThe code examples on this tab use the client library that is provided for Java.\n\n```bash\ngit clone https://github.com/IBM/keyprotect-java-client\ncd keyprotect-java-client\nmvn install\n```\n\nGitHub:\n\n[https://github.com/IBM/keyprotect-java-client](https://github.com/IBM/keyprotect-java-client)\n\n## Authentication\n\nTo call each method, you'll need to be assigned a role that includes the\nrequired IAM actions. Each method lists the associated action. For more\ninformation about IAM actions and how they map to roles, see\n[Managing access for Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-manage-access).\n\nTo work with the API, authenticate your app or service by including your\n[IBM Cloud IAM access token](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token)\nand\n[instance ID](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-instance-ID)\nin API requests.\n\nYou can build your API request by pairing a\n[service endpoint](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions#service-endpoints)\nwith your authentication credentials. For example, if you created a\nKey Protect service instance for the\n`us-south` region, use the following endpoint and API headers to browse keys in\nyour service:\n\n```bash\ncurl -X GET \\\n https://us-south.kms.cloud.ibm.com/api/v2/keys \\\n -H \"accept: application/vnd.ibm.collection+json\" \\\n -H \"authorization: Bearer \" \\\n -H \"bluemix-instance: \"\n```\n\nReplace `` with your Cloud IAM token, and `` with the\nIBM Cloud instance ID that identifies your\nKey Protect service instance.\n\nYou can retrieve an access token by first creating an API key, and then\nexchanging your API key for a Cloud IAM token. For more information, see\n[Retrieving an access token programmatically](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token#retrieve-token-api).\n\nTo find out more about setting up the\nKey Protect API, see\n[Accessing the API](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-api).\n\nTo retrieve your access token:\n\n```bash\ncurl -X POST \\\n https://iam.cloud.ibm.com/identity/token \\\n -H \"accept: application/json\" \\\n -H \"content-type: application/x-www-form-urlencoded\" \\\n -d \"grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=\" > token.json\n```\n\nReplace `` with your\n[service credentials](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token#retrieve-token-api).\nThen use the full `access_token` value, prefixed by the _Bearer_token type, to\nauthenticate your API requests.\n\nTo retrieve your instance ID:\n\n```bash\nibmcloud resource service-instance --output JSON\n```\n\nReplace `` with the unique alias that you assigned to your\nKey Protect service instance. The `GUID`\nvalue in the JSON output represents the instance ID for the service.\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to\nauthenticate to the Key Protect API. The SDK\nprovides client config initialization method in which you will need to replace\n`` with the appropriate [service endpoint](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions#service-endpoints),\nthe `` with the [API key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token#retrieve-token-api)\nassociated with your application, and `` with the IBM Cloud\ninstance ID that identifies your Key Protect\nservice instance.\n\nThe value `kp.DefaultTokenURL` for `TokenURL` defaults to the IAM production URL,\nbut you may need to alter the value to be associated with virtual private networks.\nUse the client config options in the method to create a new\nKey Protect client. The method handles the\nauthentication procedure with the provided API_KEY.\n\nTo authenticate to Key Protect API:\n\n```go\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc getConfigAPIKey() kp.ClientConfig {\n return kp.ClientConfig{\n BaseURL: ,\n APIKey: ,\n TokenURL: kp.DefaultTokenURL,\n InstanceID: ,\n Verbose: kp.VerboseFailOnly,\n }\n}\n\nfunc main() {\n options := getConfigAPIKey()\n api, err := kp.New(options, kp.DefaultTransport())\n if err != nil {\n fmt.Println(\"Error creating kp client\")\n return\n }\n}\n```\n\nTo access the API through your service endpoint, you will need to use the following format.\n\nAPI endpoint format:\n\n```bash\nhttps://.kms.cloud.ibm.com\n```\n\nReplace `` with the prefix that represents the geographic area where\nyour Key Protect service instance resides.\nFor more informaton, see\n[Regions and locations](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions).\n\nTo retrieve your instance ID, run the following command using the [CLI](https://cloud.ibm.com/docs/key-protect?topic=key-protect-set-up-cli):\n\n```bash\nibmcloud resource service-instance --output JSON\n```\n\nReplace `` with the unique alias that you assigned to your\nKey Protect service instance. The `GUID`\nvalue in the JSON output represents the `` for the service.\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Key Protect API. The SDK provides a client config setup in which you will need to `export` environment variables to match the `IBMCLOUD_API_KEY` term with the API key associated with your [service credentials](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token#retrieve-token-api), another term, `IAM_AUTH_URL` with the appropriate URL like 'https://iam.cloud.ibm.com/identity/token', another term, `KP_SERVICE_URL` with the endpoint, including the region, such as `https://us-south.kms.cloud.ibm.com`, and `KP_INSTANCE_ID` with the IBM Cloud instance ID that identifies your Key Protect service instance.\n\nTo retrieve your instance ID:\n\n```bash\nibmcloud resource service-instance --output JSON\n```\n\nTo authenticate to Key Protect API:\n\n```js\nconst KeyProtectV2 = require('@ibm-cloud/ibm-key-protect/ibm-key-protect-api/v2');\nconst { IamAuthenticator } = require('@ibm-cloud/ibm-key-protect/auth');\n\n// using external configuration of environment variables\nconst envConfigs = {\n apiKey: process.env.IBMCLOUD_API_KEY,\n iamAuthUrl: process.env.IAM_AUTH_URL,\n serviceUrl: process.env.KP_SERVICE_URL,\n bluemixInstance: process.env.KP_INSTANCE_ID,\n};\n\n// Create an IAM authenticator.\nconst authenticator = new IamAuthenticator({\n apikey: envConfigs.apiKey,\n url: envConfigs.iamAuthUrl,\n});\n\n// Construct the service client.\nconst keyProtectClient = new KeyProtectV2({\n authenticator,\n serviceUrl: envConfigs.serviceUrl,\n});\n\n```\n\nFor more information on the regional endpoint where your data can be accessed, see\n[Regions and locations](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions).\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to\nauthenticate to the Key Protect API. The SDK\nprovides a client config setup in which you will need to replace the\n`IBMCLOUD_API_KEY` with the API key associated with your application, and\n`KP_INSTANCE_ID` with the IBM Cloud instance ID that identifies your\nKey Protect service instance.\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to\nauthenticate to the Key Protect API. The SDK\nprovides a client config setup in which you will need to replace the\n`IBMCLOUD_API_KEY` with the API key associated with your application, and\n`KP_INSTANCE_ID` with the IBM Cloud instance ID that identifies your\nKey Protect service instance.\n\nTo authenticate to Key Protect API:\n\n```python\nimport os\n\nimport keyprotect\nfrom keyprotect import bxauth\n\ntm = bxauth.TokenManager(api_key=os.getenv(\"\"))\n\nkp = keyprotect.Client(\n credentials=tm,\n region=\"\",\n service_instance_id=os.getenv(\"\")\n)\n```\n\nReplace `` with your\n[service credentials](https://cloud.ibm.com/docs/key-protect?topic=key-protect-retrieve-access-token#retrieve-token-api).\n\nReplace `` with the UUID that identifies your\nKey Protect instance.\n\nTo retrieve your instance ID:\n\n```bash\nibmcloud resource service-instance --output JSON\n```\n\nReplace `` with the prefix that represents the geographic area where\nyour Key Protect service instance resides.\nFor more information, see\n[Regions and locations](https://cloud.ibm.com/docs/key-protect?topic=key-protect-regions).\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to \nauthenticate to the Key Protect API.\nThe SDK provides a client config setup in which you will need to replace the \n`IAM_API_KEY` with the API key associated with your application, `IAM_AUTH_URL` \nwith your Cloud IAM token,`KEY_PROTECT_URL` with a service endpoint, and \n`INSTANCE_ID` with the IBM Cloud instance ID that identifies your \nKey Protect service instance. \n\nTo authenticate to Key Protect API:\n\n```java\nimport com.ibm.cloud.ibm_key_protect_api.v2.IbmKeyProtectApi;\nimport com.ibm.cloud.ibm_key_protect_api.v2.model.*;\nimport com.ibm.cloud.sdk.core.http.Response;\nimport com.ibm.cloud.sdk.core.security.*;\n\npublic class KPClient {\n \n private static IbmKeyProtectApi testClient;\n\n public static void main(String[] args) {\n \n IamAuthenticator authenticator = new IamAuthenticator(\"\");\n authenticator.setURL(\"\");\n authenticator.validate();\n \n testClient = new IbmKeyProtectApi(\"\", authenticator);\n testClient.setServiceUrl(\"\");\n }\n}\n```\n\nReplace `` with the UUID that identifies your Key Protect instance.\n\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/services/key-protect?topic=key-protect-retrieve-access-token#retrieve-token-api).\n\nReplace `` with `https://iam.cloud.ibm.com/identity/token`.\n\nReplace `` with the service endpoint for your instance that handles your requests.\n\nTo retrieve your instance ID, replace <instance_name> in the command as shown:\n\n```bash\nibmcloud resource service-instance --output JSON\n```\n\nYour endpoint is specific to the geographic area where your Key Protect service instance resides. For more \ninformation, see [Regions and locations](https://cloud.ibm.com/docs/services/key-protect?topic=key-protect-regions).\n\n## Auditing\n\nYou can monitor API activity within your account. Whenever an API method is called, an event is generated that you can then track and audit. The specific event type is listed for each method that generates auditing events. For methods that don't list any events, no events are generated.\n\nFor more information about how to track Key Protect activity, see [Auditing the events for Key Protect](https://cloud.ibm.com/docs/key-protect?topic=key-protect-at-events).\n\n## Error handling\n\nThe Key Protect service uses standard HTTP\nresponse codes to indicate whether a method completed successfully. A `200`\nresponse always indicates success. A `400` type response is some sort of\nfailure, and a `500` type response usually indicates an internal system error.\n\n| Status code | Description |\n| --- | --- |\n| 200 **`OK`** | Everything worked as expected. |\n| 201 **`OK`** | Everything worked as expected; no content. |\n| 400 **`Bad Request`** | The request was unsuccessful; ensure no required parameters are missing. |\n| 401 **`Unauthorized`** | The parameters were valid but the request failed due insufficient permissions. |\n| 404 **`Not Found`** | The requested resource doesn't exist. |\n| 410 **`Gone`** | The requested resource was deleted and no longer exists. |\n| 429 **`Too Many Requests`** | Too many requests hit the API too quickly. |\n| 500 **`Server Error`** | Something went wrong on Key Protect's end. |\n\n## Metadata\n\nWhen you create or store keys in\nKey Protect, you can attach key-value data\nto your resources for easy identification of your keys.\n\nThe `name`, `description`, and `tag` parameters are useful for storing\ninformation on your resources. For example, you can store corresponding unique\nidentifiers from your app or system on a\nKey Protect key.\n\nTo protect your privacy, do not store any personally identifiable information,\nsuch as your name or location, as metadata for your keys.\n\n## Pagination\n\nSome API requests might return a large number of results. By specifying the\n`limit` and `offset` parameters at query time, you can retrieve a subset of your\nkeys, starting with the offset value that you specify. For more information, see\n[Retrieving a subset of keys](https://cloud.ibm.com/docs/key-protect?topic=key-protect-view-keys#retrieve-subset-keys-api).\n\nThere are optional operations that can effect pagination and the resulting list of keys returned by the service. Some operations may still be in development, and will be listed as \"Beta\" while that is the case.\n\n**Search**\n\nWhen used, this operation performs a search, possibly limiting the number of keys returned. If you want to narrow the number of results returned by a search, try using one or a combination of the following values as a prefix for the term you wish to have searched:\n\n* `not:` when specified, inverts the logic the search uses (for example, `not:foo` will search for keys that have aliases or names that do not contain `foo`).\n* `escape:` everything after this option is take as plaintext (example: `escape:not:` will search for keys that have an alias or name containing the substring `not:`).\n* `exact:` only looks for exact matches.\n* `alias:` only looks for key aliases.\n* `name:` only looks for key names.\n\nThe list of keys returned is sorted on id by default, if this parameter is not provided.\n\n**Sort**\n\nWhen used, this operation sorts the list of keys returned based on one or more key properties. The key properties that can be sorted at this time are:\n \n- `id`\n- `state`\n- `extractable`\n- `imported`\n- `creationDate`\n- `lastUpdateDate`\n- `lastRotateDate`\n- `deletionDate`\n- `expirationDate`\n\nThe list of keys returned is sorted on id by default, if this parameter is not provided.\n\n## Rate Limiting\n\nRate limits for API requests are enforced on a per-service-instance basis. If the number of requests for a particular method and endpoint reaches the request limit within the specified time window, no further requests are accepted until the timer expires. After the timer expires, a new time window begins with the next accepted request.\n\nAn HTTP status code of 429 indicates that the rate limit has been exceeded.\n\n## Change log\n\nImportant changes, such as additions, updates, and breaking changes, are marked with a change notice in this reference.\n\nNew features will be initially released as \"beta\" implementations. \n\n\"Beta\" means that the specification is subject to change, with limited support in different environments (from partial support to none at all, depending on the specifics), in order to test new features that are not yet stable for use in production environments.\n\nAs part of continued migration and improvement, the `algorithmBitSize`, `algorithmMode`,\n`algorithmType` and `algorithmMetadata` fields are deprecated within the Key Protect API.\n\nKey Protect announces several changes to both the structure and to particular names of certain events to better conform with IBM naming conventions. \n\nThe `alias` parameter in the event generated with a key `alias` added to a key at creation time is being moved from the response data section to the request data section.\n\nAlso, to better conform with IBM standards, the names of certain events are changing.\n\n| Old event name | New event name |\n| --- | --- |\n| kms.secrets.eventack | kms.secrets-event.ack|\n| kms.secrets.readmetadata | kms.secrets-metadata.read|\n| kms.secrets.listkeyversions | kms.secrets-key-versions.list|\n| kms.secrets.defaultalias | kms.secrets-alias.default|\n| kms.secrets.createalias | kms.secrets-alias.create|\n| kms.secrets.deletealias | kms.secrets-alias.delete|\n| kms.importtoken.create | kms.import-token.create|\n| kms.importtoken.default | kms.import-token.default|\n| kms.importtoken.read | kms.import-token.read|\n| kms.instancepolicies.write | kms.instance-policies.write|\n| kms.instancepolicies.default | kms.instance-policies.default|\n| kms.instancepolicies.read | kms.instance-policies.read|\n| kms.instance.readallowedipport | kms.instance-allowed-ip-port.read|\n| kms.instance.readipwhitelistport | kms.instance-ip-whitelist-port.read|\n| kms.keyrings.create | kms.key-rings.create|\n| kms.keyrings.delete | kms.key-rings.delete|\n| kms.keyrings.list | kms.key-rings.list|\n| kms.keyrings.default | kms.key-rings.default|\n| kms.governance.configread | kms.governance-config.read |", "version": "2.0.0", "contact": { "name": "IBM Key Protect", "url": "https://cloud.ibm.com/docs/key-protect/" }, "license": { "name": "IBM-License", "url": "http://ibm.com/LICENSE-IBM" }, "x-ibm-name": "key-protect", "x-sdk-supported-languages": [ "curl", "python", "node", "java", "go" ], "x-try-it-out-enabled": { "enabled": false, "credentials": false, "defaultApiEndpoint": "https://us-south.kms.cloud.ibm.com", "corsPolicy": true }, "x-ibm-change-notices": [ { "version": "2.0.0", "type": "breaking", "description": "As part of continued migration and improvement, the `algorithmBitSize`, `algorithmMode`, `algorithmType` and `algorithmMetadata` fields will be deprecated within the Key Protect API." } ], "x-github": "https://github.ibm.com/cloud-api-docs/key-protect", "x-github-issues": "https://github.ibm.com/cloud-api-docs/key-protect/issues/new", "x-last-updated": "2024-05-16" }, "servers": [ { "url": "https://{region}.kms.cloud.ibm.com", "variables": { "region": { "description": "The region prefix that represents the geographic area where your Key Protect service instance resides.", "default": "us-south", "enum": [ "au-syd", "br-sao", "ca-tor", "eu-de", "eu-gb", "jp-tok", "jp-osa", "us-east", "us-south" ] } } } ], "tags": [ { "name": "Keys" }, { "name": "Key actions" }, { "name": "Policies" }, { "name": "Import tokens" }, { "name": "Registrations" }, { "name": "Key events" }, { "name": "Aliases" }, { "name": "Key Rings" }, { "name": "KMIP Adapters" } ], "paths": { "/api/v2/keys": { "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "post": { "summary": "Create a key", "tags": [ "Keys" ], "description": "Creates a new key with specified key material.\n\nKey Protect designates the resource as either a root key or a standard\nkey based on the `extractable` value that you specify. A successful\n`POST /keys` operation adds the key to the service and returns the\ndetails of the request in the response entity-body, if the Prefer header\nis set to `return=representation`.", "operationId": "createKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" }, { "$ref": "#/components/parameters/KeyRingDefault" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateKeyBody" }, "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.create" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.create" } ] }, "x-codegen-request-body-name": "KeyCreateBody", "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.key+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.key+json\",\n \"name\": \"Root-key\",\n \"description\": \"A Key Protect key\",\n \"extractable\": false\n }\n ]\n }'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n // Method CreateKeyWithAliases supports creating key with aliases. To provide alias names pass array of strings to the method \n // otherwise pass nil.\n rootkey, err := api.CreateKeyWithAliases(context.Background(), , , , )\n if err != nil {\n fmt.Println(\"Error while creating key: \", err)\n return\n }\n b, _ := json.MarshalIndent(rootkey, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "lang": "node", "source": [ "// Initialize the Key Protect client as specified in Authentication\n\n// Define the key parameters\nconst body = {\n metadata: {\n collectionType: 'application/vnd.ibm.kms.key+json',\n collectionTotal: 1,\n },\n resources: [\n {\n type: 'application/vnd.ibm.kms.key+json',\n name: 'nodejsKey',\n extractable: false,\n },\n ],\n};\nconst createParams = Object.assign({}, envConfigs);\ncreateParams.body = body;\nconst response = keyProtectClient.createKey(createParams);\nconst keyId = response.result.resources[0].id;\nconsole.log('Key created, id is: ' + keyId);" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "lang": "python", "source": [ "import os\n\nimport keyprotect\nfrom keyprotect import bxauth\n\n# Initialize the Key Protect client as specified in Authentication\nkey = kp.create(name=\"\")\nprint(\"Created key '%s'\" % key[\"id\"])" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "// payload is null if not an imported key\n// payload should be base64 encoded string\n// notRootKey is false if this is a root key\npublic static String createKey(String keyName, String keyDescription, String payload, boolean notRootKey) {\n \n InputStream inputstream = null;\n CreateKeyOptions createKeyOptionsModel = null;\n \n try {\n // build json format input stream\n JsonObjectBuilder resourceObjectBuilder = Json.createObjectBuilder()\n .add(\"name\", keyName)\n .add(\"extractable\", notRootKey)\n .add(\"description\", keyDescription);\n\n // imported key\n if (payload != null) {\n resourceObjectBuilder.add(\"payload\", payload);\n }\n\n JsonObjectBuilder jsonObjectBuilder = Json.createObjectBuilder()\n .add(\"metadata\", Json.createObjectBuilder()\n .add(\"collectionType\", \"application/vnd.ibm.kms.key+json\")\n .add(\"collectionTotal\", 1))\n .add(\"resources\", Json.createArrayBuilder()\n .add(resourceObjectBuilder));\n\n JsonObject jsonObject = jsonObjectBuilder.build();\n\n inputstream = new ByteArrayInputStream(jsonObject.toString().getBytes());\n \n createKeyOptionsModel = new CreateKeyOptions.Builder()\n .bluemixInstance(\"\")\n .createKeyOneOf(inputstream)\n .prefer(\"return=representation\")\n .build();\n \n } catch(ClassCastException e) {\n System.out.println(\"Error: \" + e.toString());\n return \"failed to create key\";\n }\n \n Response response = testClient.createKey(createKeyOptionsModel).execute();\n List key = response.getResult().getResources(); \n return key.toString();\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.key+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.key+json\",\n \"name\": \"Root-key\",\n \"description\": \"Test key\",\n \"extractable\": false\n }\n ]\n}" ] } ], "responses": { "201": { "description": "The key was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false } ] } } } }, "400": { "description": "The key is missing a required field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key is missing a required field." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "There are three possible causes for HTTP 404 while trying to create\na key, specifying a reason code (resouces[0].reasons[0].code) as\nfollows:\n\nKEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note the default key ring name is \"default.\"\n\nINSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist.\n\nIMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist." }, "409": { "description": "The import token that was used to encrypt this key has reached its\n`maxAllowedRetrievals` or `expirationDate`, and it is no longer\navailable for operations. To create a new import token, use\n`POST /import_token`.\n\nIn very rare cases, the import token may expire before its\nexpiration time. Ensure that your client application is configured\nwith a retry mechanism for catching and responding to `409` conflict\nexceptions.\n\nKEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached.\n\nKEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance.\n\nKEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Key Protect only permits the creation or\nimport of keys in your Key Protect instance that follow the key creation\nand import settings listed on the keyCreateImportAccess policy.\n\nIMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: The import token that was used to encrypt this key has reached its 'maxAllowedRetrievals' or 'expirationDate', and it is no longer available for key operations. To create a new import token, use 'POST /import_token'." } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "summary": "List keys", "tags": [ "Keys" ], "description": "Retrieves a list of keys that are stored in your Key Protect service\ninstance.\n\n**Important:** When a user of Key Protect on Satellite views lists of \nkeys through the [IBM Console](https://cloud.ibm.com/login), \nor programmatically via this API, keys with [\"fine grain\" \npermissions](/docs/key-protect?topic=key-protect-grant-access-keys#grant-access-key-level) \nwon't appear due to the manner in which the service aggregates the \ncollection. While the user can still use the key resource, only by using \nthe CLI or API and passing the specific key ID can a user access the \nmetadata and other details of the key.\n\n**Note:** `GET /keys` will not return the key material in the response\nbody. You can retrieve the key material for a standard key with a\nsubsequent `GET /keys/{id}` request.", "operationId": "getKeys", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/LimitParam" }, { "$ref": "#/components/parameters/OffsetParam" }, { "$ref": "#/components/parameters/StateParam" }, { "$ref": "#/components/parameters/ExtractableParam" }, { "name": "search", "in": "query", "schema": { "type": "string", "minLength": 0, "maxLength": 256, "pattern": "^.{0,256}$" }, "description": "When provided, performs a search, possibly limiting the number of keys returned.\n*Examples*:\n\n - `foobar` - find keys where the name or any of its aliases contain `foobar`, case insentive (i.e. matches `xfoobar`, `Foobar`).\n - `fadedbee-0000-0000-0000-1234567890ab` (a valid key id) - find keys where the id the key is `fadedbee-0000-0000-0000-1234567890ab`, or the name or any of its aliases contain `fadedbee-0000-0000-0000-1234567890ab`, case insentive.\n\nMay prepend with options:\n\n - `not:` = when specified, inverts matching logic (example: `not:foo` will search for keys that have aliases or names that do not contain `foo`)\n - `escape:` = everything after this option is take as plaintext (example: `escape:not:` will search for keys that have an alias or name containing the substring `not:`)\n - `exact:` = only looks for exact matches\n\nMay prepend with search scopes:\n\n - `alias:` = search in key aliases for search query\n - `name:` = search in key names for search query\n \n*Examples*:\n\n - `not:exact:foobar`/`exact:not:foobar` - find keys where the name nor any of its aliases are *not* exactly `foobar` (i.e. matches `xfoobar`, `bar`, `foo`)\n - `exact:escape:not:foobar` - find keys where the name or any of its aliases are exactly `not:foobar`\n - `not:alias:foobar`/`alias:not:foobar` - find keys where any of its aliases do *not* contain `foobar`\n - `name:exact:foobar`/`exact:name:foobar` - find keys where the name is exactly `foobar`\n\n*Note*:\n\n By default, if no scopes are provided, search will be performed in both `name` and `alias` scopes.\n\n Search is only possible on a intial searchable space of at most 5000 keys. If the initial seachable space is greater than 5000 keys, the API returns HTTP 400 with the property resouces[0].reasons[0].code equals to 'KEY_SEARCH_TOO_BROAD'. \n Use the following filters to reduce the initial searchable space:\n \n - `state` (query parameter)\n - `extractable` (query parameter)\n - `X-Kms-Key-Ring` (HTTP header)\n\n If the total intial searchable space exceeds the 5000 keys limit and when providing a fully specified key id or when searching within the `alias` scope, a lookup\n will be performed and if a key is found, the key will be returned as the only resource and in the response metadata the property `incompleteSearch` will\n be `true`.\n\n When providing a fully specified key id or when searching within the `alias` scope, a key lookup is performed in addition to the search. \n This means search will try to lookup a single key that is uniquely identified by the key id or provided alias, this key will be included in the response\n as the first resource, before other matches. \n\n Search scopes are disjunctive, behaving in an *OR* manner. When using more than one search scope,\n a match in at least one of the scopes will result in the key being returned.\n " }, { "name": "sort", "in": "query", "schema": { "type": "string", "minLength": 2, "maxLength": 14, "enum": [ "id", "state", "extractable", "imported", "creationDate", "lastUpdateDate", "lastRotateDate", "deletionDate", "expirationDate" ], "default": "id" }, "description": "When provided, sorts the list of keys returned based on one or more key properties.\nTo sort on a property in descending order, prefix the term with \"-\". To sort on multiple key properties, use a comma to separate each properties. The first property in the comma-separated list will be evaluated before the next.\nThe key properties that can be sorted at this time are:\n - `id`\n - `state`\n - `extractable`\n - `imported`\n - `creationDate`\n - `lastUpdateDate`\n - `lastRotateDate`\n - `deletionDate`\n - `expirationDate`\n\nThe list of keys returned is sorted on id by default, if this parameter is not provided." }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/KeyRingList" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.list" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n keys, err := api.GetKeys(context.Background(), , )\n if err != nil {\n fmt.Println(\"Error while retrieving keys: \", err)\n return\n }\n b, _ := json.MarshalIndent(keys, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request with options", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n limit := uint32(5)\n offset := uint32(0)\n extractable := false\n keyStates := []kp.KeyState{kp.KeyState(kp.Active), kp.KeyState(kp.Suspended)}\n\n\n listKeysOptions := &kp.ListKeysOptions{\n Limit : &limit,\n Offset : &offset,\n Extractable : &extractable,\n State : keyStates,\n }\n\n keys, err := client.ListKeys(ctx, listKeysOptions)\n if err != nil {\n fmt.Println(err)\n }\n fmt.Println(keys)\n}" ] } ] }, { "name": "Example request with sorting", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n srtStr, _ := kp.GetKeySortStr(kp.WithCreationDate(), WithImportedDesc())\n\n listKeysOptions := &kp.ListKeysOptions{\n Sort:srtStr,\n }\n\n keys, err := client.ListKeys(ctx, listKeysOptions)\n if err != nil {\n fmt.Println(err)\n }\n\n fmt.Println(keys)\n}" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "lang": "python", "source": [ "import os\n\nimport keyprotect\nfrom keyprotect import bxauth\n\n# Initialize the Key Protect client as specified in Authentication\nkeys = kp.keys()\nfor key in kp.keys():\n print(\"%s\\t%s\" % (key[\"id\"], key[\"name\"]))" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "lang": "node", "source": [ "// Initialize the Key Protect client as specified in Authentication\n\nconst response = keyProtectClient.getKeys(envConfigs);\nconsole.log('Get keys result:');\nfor (let resource of response.result.resources){\n console.log(resource);\n}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "public static List getKeys() {\n GetKeysOptions getKeysOptionsModel = new GetKeysOptions.Builder()\n .bluemixInstance(\"\")\n .build();\n Response response = testClient.getKeys(getKeysOptionsModel).execute();\n List keys = response.getResult().getResources();\n return keys;\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The list of keys was successfully retrieved.", "headers": { "Key-Total": { "schema": { "type": "integer", "minimum": 0, "description": "The number of keys in your service instance." } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKeys" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 2 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "lastRotateDate": "2000-03-21T00:00:00Z", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false }, { "type": "application/vnd.ibm.kms.key+json", "id": "addedace-0000-0000-0000-1234567890ab", "name": "Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:addedace-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false }, { "type": "application/vnd.ibm.kms.key+json", "id": "beadcafe-0000-0000-0000-1234567890ab", "name": "Deleted-Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 5, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:beadcafe-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": true, "deletionDate": "2000-03-21T00:00:00Z", "restoreAllowed": true, "restoreExpirationDate": "2000-03-21T00:00:00Z", "purgeAllowed": false, "purgeAllowedFrom": "2000-03-21T00:00:00Z", "purgeScheduledOn": "2000-03-21T00:00:00Z" } ] } } } }, "400": { "description": "If reason code (resouces[0].reasons[0].code) is present and is equal to 'KEY_SEARCH_TOO_BROAD', the total searchable space is more than 5000 keys.\nTry using a filter to reduce the seachable space." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "head": { "summary": "Retrieve key total", "tags": [ "Keys" ], "description": "Returns the same HTTP headers as a GET request without returning the entity-body. This operation returns the number of keys in your instance in a header called `Key-Total`.", "operationId": "getKeyCollectionMetadata", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/StateParam" }, { "$ref": "#/components/parameters/ExtractableParam" }, { "$ref": "#/components/parameters/Filter" }, { "$ref": "#/components/parameters/KeyRingList" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.head" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.head" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -I HEAD \\\n https://.kms.cloud.ibm.com/api/v2/keys \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The metadata was successfully retrieved.", "headers": { "Key-Total": { "schema": { "type": "integer", "minimum": 0, "description": "The number of keys in your service instance." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys_with_policy_overrides": { "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "post": { "summary": "Create a key with policy overrides", "tags": [ "Keys" ], "description": "Creates a new key with specified key material and key policies. This API overrides the policy configurations set at instance level with policies provided in the payload.\nKey Protect designates the resource as a root key or a standard key based on the extractable value that you specify.\nA successful `POST /keys_with_policy_overrides` operation adds the key and key policies to the service and returns the\ndetails of the request in the response entity-body, if the Prefer header\nis set to `return=representation`.", "operationId": "createKeyWithPoliciesOverrides", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" }, { "$ref": "#/components/parameters/KeyRingDefault" } ], "requestBody": { "$ref": "#/components/requestBodies/CreateKeyWithPolicyOverridesBody" }, "x-ibm-permissions": { "actions": [ { "name": "kms.secrets-with-policy-overrides.create" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets-with-policy-overrides.create" } ] }, "x-codegen-request-body-name": "KeyWithPolicyOverridesCreateBody", "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys_with_policy_overrides \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.key+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.key+json\",\n \"name\": \"Root-key\",\n \"description\": \"A Key Protect key\",\n \"extractable\": false,\n \"dualAuthDelete\": {\n \"enabled\": true\n },\n \"rotation\":{\n \"enabled\": true,\n \"interval_month\": 6\n }\n }\n ]\n }'" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.key+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.key+json\",\n \"name\": \"Root-key-With-Policies\",\n \"description\": \"Test key\",\n \"extractable\": false,\n \"dualAuthDelete\": {\n \"enabled\": true\n },\n \"rotation\":{\n \"enabled\": true,\n \"interval_month\": 6\n }\n }\n ]\n}" ] } ], "responses": { "201": { "description": "The key was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, "rotation": { "interval_month": 3 }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false } ] } } } }, "400": { "description": "The key is either missing a required field or it may contain an invalid or malformed input.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key is missing a required field." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "There are three possible causes for HTTP 404 while trying to create\na key, specifying a reason code (resouces[0].reasons[0].code) as\nfollows:\n\nKEY_RING_NOT_FOUND_ERR: The key cannot be created because the key ring does not exist. Note the default key ring name is \"default.\"\nINSTANCE_NOT_FOUND_ERR: The key cannot be created because the instance does not exist.\nIMPORT_TOKEN_NOT_FOUND_ERR: The key cannot be created because the import token does not exist." }, "409": { "description": "The import token that was used to encrypt this key has reached its\n`maxAllowedRetrievals` or `expirationDate`, and it is no longer\navailable for operations. To create a new import token, use\n`POST /import_token`.\nIn very rare cases, the import token may expire before its\nexpiration time. Ensure that your client application is configured\nwith a retry mechanism for catching and responding to `409` conflict\nexceptions.\nKEY_ALIAS_QUOTA_ERR: The alias quota for this key has been reached.\nKEY_ALIAS_NOT_UNIQUE_ERR: One or more aliases are already associated with a key in the instance.\nKEY_CREATE_IMPORT_ACCESS_ERR: KeyCreateImportAccess instance policy is enabled. Key Protect only permits the creation or\nimport of keys in your Key Protect instance that follow the key creation\nand import settings listed on the keyCreateImportAccess policy.\nIMPORT_TOKEN_EXPIRED_ERR: The key cannot be created because the import token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: The import token that was used to encrypt this key has reached its 'maxAllowedRetrievals' or 'expirationDate', and it is no longer available for key operations. To create a new import token, use 'POST /import_token'." } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}": { "parameters": [ { "$ref": "#/components/parameters/KeyId" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "get": { "summary": "Retrieve a key", "tags": [ "Keys" ], "description": "Retrieves a key and its details by specifying the ID or alias of the key.", "operationId": "getKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.read" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys/ \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n key, err := api.GetKey(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while retrieving the key: \", err)\n return\n }\n b, _ := json.MarshalIndent(key, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "lang": "node", "source": [ "// Initialize the Key Protect client as specified in Authentication\n\nconst getKeyParams = Object.assign({}, envConfigs);\ngetKeyParams.id = \"\";\nconst response = keyProtectClient.getKey(getKeyParams);\nconsole.log('Get key result: ');\nconsole.log(response.result.resources[0]);" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "lang": "python", "source": [ "import os\n\nimport keyprotect\nfrom keyprotect import bxauth\n\n# Initialize the Key Protect client as specified in Authentication\nkey = kp.get(\"\")\nprint(\"%s\\t%s\" % (key[\"id\"], key[\"name\"]))" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "public static List getKey(String keyId) {\n GetKeyOptions getKeyOptionsModel = new GetKeyOptions.Builder()\n .bluemixInstance(\"\")\n .id(keyId)\n .build();\n Response response = testClient.getKey(getKeyOptionsModel).execute();\n List key = response.getResult().getResources();\n return key;\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The key was successfully retrieved. If the key was previously deleted, `keyVersion.creationDate` is omitted from the request response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetKey" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false, "payload": "x089YbmN9GSvpxEKe0LaqA==" } ] } } } }, "400": { "description": "The key could not be retrieved due to a malformed, invalid, or missing ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key could not be retrieved due to a malformed, invalid, or missing ID." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The key could not be found. Verify that the key ID specified is valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. Verify that the key ID specified is valid." } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Invoke an action on a key", "tags": [ "Keys" ], "description": "**Note:** This API has been **deprecated** and transitioned to\nindividual request paths. Existing actions using this API will continue\nto be supported, but new actions will no longer be added to it. We\nrecommend, if possible, aligning your request URLs to the new API path.\nThe generic format of actions is now the following:\n`/api/v2/keys//actions/` where `key_ID` is the key you\nwant to operate on/with and `action` is the same action that was passed\nas a query parameter previously.\n\nInvokes an action on a specified key. This method supports the following\nactions:\n\n- `disable`: [Disable operations](/docs/key-protect?topic=key-protect-disable-keys) for a key\n- `enable`: [Enable operations](/docs/key-protect?topic=key-protect-disable-keys#enable-api) for a key\n- `restore`: [Restore a root key](/docs/key-protect?topic=key-protect-restore-keys)\n- `rewrap`: Use a root key to [rewrap or reencrypt a data encryption key](/docs/key-protect?topic=key-protect-rewrap-keys)\n- `rotate`: [Create a new version](/docs/key-protect?topic=key-protect-rotate-keys) of a root key\n- `setKeyForDeletion`: [Authorize deletion](/docs/key-protect?topic=key-protect-delete-dual-auth-keys#set-key-deletion-api) for a key with a dual authorization policy\n- `unsetKeyForDeletion`: [Remove an authorization](/docs/key-protect?topic=key-protect-delete-dual-auth-keys#unset-key-deletion-api) for a key with a dual authorization policy\n- `unwrap`: Use a root key to [unwrap or decrypt a data encryption key](/docs/key-protect?topic=key-protect-unwrap-keys)\n- `wrap`: Use a root key to [wrap or encrypt a data encryption key](/docs/key-protect?topic=key-protect-wrap-keys)\n\n**Note:** If you unwrap a wrapped data encryption key (WDEK) that was not \nwrapped by the latest version of the key, the service also returns the a \nnew WDEK, wrapped with the latest version of the key as the ciphertext field. \nThe recommendation is to store and use that WDEK, although older WDEKs will continue to work.", "operationId": "actionOnKey", "deprecated": true, "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "action", "in": "query", "description": "The action to perform on the specified key.", "schema": { "type": "string", "enum": [ "disable", "enable", "restore", "rewrap", "rotate", "setKeyForDeletion", "unsetKeyForDeletion", "unwrap", "wrap" ], "minLength": 4, "maxLength": 19 }, "required": true }, { "$ref": "#/components/parameters/Prefer" } ], "requestBody": { "$ref": "#/components/requestBodies/KeyActionBody" }, "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.disable" }, { "name": "kms.secrets.enable" }, { "name": "kms.secrets.restore" }, { "name": "kms.secrets.rewrap" }, { "name": "kms.secrets.rotate" }, { "name": "kms.secrets.setkeyfordeletion" }, { "name": "kms.secrets.unsetkeyfordeletion" }, { "name": "kms.secrets.unwrap" }, { "name": "kms.secrets.wrap" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.disable" }, { "name": "kms.secrets.enable" }, { "name": "kms.secrets.restore" }, { "name": "kms.secrets.rewrap" }, { "name": "kms.secrets.rotate" }, { "name": "kms.secrets.setkeyfordeletion" }, { "name": "kms.secrets.unsetkeyfordeletion" }, { "name": "kms.secrets.unwrap" }, { "name": "kms.secrets.wrap" } ] }, "x-codegen-request-body-name": "KeyActionBody", "responses": { "200": { "description": "Successful key operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyActionOneOfResponse" }, "examples": { "WrapKey": { "value": { "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" } } } } } } }, "201": { "description": "The imported key was successfully restored.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Key" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": true, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false } ] } } } }, "204": { "description": "Successful key operation." }, "400": { "description": "Your authentication data or key is invalid, or the entity-body is missing a required field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Your authentication data or key is invalid, or the entity-body is missing a required field." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The key is not in an appropriate state, so the KeyAction has failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: The key is not in an appropriate state, so the KeyAction has failed." } ] } } } }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "description": "The ciphertext provided for the unwrap operation was not wrapped by this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unprocessable Entity: The ciphertext provided for the unwrap operation was not wrapped by this key." } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "patch": { "summary": "Update (patch) a key", "tags": [ "Keys" ], "description": "Update attributes of a key. Currently only the following attributes are applicable for update: - keyRingID Note: If provided, the `X-Kms-Key-Ring` header should specify the key's current key ring. To change the key ring of the key, specify the new key ring in the request body.", "operationId": "patchKey", "security": [ { "BearerAuth": [] } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PATCH \\\n https://.kms.cloud.ibm.com/api/v2/keys/ \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key+json' \\\n -d '{\n \"keyRingID\": \"new-key-ring\"\n }'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n keyDetails, err := api.SetKeyRing(context.Background(), , )\n if err != nil {\n fmt.Println(\"Error while updating the key: \", err)\n return\n }\n b, _ := json.MarshalIndent(keyDetails, \"\", \" \",)\n fmt.Println(string(b))\n}" ] } ] } ] } }, "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.patch" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.patch" } ] }, "x-codegen-request-body-name": "KeyPatchBody", "requestBody": { "description": "The base request for patch key.", "required": false, "content": { "application/vnd.ibm.kms.key+json": { "schema": { "$ref": "#/components/schemas/PatchKeyRequestBody" }, "example": { "keyRingID": "new-key-ring-id" } } } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "header", "name": "X-Kms-Key-Ring", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"keyRingID\": \"new-key-ring\"\n}" ] } ], "responses": { "200": { "description": "Successful key update.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchKeyResponseBody" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "new-key-ring-id", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "There are two possible causes for HTTP 404 while trying to update a key, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_NOT_FOUND_ERR: The key could not be found.\nKEY_RING_NOT_FOUND_ERR: Key could not be updated, key ring specified does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be restored. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Delete a key", "tags": [ "Keys" ], "description": "Deletes a key by specifying the ID or alias of the key.\n\nBy default, Key Protect requires a single authorization to delete keys.\nFor added protection, you can\n[enable a dual authorization policy](#set-key-policies)\nto safely delete keys from your service instance.\n\n**Important:** After a key has been deleted, any data that is encrypted by the key becomes inaccessible, though this can be reversed if the key is \nrestored within the 30-day time frame. After 30 days, key metadata, \nregistrations, and policies are available for up to 90 days, at which \npoint the key becomes eligible to be purged. Note that once a key is no \nlonger restorable and has been purged, its associated data can no longer \nbe accessed.\n\n**Note:** By default, Key Protect blocks the deletion of a key that's\nprotecting a cloud resource, such as a Cloud Object Storage bucket. Use\n`GET keys/{id}/registrations` to verify if the key has an active\nregistration to a resource. To delete the key and its associated\nregistrations, set the optional `force` parameter to `true`.", "operationId": "deleteKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" }, { "$ref": "#/components/parameters/Force" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.delete" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://.kms.cloud.ibm.com/api/v2/keys/ \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n force := false // set this to true if force-delete is needed\n delKey, err := client.DeleteKey(context.Background(), key.ID, kp.ReturnRepresentation, kp.ForceOpt{Force: force})\n if err != nil {\n fmt.Println(\"Error while deleting the key: \", err)\n return\n }\n b, _ := json.MarshalIndent(delKey, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "lang": "node", "source": [ "// Initialize the Key Protect client as specified in Authentication\n\nconst deleteKeyParams = Object.assign({}, envConfigs);\ndeleteKeyParams.id = \"\";\ndeleteKeyParams.prefer = 'return=representation';\nconst response = keyProtectClient.deleteKey(deleteKeyParams);\nconsole.log('Delete key response status: ' + response.status);" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "lang": "python", "source": [ "import os\n\nimport keyprotect\nfrom keyprotect import bxauth\n\n# Initialize the Key Protect client as specified in Authentication\ndeletedKey = kp.delete(\"\")\nprint(\"Deleted key '%s'\" % key_id)" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "public static DeleteKey deleteKey(String keyId, Boolean forceDelete) {\n \n Boolean deleteForceParam = false;\n if (forceDelete != null) {\n deleteForceParam = forceDelete;\n }\n \n DeleteKeyOptions deleteKeyOptionsModel = new DeleteKeyOptions.Builder()\n .bluemixInstance(\"\")\n .id(keyId)\n .force(deleteForceParam)\n .build();\n Response response = testClient.deleteKey(deleteKeyOptionsModel).execute();\n DeleteKey result = response.getResult();\n return result; // null result on success \n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The key was successfully deleted. The status code is the only response, unless the `prefer` parameter contains `return=representation`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteKey" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 5, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "lastRotateDate": "2000-03-21T00:00:00Z", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": true, "deletionDate": "2000-03-21T00:00:00Z", "deletedBy": "IBMid-0000000000", "restoreAllowed": true, "restoreExpirationDate": "2000-03-21T00:00:00Z", "purgeAllowed": false, "purgeAllowedFrom": "2000-03-21T00:00:00Z", "purgeScheduledOn": "2000-03-21T00:00:00Z" } ] } } } }, "204": { "description": "The key was successfully deleted. No content. The status code is the only response, unless the `prefer` parameter contains `return=representation`." }, "400": { "description": "The key cannot be deleted due to a malformed, invalid, or missing ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key cannot be deleted due to a malformed, invalid, or missing ID." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "There are three possible causes for HTTP 409 while trying to delete\na key, specifying a reason code (resouces[0].reasons[0].code) as\nfollows: \n\nAUTHORIZATIONS_NOT_MET: The key cannot be deleted because it failed\nthe dual authorization request. Before you delete this key, make\nsure dual authorization procedures are followed. See the topic,\n[Deleting keys using dual authorization](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-dual-auth-keys).\n\nPROTECTED_RESOURCE_ERR: The key cannot be deleted because the key\nhas one or more associated resources. See the topic, [Considerations\nbefore deleting and purging a key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-purge-keys#delete-purge-keys-considerations).\n\nPREV_KEY_DEL_ERR: The key cannot be deleted because it's protecting\na cloud resource that has a retention policy. Before you delete this\nkey, contact an account owner to remove the retention policy on each\nresource that is associated with the key. See the topic, [Considerations before deleting and purging a key](https://cloud.ibm.com/docs/key-protect?topic=key-protect-delete-purge-keys#delete-purge-keys-considerations).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key could not be deleted. See 'reasons' for more details.", "reasons": [ { "code": "PREV_KEY_DEL_ERR", "message": "The key cannot be deleted because it's protecting a cloud resource that has a retention policy. Before you delete this key, contact an account owner to remove the retention policy on each resource that is associated with the key.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/metadata": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "get": { "summary": "Retrieve key metadata", "tags": [ "Keys" ], "description": "Retrieves the details of a key by specifying the ID of the key.", "operationId": "getKeyMetadata", "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.readmetadata" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets-metadata.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys//metadata \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n keyMetadata, err := api.GetKeyMetadata(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while retrieving key metadata: \", err)\n return\n }\n b, _ := json.MarshalIndent(keyMetadata, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "public static GetKeyMetadata getKeyMetadata(String keyId) {\n GetKeyMetadataOptions getKeyMetadataOptionsModel = new GetKeyMetadataOptions.Builder()\n .id(keyId)\n .bluemixInstance(\"\")\n .build();\n Response response = testClient.getKeyMetadata(getKeyMetadataOptionsModel).execute();\n GetKeyMetadata metadata = response.getResult();\n \n return metadata;\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The key metadata was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetKeyMetadata" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Standard-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": true, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false } ] } } } }, "400": { "description": "The key metadata could not be retrieved due to a malformed, invalid, or missing ID or alias.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key metadata could not be retrieved due to a malformed, invalid, or missing ID." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "The key metadata for the key with specified ID could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key metadata could not be retrieved. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/purge": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "delete": { "summary": "Purge a deleted key", "tags": [ "Keys" ], "description": "Purges all key metadata and registrations associated with the specified key. This method requires setting the [_KeyPurge_ permission](https://cloud.ibm.com/docs/key-protect?topic=key-protect-grant-access-keys#grant-access-keys-specific-functions) that is not enabled by default. Purging a key can only be applied to a key in the **Destroyed** (5) state. After a key is deleted, there is a wait period of up to four hours before purge key operation is allowed. \n**Important:** When you purge a key, you permanently shred its contents and associated data. The action cannot be reversed. ", "operationId": "purgeKey", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.purge" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.purge" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://.kms.cloud.ibm.com/api/v2/keys//purge \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n purgedKey, err := api.PurgeKey(context.Background(), , kp.ReturnRepresentation)\n if err != nil {\n fmt.Println(\"Error while purging key : \", err)\n return\n }\n b, _ := json.MarshalIndent(purgedKey, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The key was successfully purged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PurgeKey" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 5, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "lastRotateDate": "2000-03-21T00:00:00Z", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": true, "deletionDate": "2000-03-21T00:00:00Z", "deletedBy": "IBMid-0000000000", "purgeAllowed": true, "purgeAllowedFrom": "2000-03-21T00:00:00Z", "purgeScheduledOn": "2000-03-21T00:00:00Z" } ] } } } }, "204": { "description": "The key was successfully purged. No content." }, "400": { "description": "The key cannot be purged due to a malformed ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The key cannot be purged due to a malformed ID." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "There are two possible causes for HTTP 409 while trying to delete a key, specifying a reason code (resouces[0].reasons[0].code) as follows:\nREQ_TOO_EARLY_ERR: The key could not be purged due to wait period of four hours has not been reached.\nKEY_ACTION_INVALID_STATE_ERR: The key could not be purged because it is not in the Destroyed (5) state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key could not be purged. See 'reasons' for more details.", "reasons": [ { "code": "KEY_INVALID_STATE_ERR", "message": "Key is not in a valid state.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/restore": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Restore a key", "description": "[Restore a key](/docs/key-protect?topic=key-protect-restore-keys) that has been deleted.", "operationId": "restoreKey", "tags": [ "Keys" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.restore" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.restore" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example restore key request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//restore \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key_action_restore+json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n restoredKey, err := api.RestoreKey(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while restoring key: \", err)\n return\n }\n b, _ := json.MarshalIndent(restoredKey, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "java": [ { "name": "Example restore key request", "example": [ { "type": "code", "lang": "java", "source": [ "public static KeyActionOneOfResponse restoreKey(String keyId) {\n InputStream inputStream = null;\n ActionOnKeyOptions restoreKeyOptionsModel = null;\n Response response = null;\n KeyActionOneOfResponse responseObj = null;\n\n try {\n // Only imported root keys can be restored; if the file conforms to the\n // SecureRestoreKeyRequestBody format, include the encryption method,\n // encrypted payload, encrypted nonce, and initialization vector.\n inputStream = new FileInputStream(\"/path/to/file.txt\");\n restoreKeyOptionsModel = new ActionOnKeyOptions.Builder()\n .id(keyId)\n .bluemixInstance(\"\")\n .action(\"restore\")\n .keyActionOneOf(inputStream)\n .prefer(\"return=minimal\")\n .build();\n } catch(FileNotFoundException e) {\n System.out.println(\"File not found: \" + e.toString());\n return responseObj;\n }\n\n response = testClient.actionOnKey(restoreKeyOptionsModel).execute();\n responseObj = response.getResult();\n return responseObj;\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.key_action_restore+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"payload\": \"\",\n \"encryptedNonce\": \"\",\n \"iv\": \"\",\n \"encryptionAlgorithm\": \"\"\n }\n ]\n}" ] } ], "responses": { "201": { "description": "The key was successfully restored.", "content": { "application/vnd.ibm.kms.key+json": { "schema": { "$ref": "#/components/schemas/Key" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "id": "fadedbee-0000-0000-0000-1234567890ab", "name": "Root-key", "aliases": [ "alias-for-this-key" ], "description": "A Key Protect key", "state": 1, "extractable": false, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": true, "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": "256", "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "2000-03-21T00:00:00Z", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "2000-03-21T00:00:00Z" }, "deleted": false } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be restored. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "There are three possible causes for HTTP 409 while trying to restore a key, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_ACTION_INVALID_STATE_ERR: The requested key is not in the `Destroyed` (5) [state](/docs/key-protect?topic=key-protect-key-states).\nREQ_TOO_EARLY_ERR: Key could not be restored. The key was updated recently, wait and try again. Restoring a key is only allowed when 30 seconds after key is deleted has passed.\nKEY_RING_RESOURCE_QUOTA_ERR: Key could not be restored. The resource quota for key rings in this instance has been reached and key rings cannot be created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be restored. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/versions": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "get": { "summary": "List key versions", "tags": [ "Keys" ], "description": "Retrieves all versions of a root key by specifying the ID or alias of the key.\n\nWhen you rotate a root key, you generate a new version of the key. If\nyou're using the root key to protect resources across IBM Cloud, the\nregistered cloud services that you associate with the key use the\nlatest key version to wrap your data.\n[Learn more](/docs/key-protect?topic=key-protect-key-rotation).", "operationId": "getKeyVersions", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/KeyVersionsLimitParam" }, { "$ref": "#/components/parameters/KeyVersionsOffsetParam" }, { "$ref": "#/components/parameters/KeyVersionsTotalCount" }, { "$ref": "#/components/parameters/KeyVersionsAllKeyStates" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.listkeyversions" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets-key-versions.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys//versions \\\n -H 'accept: application/vnd.ibm.kms.key.version+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "public static List getKeyVersions(String keyId) {\n GetKeyVersionsOptions getKeyVersionsOptionsModel = new GetKeyVersionsOptions.Builder()\n .id(keyId)\n .bluemixInstance(\"\")\n .build();\n Response response = testClient.getKeyVersions(getKeyVersionsOptionsModel ).execute();\n List details = response.getResult().getResources();\n return details;\n}" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n limit := uint32(2)\n offset := uint32(0)\n totalCount := true\n\n listkeyVersionsOptions := &kp.ListKeyVersionsOptions{\n Limit : &limit,\n Offset : &offset,\n TotalCount : &totalCount,\n }\n\n keyVersions, err := client.ListKeyVersions(ctx, \"key_id_or_alias\", listkeyVersionsOptions)\n if err != nil {\n fmt.Println(err)\n }\n\n fmt.Println(keyVersions)\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The list of key versions was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKeyVersions" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 2, "totalCount": 4 }, "resources": [ { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" }, { "id": "addedace-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The key is not in an active state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: The key is not in an active state." } ] } } } }, "410": { "$ref": "#/components/responses/Gone" } } } }, "/api/v2/keys/{id}/actions/wrap": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Wrap a key", "description": "Use a root key to [wrap or encrypt a data encryption key](/docs/key-protect?topic=key-protect-wrap-keys).\nWhen present, the ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect.", "operationId": "wrapKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.wrap" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.wrap" } ] }, "x-codegen-request-body-name": "KeyActionWrapBody", "requestBody": { "description": "The base request for wrap key action.", "required": false, "content": { "application/vnd.ibm.kms.key_action_wrap+json": { "schema": { "$ref": "#/components/schemas/WrapKeyRequestBody" }, "example": { "plaintext": "", "aad": [ "", "" ] } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example wrap request (generated DEK)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/wrap \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key_action_wrap+json'" ] } ] }, { "name": "Example wrap request with provided plaintext", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/wrap \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key_action_wrap+json' \\\n -d '{\n \"plaintext\": \"\",\n \"aad\": [\"\", \"\"]\n }'" ] } ] } ], "go": [ { "name": "Example wrap request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n aad := []string{\"\", \"\"}\n plaintext := []byte()\n ciphertext, err := api.Wrap(context.Background(), , plaintext, &aad)\n if err != nil {\n fmt.Println(\"Error wrapping the key: \", err)\n return\n }\n fmt.Println(string(ciphertext))\n}" ] } ] } ], "node": [ { "name": "Example wrap request", "example": [ { "type": "code", "lang": "node", "source": [ "// Initialize the Key Protect client as specified in Authentication\n\n// Wrap and unwrap base64 encoded plaintext using key\nconst samplePlaintext = 'dGhpcyBpcyBhIGJhc2U2NCBzdHJpbmcK'; // base64 encoded plaintext\n\nconst wrapKeyParams = Object.assign({}, envConfigs);\nwrapKeyParams.id = \"\";\nwrapKeyParams.keyActionWrapBody = {\n plaintext: samplePlaintext,\n};\n\nconst response = keyProtectClient.wrapKey(wrapKeyParams);\nconsole.log('Wrap key response cipher: ' + response.result.ciphertext);\nconst ciphertextResult = response.result.ciphertext; // saved for the unwrap example" ] } ] } ], "python": [ { "name": "Example wrap request", "example": [ { "type": "code", "lang": "python", "source": [ "import os\n\nimport keyprotect\nfrom keyprotect import bxauth\n\n# Initialize the Key Protect client as specified in Authentication\n\nkey = kp.create(name=\"MyRootKey\", root=True)\n\n# payload should be a bytestring\nmessage = b'This is an important test message.'\nwrapped = kp.wrap(key.get('id'), message)\nciphertext = wrapped.get(\"ciphertext\")" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"plaintext\": \"\",\n \"aad\": []\n}" ] } ], "responses": { "200": { "description": "The key was successfully wrapped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WrapKeyResponseBody" }, "example": { "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" } } } } }, "400": { "description": "The request is malformed or illegal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Wrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field 'plaintext' must be a base64 encoded key material.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "plaintext" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Wrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist.", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "The key is not in the `Active` (1) [state](/docs/key-protect?topic=key-protect-key-states).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Wrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Wrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/unwrap": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Unwrap a key", "description": "Use a root key to\n[unwrap or decrypt a data encryption key](/docs/key-protect?topic=key-protect-unwrap-keys).\n\n**Note:** When you unwrap a wrapped data encryption key (WDEK) by using\na rotated root key, the service returns a new ciphertext in the response\nentity-body. Each ciphertext remains available for `unwrap` actions. If\nyou unwrap a DEK with a previous ciphertext, the service also returns\nthe latest ciphertext and latest key version in the response. Use the\nlatest ciphertext for future unwrap operations.", "operationId": "unwrapKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.unwrap" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.unwrap" } ] }, "x-codegen-request-body-name": "KeyActionUnwrapBody", "requestBody": { "description": "The base request for unwrap key action.", "required": true, "content": { "application/vnd.ibm.kms.key_action_unwrap+json": { "schema": { "$ref": "#/components/schemas/UnwrapKeyRequestBody" }, "example": { "ciphertext": "", "aad": [ "", "" ] } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example unwrap request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/unwrap \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key_action_unwrap+json' \\\n -d '{\n \"ciphertext\": \"\",\n \"aad\": [\"\", \"\"]\n }'" ] } ] } ], "go": [ { "name": "Example unwrap request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n aad := []string{\"\", \"\"}\n ciphertext := []byte()\n pt2, err := api.Unwrap(context.Background(), , ciphertext, &aad)\n if err != nil {\n fmt.Println(\"Error while unwrapping DEK: \", err)\n return\n }\n b, _ := json.MarshalIndent(pt2, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "node": [ { "name": "Example unwrap request", "example": [ { "type": "code", "lang": "node", "source": [ "// Initialize the Key Protect client as specified in Authentication\n\nconst unwrapKeyParams = Object.assign({}, envConfigs);\nunwrapKeyParams.id = \"\";\nunwrapKeyParams.keyActionUnwrapBody = {\n ciphertext: ciphertextResult, // encrypted result from wrap key response\n};\nconst response = keyProtectClient.unwrapKey(unwrapKeyParams);\nconsole.log('Unwrap key response result: ' + response.result.plaintext); // validate that result is same as above" ] } ] } ], "python": [ { "name": "Example unwrap request", "example": [ { "type": "code", "lang": "python", "source": [ "import os\n\nimport keyprotect\nfrom keyprotect import bxauth\n\n# Continue from example for wrap key\n# key = kp.create(name=\"MyRootKey\", root=True)\n# message = b'This is a really important message.'\n\nunwrapped = kp.unwrap(key.get('id'), ciphertext)\nassert message == unwrapped" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"ciphertext\": \"\",\n \"aad\": []\n}" ] } ], "responses": { "200": { "description": "Successfully unwrapped key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnwrapKeyResponseBody" }, "example": { "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" } } } } }, "400": { "description": "The request is malformed or illegal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Unwrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "MISSING_FIELD_ERR", "message": "The field 'ciphertext' is required.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "name" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Unwrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "The key is not in the `Active` (1) or `Deactivated` (3) [state](/docs/key-protect?topic=key-protect-key-states).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Wrap action could not be performed with the key. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Unwrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "422": { "description": "The ciphertext provided was not wrapped by this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unprocessable Entity: Unwrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "UNPROCESSABLE_CIPHERTEXT_ERR", "message": "The provided ciphertext is invalid or corrupted.", "status": 422, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/rewrap": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Rewrap a key", "description": "Use a root key to [rewrap or reencrypt a data encryption key](/docs/key-protect?topic=key-protect-rewrap-keys).", "operationId": "rewrapKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.rewrap" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.rewrap" } ] }, "x-codegen-request-body-name": "KeyActionRewrapBody", "requestBody": { "description": "The base request for rewrap key action.", "required": true, "content": { "application/vnd.ibm.kms.key_action_rewrap+json": { "schema": { "$ref": "#/components/schemas/RewrapKeyRequestBody" }, "example": { "ciphertext": "", "aad": [ "", "" ] } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/rewrap \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key_action_rewrap+json' \\\n -d '{\n \"ciphertext\": \"\",\n \"aad\": [\"\", \"\"]\n }'" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"ciphertext\": \"\",\n \"aad\": []\n}" ] } ], "responses": { "200": { "description": "The key was successfully rewrapped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewrapKeyResponseBody" }, "example": { "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab" }, "rewrappedKeyVersion": { "id": "addedace-0000-0000-0000-1234567890ab" } } } } }, "400": { "description": "The request is malformed or illegal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Rewrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field 'ciphertext' must be the original base64 encoded ciphertext from the wrap operation.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "ciphertext" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Rewrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "The key is not in the `Active` (1) or `Deactivated` (3) [state](/docs/key-protect?topic=key-protect-key-states).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Rewrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Rewrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "422": { "description": "The ciphertext provided was not wrapped by this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unprocessable Entity: Rewrap with key could not be performed. See 'reasons' for more details.", "reasons": [ { "code": "UNPROCESSABLE_CIPHERTEXT_ERR", "message": "The provided ciphertext is invalid or corrupted", "status": 422, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/rotate": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Rotate a key", "description": "[Create a new version](/docs/key-protect?topic=key-protect-rotate-keys) of a root key.", "operationId": "rotateKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.rotate" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.rotate" } ] }, "x-codegen-request-body-name": "KeyActionRotateBody", "requestBody": { "description": "The base request for rotate key action.", "required": false, "content": { "application/vnd.ibm.kms.key_action_rotate+json": { "schema": { "$ref": "#/components/schemas/RotateKeyOneOf" }, "examples": { "RotateKey": { "$ref": "#/components/examples/RotateKey" }, "SecureRotateKey": { "$ref": "#/components/examples/SecureRotateKey" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example key rotate request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/rotate \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example imported key rotate request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/rotate \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key_action_rotate+json' \\\n -d '{\n \"payload\": \"\"\n }'" ] } ] }, { "name": "Example secure imported key rotate request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/rotate \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.key_action_rotate+json' \\\n -d '{\n \"payload\": \"\",\n \"encryptedNonce\": \"\",\n \"iv\": \"\",\n \"encryptionAlgorithm\": \"RSAES_OAEP_SHA_256\"\n }'" ] } ] } ], "go": [ { "name": "Example key rotate request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n // Set the payload to a base64 encoded string if your key is an imported root key\n // Skip setting payload if your key is a generated root key\n payload := \"\"\n err = api.Rotate(context.Background(), , payload)\n if err != nil {\n fmt.Println(\"Error rotating the key: \", err)\n return\n }\n fmt.Println(\"Key successfully rotated\")\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"payload\": \"\",\n \"encryptedNonce\": \"\",\n \"iv\": \"\",\n \"encryptionAlgorithm\": \"\"\n}" ] } ], "responses": { "204": { "description": "The key was successfully rotated. No content." }, "400": { "description": "The request is malformed or illegal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be rotated. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field 'payload' must be: a base64 encoded value", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "payload" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "There are three possible causes for HTTP 404 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_NOT_FOUND_ERR: The key could not be found.\nINSTANCE_NOT_FOUND_ERR: Key could not be rotated, specified instance does not exist.\nIMPORT_TOKEN_NOT_FOUND_ERR: Key could not be rotated, import_token does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be rotated. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "There are four possible causes for HTTP 409 while trying to rotate a key, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_ACTION_INVALID_STATE_ERR: The requested key is not in the `Active` (1) or `Deactivated` (3) [state](/docs/key-protect?topic=key-protect-key-states).\nKEY_ROTATION_NOT_PERMITTED: Key could not be rotated, this key has been rotated within the last hour, only one rotate action per hour is permitted.\nKEY_CREATE_IMPORT_ACCESS_ERR: Instance policy does not allow this action.\nIMPORT_TOKEN_EXPIRED_ERR: Key could not be rotated, the import token has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be rotated. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be rotated. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/setKeyForDeletion": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Set a key for deletion", "description": "[Authorize deletion](/docs/key-protect?topic=key-protect-delete-dual-auth-keys#set-key-deletion-api) for a key with a dual authorization policy.", "operationId": "setKeyForDeletion", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.setkeyfordeletion" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.setkeyfordeletion" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example set key for deletion request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/setKeyForDeletion \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err := api.InitiateDualAuthDelete(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while initiating dual auth delete for key: \", err)\n return\n }\n fmt.Println(\"Key successfully initiated for dual auth delete\")\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "204": { "description": "The key was successfully set for deletion. No content." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "There are two possible causes for HTTP 404 while trying to set a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_NOT_FOUND_ERR: The key could not be found. DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key deletion could not be scheduled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "The key does not have a dual-authorization delete policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key deletion could not be scheduled. See 'reasons' for more details.", "reasons": [ { "code": "NOT_DUAL_AUTH_ERR", "message": "The key is not dual auth enabled and cannot be set for deletion.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key deletion could not be scheduled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/unsetKeyForDeletion": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Unset a key for deletion", "description": "[Remove an authorization](/docs/key-protect?topic=key-protect-delete-dual-auth-keys#unset-key-deletion-api) for a key with a dual authorization policy.", "operationId": "unsetKeyForDeletion", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.unsetkeyfordeletion" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.unsetkeyfordeletion" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example unset key for deletion request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/unsetKeyForDeletion \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err := api.CancelDualAuthDelete(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while cancelling dual auth delete for key: \", err)\n return\n }\n fmt.Println(\"Key successfully cancelled for dual auth delete\")\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "204": { "description": "The key was successfully unset for deletion. No content." }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "There are two possible causes for HTTP 404 while trying to unset a key for deletion, specifying a reason code (resouces[0].reasons[0].code) as follows: KEY_NOT_FOUND_ERR: The key could not be found. DUAL_AUTH_POLICY_NOT_FOUND_ERR: Dual authorization policy is not enabled for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key deletion could not be cancelled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "The key does not have a dual-authorization delete policy.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key deletion could not be cancelled. See 'reasons' for more details.", "reasons": [ { "code": "NOT_DUAL_AUTH_ERR", "message": "The key is not dual auth enabled and cannot be set for deletion", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key deletion could not be cancelled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/enable": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Enable a key", "description": "[Enable operations](/docs/key-protect?topic=key-protect-disable-keys#enable-api) for a key.", "operationId": "enableKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.enable" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.enable" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example enable key request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/enable \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err := api.EnableKey(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while enabling the key: \", err)\n return\n }\n fmt.Println(\"Key successfully enabled\")\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "204": { "description": "The key was successfully enabled. No content." }, "400": { "description": "The request is malformed or illegal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be enabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ROOT_REQ_ERR", "message": "Requested action can only be completed with a root key.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be enabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist.", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "There are two possible causes for HTTP 409 while trying to enable a key, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_ACTION_INVALID_STATE_ERR: The requested key is not in the `Suspended` (2) [state](/docs/key-protect?topic=key-protect-key-states) or the state of the key has changed within the last 30 seconds.\nREQ_TOO_EARLY_ERR: Key could not be enabled, as the key was updated recently. After key is disabled, the event must fully propagate before enabling key operations. Wait and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be enabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be enabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/disable": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Disable a key", "description": "[Disable operations](/docs/key-protect?topic=key-protect-disable-keys) for a key.", "operationId": "disableKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.disable" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.disable" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example disable key request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/disable \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err := api.DisableKey(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while disabling the key: \", err)\n return\n }\n fmt.Println(\"Key successfully disabled\")\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "204": { "description": "The key was successfully disabled. No content." }, "400": { "description": "The request is malformed or illegal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Key could not be disabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ROOT_REQ_ERR", "message": "Requested action can only be completed with a root key.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Key could not be disabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "The requested key is not in the `Active` (1) [state](/docs/key-protect?topic=key-protect-key-states).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Key could not be disabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ACTION_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "410": { "description": "The requested key was previously deleted and is no longer available. The key may be restored within thirty (30) days of deletion using `POST /keys/{id}/restore`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: Key could not be disabled. See 'reasons' for more details.", "reasons": [ { "code": "KEY_DELETED_ERR", "message": "Key has already been deleted. Delete references to this key.", "status": 410, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/actions/sync": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Sync associated resources", "description": "Initiate a [manual data synchronization](/docs/key-protect?topic=key-protect-sync-associated-resources&interface=api) request to the associated\nresources of a key. Regular key lifecycle events automatically notify\nintegrated services of any change. However, in the case a service does\nnot respond to a key lifecycle event notification after four hours, the\n`sync` API may be used to initiate a renotification to the integrated\nservices that manage the associated resources linked to the key.\n\n**Note:** The services that manage the associated resources linked to\nthe key are responsible for maintaining current records of the key\nstate and version. Key Protect does not have the ability to force data\nsynchronization for other services, which may take up to four hours to\ncomplete. The `sync` API is meant to **initiate** a request for all\nassociated resources to synchronize their key records with the\ninformation returned from the Key Protect API.", "operationId": "syncAssociatedResources", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.sync" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets.sync" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example sync associated resources request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//actions/sync \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "204": { "description": "The sync of associate resources for a key has been initiated. No content." }, "400": { "description": "The request is malformed or illegal.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: Associated resources could not be synced. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ROOT_REQ_ERR", "message": "Requested action can only be completed with a root key.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "There are two possible causes for HTTP 404 for the synchronization request, the reason code (resources[0].reasons[0].code) as follows:\nKEY_NOT_FOUND: The specified key could not be found. NOT_SUPPORTED_IN_SATELLITE_LOCATION: The synchronization request for the specified key is not supported in this location.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: Associated resources could not be synced. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND_ERR", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "The key has been synced or updated (i.e. rotated, restored, disabled, enabled, deleted) within the last hour.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: Associated resources could not be synced. See 'reasons' for more details.", "reasons": [ { "code": "REQ_TOO_EARLY_ERR", "message": "The key was updated recently. Wait and try again.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/policies": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "put": { "summary": "Set key policies", "tags": [ "Policies" ], "description": "Creates or updates one or more policies for the specified key.\n\nYou can set policies for a key, such as an\n[automatic rotation policy](/docs/key-protect?topic=key-protect-set-rotation-policy)\nor a\n[dual authorization policy](/docs/key-protect?topic=key-protect-set-dual-auth-key-policy)\nto protect against the accidental deletion of keys. Use\n`PUT /keys/{id}/policies` to create new policies for a key or update an\nexisting policy.", "operationId": "putPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/KeyPolicyType" } ], "requestBody": { "$ref": "#/components/requestBodies/KeyCreateUpdatePolicyBody" }, "x-ibm-permissions": { "actions": [ { "name": "kms.policies.write" } ] }, "x-ibm-events": { "events": [ { "name": "kms.policies.write" } ] }, "x-codegen-request-body-name": "KeyPolicyPutBody", "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/keys//policies \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 2\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.policy+json\",\n \"rotation\": {\n \"enabled\": ,\n \"interval_month\": \n }\n },\n {\n \"type\": \"application/vnd.ibm.kms.policy+json\",\n \"dualAuthDelete\": {\n \"enabled\": \n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (dual authorization policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/keys//policies?policy=dualAuthDelete \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.policy+json\",\n \"dualAuthDelete\": {\n \"enabled\": \n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (rotation policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/keys//policies?policy=rotation \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.policy+json\",\n \"rotation\": {\n \"enabled\": ,\n \"interval_month\": \n }\n }\n ]\n }'" ] } ] } ], "go": [ { "name": "Example request (multiple policies)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n // Pass setRotationPolicy as true if setting rotation policy otherwise false\n // Pass setDualAuthDeletePolicy as true if setting dual authorization policy otherwise false\n // Pass dualAuthEnabled as true to enable or false to disable the dual auth delete policy.\n policies, err := api.SetPolicies(context.Background(), , , , , )\n if err != nil {\n fmt.Println(\"Error while setting the policies: \", err)\n return\n }\n b, _ := json.MarshalIndent(policies, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (rotation policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.SetRotationPolicy(context.Background(), , )\n if err != nil {\n fmt.Println(\"Error while setting rotation policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (dual authorization policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n // Pass enabled as true to set the policy and false to unset the policy\n policy, err := api.SetDualAuthDeletePolicy(context.Background(), , )\n if err != nil {\n fmt.Println(\"Error while setting dual auth delete policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 2\n },\n \"resources\": [\n {\n \"type\": \"application/vnd.ibm.kms.policy+json\",\n \"rotation\": {\n \"enabled\": ,\n \"interval_month\": 3\n }\n },\n {\n \"type\": \"application/vnd.ibm.kms.policy+json\",\n \"dualAuthDelete\": {\n \"enabled\": \n }\n }\n ]\n}" ] } ], "responses": { "200": { "description": "The policy or policies were successfully created or updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetKeyPoliciesOneOf" }, "examples": { "policies": { "$ref": "#/components/examples/GetMultipleKeyPolicies" }, "dualAuthDelete": { "$ref": "#/components/examples/GetKeyPolicyDualAuthDelete" }, "rotation": { "$ref": "#/components/examples/GetKeyPolicyRotation" } } } } }, "204": { "description": "The policy or policies were successfully created or updated. No content." }, "400": { "description": "The policy or policies cannot be created or updated due to a malformed, invalid, or missing ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "410": { "$ref": "#/components/responses/Gone" }, "422": { "description": "The key with specified ID is invalid for use with policies.\n\nA key must be a root key (non-extractable) in the Activated (1)\nstate.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key policy could not be created. See `reasons` for more details.", "reasons": [ { "code": "KEY_INVALID_STATE_ERR", "message": "Key is not in a valid state", "status": 422, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "summary": "List key policies", "tags": [ "Policies" ], "description": "Retrieves a list of policies that are associated with a specified key.\n\nYou can set policies for a key, such as an\n[automatic rotation policy](/docs/key-protect?topic=key-protect-set-rotation-policy)\nor a\n[dual authorization policy](/docs/key-protect?topic=key-protect-set-dual-auth-key-policy)\nto protect against the accidental deletion of keys. Use\n`GET /keys/{id}/policies` to browse the policies that exist for a\nspecified key.", "operationId": "getPolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/KeyPolicyType" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.policies.read" } ] }, "x-ibm-events": { "events": [ { "name": "kms.policies.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request (all key policies)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys//policies \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (dual authorization policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys//policies?policy=dualAuthDelete \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (rotation policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys//policies?policy=rotation \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request (all key policies)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policies, err := api.GetPolicies(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while getting policies: \", err)\n return\n }\n b, _ := json.MarshalIndent(policies, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (rotation policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.GetRotationPolicy(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while getting rotation policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (dual auth delete policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.GetDualAuthDeletePolicy(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while getting dual auth delete policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The policy resources were successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetKeyPoliciesOneOf" }, "examples": { "policies": { "$ref": "#/components/examples/GetMultipleKeyPolicies" }, "dualAuthDelete": { "$ref": "#/components/examples/GetKeyPolicyDualAuthDelete" }, "rotation": { "$ref": "#/components/examples/GetKeyPolicyRotation" } } } } }, "400": { "description": "The request is missing a required field or contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/instance/policies": { "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "put": { "summary": "Set instance policies", "tags": [ "Policies" ], "description": "Creates or updates one or more policies for the specified service\ninstance.\n\n**Note:** When you set an instance policy, Key Protect associates the\npolicy information with keys that you add to the instance after the\npolicy is updated. This operation does not affect existing keys in the\ninstance.", "operationId": "putInstancePolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InstancePolicyType" } ], "requestBody": { "$ref": "#/components/requestBodies/InstanceCreateUpdatePolicyBody" }, "x-ibm-permissions": { "actions": [ { "name": "kms.instancepolicies.write" } ] }, "x-ibm-events": { "events": [ { "name": "kms.instance-policies.write" } ] }, "x-codegen-request-body-name": "InstancePolicyPutBody", "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 6\n },\n \"resources\": [\n {\n \"policy_type\": \"allowedNetwork\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"allowed_network\": \"\"\n }\n }\n },\n {\n \"policy_type\": \"dualAuthDelete\",\n \"policy_data\": {\n \"enabled\": \n }\n },\n {\n \"policy_type\": \"allowedIP\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"allowed_ip\": [\"X.X.X.X/N\", \"X.X.X.X/N\"]\n }\n }\n },\n {\n \"policy_type\": \"keyCreateImportAccess\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"create_root_key\": ,\n \"create_standard_key\": ,\n \"import_root_key\": ,\n \"import_standard_key\": ,\n \"enforce_token\": \n }\n }\n },\n {\n \"policy_type\": \"metrics\",\n \"policy_data\": {\n \"enabled\": \n }\n },\n {\n \"policy_type\": \"rotation\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"interval_month\": \n }\n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (allowed network policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedNetwork \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"policy_type\": \"allowedNetwork\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"allowed_network\": \"\"\n }\n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (dual authorization policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"policy_type\": \"dualAuthDelete\",\n \"policy_data\": {\n \"enabled\": \n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (metrics)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"policy_type\": \"metrics\",\n \"policy_data\": {\n \"enabled\": \n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (allowed IP policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedIP \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"policy_type\": \"allowedIP\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"allowed_ip\": [\"X.X.X.X/N\", \"X.X.X.X/N\"]\n }\n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (key create and import access policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"policy_type\": \"keyCreateImportAccess\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"create_root_key\": ,\n \"create_standard_key\": ,\n \"import_root_key\": ,\n \"import_standard_key\": ,\n \"enforce_token\": \n }\n }\n }\n ]\n }'" ] } ] }, { "name": "Example request (rotation)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=rotation \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.policy+json' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"policy_type\": \"rotation\",\n \"policy_data\": {\n \"enabled\": ,\n \"attributes\": {\n \"interval_month\": \n }\n }\n }\n ]\n }'" ] } ] } ], "go": [ { "name": "Example request (all policies)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n // Pass multiple_policies as an object of kp.MultiplePolicies setting\n // the policies accordingly.\n multiple_policies := kp.MultiplePolicies{\n DualAuthDelete: &kp.BasicPolicyData{\n Enabled: \n },\n AllowedNetwork: &kp.AllowedNetworkPolicyData{\n Enabled: ,\n Network: \"\",\n },\n AllowedIP: &kp.AllowedIPPolicyData{\n Enabled: ,\n IPAddresses: <[]string{,}>\n }\n Metrics: &kp.BasicPolicyData{\n Enabled: \n }.\n KeyCreateImportAccess: &kp.KeyCreateImportAccessInstancePolicy{\n Enabled: ,\n CreateRootKey: ,\n CreateStandardKey: ,\n ImportRootKey: ,\n ImportStandardKey: ,\n EnforceToken: \n }\n }\n err = api.SetPolicies(context.Background(), multiple_policies)\n if err != nil {\n fmt.Println(\"Error while setting policies: \", err)\n return\n }\n fmt.Println(\"Instance policies set successfully\")\n}" ] } ] }, { "name": "Example request (allowedIP policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n allowedIPs := []string{,}\n err = api.SetAllowedIPInstancePolicy(context.Background(), , allowedIPs)\n if err != nil {\n fmt.Println(\"Error while setting allowed IP policy: \", err)\n return\n }\n fmt.Println(\"Allowed IP instance policy set successfully\")\n}" ] } ] }, { "name": "Example request (allowed network policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n networkType := \"\"\n err = api.SetAllowedNetworkInstancePolicy(context.Background(), , networkType)\n if err != nil {\n fmt.Println(\"Error while setting allowed network policy: \", err)\n return\n }\n fmt.Println(\"Allowed network instance policy set successfully\")\n}" ] } ] }, { "name": "Example request (dual authorization policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err = api.SetDualAuthInstancePolicy(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while setting dual authorization policy: \", err)\n return\n }\n fmt.Println(\"Dual auth instance policy set successfully\")\n}" ] } ] }, { "name": "Example request (key create import access policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n // Pass true to set the policy or false to unset the policy\n attributes := map[string]bool{\n kp.CreateRootKey: ,\n kp.CreateStandardKey: ,\n kp.ImportRootKey: ,\n kp.ImportStandardKey: ,\n kp.EnforceToken: ,\n }\n err = api.SetKeyCreateImportAccessInstancePolicy(context.Background(), , attributes)\n if err != nil {\n fmt.Println(\"Error while setting key create import access policy: \", err)\n return\n }\n fmt.Println(\"Key create import access instance policy set successfully\")\n}" ] } ] }, { "name": "Example request (metrics policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err = api.SetMetricsInstancePolicy(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while setting metrics policy: \", err)\n return\n }\n fmt.Println(\"Metrics instance policy set successfully\")\n}" ] } ] }, { "name": "Example request (rotation policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n intervalMonth := 3\n enable := true\n\n err := client.SetRotationInstancePolicy(context.Background(), enable, &intervalMonth)\n if err != nil {\n fmt.Println(err)\n }\n\n rotationInstancePolicy, err := client.GetRotationInstancePolicy(context.Background())\n if err != nil {\n fmt.Println(err)\n }\n fmt.Println(rotationInstancePolicy)\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "path", "name": "id", "value": "" }, { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "body", "name": "body", "value": [ "{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.policy+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"policy_type\": \"dualAuthDelete\",\n \"policy_data\": {\n \"enabled\": \n }\n }\n ]\n}" ] } ], "responses": { "204": { "description": "The policy or policies were successfully created or updated. No content." }, "400": { "description": "The policy or policies cannot be created or updated due to a malformed or invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "There are two possible causes for HTTP 403 while trying to set instance policies, specifying a reason code (resouces[0].reasons[0].code) as follows:\nFEATURE_RESTRICTED_ERR: Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect.\nCONFIG_RULE_CONFLICT_ERR: Instance policy could not be created, requested change is not compliant with configuration rules." }, "410": { "$ref": "#/components/responses/Gone" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "summary": "List instance policies", "tags": [ "Policies" ], "description": "Retrieves a list of policies that are associated with a specified\nservice instance.\n\nYou can manage advanced preferences for keys in your service instance by\ncreating instance-level policies. Use `GET /instance/policies` to browse\nthe policies that are associated with the specified instance. Currently,\ndual authorization policies are supported.", "operationId": "getInstancePolicy", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/InstancePolicyType" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.instancepolicies.read" } ] }, "x-ibm-events": { "events": [ { "name": "kms.instance-policies.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (allowed network policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedNetwork \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (dual authorization policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=dualAuthDelete \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (allowedIP)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=allowedIP \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (key create and import access policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=keyCreateImportAccess \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (metrics)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=metrics \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] }, { "name": "Example request (rotation)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/policies?policy=rotation \\\n -H 'accept: application/vnd.ibm.kms.policy+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request (all policies)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policies, err := api.GetInstancePolicies(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting policies: \", err)\n return\n }\n b, _ := json.MarshalIndent(policies, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (allowedIP policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.GetAllowedIPInstancePolicy(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting allowed IP policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (allowedNetwork policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.GetAllowedNetworkInstancePolicy(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting allowed network policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (dual authorization policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.GetDualAuthInstancePolicy(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting dual auth policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (key create import access policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.GetKeyCreateImportAccessInstancePolicy(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting key create import access policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] }, { "name": "Example request (metrics policy)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n policy, err := api.GetMetricsInstancePolicy(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting metrics policy: \", err)\n return\n }\n b, _ := json.MarshalIndent(policy, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The policy resources were successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInstancePoliciesOneOf" }, "examples": { "policies": { "$ref": "#/components/examples/GetMultipleInstancePolicies" }, "allowedNetwork": { "$ref": "#/components/examples/GetInstancePolicyAllowedNetwork" }, "dualAuthDelete": { "$ref": "#/components/examples/GetInstancePolicyDualAuthDelete" }, "allowedIP": { "$ref": "#/components/examples/GetInstancePolicyAllowedIP" }, "keyCreateImportAccess": { "$ref": "#/components/examples/GetInstancePolicyKeyCreateImportAccess" }, "metrics": { "$ref": "#/components/examples/GetInstancePolicyMetrics" }, "rotation": { "$ref": "#/components/examples/GetInstancePolicyRotation" } } } } }, "400": { "description": "The request is missing a required field or contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/instance/allowed_ip_port": { "get": { "summary": "Retrieve allowed IP port", "tags": [ "Policies" ], "description": "Retrieves the private endpoint port associated with your service instance's active allowed IP policy. If the instance does not contain an active allowed IP policy, no information will be returned.", "operationId": "getAllowedIPPort", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.instance.readallowedipport" } ] }, "x-ibm-events": { "events": [ { "name": "kms.instance-allowed-ip-port.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/instance/allowed_ip_port \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.allowed_ip_port+json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n port, err := api.GetAllowedIPPrivateNetworkPort(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting allowed IP private port: \", err)\n return\n }\n fmt.Printf(\"Port number: %d\", port)\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The allowed IP port information was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllowedIPPort" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.allowed_ip_metadata+json", "collectionTotal": 1 }, "resources": [ { "private_endpoint_port": 8888 } ] } } } }, "400": { "description": "The request is missing a required field or contains invalid values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/import_token": { "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingDefault" } ], "post": { "summary": "Create an import token", "tags": [ "Import tokens" ], "description": "Creates an import token that you can use to encrypt and import root keys\ninto the service.\n[Learn more](/docs/key-protect?topic=key-protect-importing-keys#using-import-tokens).\n\nWhen you call `POST /import_token`, Key Protect creates an RSA key-pair\nfrom its HSMs. The service encrypts and stores the private key in the\nHSM, and returns the corresponding public key when you call\n`GET /import_token`. You can create only one import token per service\ninstance.", "operationId": "postImportToken", "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.importtoken.create" } ] }, "x-ibm-events": { "events": [ { "name": "kms.import-token.create" } ] }, "requestBody": { "description": "The base request to create an import token.", "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportToken" } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/import_token \\\n -H 'accept: application/vnd.ibm.collection+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json' \\\n -d '{\n \"expiration\": \"\",\n \"maxAllowedRetrievals\": \n }'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n importToken, err := api.CreateImportToken(context.Background(), , )\n if err != nil {\n fmt.Println(\"Error while creating import token: \", err)\n return\n }\n b, _ := json.MarshalIndent(importToken, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The import token was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportToken" }, "example": { "creationDate": "2000-03-21T00:00:00Z", "expirationDate": "2000-03-21T00:00:00Z", "maxAllowedRetrievals": 10, "remainingRetrievals": 10 } } } }, "400": { "description": "The import token cannot be created due to a malformed or invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "summary": "Retrieve an import token", "tags": [ "Import tokens" ], "description": "Retrieves the import token that is associated with your service\ninstance.\n\nWhen you call `GET /import_token`, Key Protect returns the public key\nthat you can use to encrypt and import key material to the service,\nalong with details about the key.\n\n**Note:** After you reach the `maxAllowedRetrievals` or `expirationDate`\nfor the import token, the import token and its associated public key can\nno longer be used for key operations. To create a new import token, use\n`POST /import_token`.", "operationId": "getImportToken", "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.importtoken.read" } ] }, "x-ibm-events": { "events": [ { "name": "kms.import-token.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/import_token \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/vnd.ibm.kms.import_token+json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n importToken, err := api.GetImportTokenTransportKey(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting import token: \", err)\n return\n }\n b, _ := json.MarshalIndent(importToken, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The import token was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetImportToken" }, "example": { "creationDate": "2000-03-21T00:00:00Z", "expirationDate": "2000-03-21T00:00:00Z", "maxAllowedRetrievals": 10, "remainingRetrievals": 9, "payload": "QUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUE=", "nonce": "8zJE9pKVdXVe/nLb" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "There are two possible causes for HTTP 404 while trying to retrieve an import token, specifying a reason code (resouces[0].reasons[0].code) as follows:\nIMPORT_TOKEN_NOT_FOUND_ERR: An import token was not found in the specified service instance. To create an import token, use `POST /import_token`.\nINSTANCE_NOT_FOUND_ERR: Import token could not be retrieved, instance does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not found: An import token was not found in the specified service instance. To create an import token, use 'POST /import_token'." } ] } } } }, "409": { "description": "The import token has reached its `maxAllowedRetrievals` or\n`expirationDate`, and it is no longer available for use. To create a\nnew import token, use `POST /import_token`.\n\nIn very rare cases, the import token may expire before its\nexpiration time. Ensure that your client application is configured\nwith a retry mechanism for catching and responding to `409` conflict\nexceptions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: The import token has reached its 'maxAllowedRetrievals' or 'expirationDate'. To create a new import token, use 'POST /import_token'." } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/{id}/registrations/{urlEncodedResourceCRN}": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/UrlEncodedResourceCRN" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ] }, "/api/v2/keys/{id}/registrations": { "parameters": [ { "$ref": "#/components/parameters/KeyId" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "get": { "summary": "List registrations for a key", "tags": [ "Registrations" ], "description": "Retrieves a list of registrations that are associated with a specified\nroot key.\n\nWhen you use a root key to protect an IBM Cloud resource, such as a\nCloud Object Storage bucket, Key Protect creates a registration between\nthe resource and root key. You can use `GET /keys/{id}/registrations` to\nunderstand which cloud resources are protected by the key that you\nspecify.", "operationId": "getRegistrations", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/RegistrationsLimitParam" }, { "$ref": "#/components/parameters/RegistrationsOffsetParam" }, { "$ref": "#/components/parameters/UrlEncodedResourceCRNQuery" }, { "$ref": "#/components/parameters/PreventKeyDeletion" }, { "$ref": "#/components/parameters/TotalCount" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.registrations.list" } ] }, "x-ibm-events": { "events": [ { "name": "kms.registrations.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys//registrations \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request (list registrations of a key)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n registrations, err := api.ListRegistrations(context.Background(), , \"\")\n if err != nil {\n fmt.Println(\"Error while getting registrations: \", err)\n return\n }\n b, _ := json.MarshalIndent(registrations, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "responses": { "200": { "description": "The list of registrations was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationWithTotalCount" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.registration+json", "collectionTotal": 2, "totalCount": 4 }, "resources": [ { "keyId": "fadedbee-0000-0000-0000-1234567890ab", "keyName": "Root-key", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z", "description": "Registration between a bucket and root key", "preventKeyDeletion": false, "keyVersion": { "id": "addedace-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" } }, { "keyId": "fadedbee-0000-0000-0000-1234567890ab", "keyName": "Root-key", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z", "description": "Registration between the root key and a different bucket", "preventKeyDeletion": false, "keyVersion": { "id": "addedace-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" } } ] } } } }, "400": { "description": "The list of registrations could not be retrieved due to a malformed `urlEncodedResourceCRN`, an invalid or missing request body, or an invalid key ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Registration could not be deleted. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_PARAM_ERR", "message": "The param 'urlEncodedResourceCRNQuery' must be: specified to at least the service instance.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "urlEncodedResourceCRNQuery" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRegistration" }, "404": { "description": "The key with specified ID could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Registration could not be created. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND", "message": "Key does not exist.", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/keys/registrations": { "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingList" } ], "get": { "summary": "List registrations for any key", "tags": [ "Registrations" ], "description": "Retrieves a list of registrations that match the Cloud Resource Name\n(CRN) query that you specify.\n\nWhen you use a root key to protect an IBM Cloud resource, such as a\nCloud Object Storage bucket, Key Protect creates a registration between\nthe resource and root key. You can use `GET /keys/registrations` to\nunderstand which cloud resources are protected by keys in your Key\nProtect service instance.", "operationId": "getRegistrationsAllKeys", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/UrlEncodedResourceCRNQueryOptional" }, { "$ref": "#/components/parameters/RegistrationsLimitParam" }, { "$ref": "#/components/parameters/RegistrationsOffsetParam" }, { "$ref": "#/components/parameters/PreventKeyDeletion" }, { "$ref": "#/components/parameters/TotalCount" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.registrations.list" } ] }, "x-ibm-events": { "events": [ { "name": "kms.registrations.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/keys/registrations?urlEncodedResourceCRNQuery= \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request (list registrations of any key)", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n registrations, err := api.ListRegistrations(context.Background(), \"\", )\n if err != nil {\n fmt.Println(\"Error while getting registrations: \", err)\n return\n }\n b, _ := json.MarshalIndent(registrations, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ] } }, "responses": { "200": { "description": "The list of registrations was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationWithTotalCount" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.registration+json", "collectionTotal": 2, "totalCount": 4 }, "resources": [ { "keyId": "fadedbee-0000-0000-0000-1234567890ab", "keyName": "Root-key", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z", "description": "Registration between a bucket and root key", "preventKeyDeletion": false, "keyVersion": { "id": "addedace-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" } }, { "keyId": "beadcafe-0000-0000-0000-1234567890ab", "keyName": "Root-key", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z", "description": "Registration between a bucket and root key", "preventKeyDeletion": false, "keyVersion": { "id": "beadcafe-0000-0000-0000-1234567890ab", "creationDate": "2000-03-21T00:00:00Z" } } ] } } } }, "400": { "description": "The list of registrations could not be retrieved due to a malformed `urlEncodedResourceCRNQuery`, an invalid or missing request body, or a mismatch between the cloud service CRN and the resource CRN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Registration could not be deleted. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_PARAM_ERR", "message": "The param 'urlEncodedResourceCRNQuery' must be: specified to at least the service instance.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "urlEncodedResourceCRNQuery" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/ForbiddenRegistration" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/event_ack": { "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingDefault" } ] }, "/api/v2/keys/{id}/aliases/{alias}": { "parameters": [ { "$ref": "#/components/parameters/KeyIdOrAlias" }, { "$ref": "#/components/parameters/Alias" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KeyRingSingleKey" } ], "post": { "summary": "Create an alias", "tags": [ "Aliases" ], "description": "Creates a unique alias for the specified key.", "operationId": "createKeyAlias", "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.createalias" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets-alias.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/keys//aliases/ \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n keyAlias, err := api.CreateKeyAlias(context.Background(), , )\n if err != nil {\n fmt.Println(\"Error while creating key alias name: \", err)\n return\n }\n b, _ := json.MarshalIndent(keyAlias, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "public static List createKeyAlias(String keyId_or_alias, String keyAlias) {\n List responseObj = null;\n \n try {\n // Construct an instance of the CreateKeyAliasOptions model\n CreateKeyAliasOptions createKeyAliasOptionsModel = new CreateKeyAliasOptions.Builder()\n .id(keyId_or_alias)\n .alias(keyAlias)\n .bluemixInstance(\"\")\n .build();\n\n // Invoke operation with valid options model\n Response response = testClient.createKeyAlias(createKeyAliasOptionsModel).execute();\n responseObj = response.getResult().getResources();\n } catch (ClassCastException e) {\n System.out.println(\"Error: \" + e.toString());\n return responseObj; // null if error\n }\n return responseObj; // key alias resource\n}" ] } ] } ] } }, "responses": { "200": { "description": "An identical alias was previously created for the specified key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyAlias" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.alias+json", "collectionTotal": 1 }, "resources": [ { "keyId": "fadedbee-0000-0000-0000-1234567890ab", "alias": "my-alias", "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z" } ] } } } }, "201": { "description": "A new alias was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyAlias" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.alias+json", "collectionTotal": 1 }, "resources": [ { "keyId": "fadedbee-0000-0000-0000-1234567890ab", "alias": "my-alias", "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z" } ] } } } }, "400": { "description": "The alias could not be created due to a malformed `alias` or an invalid key ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be created. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param 'alias' must be: alphanumeric, and no spaces or special characters other than '-' or '_', and can not be a version 4 UUID.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "aliases" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "There are two possible causes for HTTP 404 while trying to create an alias, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_NOT_FOUND_ERR: The key with specified ID could not be found.\nINSTANCE_NOT_FOUND_ERR: Key alias could not be created, instance does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be created. See 'reasons' for more details.", "reasons": [ { "code": "KEY_NOT_FOUND", "message": "Key does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "409": { "description": "There are three possible causes for HTTP 409 while trying to create\nan alias, specifying a reason code (resouces[0].reasons[0].code) as\nfollows:\n\nKEY_ALIAS_QUOTA_ERR: The alias quota for this key or instance has been\nreached and alias can not be created.\n\nKEY_RING_RESOURCE_QUOTA_ERR: Key alias could not be created, the resource\nquota for key rings in this instance has been reached and alais\ncan not be created.\n\nKEY_ALIAS_NOT_UNIQUE_ERR: The alias is already associated with a key in the specified instance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key alias could not be created. See 'reasons' for more details.", "reasons": [ { "code": "KEY_ALIAS_NOT_UNIQUE_ERR", "message": "One or more aliases are already associated with a key in the instance.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Delete an alias", "tags": [ "Aliases" ], "description": "Deletes an alias from the associated key.\n\nDelete alias does not delete the key.", "operationId": "deleteKeyAlias", "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "kms.secrets.deletealias" } ] }, "x-ibm-events": { "events": [ { "name": "kms.secrets-alias.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://.kms.cloud.ibm.com/api/v2/keys//aliases/ \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err := api.DeleteKeyAlias(context.Background(), , )\n if err != nil {\n fmt.Println(\"Error while deleting key alias name: \", err)\n return\n }\n fmt.Println(\"Key alias successfully deleted\")\n}" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "public static String deleteKeyAlias (String keyId_or_alias, String keyAlias) {\n\n // Construct an instance of the DeleteKeyAliasOptions model\n DeleteKeyAliasOptions deleteKeyAliasOptionsModel = new DeleteKeyAliasOptions.Builder()\n .id(keyId_or_alias)\n .alias(keyAlias)\n .bluemixInstance(\"\")\n .build();\n\n // Invoke operation with valid options model\n try {\n return testClient.deleteKeyAlias(deleteKeyAliasOptionsModel).execute().toString() + \" success\";\n } catch (ClassCastException e){\n return e.toString();\n }\n}" ] } ] } ] } }, "responses": { "204": { "description": "An alias was successfully deleted. No content." }, "400": { "description": "The alias could not be deleted due to a malformed `alias` or an invalid key ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be deleted. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The param 'alias' must be: alphanumeric, and no spaces or special characters other than '-' or '_', and can not be a version 4 UUID.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "aliases" } } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "There are two possible causes for HTTP 404 while trying to delete an alias, specifying a reason code (resouces[0].reasons[0].code) as follows:\nALIAS_NOT_FOUND_ERR: The alias with specified key ID could not be found.\nINSTANCE_NOT_FOUND_ERR: Key alias could not be deleted, instance does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Alias could not be deleted. See 'reasons' for more details.", "reasons": [ { "code": "ALIAS_NOT_FOUND", "message": "Alias does not exist", "status": 404, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/key_rings": { "parameters": [ { "$ref": "#/components/parameters/KeyRingLimitParam" }, { "$ref": "#/components/parameters/KeyRingOffsetParam" }, { "$ref": "#/components/parameters/KeyRingTotalCount" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "get": { "summary": "List key rings", "tags": [ "Key Rings" ], "description": "List all key rings in the instance.", "operationId": "listKeyRings", "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.keyrings.list" } ] }, "x-ibm-events": { "events": [ { "name": "kms.key-rings.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example list key rings", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/key_rings \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n keyRings, err := api.GetKeyRings(context.Background())\n if err != nil {\n fmt.Println(\"Error while getting key rings: \", err)\n return\n }\n b, _ := json.MarshalIndent(keyRings, \"\", \" \")\n fmt.Println(string(b))\n}" ] } ] } ], "java": [ { "name": "Example list key rings", "example": [ { "type": "code", "lang": "java", "source": [ "public static ListKeyRingsWithTotalCount getKeyRings () {\n ListKeyRingsWithTotalCount result = null;\n\n // Construct an instance of the ListKeyRingsWithTotalCountOptions model\n ListKeyRingsWithTotalCountOptions listKeyRingsWithTotalCountOptionsModel = new ListKeyRingsWithTotalCountOptions.Builder()\n .bluemixInstance(\"\")\n .build();\n\n try {\n // Invoke operation with valid options model\n Response response = testClient.listKeyRingsWithTotalCount(listKeyRingsWithTotalCountOptionsModel).execute();\n return response.getResult();\n } catch (ClassCastException e) {\n return result;\n }\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" } ], "responses": { "200": { "description": "The list of key rings was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKeyRingsWithTotalCount" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.key_ring+json", "collectionTotal": 3, "totalCount": 4 }, "resources": [ { "id": "default" }, { "id": "example-key-ring", "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000" }, { "id": "key-ring-name-2", "creationDate": "2000-03-21T00:00:00Z", "createdBy": "IBMid-0000000000" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/key_rings/{key-ring-id}": { "parameters": [ { "$ref": "#/components/parameters/KeyRingId" }, { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "post": { "summary": "Create a key ring", "tags": [ "Key Rings" ], "description": "Create a key ring in the instance with the specified name. The key ring ID `default` is a reserved key ring ID and cannot be created nor destroyed. The `default` key ring is an initial key ring that is generated with each newly created instance. All keys not associated with an otherwise specified key ring exist within the default key ring.", "operationId": "createKeyRing", "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.keyrings.create" } ] }, "x-ibm-events": { "events": [ { "name": "kms.key-rings.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example create Key Ring", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/key_rings/ \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err := api.CreateKeyRing(context.Background(), )\n if err != nil {\n fmt.Println(\"Error while creating key ring: \", err)\n return\n }\n fmt.Println(\"Key ring successfully created\")\n}" ] } ] } ], "java": [ { "name": "Example create Key Ring", "example": [ { "type": "code", "lang": "java", "source": [ "public static KeyRing createKeyRing (String keyRingId) {\n KeyRing result = null;\n\n // Construct an instance of the CreateKeyRingOptions model\n CreateKeyRingOptions createKeyRingOptionsModel = new CreateKeyRingOptions.Builder()\n .keyRingId(keyRingId)\n .bluemixInstance(\"\")\n .build();\n\n try {\n // Invoke operation with valid options model\n Response response = testClient.createKeyRing(createKeyRingOptionsModel).execute();\n System.out.println(\"Prelim: \" + response.toString());\n result = response.getResult();\n return result;\n } catch (ClassCastException e) {\n return result;\n }\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "path", "name": "key-ring-id", "value": "" } ], "responses": { "201": { "description": "The key ring was successfully created." }, "204": { "description": "The key ring already exists. No content." }, "400": { "description": "The key ring could not be created due to invalid request data.", "content": { "application/json": { "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. See `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `id` must be: a string matching pattern `^[a-zA-Z0-9-]*$`.", "status": 400, "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "key-ring-id" } } ] } ] }, "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Key ring resource quota has been reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. See `reasons` for more details.", "reasons": [ { "code": "KEY_RING_RESOURCE_QUOTA_ERR", "message": "The resource quota for key rings in this instance has been reached/exceeded and key rings cannot be created.", "status": 409, "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Delete key ring", "tags": [ "Key Rings" ], "description": "Delete the key ring from the instance. The key ring ID `default` cannot be destroyed.", "operationId": "deleteKeyRing", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/KeyRingForceDeleteParam" } ], "x-ibm-permissions": { "actions": [ { "name": "kms.keyrings.delete" } ] }, "x-ibm-events": { "events": [ { "name": "kms.key-rings.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example delete Key Ring", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://.kms.cloud.ibm.com/api/v2/key_rings/ \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\n\nimport (\n \"context\"\n \"encoding/json\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc main() {\n // Initialize the Key Protect client as specified in Authentication\n err := api.DeleteKeyRing(context.Background())\n if err != nil {\n fmt.Println(\"Error while deleting key ring: \", err)\n return\n }\n fmt.Println(\"Key ring successfully deleted\")\n}" ] } ] } ], "java": [ { "name": "Example delete Key Ring", "example": [ { "type": "code", "lang": "java", "source": [ "public static String deleteKeyRing (String keyRingId) {\n\n // Construct an instance of the DeleteKeyRingOptions model\n DeleteKeyRingOptions deleteKeyRingOptionsModel = new DeleteKeyRingOptions.Builder()\n .keyRingId(keyRingId)\n .bluemixInstance(\"\")\n .build();\n\n try {\n // Invoke operation with valid options model\n return testClient.deleteKeyRing(deleteKeyRingOptionsModel).execute().toString() + \" success\";\n } catch (ClassCastException e) {\n return e.toString();\n }\n}" ] } ] } ] } }, "x-try-it-out-example": [ { "in": "header", "name": "Authorization", "value": "" }, { "in": "header", "name": "Bluemix-Instance", "value": "" }, { "in": "path", "name": "key-ring-id", "value": "" } ], "responses": { "204": { "description": "The key ring was successfully deleted. No content." }, "400": { "description": "The key ring could not be deleted due to invalid request data.", "content": { "application/json": { "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. See `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `id` must be: a string matching pattern `^[a-zA-Z0-9-]*$`.", "status": 400, "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "key-ring-id" } } ] } ] }, "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "There are two possible causes for HTTP 409 while trying to delete a key ring, specifying a reason code (resouces[0].reasons[0].code) as follows:\nKEY_RING_NOT_EMPTY_ERR: The specified key ring contains at least one key (in any state). KEY_RING_KEYS_NOT_DELETED_ERR: (If `force` is set to `true`) The specified key ring contains at least one non-deleted key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Key ring could not be created. See `reasons` for more details.", "reasons": [ { "code": "KEY_RING_NOT_EMPTY_ERR", "message": "The specified key ring contains at least one key (in any state).", "status": 409, "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/api/v2/kmip_adapters": { "get": { "summary": "List KMIP Adapters", "description": "Retrieves a list of KMIP Adapters.", "operationId": "get_kmip_adapters", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KMIPAdapterLimitParam" }, { "$ref": "#/components/parameters/KMIPAdapterOffsetParam" }, { "$ref": "#/components/parameters/KMIPAdapterTotalCountParam" }, { "$ref": "#/components/parameters/KMIPAdapterCRKFilterParam" } ], "responses": { "200": { "description": "Returns a list of all KMIP Adapters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPAdaptersWithTotalCount" }, "examples": { "GetKMIPAdapters": { "$ref": "#/components/examples/GetKMIPAdapters" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.list" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] }, "post": { "summary": "Create a KMIP Adapter", "description": "Creates a KMIP adapter.", "operationId": "create_kmip_adapter", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KMIPAdapterAllowExpiringKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKMIPAdapterRequestBody" } } } }, "responses": { "201": { "description": "Returns the KMIP Adapter just created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPAdapters" }, "examples": { "CreateKMIPAdapter": { "$ref": "#/components/examples/CreateKMIPAdapter" } } } } }, "400": { "description": "The KMIP Adapter could not be created due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadFieldValidation": { "$ref": "#/components/examples/KMIPAdapterBadFieldValidation" }, "KMIPAdapterBadProfile": { "$ref": "#/components/examples/KMIPAdapterBadProfile" }, "KMIPAdapterBadProfileDataNotFound": { "$ref": "#/components/examples/KMIPAdapterBadProfileDataNotFound" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "KMIP adapter could not be created due to a constraint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterDupNameError": { "$ref": "#/components/examples/KMIPAdapterDupNameError" }, "KMIPAdapterNativeCRKNotFoundError": { "$ref": "#/components/examples/KMIPAdapterNativeCRKNotFoundError" }, "KMIPAdapterNativeCRKInvalidError": { "$ref": "#/components/examples/KMIPAdapterNativeCRKInvalidError" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.create" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json' \\\n -d '{\n \"metadata\": {\n \"collectionTotal\": 1,\n \"collectionType\": \"application/vnd.ibm.kms.kmip_adapter+json\"\n },\n \"resources\": [\n {\n \"name\": \"\",\n \"profile\": \"\",\n \"profile_data\": {\n \"crk_id\": \"\"\n }\n }\n ]\n }'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] } }, "/api/v2/kmip_adapters/{id}": { "parameters": [ { "$ref": "#/components/parameters/KMIPAdapterIdPath" } ], "get": { "summary": "Retrieve a KMIP Adapter", "description": "Retrieves a KMIP adapter using its id / name.", "operationId": "get_kmip_adapter", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "Returns the KMIP Adapter with the given ID / name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPAdapters" }, "examples": { "GetKMIPAdapter": { "$ref": "#/components/examples/CreateKMIPAdapter" } } } } }, "400": { "description": "The KMIP Adapter could not be retrieved due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/KMIPAdapterNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.read" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters/ \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] }, "delete": { "summary": "Delete a KMIP Adapter", "description": "Deletes a KMIP Adapter, including all its client certificates, with the given id / name.", "operationId": "delete_kmip_adapter", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "204": { "description": "The KMIP Adapter was successfully deleted. No content." }, "400": { "description": "The KMIP Adapter could not be deleted due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/KMIPAdapterNotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.delete" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters/ \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] } }, "/api/v2/kmip_adapters/{adapter_id}/kmip_objects": { "parameters": [ { "$ref": "#/components/parameters/KMIPAdapterFullIdPath" } ], "get": { "summary": "List KMIP objects of a KMIP Adapter", "description": "List KMIP objects of a KMIP Adapter.", "operationId": "get_kmip_objects", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/KMIPObjectLimitParam" }, { "$ref": "#/components/parameters/KMIPObjectOffsetParam" }, { "$ref": "#/components/parameters/KMIPObjectTotalCountParam" }, { "$ref": "#/components/parameters/KMIPObjectStateParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "List of KMIP objects associated with the KMIP Adapter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPObjectsWithTotalCount" }, "examples": { "GetKMIPObjects": { "$ref": "#/components/examples/GetKMIPObjects" } } } } }, "400": { "description": "The KMIP Objects could not be retrieved due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadFullId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The KMIP Objects could not be retrieved because a resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFoundObjectPathRetrieve" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.list" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters//kmip_objects \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] } }, "/api/v2/kmip_adapters/{adapter_id}/kmip_objects/{id}": { "parameters": [ { "$ref": "#/components/parameters/KMIPAdapterFullIdPath" } ], "get": { "summary": "Retrieve a KMIP object from a KMIP Adapter", "description": "Retrieves a KMIP object from a KMIP Adapter by its id.", "operationId": "get_kmip_object", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/KMIPObjectIdPath" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "The KMIP object associated with the given id in the KMIP Adapter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPObjectsWithTotalCount" }, "examples": { "GetKMIPObject": { "$ref": "#/components/examples/GetKMIPObject" } } } } }, "400": { "description": "The KMIP object could not be retrieved due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadFullId" }, "KMIPObjectBadId": { "$ref": "#/components/examples/KMIPObjectBadId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The KMIP object could not be retrieved because a resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPObjectNotFound": { "$ref": "#/components/examples/KMIPObjectNotFound" }, "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFoundObjectPathRetrieve" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.read" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters//kmip_objects/ \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] }, "delete": { "summary": "Delete a KMIP object from a KMIP Adapter", "description": "Deletes a KMIP object from a KMIP Adapter given its id. Changes the state of the KMIP object to 5 (Destroyed) and erases its key material. Any data encrypted by this KMIP object will be crypto erased when the KMIP Object changes it state to 5 (Destroyed).", "operationId": "delete_kmip_object", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/KMIPClientCertificateIdPath" }, { "$ref": "#/components/parameters/CorrelationId" }, { "$ref": "#/components/parameters/KMIPObjectForceDeleteParam" } ], "responses": { "204": { "description": "Delete succeeded and no content is returned." }, "400": { "description": "The KMIP object associated with the KMIP Adapter could not be deleted due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadFullId" }, "KMIPObjectBadId": { "$ref": "#/components/examples/KMIPObjectBadId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "KMIP object could not be deleted because a resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPObjectNotFound": { "$ref": "#/components/examples/KMIPObjectNotFoundDelete" }, "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFoundObjectPathDelete" } } } } }, "409": { "description": "KMIP object could not be deleted because there is a conflict. KMIP_OBJECT_NONDELETABLE_STATE_ERR: The kmip object is not in pre-active, deactivated, or compromised state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPObjectNotFound": { "$ref": "#/components/examples/KMIPObjectNonDeletableState" } } } } }, "410": { "description": "KMIP object could not be deleted because the resource is already deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPObjectNotFound": { "$ref": "#/components/examples/KMIPObjectDeleted" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.delete" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters//kmip_objects/ \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] } }, "/api/v2/kmip_adapters/{adapter_id}/certificates": { "parameters": [ { "$ref": "#/components/parameters/KMIPAdapterFullIdPath" } ], "get": { "summary": "List client certificates of a KMIP Adapter", "description": "List client certificates of a KMIP Adapter.", "operationId": "get_kmip_client_certificates", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/KMIPClientCertificateLimitParam" }, { "$ref": "#/components/parameters/KMIPClientCertificateOffsetParam" }, { "$ref": "#/components/parameters/KMIPClientCertificateTotalCountParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "List of client certificates associated with the KMIP Adapter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPPartialClientCertificatesWithTotalCount" }, "examples": { "GetKMIPClientCertificates": { "$ref": "#/components/examples/GetKMIPClientCertificates" } } } } }, "400": { "description": "The client certificates could not be retrieved due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadFullId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The client certificates could not be retrieved because a resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFoundCertPathRetrieve" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.list" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters//certificates \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] }, "post": { "summary": "Add a client certificate to a KMIP Adapter", "description": "Add a client certificate to a KMIP Adapter. It might take up to 5 minutes for a KMIP call using the newly add certificate to pass authentication. A maximum of 200 client certificates can be associated with a KMIP Adapter at a time.", "operationId": "add_kmip_client_certificate", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateKMIPClientCertificateRequestBody" } } } }, "responses": { "201": { "description": "The full details of the KMIP Certificate just created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPClientCertificates" }, "examples": { "CreateKMIPClientCertificate": { "$ref": "#/components/examples/CreateKMIPClientCertificate" } } } } }, "400": { "description": "A client certificate could not be added to the KMIP Adapter due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPCertificateBadFieldValidation": { "$ref": "#/components/examples/KMIPCertificateBadFieldValidation" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Certificate could not be created because a resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFoundCertPathCreate" } } } } }, "409": { "description": "KMIP_CERT_QUOTA_ERR: The quota for certificates in this KMIP adapter instance has been reached. Unable to add any more certificates\nKMIP_CERT_DUPLICATE_NAME_ERR: There is a kmip client certificate in this kms adapter with the same name. Please choose a different name\nKMIP_CERT_DUPLICATE_ERR: The certificate payload is already associated with this adapter\nKMIP_CERT_REUSE_ERR: Another KMIP adapter reserves exclusive use of this certificate payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIP_CERT_QUOTA_ERR": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)", "reasons": [ { "code": "KMIP_CERT_QUOTA_ERR", "message": "The quota for certificates in this KMIP instance has been reached. Unable to add any more certificates.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } }, "KMIP_CERT_DUPLICATE_NAME_ERR": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)", "reasons": [ { "code": "KMIP_CERT_DUPLICATE_NAME_ERR", "message": "There is a certificate in this kmip adapter with the same name. Please choose a different name", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } }, "KMIP_CERT_DUPLICATE_ERR": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)", "reasons": [ { "code": "KMIP_CERT_DUPLICATE_ERR", "message": "The certificate payload is already associated with this adapter.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } }, "KMIP_CERT_REUSE_ERR": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: KMIP Client Certificate could not be added: Please see `reasons` for more details (KMIP_CERT_DUPLICATE_ERR)", "reasons": [ { "code": "KMIP_CERT_REUSE_ERR", "message": "Another KMIP adapter reserves exclusive use of this certificate payload.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.create" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters//certificates \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json' \\\n -d '{\n \"metadata\": {\n \"collectionTotal\": 1,\n \"collectionType\": \"application/vnd.ibm.kms.kmip_client_certificate+json\"\n },\n \"resources\": [\n {\n \"name\": \"\",\n \"certificate\": \"-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----\"\n }\n ]\n }'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] } }, "/api/v2/kmip_adapters/{adapter_id}/certificates/{id}": { "parameters": [ { "$ref": "#/components/parameters/KMIPAdapterFullIdPath" }, { "$ref": "#/components/parameters/KMIPClientCertificateIdPath" } ], "get": { "summary": "Retrieve a client certificate from a KMIP Adapter", "description": "Retrieves a client certificate from a KMIP Adapter using its id / name.", "operationId": "get_kmip_client_certificate", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "200": { "description": "The full details of the KMIP Certificate with the given id / name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListKMIPClientCertificates" }, "examples": { "GetKMIPClientCertificate": { "$ref": "#/components/examples/CreateKMIPClientCertificate" } } } } }, "400": { "description": "The client certificate associated with the KMIP Adapter could not be retrieved due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadFullId" }, "KMIPCertificateBadId": { "$ref": "#/components/examples/KMIPCertificateBadId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Certificate could not be retrieved because a resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPCertificateNotFound": { "$ref": "#/components/examples/KMIPCertificateNotFound" }, "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFoundCertPathRetrieve" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.read" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters//certificates/ \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] }, "delete": { "summary": "Delete a client certificate from a KMIP Adapter", "description": "Removes a client certificate from a KMIP Adapter given its id / name. It might take up to 5 minutes for a KMIP call using deleted certificate to fail authentication.", "operationId": "delete_kmip_client_certificate", "parameters": [ { "$ref": "#/components/parameters/InstanceParam" }, { "$ref": "#/components/parameters/CorrelationId" } ], "responses": { "204": { "description": "Delete succeeded and no content is returned." }, "400": { "description": "The client certificate associated with the KMIP Adapter could not be deleted due to invalid request data.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterBadId": { "$ref": "#/components/examples/KMIPAdapterBadFullId" }, "KMIPCertificateBadId": { "$ref": "#/components/examples/KMIPCertificateBadId" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Certificate could not be retrieved because a resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPCertificateNotFound": { "$ref": "#/components/examples/KMIPCertificateNotFound" }, "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFoundCertPathDelete" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "BearerAuth": [] } ], "x-ibm-permissions": { "actions": [ { "name": "kms.kmip-management.delete" } ] }, "x-ibm-events": { "events": [ { "name": "kms.kmip-management.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://.kms.cloud.ibm.com/api/v2/kmip_adapters//certificates/ \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\\n -H 'content-type: application/json'" ] } ] } ] } }, "tags": [ "KMIP Adapters" ] } } }, "components": { "parameters": { "Alias": { "name": "alias", "in": "path", "description": "A human-readable alias that uniquely identifies a key. Each alias is unique only within the given instance and is not reserved across the Key Protect service. Each key can have up to five aliases. There is no limit to the number of aliases per instance. The length of the alias can be between 2 - 90 characters, inclusive. An alias must be alphanumeric and cannot contain spaces or special characters other than '-' or '_'. Also, the alias cannot be a version 4 UUID and must not be a Key Protect reserved name: `allowed_ip`, `key`, `keys`, `metadata`, `policy`, `policies`, `registration`, `registrations`, `ring`, `rings`, `rotate`, `wrap`, `unwrap`, `rewrap`, `version`, `versions`. ", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9_-]*$", "minLength": 2, "maxLength": 90 }, "required": true }, "KeyId": { "name": "id", "in": "path", "description": "The v4 UUID that uniquely identifies the key.", "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "required": true }, "KeyIdOrAlias": { "name": "id", "in": "path", "description": "The v4 UUID or alias that uniquely identifies the key.", "schema": { "type": "string", "pattern": "^[a-zA-Z0-9-_]{2,90}$", "minLength": 2, "maxLength": 90 }, "required": true }, "KeyRingId": { "name": "key-ring-id", "in": "path", "description": "The ID that identifies the key ring. Each ID is unique only within the given instance and is not reserved across the Key Protect service.", "schema": { "$ref": "#/components/schemas/KeyRingID" }, "required": true }, "KMIPAdapterIdPath": { "description": "The name or v4 UUID of the KMIP Adapter that uniquely identifies it.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 40, "pattern": "^[a-zA-Z0-9-_]{2,40}$" }, "style": "simple" }, "KMIPAdapterFullIdPath": { "description": "The name or v4 UUID of the KMIP Adapter that uniquely identifies it.", "in": "path", "name": "adapter_id", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 40, "pattern": "^[a-zA-Z0-9-_]{2,40}$" }, "style": "simple" }, "KMIPClientCertificateIdPath": { "description": "The name or v4 UUID of the client certificate that uniquely identifies it.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 40, "pattern": "^[a-zA-Z0-9-_]{2,40}$" }, "style": "simple" }, "KMIPObjectIdPath": { "description": "The v4 UUID of the kmip object that uniquely identifies it.", "in": "path", "name": "id", "required": true, "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "style": "simple" }, "UrlEncodedResourceCRN": { "name": "urlEncodedResourceCRN", "in": "path", "description": "The URL encoded [Cloud Resource Name](/docs/account?topic=account-crn) (CRN) that uniquely identifies the cloud resource. At minimum, provide a CRN that includes the `service-instance` segment.", "schema": { "type": "string", "minLength": 9, "maxLength": 400, "pattern": "^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$" }, "required": true, "example": "crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f00000000000000000000000000000000%3afeddecaf-0000-0000-0000-1234567890ab%3a%3abucket" }, "ExtractableParam": { "name": "extractable", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "The type of keys to be retrieved. Filters keys based on the `extractable` property. You can use this query parameter to search for keys whose material can leave the service. If set to `true`, standard keys will be retrieved. If set to `false`, root keys will be retrieved. If omitted, both root and standard keys will be retrieved.\n**Usage:** If you want to retrieve standard keys, use `../keys?extractable=true`." }, "Filter": { "name": "filter", "in": "query", "schema": { "type": "string", "minLength": 0, "maxLength": 512, "pattern": "^.{0,512}$" }, "required": false, "description": "When provided, returns the list of keys that match the queried properties.\nEach key property to be filtered on is specified as the property name itself, followed by an “=“ symbol, and then the value to filter on, followed by a space if there are more properties to filter only.\nNote: Anything between `<` and `>` in the examples or descriptions represent placeholder to specify the value\n*Basic format*: = = - The value to filter on may contain a value related to the property itself, or an operator followed by a value accepted by the operator - Only one operator and value, or one value is accepted per property at a time\n*Format with operator/value pair*: =:\nUp to three of the same property may be specified at a time.\nThe key properties that can be filtered at this time are:\n- `creationDate`\n * Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”\n- `deletionDate`\n * Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”\n- `expirationDate`\n * Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”\n- `extractable`\n * Boolean true or false without quotes, case-insensitive\n- `lastRotateDate`\n * Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”\n- `lastUpdateDate`\n * Date in RFC 3339 format in double-quotes: “2000-03-21T00:00:00Z”\n- `state`\n * A list of comma-separated integers with no space in between: 0,1,2,3,5\nComparison operations (operators) that can be performed on date values are:\n- `lte:` Less than or equal to - `lt:` Less than - `gte:` Greater than or equal to - `gt:` Greater than\nA special keyword for date, `none` (case-insensitive), may be used to retreive keys that do not have that property. This is useful for `lastRotateDate`, where only keys that have never been rotated can be retreived.\n*Examples*:\n- `lastRotateDate=\"2022-02-15T00:00:00Z\"` Filter keys that were last rotated on February 15, 2022 - `lastRotateDate=gte:\"2022-02-15T00:00:00Z\"` Filter keys that were last rotated after or on February 15, 2022 - `lastRotateDate=gte:\"2022-02-15T00:00:00Z\" lastRotateDate=lt:\"2022-03-15T00:00:00Z\"` Filter keys that were last rotated after or on February 15, 2022 but before (not including) March 15, 2022 - `lastRotateDate=\"2022-02-15T00:00:00Z\" state=0,1,2,3,5 extractable=false` Filter root keys that were last rotated on February 15, 2022, with any state\n*Note*: When you filter by `state` or `extractable` in this query parameter, you will not be able to use the deprecated `state` or `extractable` independent query parameter. You will get a 400 response code if you specify a value for one of the two properties in both this filter query parameter and the deprecated independent query of the same name (the same applies vice versa)." }, "Force": { "name": "force", "in": "query", "schema": { "type": "boolean", "default": false }, "required": false, "description": "If set to `true`, Key Protect forces deletion on a key that is protecting a cloud resource, such as a Cloud Object Storage bucket. The action removes any registrations that are associated with the key.\n**Note:** If a key is protecting a cloud resource that has a retention policy, Key Protect cannot delete the key. Use `GET keys/{id}/registrations` to review registrations between the key and its associated cloud resources. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key." }, "InstancePolicyType": { "description": "The type of policy that is associated with the specified instance.", "in": "query", "name": "policy", "required": false, "schema": { "enum": [ "allowedNetwork", "dualAuthDelete", "allowedIP", "keyCreateImportAccess", "metrics", "rotation" ], "type": "string", "minLength": 7, "maxLength": 21 } }, "KeyPolicyType": { "description": "The type of policy that is associated with the specified key.", "in": "query", "name": "policy", "required": false, "schema": { "enum": [ "dualAuthDelete", "rotation" ], "type": "string", "minLength": 8, "maxLength": 14 } }, "KeyRingForceDeleteParam": { "name": "force", "in": "query", "schema": { "type": "boolean", "default": false }, "required": false, "description": "Force delete the key ring. All keys in the key ring are required to be deleted (in state `5`) before this action can be performed. If the key ring to be deleted contains keys, they will be moved to the `default` key ring which requires the `kms.secrets.patch` IAM action." }, "KeyRingLimitParam": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 100 }, "required": false, "description": "The number of key rings to retrieve. By default, `GET /key_rings` returns 100 key rings including the default key ring. To retrieve a different set of key rings, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5,000.\n**Usage:** If you have 20 key rings in your instance, and you want to retrieve only the first 5 key rings, use `../key_rings?limit=5`." }, "KeyRingOffsetParam": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "The number of key rings to skip. By specifying `offset`, you retrieve a subset of key rings that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.\n**Usage:** If you have 20 key rings in your instance, and you want to retrieve keys 10 through 20, use `../keys?offset=10&limit=10`." }, "KeyRingTotalCount": { "name": "totalCount", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of key rings that match the request, disregarding limit and offset. The default is set to false.\n**Usage:** To return the `totalCount` value for use with pagination, use `../key_rings?totalCount=true`." }, "KeyVersionsAllKeyStates": { "name": "allKeyStates", "in": "query", "schema": { "type": "boolean", "default": false }, "required": false, "description": "If set to `true`, returns the key versions of a key in any state. **Usage:** If you have deleted a key and still want to retrieve its key versions use `../versions?allKeyStates=true`." }, "KeyVersionsLimitParam": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 200 }, "required": false, "description": "The number of key versions to retrieve. By default, `GET /versions` returns the first 200 key versions. To retrieve a different set of key versions, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5,000.\n**Usage:** If you have a key with 20 versions in your instance, and you want to retrieve only the first 5 versions, use `../versions?limit=5`." }, "KeyVersionsOffsetParam": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "The number of key versions to skip. By specifying `offset`, you retrieve a subset of key versions that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.\n**Usage:** If you have a key with 100 versions in your instance, and you want to retrieve versions 26 through 50, use `../versions?offset=25&limit=25`." }, "KeyVersionsTotalCount": { "name": "totalCount", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of key versions that match the request, disregarding limit and offset. The default is set to false.\n**Usage:** To return the `totalCount` value for use with pagination, use `../versions?totalCount=true`." }, "KMIPAdapterAllowExpiringKey": { "name": "allowExpiringKey", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "If set to 'true', allows an active root key containing an expiration date to be associated with the KMIP adapter." }, "KMIPAdapterTotalCountParam": { "name": "totalCount", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of kmip adapters that match the request, disregarding limit and offset. The default is set to false. **Usage:** To return the `totalCount` value for use with pagination, use `../kmip_adapters?totalCount=true`." }, "KMIPAdapterLimitParam": { "description": "The number of KMIP Adapters to retrieve. By default, `GET /kmip_adapters` returns the first 100 KMIP Adapters. To retrieve a different set of KMIP adapters, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 200.\n**Usage:** If you have 20 KMIP Adapters, and you want to retrieve only the first 5 adapters, use `../kmip_adapters?limit=5`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "type": "integer" }, "style": "form" }, "KMIPAdapterOffsetParam": { "description": "The number of KMIP adapters to skip. By specifying `offset`, you retrieve a subset of KMIP adapters that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.\n**Usage:** If you have 20 KMIP Adapters, and you want to retrieve adapters 11 through 15, use `../kmip_adapters?offset=10&limit=5`.", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" }, "style": "form" }, "KMIPAdapterCRKFilterParam": { "description": "The root key ID(`crk_id`) in the `profile_data` to filter on. This field is currently only applicable to profile `\"native_1.0\"`.\nIt will only return adapters with profile_data that contains this field.\nExample usage `../kmip_adapters?crk_id=feddecaf-0000-0000-0000-1234567890ab`.", "in": "query", "name": "crk_id", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "The v4 UUID referring to a root key ID." } ] }, "style": "form" }, "KMIPClientCertificateLimitParam": { "description": "The number of client certificates to retrieve. By default, `GET /kmip_adapters/{id}/certificates` returns the first 100 certificates. To retrieve a different set of certificates, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 200.\n**Usage:** If you have 20 certificates associated with your KMIP adapter, and you want to retrieve only the first 5 certificates, use `../kmip_adapters/{id}/certificates?limit=5`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 200, "minimum": 1, "type": "integer" }, "style": "form" }, "KMIPClientCertificateOffsetParam": { "description": "The number of client certificates to skip. By specifying `offset`, you retrieve a subset of certificates that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.\n**Usage:** If you have 20 certificates associated with your KMIP adapter, and you want to retrieve certificates 11 through 15, use `../kmip_adapters/{id}/certificates?offset=10&limit=5`.", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" }, "style": "form" }, "KMIPClientCertificateTotalCountParam": { "name": "totalCount", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of client certificates that match the request, disregarding limit and offset. The default is set to false. **Usage:** To return the `totalCount` value for use with pagination, use `../kmip_adapters/{id}/certificates?totalCount=true`." }, "KMIPObjectForceDeleteParam": { "name": "force", "in": "query", "schema": { "type": "boolean", "default": false }, "required": false, "description": "Force delete the KMIP object, regardless of the object's state. All object data is eligible to be purged 90 days after deletion." }, "KMIPObjectLimitParam": { "description": "The number of kmip objects to retrieve. By default, `GET /kmip_adapters/{id}/kmip_objects` returns the first 100 kmip_objects. To retrieve a different set of kmip objects, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5000.\n**Usage:** If you have 20 kmip objects associated with your KMIP adapter, and you want to retrieve only the first 5 kmip objects, use `../kmip_adapters/{id}/kmip_objects?limit=5`.", "in": "query", "name": "limit", "required": false, "schema": { "default": 100, "maximum": 5000, "minimum": 1, "type": "integer" }, "style": "form" }, "KMIPObjectOffsetParam": { "description": "The number of kmip objects to skip. By specifying `offset`, you retrieve a subset of kmip objects that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.\n**Usage:** If you have 20 kmip objects associated with your KMIP adapter, and you want to retrieve kmip objects 11 through 15, use `../kmip_adapters/{id}/kmip_objects?offset=10&limit=5`.", "in": "query", "name": "offset", "required": false, "schema": { "default": 0, "minimum": 0, "type": "integer" }, "style": "form" }, "KMIPObjectTotalCountParam": { "name": "totalCount", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of kmip objects that match the request, disregarding limit and offset. The default is set to false. **Usage:** To return the `totalCount` value for use with pagination, use `../kmip_adapters/{id}/kmip_objects?totalCount=true`." }, "KMIPObjectStateParam": { "name": "state", "in": "query", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/KMIPObjectPropertyState" }, "default": [ 1, 2, 3, 4 ], "minItems": 0, "maxItems": 4 }, "required": false, "description": "List of states to filter the KMIP objects on. The `default` is set to `[1,2,3,4]`. States are integers and correspond to Pre-Active = 1, Active = 2, Deactivated = 3, Compromised = 4, Destroyed = 5, Destroyed Compromised = 6. **Usage:** To filter on multiples `state` values, use `../kmip_adapters/{id}/kmip_objects?state=2,3`." }, "LimitParam": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 200 }, "required": false, "description": "The number of keys to retrieve. By default, `GET /keys` returns the first 200 keys. To retrieve a different set of keys, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5,000.\n**Usage:** If you have 20 keys in your instance, and you want to retrieve only the first 5 keys, use `../keys?limit=5`." }, "OffsetParam": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "The number of keys to skip. By specifying `offset`, you retrieve a subset of keys that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.\n**Usage:** If you have 100 keys in your instance, and you want to retrieve keys 26 through 50, use `../keys?offset=25&limit=25`." }, "PreventKeyDeletion": { "name": "preventKeyDeletion", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "Filters registrations based on the `preventKeyDeletion` property. You can use this query parameter to search for registered cloud resources that are non-erasable due to a retention policy. This policy should only be set if a WORM policy (https://www.ibm.com/docs/en/spectrum-scale/5.0.1?topic=ics-how-write-once-read-many-worm-storage-works) must be satisfied. \nDo not set this policy by default.\n**Usage:** To search for registered cloud resources that have a retention policy, use `../registrations?preventKeyDeletion=true`." }, "RegistrationAction": { "description": "The action to perform on the specified key.", "name": "action", "in": "query", "schema": { "type": "string", "enum": [ "deactivate" ], "minLength": 10, "maxLength": 10 }, "required": true }, "RegistrationsLimitParam": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 200 }, "required": false, "description": "The number of registrations to retrieve. By default returns the first 200 registrations. To retrieve a different set of registrations, use `limit` with `offset` to page through your available resources. The maximum value for `limit` is 5,000.\n**Usage:** If you have 20 registrations that are associated with a key, and you want to retrieve only the first 5 registrations, use `../registrations?limit=5`." }, "RegistrationsOffsetParam": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 }, "required": false, "description": "The number of registrations to skip. By specifying `offset`, you retrieve a subset of registrations that starts with the `offset` value. Use `offset` with `limit` to page through your available resources.\n**Usage:** If you have 100 registrations that are associated with a key, and you want to retrieve registrations 26 through 50, use `../registrations?offset=25&limit=25`." }, "StateParam": { "name": "state", "in": "query", "schema": { "type": "array", "items": { "type": "integer", "enum": [ 0, 1, 2, 3, 5 ], "minimum": 0, "maximum": 5 }, "default": [ 0, 1, 2, 3 ], "minItems": 0, "maxItems": 5 }, "required": false, "description": "The state of the keys to be retrieved. States must be a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. Valid states are based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values.\n**Usage:** If you want to retrieve active and deleted keys, use `../keys?state=1,5`." }, "TotalCount": { "name": "totalCount", "in": "query", "schema": { "type": "boolean" }, "required": false, "description": "If set to `true`, returns `totalCount` in the response metadata for use with pagination. The `totalCount` value returned specifies the total number of registrations that match the request, disregarding limit and offset.\n**Usage:** To return the `totalCount` value for use with pagination, use `../registrations?totalCount=true`." }, "UrlEncodedResourceCRNQuery": { "name": "urlEncodedResourceCRNQuery", "in": "query", "schema": { "type": "string", "minLength": 9, "maxLength": 4000, "pattern": "^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$" }, "required": false, "description": "Filters for resources that are associated with a specified [Cloud Resource Name](/docs/account?topic=account-crn) (CRN) by using URL encoded wildcard characters (`*`). The parameter should contain all CRN segments and must be URL encoded. Supports a prefix search when you specify `*` on the last CRN segment.\n**Usage:** To list registrations that are associated with all resources in ``, use a URL encoded version of the following string: `crn:v1:bluemix:public:::a/::*:*`. To search for subresources, use the following CRN format: `crn:v1:bluemix:public:::a/:::/`.\nFor more examples, see [CRN query examples](/docs/key-protect?topic=key-protect-view-protected-resources#crn-query-examples).", "example": "crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F00000000000000000000000000000000%3Afeddecaf-0000-0000-0000-1234567890ab%3A*%3A*" }, "UrlEncodedResourceCRNQueryOptional": { "name": "urlEncodedResourceCRNQuery", "in": "query", "schema": { "type": "string", "minLength": 9, "maxLength": 4000, "pattern": "^(((?!((%3a)|(%3A))).)*((%3a|%3A))){9}(((?!((%3a)|(%3A))).)*)$" }, "required": false, "description": "Filters for resources that are associated with a specified [Cloud Resource Name](/docs/account?topic=account-crn) (CRN) by using URL encoded wildcard characters (`*`). The parameter should contain all CRN segments and must be URL encoded.\nIf provided, the parameter should not contain (`*`) in the first eight segments. If this parameter is not provided, registrations for all keys in the requested Key Protect instance are returned.", "example": "crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F00000000000000000000000000000000%3Afeddecaf-0000-0000-0000-1234567890ab%3A*%3A*" }, "CorrelationId": { "name": "Correlation-Id", "in": "header", "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "description": "The v4 UUID used to correlate and track transactions.", "required": false }, "InstanceParam": { "name": "Bluemix-Instance", "in": "header", "schema": { "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "description": "The IBM Cloud instance ID that identifies your Key Protect service instance.", "required": true }, "KeyRingDefault": { "name": "X-Kms-Key-Ring", "in": "header", "schema": { "type": "string", "default": "default", "minLength": 2, "maxLength": 100, "pattern": "^[a-zA-Z0-9-]*$" }, "description": "The ID of the key ring that the specified key belongs to. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an `X-Kms-Key-Ring` header is: `default`." }, "KeyRingList": { "name": "X-Kms-Key-Ring", "in": "header", "schema": { "type": "string", "minLength": 2, "maxLength": 100, "pattern": "^[a-zA-Z0-9-]*$" }, "description": "The ID of the target key ring. If unspecified, all resources in the instance that the caller has access to will be returned. When the header is specified, only resources within the specified key ring, that the caller has access to, will be returned. The key ring ID of keys that are created without an `X-Kms-Key-Ring` header is: `default`." }, "KeyRingSingleKey": { "name": "X-Kms-Key-Ring", "in": "header", "schema": { "type": "string", "minLength": 2, "maxLength": 100, "pattern": "^[a-zA-Z0-9-]*$" }, "description": "The ID of the key ring that the specified key is a part of. When the header is not specified, Key Protect will perform a key ring lookup. For a more optimized request, specify the key ring on every call. The key ring ID of keys that are created without an `X-Kms-Key-Ring` header is: `default`." }, "Prefer": { "name": "Prefer", "in": "header", "schema": { "type": "string", "enum": [ "return=representation", "return=minimal" ], "minLength": 14, "maxLength": 21 }, "description": "Alters server behavior for POST or DELETE operations. A header with `return=minimal` causes the service to return only the key identifier as metadata. A header containing `return=representation` returns both the key material and metadata in the response entity-body. If the key has been designated as a root key, the system cannot return the key material.\n**Note:** During POST operations, Key Protect may not immediately return the key material due to key generation time. To retrieve the key material, you can perform a subsequent `GET /keys/{id}` request.", "required": false } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Your IBM Cloud access token.", "bearerFormat": "JWT" } }, "schemas": { "AcknowledgeBody": { "description": "The base schema for the resource in the body of the key event acknowledgement.", "required": [ "eventId", "adopterKeyState", "timestamp" ], "properties": { "eventId": { "description": "The v4 UUID that uniquely identifies the Hyperwarp event.", "nullable": false, "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "adopterKeyState": { "description": "The adopter's reported key state at time of processing the event.", "type": "string", "enum": [ "DEK_ENABLED", "DEK_DISABLED", "DEK_NOT_FOUND" ], "minLength": 11, "maxLength": 13, "pattern": "^.{11,13}$" }, "timestamp": { "description": "The date the event was processed by the adopter service. The date format follows RFC 3339.", "type": "string", "minLength": 20, "maxLength": 20, "format": "date-time", "example": "2000-03-21T00:00:00Z" }, "keyStateData": { "$ref": "#/components/schemas/KeyStateData" }, "deleteRegistration": { "description": "A boolean that determines whether Key Protect attempts to delete the registration associated with the given eventId. This field may only be specified when `adopterKeyState` is `DEK_NOT_FOUND`.\nIf set to `false`, the registration associated with the eventID is not deleted. By default, Key Protect sets the value to `true` and attempts to delete the registration.", "type": "boolean", "nullable": true, "default": true } } }, "CollectionMetadata": { "description": "The metadata that describes the resource array.", "type": "object", "required": [ "collectionType", "collectionTotal" ], "properties": { "collectionType": { "description": "The type of resources in the resource array.", "type": "string", "enum": [ "application/vnd.ibm.kms.allowed_ip_metadata+json", "application/vnd.ibm.kms.crn+json", "application/vnd.ibm.kms.error+json", "application/vnd.ibm.kms.event_acknowledge+json", "application/vnd.ibm.kms.import_token+json", "application/vnd.ibm.kms.key+json", "application/vnd.ibm.kms.key_action+json", "application/vnd.ibm.kms.alias+json", "application/vnd.ibm.kms.key_ring+json", "application/vnd.ibm.kms.policy+json", "application/vnd.ibm.kms.registration_input+json", "application/vnd.ibm.kms.registration+json", "application/vnd.ibm.kms.resource_crn+json", "application/vnd.ibm.kms.kmip_adapter+json", "application/vnd.ibm.kms.kmip_client_certificate+json", "application/vnd.ibm.kms.kmip_object+json" ], "minLength": 32, "maxLength": 52 }, "collectionTotal": { "description": "The number of elements in the resource array.", "type": "integer", "format": "int64", "minimum": 0, "maximum": 5000, "example": 1 } } }, "CollectionMetadataListKeys": { "description": "The metadata that describes the list keys response", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CollectionMetadata" }, { "$ref": "#/components/schemas/ListKeysMetadataProperties" } ] }, "CollectionMetadataOneOf": { "oneOf": [ { "$ref": "#/components/schemas/CollectionMetadata" } ] }, "CollectionMetadataWithTotalCount": { "allOf": [ { "$ref": "#/components/schemas/CollectionMetadata" }, { "type": "object", "properties": { "totalCount": { "description": "The total number of elements that match the request, disregarding limit and offset.", "nullable": true, "type": "integer", "format": "int64", "minimum": 0, "maximum": 5000, "example": 1 } } } ] }, "CreateKey": { "description": "The base schema for the resource given in the Create Key request body.", "allOf": [ { "$ref": "#/components/schemas/KeyResource" }, { "type": "object", "required": [ "name", "type" ] } ] }, "CreateKeyOneOf": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CreateKeyRequestBody" }, { "$ref": "#/components/schemas/ImportKeyRequestBody" }, { "$ref": "#/components/schemas/ImportKeyWithImportTokenRequestBody" } ] }, "CreateKeyRequestBody": { "description": "The base schema for the request body of a `POST /keys`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/CreateKey" }, "minItems": 1, "maxItems": 1 } } }, "CreateKeyWithPolicyOverrides": { "description": "The base schema for the resource given in the Create Key with policies request body.", "allOf": [ { "$ref": "#/components/schemas/KeyResource" }, { "type": "object", "required": [ "name", "type" ] }, { "type": "object", "properties": { "dualAuthDelete": { "$ref": "#/components/schemas/KeyPolicyDualAuthDeleteDualAuthDelete" }, "rotation": { "$ref": "#/components/schemas/KeyPolicyRotationRotation" } } } ] }, "CreateKeyWithPolicyOverridesOneOf": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CreateKeyWithPolicyOverridesRequestBody" }, { "$ref": "#/components/schemas/ImportKeyWithPolicyOverridesRequestBody" }, { "$ref": "#/components/schemas/ImportKeyWithImportTokenWithPolicyOveridesRequestBody" } ] }, "CreateKeyWithPolicyOverridesRequestBody": { "description": "The base schema for the request body of a `POST /keys_with_policy_overrides`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/CreateKeyWithPolicyOverrides" } } } }, "DeleteKey": { "description": "The base schema for deleting keys.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KeyWithPayload" }, "minItems": 1, "maxItems": 1 } } }, "DeleteProperties": { "type": "object", "description": "Properties returned only for DELETE.", "properties": { "deleted": { "description": "A boolean that determines whether the key has been deleted.", "type": "boolean", "readOnly": true }, "deletionDate": { "description": "The date the key material was destroyed. The date format follows RFC 3339.", "type": "string", "minLength": 20, "maxLength": 20, "nullable": true, "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" }, "deletedBy": { "description": "The unique identifier for the resource that deleted the key.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "readOnly": true }, "restoreExpirationDate": { "description": "The date the key will no longer have the ability to be restored.", "type": "string", "nullable": true, "format": "date-time", "example": "2000-03-21T00:00:00Z" }, "restoreAllowed": { "description": "A boolean that specifies if your key has the ability to be restored.\nA value of `true` indicates that the key can be restored. A value of `false` indicates that the key is unable to be restored.", "type": "boolean", "nullable": true }, "purgeAllowed": { "description": "A boolean that specifies if the key can be purged.\nA value of `true` indicates that the key can be purged. A value of `false` indicates that the key is within the purge wait period and is not ready to be purged.", "type": "boolean", "nullable": true }, "purgeAllowedFrom": { "description": "The date the key will be ready to be purged.", "type": "string", "nullable": true, "format": "date-time", "example": "2000-03-21T00:00:00Z" }, "purgeScheduledOn": { "description": "The date the deleted key will be automatically purged from Key Protect system.", "type": "string", "nullable": true, "format": "date-time", "example": "2000-03-21T00:00:00Z" } } }, "DualAuthKeyMetadata": { "description": "Metadata that indicates the status of a dual authorization policy on the key.", "type": "object", "nullable": true, "required": [ "enabled" ], "properties": { "enabled": { "description": "The status of a dual authorization policy on the key.\nIf `true`, dual authorization is required to delete the key. If `false`, no prior authorization is required to delete the key.", "type": "boolean", "example": true }, "keySetForDeletion": { "description": "Indicates if a delete authorization has been issued for a key.\nIf `true`, an authorization to delete this key has been issued by the first user, and a second user with a Manager access policy can safely delete the key. If the `enabled` property is `false`, this field is omitted in the response body.", "type": "boolean", "nullable": true, "example": true }, "authExpiration": { "description": "The date that an authorization for deletion expires for the key. If this date has passed, the authorization is no longer valid. If the `enabled` or `keySetForDeletion` properties are `false`, this field is omitted in the response body.", "type": "string", "nullable": true, "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" } } }, "ErrorCollection": { "description": "The base schema for error responses.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/Error" }, "minItems": 1, "maxItems": 1 } } }, "ErrorCollectionWithReason": { "description": "The base schema for error responses that MAY include a fine grain reason.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/ErrorWithReason" }, "minItems": 1, "maxItems": 1 } } }, "EventAcknowledge": { "description": "The base schema for acknowledging one or more key events. The request body should be of `collectionType: application/vnd.ibm.kms.event_acknowledge+json`.", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "items": { "$ref": "#/components/schemas/AcknowledgeBody" }, "type": "array", "minItems": 1, "maxItems": 1000 } }, "required": [ "metadata", "resources" ] }, "GetImportToken": { "description": "The base schema for retrieving an import token.", "allOf": [ { "$ref": "#/components/schemas/ImportToken" }, { "type": "object", "properties": { "payload": { "description": "The public encryption key that you can use to encrypt key material before you import it into the service.\nThis value is a PEM-encoded public key in PKIX format. Because PEM encoding is a binary format, the value is base64 encoded.", "type": "string", "format": "byte", "minLength": 1068, "maxLength": 1068, "pattern": "^.{1068}$", "readOnly": true }, "nonce": { "description": "The nonce value that is used to verify a key import request. Encrypt and provide the encrypted nonce value when you use `POST /keys` to securely import a key to the service.", "type": "string", "minLength": 16, "maxLength": 16, "format": "byte", "readOnly": true } } } ] }, "GetKey": { "description": "The base schema for retrieving keys.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/KeyWithPayload" } } } }, "GetKeyMetadata": { "description": "The base schema for retrieving key metadata.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KeyFullRepresentation" }, "minItems": 1, "maxItems": 1 } } }, "GetKeyPolicyDualAuthDelete": { "description": "The base schema for retrieving a dual authorization key policy.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GetKeyPolicy" }, { "$ref": "#/components/schemas/KeyPolicyDualAuthDelete" } ] }, "minItems": 0, "maxItems": 1 } } }, "GetKeyPolicyRotation": { "description": "The base schema for retrieving a dual authorization key policy.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/GetKeyPolicy" }, { "$ref": "#/components/schemas/KeyPolicyRotation" } ] }, "minItems": 0, "maxItems": 1 } } }, "GetMultipleKeyPoliciesResource": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/KeyPolicyDualAuthDeleteNonRequired" }, { "$ref": "#/components/schemas/KeyPolicyRotationNonRequired" }, { "$ref": "#/components/schemas/GetKeyPolicy" } ] }, "GetMultipleKeyPolicies": { "description": "The base schema for retrieving all key policies.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/GetMultipleKeyPoliciesResource" }, "minItems": 0, "maxItems": 2 } } }, "ImportKey": { "description": "The base schema for the resource given in the Import Key request body.", "allOf": [ { "$ref": "#/components/schemas/CreateKey" }, { "type": "object", "required": [ "payload" ], "properties": { "payload": { "$ref": "#/components/schemas/ImportPayload" } } } ] }, "ImportKeyRequestBody": { "description": "The base schema for the request body of a `POST /keys`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/ImportKey" }, "minItems": 1, "maxItems": 1 } } }, "ImportKeyWithImportToken": { "description": "The base schema for the resource given in the Import Key With Import Token request body.", "allOf": [ { "$ref": "#/components/schemas/CreateKey" }, { "$ref": "#/components/schemas/SecureImport" } ] }, "ImportKeyWithImportTokenRequestBody": { "description": "The base schema for the request body of a `POST /keys`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/ImportKeyWithImportToken" }, "minItems": 1, "maxItems": 1 } } }, "ImportPayload": { "description": "The key material that you want to store and manage in the service.\nTo import a key, provide a base64 encoded payload in the request entity-body. If you're importing a root key, ensure that the key is 128, 192, or 256 bits in length.\n**Note:** Access to the Key Protect service takes place over HTTPS. All communication uses the Transport Layer Security (TLS) protocol to encrypt data in transit. For more information about TLS and the ciphers supported by Key Protect, check out [Data encryption](/docs/key-protect?topic=key-protect-security-and-compliance#data-security).", "type": "string", "minLength": 16, "maxLength": 32, "pattern": "^.{16,32}$", "format": "byte", "writeOnly": true }, "ImportKeyWithPolicyOverridesRequestBody": { "description": "The base schema for the request body of a `POST /keys_with_policy_overrides`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/ImportKeyWithPolicyOverrides" }, "minItems": 1, "maxItems": 1 } } }, "ImportKeyWithPolicyOverrides": { "description": "The base schema for the resource given in the Import Key request body.", "allOf": [ { "$ref": "#/components/schemas/CreateKeyWithPolicyOverrides" }, { "type": "object", "required": [ "payload" ], "properties": { "payload": { "$ref": "#/components/schemas/ImportPayload" } } } ] }, "ImportKeyWithImportTokenWithPolicyOveridesRequestBody": { "description": "The base schema for the request body of a `POST /keys_with_policy_overrides`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/ImportKeyWithImportTokenWithPolicyOverrides" }, "minItems": 0, "maxItems": 1 } } }, "ImportKeyWithImportTokenWithPolicyOverrides": { "description": "The base schema for the resource given in the Import Key With Import Token request body.", "allOf": [ { "$ref": "#/components/schemas/CreateKeyWithPolicyOverrides" }, { "$ref": "#/components/schemas/SecureImport" } ] }, "KeyAlias": { "description": "Properties associated with a specific key alias.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KeyAliasResource" }, "minItems": 1, "maxItems": 1 } } }, "KeyFullRepresentation": { "allOf": [ { "$ref": "#/components/schemas/KeyRepresentation" }, { "$ref": "#/components/schemas/DeleteProperties" } ] }, "KeyRepresentation": { "allOf": [ { "$ref": "#/components/schemas/KeyResource" }, { "$ref": "#/components/schemas/KeyMetadata" }, { "type": "object", "properties": { "dualAuthDelete": { "$ref": "#/components/schemas/DualAuthKeyMetadata" }, "rotation": { "$ref": "#/components/schemas/RotationKeyMetadata" } } } ] }, "KeyRing": { "description": "Base properties of an instance key ring.", "properties": { "id": { "$ref": "#/components/schemas/KeyRingID" }, "creationDate": { "description": "The date the key ring was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "nullable": true, "example": "2000-03-21T00:00:00Z" }, "createdBy": { "description": "The unique identifier for the user that created the key ring.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$" } } }, "KeyRingID": { "description": "An ID that identifies the key ring. Each ID is unique only within the given instance and is not reserved across the Key Protect service.", "type": "string", "pattern": "^[a-zA-Z0-9-]*$", "minLength": 2, "maxLength": 100 }, "KeyStateData": { "oneOf": [ { "$ref": "#/components/schemas/WDEKStateData" } ] }, "KeyWithPayload": { "allOf": [ { "$ref": "#/components/schemas/KeyFullRepresentation" }, { "type": "object", "properties": { "payload": { "description": "The key material that you can export to external apps or services.\n**Note:** If the key has been designated as a root key, the system cannot return the key material.", "readOnly": true, "type": "string", "minLength": 16, "maxLength": 32, "pattern": "^.{16,32}$", "format": "byte" } } } ] }, "ListCollectionMetadata": { "oneOf": [ { "$ref": "#/components/schemas/CollectionMetadataWithTotalCount" }, { "$ref": "#/components/schemas/CollectionMetadata" } ] }, "ListKeyRingsWithTotalCount": { "description": "The base schema for listing key rings.", "required": [ "metadata" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataWithTotalCount" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KeyRing" }, "minItems": 0, "maxItems": 5000 } } }, "ListKeys": { "description": "The base schema for listing keys.", "required": [ "metadata" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataListKeys" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KeyFullRepresentation" }, "minItems": 0, "maxItems": 5000 } } }, "ListKeysMetadataProperties": { "properties": { "incompleteSearch": { "description": "If present, indicates the search did not complete due to the searchable set of keys being too large. Please retry your request with additional or more specific filters (i.e. extractable, state, etc.).\nTo determine the size of the searchable set of keys, please use `HEAD /api/v2/keys` with the desired search filters. For a search to be performmed, the resulting set contain at most 5000 keys.", "type": "boolean", "nullable": true }, "searchQuery": { "description": "Represents the parsed search query used for matching logic. Only returned when a search is requested.", "type": "object", "required": [ "query", "scopes" ], "properties": { "query": { "description": "final string to use for matching logic", "type": "string" }, "scopes": { "description": "list of scopes to search in", "type": "array", "minItems": 0, "maxItems": 100, "items": { "type": "string", "enum": [ "name", "alias" ] } }, "not": { "description": "invert matching logic", "type": "boolean", "nullable": true }, "exact": { "description": "only match query strings that are fully identical (case insensitive)", "type": "boolean", "nullable": true } }, "nullable": true } } }, "ListKeyVersions": { "description": "Properties associated with a registration response.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/ListCollectionMetadata" }, "resources": { "description": "An array of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KeyVersion" }, "minItems": 0, "maxItems": 5000 } } }, "ListKMIPAdapters": { "description": "The base schema for listing kmip adapter(s).", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/ListCollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KMIPAdapter" }, "minItems": 0, "maxItems": 200 } } }, "ListKMIPClientCertificates": { "description": "The base schema for listing client certificates in a kmip adapter.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/ListCollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 0, "maxItems": 200, "items": { "$ref": "#/components/schemas/KMIPClientCertificate" } } } }, "ListKMIPAdaptersWithTotalCount": { "description": "The base schema for listing kmip adapter with total count.", "required": [ "metadata" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataWithTotalCount" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KMIPAdapter" }, "minItems": 0, "maxItems": 200 } } }, "ListKMIPPartialClientCertificatesWithTotalCount": { "description": "The base schema for listing client certificates in a kmip adapter with total count.", "required": [ "metadata" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataWithTotalCount" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KMIPClientPartialCertificate" }, "minItems": 0, "maxItems": 200 } } }, "ListKMIPObjectsWithTotalCount": { "description": "The base schema for listing kmip objects in a kmip adapter with total count.", "required": [ "metadata" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataWithTotalCount" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/KMIPObject" }, "minItems": 0, "maxItems": 200 } } }, "PatchKeyRequestBody": { "description": "The base schema for patch key request body.", "properties": { "keyRingID": { "description": "The target key ring to move the targeted key to.", "nullable": true, "type": "string", "minLength": 2, "maxLength": 100, "pattern": "^[a-zA-Z0-9-]*$" } } }, "PatchKeyResponseBody": { "description": "The base schema for patch key response body.", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "An array of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/KeyFullRepresentation" } } } }, "PurgeKey": { "description": "The base schema for purged key.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/KeyFullRepresentation" } } } }, "RotationKeyMetadata": { "description": "Metadata that indicates the status of a rotation policy on the key.", "type": "object", "nullable": true, "required": [ "enabled" ], "properties": { "enabled": { "description": "If set to `true`, Key Protect enables a rotation policy on a single key.", "type": "boolean", "nullable": true, "example": true }, "interval_month": { "description": "Specifies the key rotation time interval in approximate months, where a month is equivalent to 30 days. A minimum of 1 and a maximum of 12 can be set.", "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "example": 3 } } }, "WDEKStateData": { "description": "Properties that are associated with a wrapped data encryption key (WDEK). This field only applies when `adopterKeyState` is `DEK_ENABLED`.", "type": "object", "required": [ "keyVersion" ], "properties": { "keyVersion": { "description": "The key version that was used to wrap the wrapped data encryption key (WDEK).\n*NOTE*: This key version is the same as the `keyVersion.id` value that's returned in a `wrap` call or the `rewrappedKeyVersion` value that's returned in a `rewrap` call.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 }, "rewrappedKeyVersion": { "description": "**Deprecated**, use **`keyVersion`.** The key version that was used to rewrap the wrapped data encryption key (WDEK). If both `rewrappedKeyVersion` and `keyVersion` are provided, `keyVersion` information will be used to update the registration.\n*NOTE*: This key version is the same as the `rewrappedKeyVersion` value that's returned in a `rewrap` call.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "deprecated": true } } }, "AllowedIPPort": { "description": "Properties associated with the port associated with an instance with an allowed IP policy.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/AllowedIPPortResource" } } } }, "AllowedIPPortResource": { "description": "Metadata of the port associated with an instance with an allowed IP policy.", "type": "object", "required": [ "private_endpoint_port" ], "properties": { "private_endpoint_port": { "description": "The port required to access an instance with an allowed IP policy via the Key Protect private service endpoint. Cannot be used with the Key Protect public service endpoint.\nFor more information, see [accessing an instance via private endpoint](/docs/key-protect?topic=key-protect-manage-allowed-ip#access-allowed-ip-private-endpoint) for instructions on how to use the `private_endpoint_port` value.", "type": "integer", "readOnly": true, "example": 8888 } } }, "AllowedIPProperties": { "type": "object", "description": "Data associated with the policy type `allowedIP`.", "nullable": true, "properties": { "allowed_ip": { "nullable": true, "description": "A string array of IPv4 or IPv6 CIDR notated subnets that are authorized to interact with the instance. If both `allowedNetwork` and `allowedIP` policies are set, only traffic aligning with both the `allowed_network` allowed network policy attribute and the `allowed_ip` allowed IP policy attribute will be allowed.\nIPv4 and iIP6 addresses are accepted for public endpoints. Only the IPv4 private network gateway addresses from the array will be authorized to access your instance via private endpoint.\n**Important:** Once set, accessing your instance may require additional steps. For more information, see [Accessing an instance via public endpoint](/docs/key-protect?topic=key-protect-manage-allowed-ip#access-allowed-ip-public-endpoint) and [Accessing an instance via private endpoint](/docs/key-protect?topic=key-protect-manage-allowed-ip#access-allowed-ip-private-endpoint) for more details.\n**Note:** An allowed IP policy does not affect requests from other IBM Cloud services.", "type": "array", "items": { "type": "string", "pattern": "^.{4,45}$", "minLength": 4, "maxLength": 45 }, "example": [ "10.1.0.0/32", "10.0.0.0/24", "192.0.2.0/32", "198.51.100.0/24", "2001:db8::/60" ], "minItems": 1, "maxItems": 1000 } } }, "AllowedNetworkPolicyProperties": { "type": "object", "nullable": true, "description": "Data associated with the policy type `allowed_network`.", "properties": { "allowed_network": { "description": "If set to `public-and-private`, Key Protect allows the instance to be accessible through public and private endpoints. If set to `private-only`, Key Protect restricts the instance to only be accessible through a private endpoint.", "type": "string", "nullable": true, "enum": [ "public-and-private", "private-only" ], "default": "public-and-private", "minLength": 12, "maxLength": 18 } } }, "CloudResourceName": { "description": "The object that contains information about the Cloud Resource Name", "type": "object", "properties": { "resourceCrn": { "description": "The [Cloud Resource Name](/docs/account?topic=account-crn) (CRN) that uniquely identifies your cloud resources.", "type": "string", "pattern": "^[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}$", "minLength": 9, "maxLength": 1289, "example": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:" } } }, "CreateKMIPAdapterRequestBody": { "description": "The base schema for the request body of a `POST /kmip_adapters`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "allOf": [ { "$ref": "#/components/schemas/CollectionMetadata" }, { "example": { "collectionType": "application/vnd.ibm.kms.kmip_adapter+json", "collectionTotal": 1 } } ] }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/CreateKMIPAdapterRequestBodyResources" } } } }, "CreateKMIPAdapterRequestBodyResources": { "$ref": "#/components/schemas/CreateKMIPAdapterObject" }, "CreateKMIPAdapterObject": { "required": [ "profile" ], "type": "object", "properties": { "name": { "$ref": "#/components/schemas/KMIPAdapterPropertyName" }, "description": { "$ref": "#/components/schemas/KMIPAdapterPropertyDescription" }, "profile": { "description": "The profile of KMIP adapter to be created", "type": "string", "enum": [ "native_1.0" ], "minLength": 10, "maxLength": 10 }, "profile_data": { "$ref": "#/components/schemas/KMIPProfileDataBody" } } }, "CreateKMIPClientCertificateRequestBody": { "description": "Properties of a client certificate that must be provided during creation", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "allOf": [ { "$ref": "#/components/schemas/CollectionMetadata" }, { "example": { "collectionType": "application/vnd.ibm.kms.kmip_client_certificate+json", "collectionTotal": 1 } } ] }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/CreateKMIPClientCertificateObject" } } } }, "CreateKMIPClientCertificateObject": { "required": [ "certificate" ], "type": "object", "example": { "certificate": "-----BEGIN CERTIFICATE-----\\nAAA\\n-----END CERTIFICATE-----", "name": "kmip-certificate-name" }, "allOf": [ { "$ref": "#/components/schemas/KMIPClientCertificateField" }, { "$ref": "#/components/schemas/KMIPClientCertificateNameField" } ] }, "CreateRegistration": { "description": "The base schema for the request body of a create registration.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/CreateRegistrationResourceBody" } } } }, "CreateRegistrationResourceBody": { "description": "The base schema for the resource in the body of a create registration.", "type": "object", "properties": { "preventKeyDeletion": { "description": "A boolean that determines whether Key Protect must prevent deletion of a root key. This policy should only be set if a WORM policy must be satisfied.\nIf set to `true`, Key Protect prevents deletion of the specified root key and its associated protected resources. The system prevents the deletion of any key that has at least one registration where `preventKeyDeletion` is `true`.", "nullable": true, "type": "boolean" }, "description": { "description": "A text field that cloud services can use to store external metadata about the registration. This field is exposed to customers when they review registered resources using GET /registrations.", "nullable": true, "type": "string", "minLength": 2, "maxLength": 240, "pattern": "^.{2,240}$" }, "registrationMetadata": { "description": "A text field that cloud services can use to store internal metadata about the registration. This field is not exposed to customers and is visible only with IBM Cloud service to service calls.", "nullable": true, "type": "string", "minLength": 2, "maxLength": 512, "pattern": "^.{2,512}$" } } }, "DeactivateRegistration": { "description": "The base schema for the request body of deactivate registration.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/CloudResourceName" } } } }, "DualAuthDeleteProperties": { "required": [ "enabled" ], "type": "object", "description": "User defined metadata that is associated with the `dualAuthDelete` instance policy type.", "properties": { "enabled": { "description": "If set to `true`, Key Protect enables a dual authorization deletion policy for your service instance.\nBy default, Key Protect requires only one authorization to delete a key. After you enable a dual authorization policy, any new key that you create or add to the instance will require an authorization from two users to delete keys.\n**Note:** This change does not affect existing keys in your instance.", "type": "boolean", "example": true } } }, "Error": { "description": "An error that occurred during the request.", "required": [ "errorMsg" ], "type": "object", "properties": { "errorMsg": { "description": "The conditions for an error response.", "type": "string", "example": "Bad Request: ..." } } }, "ErrorWithReason": { "description": "An error that occurred during the request that MAY include a reason.", "required": [ "errorMsg" ], "type": "object", "properties": { "errorMsg": { "description": "The conditions for an error response.", "type": "string" }, "reasons": { "type": "array", "minItems": 1, "maxItems": 1, "description": "An array of reasons.", "nullable": true, "items": { "type": "object", "title": "Reason", "description": "Specific description of why an error occurred.", "properties": { "code": { "description": "A machine-readable reason code that you can use to find specific details about why an error occurred.", "type": "string" }, "message": { "description": "Human-readable help text that corresponds with a reason code. This text is not suitable for error checking.", "type": "string" }, "status": { "description": "The HTTP status code that's returned in the response.", "type": "integer", "minimum": 200, "maximum": 599 }, "moreInfo": { "description": "A link to relevant documentation.", "type": "string" }, "target": { "nullable": true, "type": "object", "title": "Target", "description": "-> The problematic field, query parameter, or header.", "properties": { "type": { "type": "string", "description": "Problematic area.", "enum": [ "query_param", "path_param", "header", "field" ], "minLength": 5, "maxLength": 11 }, "name": { "description": "Specific problematic field, param or header.", "type": "string" } }, "required": [ "type", "name" ] } }, "required": [ "code", "message", "status" ] } } } }, "GetInstancePoliciesOneOf": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GetInstancePolicyAllowedNetwork" }, { "$ref": "#/components/schemas/GetInstancePolicyDualAuthDelete" }, { "$ref": "#/components/schemas/GetInstancePolicyAllowedIP" }, { "$ref": "#/components/schemas/GetInstancePolicyKeyCreateImportAccess" }, { "$ref": "#/components/schemas/GetInstancePolicyMetrics" }, { "$ref": "#/components/schemas/GetInstancePolicyRotation" }, { "$ref": "#/components/schemas/GetMultipleInstancePolicies" } ] }, "GetInstancePolicyAllowedIP": { "description": "Properties that are associated with retrieving an instance level allowed IP policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be retrieved.", "type": "string" }, "policy_data": { "description": "User defined metadata that is associated with the `allowedIP` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" } ], "properties": { "attributes": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AllowedIPProperties" } ] } } } }, "allOf": [ { "$ref": "#/components/schemas/InstancePolicyMetadata" } ] } } } }, "GetInstancePolicyAllowedNetwork": { "description": "Properties that are associated with retrieving an instance level allowed network policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be retrieved.", "type": "string" }, "policy_data": { "description": "User defined metadata that is associated with the `allowedNetwork` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" } ], "properties": { "attributes": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AllowedNetworkPolicyProperties" }, { "type": "object", "required": [ "allowed_network" ] } ] } } } }, "allOf": [ { "$ref": "#/components/schemas/InstancePolicyMetadata" } ] } } } }, "GetInstancePolicyDualAuthDelete": { "description": "Properties that are associated with retrieving an instance level dual authorization delete policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be retrieved.", "type": "string" }, "policy_data": { "$ref": "#/components/schemas/DualAuthDeleteProperties" } }, "allOf": [ { "$ref": "#/components/schemas/InstancePolicyMetadata" } ] } } } }, "GetInstancePolicyKeyCreateImportAccess": { "description": "Properties that are associated with retrieving an instance level key create and import access policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be retrieved.", "type": "string" }, "policy_data": { "description": "User defined metadata that is associated with the `keyCreateImportAccess` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" } ], "properties": { "attributes": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/KeyCreateImportAccessProperties" }, { "type": "object", "required": [ "create_root_key", "create_standard_key", "import_root_key", "import_standard_key", "enforce_token" ] } ] } } } }, "allOf": [ { "$ref": "#/components/schemas/InstancePolicyMetadata" } ] } } } }, "GetInstancePolicyMetrics": { "description": "Properties that are associated with retrieving an instance level metrics policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be retrieved.", "type": "string" }, "policy_data": { "$ref": "#/components/schemas/MetricsProperties" } }, "allOf": [ { "$ref": "#/components/schemas/InstancePolicyMetadata" } ] } } } }, "GetInstancePolicyRotation": { "description": "Properties that are associated with retrieving an instance level rotation policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be retrieved.", "type": "string" }, "policy_data": { "description": "User defined metadata that is associated with the `rotation` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" } ], "properties": { "attributes": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/RotationProperties" }, { "type": "object", "required": [ "interval_month" ] } ] } } } }, "allOf": [ { "$ref": "#/components/schemas/InstancePolicyMetadata" } ] } } } }, "GetKeyPoliciesOneOf": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/GetKeyPolicyDualAuthDelete" }, { "$ref": "#/components/schemas/GetKeyPolicyRotation" }, { "$ref": "#/components/schemas/GetMultipleKeyPolicies" } ] }, "GetKeyPolicy": { "description": "Properties that are associated with rotation policy.", "type": "object", "required": [ "id" ], "properties": { "id": { "description": "The v4 UUID used to uniquely identify the policy resource, as specified by RFC 4122.", "type": "string", "readOnly": true }, "crn": { "description": "The Cloud Resource Name (CRN) that uniquely identifies your cloud resources.", "type": "string", "readOnly": true, "example": "crn:v1:bluemix:public:kms::a/::policy:" }, "creationDate": { "description": "The date the policy was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" }, "createdBy": { "description": "The unique identifier for the resource that created the policy.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "readOnly": true }, "lastUpdateDate": { "description": "Updates when the policy is replaced or modified. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" }, "updatedBy": { "description": "The unique identifier for the resource that updated the policy.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "readOnly": true } } }, "GetMultipleInstancePolicies": { "description": "Properties that are associated with the instance level policies.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 0, "maxItems": 6, "items": { "$ref": "#/components/schemas/InstancePolicyResource" } } } }, "ImportToken": { "description": "Properties that are associated with import tokens.", "type": "object", "properties": { "expiration": { "description": "The time in seconds from the creation of an import token that determines how long its associated public key remains valid.\nThe minimum value is `300` seconds (5 minutes), and the maximum value is `86400` (24 hours). The default value is `600` (10 minutes).", "type": "number", "minimum": 300, "maximum": 86400, "default": 600, "nullable": true }, "maxAllowedRetrievals": { "description": "The number of times that an import token can be retrieved within its expiration time before it is no longer accessible.", "type": "number", "minimum": 1, "maximum": 500, "default": 1, "nullable": true }, "creationDate": { "description": "The date the import token was created. The date format follows RFC 3339.", "type": "string", "minLength": 20, "maxLength": 20, "format": "date-time", "example": "2000-03-21T00:00:00Z", "readOnly": true }, "expirationDate": { "description": "The date the import token expires. The date format follows RFC 3339.", "type": "string", "minLength": 20, "maxLength": 20, "format": "date-time", "example": "2000-03-21T00:00:00Z", "readOnly": true }, "remainingRetrievals": { "description": "The number of retrievals that are available for the import token before it is no longer accessible.", "type": "number", "minimum": 1, "default": 1, "readOnly": true } } }, "InstancePolicyAllAttributes": { "description": "All possible attributes for any instance policy type. Must be provided if the `enabled` field is `true`. Cannot be provided if the `enabled` field is `false`.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AllowedNetworkPolicyProperties" }, { "$ref": "#/components/schemas/AllowedIPProperties" }, { "$ref": "#/components/schemas/KeyCreateImportAccessProperties" }, { "$ref": "#/components/schemas/RotationProperties" } ] }, "InstancePolicyAllowedIPPolicyData": { "type": "object", "description": "User defined metadata that is associated with the `allowedIP` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" }, { "type": "object", "properties": { "attributes": { "description": "Attributes of an `allowedIP` instance policy. Must be provided if the `enabled` field is `true`. Cannot be provided if the `enabled` field is `false`.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/AllowedIPProperties" } ] } } } ] }, "InstancePolicyAllowedNetworkPolicyData": { "type": "object", "description": "User defined metadata that is associated with the `allowedNetwork` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" }, { "type": "object", "properties": { "attributes": { "description": "Attributes of an `allowedNetwork` instance policy. Must be provided if the `enabled` field is `true`. Cannot be provided if the `enabled` field is `false`.", "allOf": [ { "$ref": "#/components/schemas/AllowedNetworkPolicyProperties" }, { "type": "object", "required": [ "allowed_network" ] } ], "nullable": true, "type": "object" } } } ] }, "InstancePolicyEnabledProperty": { "required": [ "enabled" ], "description": "Property that determines whether an instance policy is active", "properties": { "enabled": { "description": "If set to `true`, Key Protect enables the specified policy for your service instance. If set to `false`, Key Protect disables the specified policy for your service instance, and the policy will no longer affect Key Protect actions.\n**Note:** If a policy with attributes is disabled, all attributes are reset and are not retained.", "type": "boolean", "example": true, "nullable": true } } }, "InstancePolicyKeyCreateImportAccessPolicyData": { "type": "object", "description": "User defined metadata that is associated with the `keyCreateImportAccess` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" }, { "type": "object", "properties": { "attributes": { "description": "Attributes of a `keyCreateImportAccess` instance policy. Must be provided if the `enabled` field is `true`. Cannot be provided if the `enabled` field is `false`.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/KeyCreateImportAccessProperties" } ] } } } ] }, "InstancePolicyMetadata": { "type": "object", "required": [ "creationDate", "createdBy" ], "properties": { "creationDate": { "description": "The date the policy was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" }, "createdBy": { "description": "The unique identifier for the resource that created the policy.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "readOnly": true }, "updatedBy": { "description": "The unique identifier for the resource that updated the policy.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "readOnly": true }, "lastUpdated": { "description": "Updates when the policy is replaced or modified. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" } } }, "InstancePolicyProperties": { "type": "object", "nullable": true, "description": "User defined metadata that is associated with any instance policy.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" }, { "type": "object", "properties": { "attributes": { "description": "Attributes associated with any instance policy type.", "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyAllAttributes" } ] } } } ] }, "InstancePolicyResource": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyMetadata" }, { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be retrieved.", "type": "string" }, "policy_data": { "$ref": "#/components/schemas/InstancePolicyProperties" } } } ] }, "InstancePolicyRotationPolicyData": { "type": "object", "description": "User defined metadata that is associated with the `rotation` instance policy type.", "allOf": [ { "$ref": "#/components/schemas/InstancePolicyEnabledProperty" }, { "type": "object", "properties": { "attributes": { "description": "Attributes of a `rotation` instance policy. Must be provided if the `enabled` field is `true`. Cannot be provided if the `enabled` field is `false`.", "allOf": [ { "$ref": "#/components/schemas/RotationProperties" } ], "nullable": true, "type": "object" } } } ] }, "Key": { "description": "Properties associated with a key response.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataOneOf" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/KeyWithPayload" } } } }, "KeyActionOneOf": { "oneOf": [ { "$ref": "#/components/schemas/WrapKeyRequestBody" }, { "$ref": "#/components/schemas/UnwrapKeyRequestBody" }, { "$ref": "#/components/schemas/RewrapKeyRequestBody" }, { "$ref": "#/components/schemas/RotateKeyRequestBody" }, { "$ref": "#/components/schemas/SecureRotateKeyRequestBody" } ] }, "KeyActionOneOfResponse": { "oneOf": [ { "$ref": "#/components/schemas/WrapKeyResponseBody" }, { "$ref": "#/components/schemas/UnwrapKeyResponseBody" }, { "$ref": "#/components/schemas/RewrapKeyResponseBody" } ] }, "KeyAliasResource": { "description": "Properties associated with an alias.", "type": "object", "properties": { "keyId": { "description": "The ID that identifies the key that is associated with the alias.", "type": "string", "example": "fadedbee-0000-0000-0000-1234567890ab", "readOnly": true }, "alias": { "description": "The unique, human-readable alias assigned to the key.", "type": "string", "example": "Example-test-key", "readOnly": true }, "createdBy": { "description": "The unique identifier for the user that created the alias.", "type": "string", "example": "IBMid-0000000000", "readOnly": true, "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$" }, "creationDate": { "description": "The date the alias was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" } } }, "KeyCreateImportAccessProperties": { "type": "object", "nullable": true, "description": "Data associated with the policy type `keyCreateImportAccess`.", "properties": { "create_root_key": { "description": "If set to `false`, the service prevents you or any authorized users from using Key Protect to create root keys in the specified service instance. If set to `true`, Key Protect allows you or any authorized users to create root keys in the instance.\n**Note:** If omitted, `POST /instance/policies` will set this attribute to the default value (`true`).", "type": "boolean", "example": true, "default": true, "nullable": true }, "create_standard_key": { "description": "If set to `false`, the service prevents you or any authorized users from using Key Protect to create standard keys in the specified service instance. If set to `true`, Key Protect allows you or any authorized users to create standard keys in the instance.\n**Note:** If omitted, `POST /instance/policies` will set this attribute to the default value (`true`).", "type": "boolean", "example": true, "default": true, "nullable": true }, "import_root_key": { "description": "If set to `false`, the service prevents you or any authorized users from importing root keys into the specified service instance. If set to `true`, Key Protect allows you or any authorized users to import root keys into the instance.\n**Note:** If omitted, `POST /instance/policies` will set this attribute to the default value (`true`).", "type": "boolean", "example": true, "default": true, "nullable": true }, "import_standard_key": { "description": "If set to `false`, the service prevents you or any authorized users from importing standard keys into the specified service instance. If set to `true`, Key Protect allows you or any authorized users to import standard keys into the instance.\n**Note:** If omitted, `POST /instance/policies` will set this attribute to the default value (`true`).", "type": "boolean", "example": true, "default": true, "nullable": true }, "enforce_token": { "description": "If set to `true`, the service prevents you or any authorized users from importing key material into the specified service instance without using an import token. If set to `false`, Key Protect allows you or any authorized users to import key material into the instance without the use of an import token.\n**Note:** If omitted, `POST /instance/policies` will set this attribute to the default value (`false`).", "type": "boolean", "example": true, "default": false, "nullable": true } } }, "KeyMetadata": { "description": "Additional properties that describe a key.", "type": "object", "properties": { "creationDate": { "description": "The date the key material was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "nullable": true, "example": "2000-03-21T00:00:00Z" }, "createdBy": { "description": "The unique identifier for the resource that created the key.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "readOnly": true }, "algorithmType": { "deprecated": true, "description": "Deprecated.", "type": "string", "enum": [ "AES", "Deprecated" ], "default": "AES", "readOnly": true, "minLength": 3, "maxLength": 10 }, "algorithmMetadata": { "deprecated": true, "description": "Deprecated.", "type": "object", "readOnly": true, "nullable": true, "properties": { "bitLength": { "description": "Deprecated.", "type": "string", "enum": [ "128", "192", "256" ], "default": "256", "minLength": 3, "maxLength": 3 }, "mode": { "description": "Deprecated.", "type": "string", "enum": [ "CBC_PAD", "Deprecated" ], "default": "CBC_PAD", "minLength": 7, "maxLength": 10 } } }, "algorithmBitSize": { "deprecated": true, "description": "Deprecated.", "type": "integer", "enum": [ 128, 192, 256 ], "default": 256 }, "algorithmMode": { "deprecated": true, "description": "Deprecated.", "type": "string", "enum": [ "CBC_PAD", "Deprecated" ], "default": "CBC_PAD", "minLength": 7, "maxLength": 10 }, "nonactiveStateReason": { "description": "A code indicating the reason the key is not in the activation state.", "type": "integer", "readOnly": true }, "lastUpdateDate": { "description": "Updates when any part of the key metadata is modified. The date format follows RFC 3339.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "example": "2000-03-21T00:00:00Z" }, "lastRotateDate": { "description": "Updates to show when the key was last rotated. The date format follows RFC 3339.", "type": "string", "nullable": true, "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" }, "keyVersion": { "$ref": "#/components/schemas/KeyVersion" }, "expirationDate": { "description": "The date and time that the key expires in the system, in RFC 3339 format (YYYY-MM-DD HH:MM:SS.SS, for example 2019-10-12T07:20:50.52Z). Keys created with an expiration date automatically transition to the Deactivated state within one hour after expiration. In this state, the only allowed actions on the key are unwrap, rewrap, rotate, and delete. Deactivated keys cannot be used to encrypt (wrap) new data, even if rotated while deactivated. Rotation does not reset or extend the expiration date, nor does it allow the date to be changed. It is recommended that any data encrypted with an expiring or expired key be re-encrypted using a new customer root key (CRK) before the original CRK expires, to prevent service disruptions. Deleting and restoring a deactivated key does not move it back to the Active state. If the expirationDate attribute is omitted, the key does not expire.", "type": "string", "nullable": true, "format": "date-time", "readOnly": true, "example": "2035-03-21T00:00:00Z" } } }, "KeyPolicyDualAuthDelete": { "description": "Properties that are associated with key level dual authorization delete policy.", "required": [ "type", "dualAuthDelete" ], "properties": { "type": { "description": "Specifies the MIME type that represents the policy resource. Currently, only the default is supported.", "type": "string", "example": "application/vnd.ibm.kms.policy+json", "enum": [ "application/vnd.ibm.kms.policy+json" ], "minLength": 35, "maxLength": 35 }, "dualAuthDelete": { "$ref": "#/components/schemas/KeyPolicyDualAuthDeleteDualAuthDelete" } } }, "KeyPolicyDualAuthDeleteDualAuthDelete": { "type": "object", "nullable": true, "required": [ "enabled" ], "description": "Data associated with the dual authorization delete policy.", "properties": { "enabled": { "description": "If set to `true`, Key Protect enables a dual authorization policy on a single key.\nAfter you enable the policy, Key Protect requires an authorization from two users to delete this key. For example, you can authorize the deletion first by using the [SetKeyForDeletion](#invoke-an-action-on-a-key) action. Then, a different user provides a second authorization implicitly by calling `DELETE /keys` to delete the key.\n**Note:** Once the dual authorization policy is set on the key, it cannot be reverted.", "type": "boolean", "nullable": true, "example": true } } }, "KeyPolicyDualAuthDeleteNonRequired": { "properties": { "dualAuthDelete": { "type": "object", "nullable": true, "required": [ "enabled" ], "description": "Data associated with the dual authorization delete policy.", "properties": { "enabled": { "description": "If set to `true`, Key Protect enables a dual authorization policy on a single key.\nAfter you enable the policy, Key Protect requires an authorization from two users to delete this key. For example, you can authorize the deletion first by using the [SetKeyForDeletion](#invoke-an-action-on-a-key) action. Then, a different user provides a second authorization implicitly by calling `DELETE /keys` to delete the key.\n**Note:** Once the dual authorization policy is set on the key, it cannot be reverted.", "type": "boolean", "example": true } } } } }, "KeyPolicyRotation": { "required": [ "type", "rotation" ], "properties": { "type": { "description": "Specifies the MIME type that represents the policy resource. Currently, only the default is supported.", "type": "string", "example": "application/vnd.ibm.kms.policy+json", "enum": [ "application/vnd.ibm.kms.policy+json" ], "minLength": 35, "maxLength": 35 }, "rotation": { "$ref": "#/components/schemas/KeyPolicyRotationRotation" } } }, "KeyPolicyRotationNonRequired": { "properties": { "rotation": { "nullable": true, "type": "object", "required": [ "enabled", "interval_month" ], "description": "Data associated with the automatic key rotation policy.", "properties": { "enabled": { "description": "If set to `true`, Key Protect enables a rotation policy on a single key.", "type": "boolean", "example": true }, "interval_month": { "description": "Specifies the key rotation time interval in approximate months standardized to 30 days each. A minimum of 1 and a maximum of 12 can be set.", "type": "integer", "minimum": 1, "maximum": 12, "example": 1 } } } } }, "KeyPolicyRotationRotation": { "type": "object", "nullable": true, "required": [ "enabled" ], "description": "Data associated with the automatic key rotation policy.", "properties": { "enabled": { "description": "If set to `true`, Key Protect enables a rotation policy on a single key.", "type": "boolean", "nullable": true, "example": true }, "interval_month": { "description": "Specifies the key rotation time interval in approximate months standardized to 30 days each. A minimum of 1 and a maximum of 12 can be set.", "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "example": 1 } } }, "KeyResource": { "description": "Properties that describe a key.", "type": "object", "properties": { "type": { "description": "Specifies the MIME type that represents the key resource. Currently, only the default is supported.", "type": "string", "minLength": 32, "maxLength": 32, "enum": [ "application/vnd.ibm.kms.key+json" ], "default": "application/vnd.ibm.kms.key+json" }, "id": { "description": "The v4 UUID used to uniquely identify the resource, as specified by RFC 4122.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "readOnly": true }, "name": { "description": "A human-readable name assigned to your key for convenience.\nTo protect your privacy do not use personal data, such as your name or location, as the name for your key.", "type": "string", "pattern": "^.{2,90}$", "minLength": 2, "maxLength": 90 }, "aliases": { "description": "One or more, up to a total of five, human-readable unique aliases assigned to your key.\nTo protect your privacy do not use personal data, such as your name or location, as an alias for your key.\nEach alias must be alphanumeric and cannot contain spaces or special characters other than `-` or `_`. The alias cannot be a UUID and must not be a Key Protect reserved name: `allowed_ip`, `key`, `keys`, `metadata`, `policy`, `policies`, `registration`, `registrations`, `ring`, `rings`, `rotate`, `wrap`, `unwrap`, `rewrap`, `version`, `versions`.", "type": "array", "items": { "type": "string", "pattern": "^[a-zA-Z0-9-_]{2,90}$", "minLength": 2, "maxLength": 90 }, "minItems": 0, "maxItems": 5 }, "description": { "description": "A text field used to provide a more detailed description of the key. The maximum length is 240 characters.\nTo protect your privacy, do not use personal data, such as your name or location, as a description for your key.", "type": "string", "minLength": 2, "maxLength": 240, "pattern": "^.{2,240}$" }, "tags": { "description": "Up to 30 tags can be created. Tags can be between 0-30 characters, including spaces. Special characters not permitted include angled brackets, comma, colon, ampersand, and vertical pipe character (|).\nTo protect your privacy, do not use personal data, such as your name or location, as a tag for your key.", "type": "array", "minItems": 0, "maxItems": 30, "items": { "type": "string", "minLength": 0, "maxLength": 30, "pattern": "^.{0,30}$" } }, "state": { "type": "integer", "description": "The key state based on NIST SP 800-57. States are integers and correspond to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values.", "readOnly": true, "enum": [ 0, 1, 2, 3, 5 ], "minimum": 0, "maximum": 5 }, "expirationDate": { "description": "The date and time that the key expires in the system, in RFC 3339 format (YYYY-MM-DD HH:MM:SS.SS, for example 2019-10-12T07:20:50.52Z). Use caution when setting an expiration date, as keys created with an expiration date automatically transition to the Deactivated state within one hour after expiration. In this state, the only allowed actions on the key are unwrap, rewrap, rotate, and delete. Deactivated keys cannot be used to encrypt (wrap) new data, even if rotated while deactivated. Rotation does not reset or extend the expiration date, nor does it allow the date to be changed. It is recommended that any data encrypted with an expiring or expired key be re-encrypted using a new customer root key (CRK) before the original CRK expires, to prevent service disruptions. Deleting and restoring a deactivated key does not move it back to the Active state. If the expirationDate attribute is omitted, the key does not expire.", "type": "string", "minLength": 20, "maxLength": 20, "format": "date-time", "writeOnly": true, "nullable": true, "example": "2035-03-21T00:00:00Z" }, "extractable": { "description": "A boolean that determines whether the key material can leave the service.\nIf set to `false`, Key Protect designates the key as a nonextractable root key used for `wrap` and `unwrap` actions. If set to `true`, Key Protect designates the key as a standard key that you can store in your apps and services. Once set to `false` it cannot be changed to `true`.", "type": "boolean", "default": true, "nullable": true }, "crn": { "description": "The Cloud Resource Name (CRN) that uniquely identifies your cloud resources.", "type": "string", "pattern": "^[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}:[^:]{0,128}$", "minLength": 9, "maxLength": 1289, "readOnly": true, "example": "crn:v1:bluemix:public:kms::a/::key:" }, "imported": { "description": "A boolean that shows whether your key was originally imported or generated in Key Protect. The value is set by Key Protect based on how the key material is initially added to the service.\nA value of `true` indicates that you must provide new key material when it's time to rotate the key. A value of `false` indicates that Key Protect will generate the new key material on a `rotate` operation, as it did in key creation.", "type": "boolean", "readOnly": true, "default": false }, "keyRingID": { "$ref": "#/components/schemas/KeyRingID" } } }, "KeyVersion": { "description": "Properties associated with a specific key version.", "type": "object", "readOnly": true, "nullable": true, "properties": { "id": { "description": "The ID of the key version.", "type": "string", "readOnly": true, "example": "fadedbee-0000-0000-0000-1234567890ab" }, "creationDate": { "description": "The date that the version of the key was created.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "example": "2000-03-21T00:00:00Z" } } }, "KeyVersionID": { "description": "Properties associated with a specific key version.", "type": "object", "readOnly": true, "nullable": true, "properties": { "id": { "description": "The ID of the key version.", "type": "string", "readOnly": true, "example": "fadedbee-0000-0000-0000-1234567890ab" } } }, "KMIPAdapter": { "description": "Properties applicable to all KMIP adapter resources.", "required": [ "id", "name", "created_at", "created_by", "updated_at", "updated_by", "profile" ], "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "The v4 UUID that uniquely identifies this KMIP adapter." } ] }, "name": { "$ref": "#/components/schemas/KMIPAdapterPropertyName" }, "created_at": { "description": "The date the KMIP adapter was created. The date format follows RFC 3339.", "format": "date-time", "nullable": true, "type": "string" }, "created_by": { "description": "The unique identifier of the user that created the KMIP adapter.", "type": "string" }, "updated_at": { "description": "The date the KMIP adapter was last modified, either by creation or by modification of adapter subresources. The date format follows RFC 3339.", "format": "date-time", "nullable": true, "type": "string" }, "updated_by": { "description": "The unique identifier of the user that updated the KMIP adapter.", "type": "string" }, "profile": { "description": "The profile of KMIP adapter.", "type": "string", "enum": [ "native_1.0" ], "minLength": 10, "maxLength": 10 }, "description": { "$ref": "#/components/schemas/KMIPAdapterPropertyDescription" }, "profile_data": { "$ref": "#/components/schemas/KMIPProfileDataBody" } } }, "KMIPAdapterPropertyDescription": { "description": "The optional description of the KMIP adapter. The maximum length is 240 characters. To protect your privacy, do not use personal data, such as your name or location, as a description for your KMIP adapter.", "type": "string", "example": "kmip adapter description", "minLength": 2, "maxLength": 240, "pattern": "^.{2,240}$" }, "KMIPAdapterPropertyName": { "description": "A human-readable name of the KMIP adapter unique within the kms instance. If one is not specified, one will be autogenerated of the format `kmip_adapter_`.\nTo protect your privacy do not use personal data, such as your name or location, as a name for your KMIP adapter. The name must be alphanumeric and cannot contain spaces or special characters other than `-` or `_`. The name cannot be a UUID.", "example": "kmip-adapter-name", "minLength": 2, "maxLength": 40, "pattern": "^[a-zA-Z0-9-_]{2,40}$", "type": "string" }, "KMIPClientCertificateField": { "required": [ "certificate" ], "properties": { "certificate": { "description": "The client certificate to be associated with the KMIP Adapter. It should explicitly have the BEGIN CERTIFICATE and END CERTIFICATE tags.", "minLength": 50, "maxLength": 100000, "pattern": "^\\s*-----BEGIN CERTIFICATE-----[A-Za-z0-9+/\\=\\r\\\\n]+-----END CERTIFICATE-----\\s*$", "type": "string" } } }, "KMIPClientCertificateNameField": { "properties": { "name": { "description": "A human-readable name that uniquely identifies a certificate within the given adapter. If one is not specified, one will be autogenerated of the format `kmip_cert_`.\nTo protect your privacy do not use personal data, such as your name or location, as a name for your client certificate. The name must be alphanumeric and cannot contain spaces or special characters other than `-` or `_`. The name cannot be a UUID.", "minLength": 2, "maxLength": 40, "pattern": "^[a-zA-Z0-9-_]{2,40}$", "type": "string" } } }, "KMIPClientCertificate": { "description": "Properties of a client certificate", "example": { "id": "feddecaf-0000-0000-0000-1234567890ab", "name": "kmip-client-certificate", "certificate": "...", "created_at": "2000-01-23T04:56:07.000Z", "created_by": "IBMid-0000000000" }, "allOf": [ { "$ref": "#/components/schemas/KMIPClientPartialCertificate" }, { "$ref": "#/components/schemas/KMIPClientCertificateField" } ] }, "KMIPClientPartialCertificate": { "description": "Partial properties of a client certificate", "required": [ "id", "name", "created_at", "created_by" ], "example": { "id": "feddecaf-0000-0000-0000-1234567890ab", "name": "kmip-client-certificate", "created_at": "2000-01-23T04:56:07.000Z", "created_by": "IBMid-0000000000" }, "allOf": [ { "$ref": "#/components/schemas/KMIPClientCertificateNameField" }, { "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "The v4 UUID that uniquely identifies this certificate resource." } ] }, "created_at": { "description": "The date this certificate resource was created on the KMIP Adapter. The date format follows RFC 3339.", "format": "date-time", "nullable": true, "type": "string" }, "created_by": { "description": "The IAM id that created the certificate resource.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$" } } } ] }, "KMIPObjectPropertyState": { "type": "integer", "minimum": 1, "maximum": 6, "description": "States are integers and correspond to Pre-Active = 1, Active = 2, Deactivated = 3, Compromised = 4, Destroyed = 5, Destroyed Compromised = 6. For more info on the KMIP specification, read https://docs.oasis-open.org/kmip/spec/v1.4/os/kmip-spec-v1.4-os.html" }, "KMIPObject": { "description": "Properties applicable to all KMIP object resources.", "required": [ "id", "kmip_object_type", "created_at", "created_by_kmip_client_cert_id" ], "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "The v4 UUID that uniquely identifies this KMIP object." } ] }, "kmip_object_type": { "description": "The object type of the kmip object according to the KMIP specification. Currently, only kmip_object_type 2(Symmetric Key) is supported. For more info on the KMIP specification and object types, read https://docs.oasis-open.org/kmip/spec/v1.4/os/kmip-spec-v1.4-os.html#_Toc490660932", "type": "integer", "enum": [ 2 ] }, "state": { "type": "integer", "description": "States are integers and correspond to Pre-Active = 1, Active = 2, Deactivated = 3, Compromised = 4, Destroyed = 5, Destroyed Compromised = 6. For more info on the KMIP specification, read https://docs.oasis-open.org/kmip/spec/v1.4/os/kmip-spec-v1.4-os.html", "enum": [ 1, 2, 3, 4, 5, 6 ], "minimum": 1, "maximum": 6 }, "created_at": { "description": "The date the KMIP object was created. The date format follows RFC 3339.", "format": "date-time", "nullable": true, "type": "string" }, "created_by_kmip_client_cert_id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "The v4 UUID that uniquely identifies the certificate used to create this KMIP object." } ] }, "created_by": { "description": "The IAM id that created the certificate resource used to create this KMIP object.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$" }, "updated_at": { "description": "The date the KMIP object was last modified. The date format follows RFC 3339.", "format": "date-time", "nullable": true, "type": "string" }, "updated_by_kmip_client_cert_id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "The v4 UUID that uniquely identifies the certificate used to update this KMIP object." } ] }, "updated_by": { "description": "The IAM id that created the certificate resource used to update this KMIP object.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$" }, "destroyed_at": { "description": "The date the KMIP object was destroyed. The date format follows RFC 3339.", "format": "date-time", "nullable": true, "type": "string" }, "destroyed_by_kmip_client_cert_id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "The v4 UUID that uniquely identifies the certificate used to destroy this KMIP object." } ] }, "destroyed_by": { "description": "The IAM id that created the certificate resource used to destroy this KMIP object.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$" }, "recoverable": { "description": "A boolean that specifies if the object has the ability to be restored.", "type": "boolean", "nullable": true } } }, "KMIPProfileDataBody": { "description": "The data specific to the KMIP Adapter profile. This is a required field for profile `native_1.0`", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/KMIPProfileDataNative" } ] }, "KMIPProfileDataNative": { "required": [ "crk_id" ], "description": "Properties that must be specified to profile_data when it is of native_1.0 KMIP adapter resource.", "type": "object", "example": { "crk_id": "feddecaf-0000-0000-0000-1234567890ab" }, "properties": { "crk_id": { "allOf": [ { "$ref": "#/components/schemas/UUID" }, { "description": "An ID that identifies the Customer Root Key(CRK) to be used. This CRK must exist in the same kms instance as the adapter." } ] } } }, "MetricsProperties": { "required": [ "enabled" ], "type": "object", "description": "User defined metadata that is associated with the `metrics` instance policy type.", "properties": { "enabled": { "description": "If set to `true`, Key Protect will send service instance metrics to your [Cloud Monitoring With Sysdig](/docs/Monitoring-with-Sysdig?topic=Monitoring-with-Sysdig-getting-started) monitoring instance.\nBy default, sending metrics to your [Cloud Monitoring With Sysdig](/docs/Monitoring-with-Sysdig?topic=Monitoring-with-Sysdig-getting-started) monitoring instance is disabled.\n**Note:** A metrics policy will add an additional metrics source to your [Cloud Monitoring With Sysdig](/docs/Monitoring-with-Sysdig?topic=Monitoring-with-Sysdig-getting-started) monitoring instance. For more information, see [Enabling Platform Metrics](/docs/Monitoring-with-Sysdig?topic=Monitoring-with-Sysdig-platform_metrics_enabling) for more information.", "type": "boolean", "example": true } } }, "ModifiableRegistrationResourceBody": { "allOf": [ { "$ref": "#/components/schemas/CreateRegistrationResourceBody" }, { "type": "object", "properties": { "keyVersionId": { "description": "The ID of the key version that you want to register. This must be a version that is newer than the registered key version.", "nullable": true, "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36 } } } ] }, "Registration": { "description": "Properties associated with a registration response.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/RegistrationResource" } } } }, "RegistrationActionOneOf": { "oneOf": [ { "$ref": "#/components/schemas/DeactivateRegistration" } ] }, "RegistrationResource": { "description": "Properties associated with a registration.", "type": "object", "properties": { "keyId": { "description": "The ID that identifies the root key that is associated with the specified cloud resource.", "type": "string", "example": "fadedbee-0000-0000-0000-1234567890ab", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "readOnly": true }, "keyName": { "description": "The human-readable reference assigned to the key that is associated with the specified cloud resource.", "type": "string", "example": "Example Key Name", "readOnly": true, "pattern": "^.{2,90}$", "minLength": 2, "maxLength": 90 }, "resourceCrn": { "description": "The [Cloud Resource Name](/docs/account?topic=account-crn) (CRN) that represents the cloud resource, such as a Cloud Object Storage bucket, that is associated with the key.", "type": "string", "example": "crn:v1:bluemix:public:::a/:::", "readOnly": true }, "createdBy": { "description": "The unique identifier for the resource that created the registration.", "type": "string", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "example": "IBMid-0000000000", "readOnly": true }, "creationDate": { "description": "The date the registration was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z", "minLength": 20, "maxLength": 20 }, "updatedBy": { "description": "The unique identifier for the resource that updated the registration.", "type": "string", "example": "IBMid-0000000000", "minLength": 5, "maxLength": 100, "pattern": "^.{5,100}$", "readOnly": true }, "lastUpdated": { "description": "Updates when the registration is modified. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2000-03-21T00:00:00Z" }, "description": { "description": "Description of the purpose of the registration.", "type": "string", "example": "Example description", "readOnly": true, "minLength": 2, "maxLength": 240, "pattern": "^.{2,240}$" }, "registrationMetadata": { "description": "Additional information about the registration. This field is not exposed to customers and is visible only with IBM Cloud service to service calls.", "type": "string", "example": "us-south", "readOnly": true, "minLength": 0, "maxLength": 512, "pattern": "^.{0,512}$" }, "preventKeyDeletion": { "description": "A boolean that determines whether Key Protect must prevent deletion of a root key.", "type": "boolean", "example": false, "readOnly": true }, "keyVersion": { "$ref": "#/components/schemas/KeyVersion" } } }, "RegistrationWithTotalCount": { "description": "Properties associated with a list registration response which may include total registration count.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadataWithTotalCount" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 0, "maxItems": 5000, "items": { "$ref": "#/components/schemas/RegistrationResource" } } } }, "ReplaceRegistration": { "description": "The base schema for the request body of a replace registration.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/ReplaceRegistrationResourceBody" } } } }, "ReplaceRegistrationResourceBody": { "allOf": [ { "$ref": "#/components/schemas/ModifiableRegistrationResourceBody" }, { "type": "object", "required": [ "description", "preventKeyDeletion", "keyVersionId", "registrationMetadata" ] } ] }, "RewrapCiphertext": { "description": "Properties that are associated with the rewrap ciphertext", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UnwrapCiphertext" }, { "type": "object", "properties": { "ciphertext": { "description": "The wrapped data encryption key (WDEK) that you want to re-encrypt by using the latest key version. When present, the ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to use store and use this WDEK in future calls to Key Protect. The value must be base64 encoded." } } } ] }, "RewrapKeyRequestBody": { "description": "Properties that are associated with the request body of a rewrap action.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RewrapCiphertext" }, { "$ref": "#/components/schemas/WrapUnwrapRequestFields" } ] }, "RewrapKeyResponseBody": { "description": "Properties that are associated with the response body of an rewrap action.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UnwrapCiphertext" }, { "$ref": "#/components/schemas/WrappedKeyVersion" }, { "$ref": "#/components/schemas/RewrappedKeyVersion" } ] }, "RewrappedKeyVersion": { "description": "Properties that are associated with the rewrapped key version.", "type": "object", "properties": { "rewrappedKeyVersion": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/KeyVersionID" }, { "description": "The latest key version that was used to rewrap the DEK. This key version is associated with the `ciphertext` value that's returned in the response." } ] } } }, "RotateKeyOneOf": { "description": "Schema for the request body of a rotate action with or without secure import.", "type": "object", "oneOf": [ { "$ref": "#/components/schemas/RotateKeyRequestBody" }, { "$ref": "#/components/schemas/SecureRotateKeyRequestBody" } ] }, "RotateKeyRequestBody": { "description": "Base schema for the request body of a rotate action.", "type": "object", "properties": { "payload": { "description": "The key material that you want to import into the service for rotating an existing root key. This value is required for a `rotate` action if you initially imported the key material when you created the key.\nTo rotate an imported root key, provide a base64 encoded payload in the request entity-body. To rotate a root key that was initially generated by Key Protect, omit the `payload` property and pass in an empty request entity-body.", "type": "string", "writeOnly": true, "minLength": 0, "maxLength": 10000, "pattern": "^.{0,10000}$" } } }, "RotationProperties": { "type": "object", "nullable": true, "description": "Data associated with the policy type `rotation`.", "properties": { "interval_month": { "description": "Specifies the key rotation time interval in approximate months, where a month is equivalent to 30 days. A minimum of 1 and a maximum of 12 can be set.", "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "example": 3 } } }, "SecureImport": { "description": "Additional properties that are associated with importing a key with an import token.", "type": "object", "required": [ "payload", "encryptedNonce", "iv", "encryptionAlgorithm" ], "properties": { "payload": { "description": "The optional encrypted key material that you want to store and manage in the service. If included, the value must be [base64 encoded](/docs/key-protect?topic=key-protect-import-root-keys#how-to-encode-root-key-material).\n\nFirst, retrieve the public key that is associated with your service\ninstance by calling `GET /import_token`. Then, use the public key to\nrun RSA encryption on the key material that you want to import to\nthe service.", "type": "string", "minLength": 0, "maxLength": 10000, "pattern": "^.{0,10000}$", "format": "byte", "writeOnly": true }, "encryptedNonce": { "description": "The optional encrypted nonce value that protects a key import request against replay attacks. When present, this value must be encrypted by using the encrypted `payload` value that represents the key that you want to import into the service. The value should be base64 encoded.\nTo retrieve a nonce value, use `GET /import_token`. Then, encrypt the value by using an AES-GCM encryption method that is compatible with your environment.", "type": "string", "minLength": 40, "maxLength": 40, "pattern": "^.{40}$", "format": "byte", "writeOnly": true }, "iv": { "description": "The initialization vector (IV) provided to the AES-GCM algorithm when you encrypt a nonce. The IV value is required to decrypt the optionally provided `encryptedNonce` value. The value should be base64 encoded.", "type": "string", "format": "byte", "writeOnly": true, "minLength": 12, "maxLength": 32, "pattern": "^.{12,32}$" }, "encryptionAlgorithm": { "description": "The RSA encryption algorithm that is used to encrypt the key material that you want to import into the service. Currently, `RSAES_OAEP_SHA_256` is supported.", "type": "string", "example": "RSAES_OAEP_SHA_256", "minLength": 18, "maxLength": 18, "pattern": "^RSAES_OAEP_SHA_256$", "writeOnly": true } } }, "SecureRotateKeyRequestBody": { "description": "Base schema for the request body of a secure rotate action.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/RotateKeyRequestBody" }, { "$ref": "#/components/schemas/SecureImport" } ] }, "SetInstancePoliciesOneOf": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SetInstancePolicyAllowedNetwork" }, { "$ref": "#/components/schemas/SetInstancePolicyDualAuthDelete" }, { "$ref": "#/components/schemas/SetInstancePolicyAllowedIP" }, { "$ref": "#/components/schemas/SetInstancePolicyKeyCreateImportAccess" }, { "$ref": "#/components/schemas/SetInstancePolicyMetrics" }, { "$ref": "#/components/schemas/SetInstancePolicyRotation" }, { "$ref": "#/components/schemas/SetMultipleInstancePolicies" } ] }, "SetInstancePolicyAllowedIP": { "description": "Properties that are associated with setting an instance level allowed IP policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "example": "allowedIP", "enum": [ "allowedIP" ], "minLength": 9, "maxLength": 9 }, "policy_data": { "$ref": "#/components/schemas/InstancePolicyAllowedIPPolicyData" } } } } } }, "SetInstancePolicyAllowedNetwork": { "description": "Properties that are associated with setting an instance level allowed network policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "example": "allowedNetwork", "enum": [ "allowedNetwork" ], "minLength": 14, "maxLength": 14 }, "policy_data": { "$ref": "#/components/schemas/InstancePolicyAllowedNetworkPolicyData" } } } } } }, "SetInstancePolicyDualAuthDelete": { "description": "Properties that are associated with setting a dual authorization delete instance policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "example": "dualAuthDelete", "enum": [ "dualAuthDelete" ], "minLength": 14, "maxLength": 14 }, "policy_data": { "$ref": "#/components/schemas/DualAuthDeleteProperties" } } } } } }, "SetInstancePolicyKeyCreateImportAccess": { "description": "Properties that are associated with setting an instance level key create and import access policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "example": "keyCreateImportAccess", "enum": [ "keyCreateImportAccess" ], "minLength": 21, "maxLength": 21 }, "policy_data": { "$ref": "#/components/schemas/InstancePolicyKeyCreateImportAccessPolicyData" } } } } } }, "SetInstancePolicyMetrics": { "description": "Properties that are associated with setting a metrics instance policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "example": "metrics", "enum": [ "metrics" ], "minLength": 7, "maxLength": 7 }, "policy_data": { "$ref": "#/components/schemas/MetricsProperties" } } } } } }, "SetInstancePolicyRotation": { "description": "Properties that are associated with setting an instance level rotation policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "example": "rotation", "enum": [ "rotation" ], "minLength": 8, "maxLength": 8 }, "policy_data": { "$ref": "#/components/schemas/InstancePolicyRotationPolicyData" } } } } } }, "SetKeyPoliciesOneOf": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/SetKeyPolicyDualAuthDelete" }, { "$ref": "#/components/schemas/SetKeyPolicyRotation" }, { "$ref": "#/components/schemas/SetMultipleKeyPolicies" } ] }, "SetKeyPolicyDualAuthDelete": { "description": "Base schema for request of create/update of key level dual authorization delete policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/KeyPolicyDualAuthDelete" } } } }, "SetKeyPolicyRotation": { "description": "Base schema for request of create/update of key level rotation policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/KeyPolicyRotation" } } } }, "SetMultipleInstancePolicies": { "description": "Properties that are associated with setting any type of instance level policy.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 6, "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "enum": [ "allowedNetwork", "dualAuthDelete", "allowedIP", "keyCreateImportAccess", "metrics", "rotation" ], "minLength": 7, "maxLength": 21 }, "policy_data": { "allOf": [ { "$ref": "#/components/schemas/InstancePolicyProperties" }, { "type": "object", "properties": { "attributes": { "description": "Attributes associated with any instance policy type. Must be provided if the `enabled` field is `true`. Cannot be provided if the `enabled` field is `false`. Only attributes corresponding to the `policy_type` can be provided.", "nullable": true, "type": "object" } } } ], "nullable": true, "type": "object" } } } } } }, "SetMultipleKeyPoliciesResource": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/KeyPolicyDualAuthDelete" }, { "$ref": "#/components/schemas/KeyPolicyRotation" } ] }, "SetMultipleKeyPolicies": { "description": "Properties that are associated with key.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 2, "items": { "$ref": "#/components/schemas/SetMultipleKeyPoliciesResource" } } } }, "UnwrapCiphertext": { "description": "Properties that are associated with the unwrap ciphertext. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect.", "type": "object", "properties": { "ciphertext": { "type": "string", "description": "The wrapped data encryption key (WDEK) that you can export to your app or service. The ciphertext contains the DEK wrapped by the latest version of the key (WDEK). It is recommended to store and use this WDEK in future calls to Key Protect. The value is base64 encoded.", "minLength": 4, "maxLength": 7184, "pattern": "^.{4,7184}$" } } }, "UnwrapKeyRequestBody": { "description": "Properties that are associated with the request body of a unwrap action.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/UnwrapCiphertext" }, { "$ref": "#/components/schemas/WrapUnwrapRequestFields" } ] }, "UnwrapKeyResponseBody": { "description": "Properties that are associated with the response body of an unwrap action.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WrapPlaintext" }, { "$ref": "#/components/schemas/UnwrapCiphertext" }, { "$ref": "#/components/schemas/WrappedKeyVersion" }, { "$ref": "#/components/schemas/RewrappedKeyVersion" } ] }, "UpdateRegistration": { "description": "The base schema for the request body of a update registration.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "minItems": 1, "maxItems": 1, "items": { "$ref": "#/components/schemas/ModifiableRegistrationResourceBody" } } } }, "UUID": { "title": "UUID", "description": "A v4 UUID identifier.", "type": "string", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "minLength": 36, "maxLength": 36, "example": "feddecaf-0000-0000-0000-1234567890ab" }, "WrapKeyRequestBody": { "description": "Properties that are associated with the request body of a wrap action.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WrapPlaintext" }, { "$ref": "#/components/schemas/WrapUnwrapRequestFields" } ] }, "WrapKeyResponseBody": { "description": "Properties that are associated with the response body of a wrap action.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WrapPlaintext" }, { "$ref": "#/components/schemas/UnwrapCiphertext" }, { "$ref": "#/components/schemas/WrappedKeyVersion" } ] }, "WrappedKeyVersion": { "description": "Properties that are associated with the wrapped key version.", "type": "object", "properties": { "keyVersion": { "nullable": true, "type": "object", "allOf": [ { "$ref": "#/components/schemas/KeyVersionID" }, { "description": "The key version that was used to wrap the DEK. This key version is associated with the `ciphertext` value that was used in the request." } ] } } }, "WrapPlaintext": { "description": "Properties that are associated with the wrap plaintext.", "type": "object", "properties": { "plaintext": { "type": "string", "description": "The data encryption key (DEK) used in wrap actions when the query parameter is set to `wrap`. The system returns a base64 encoded plaintext in the response entity-body when you perform an `unwrap` action on a key.\nTo wrap an existing DEK, provide a base64 encoded plaintext during a `wrap` action. To generate a new DEK, omit the `plaintext` property. Key Protect generates a random plaintext (32 bytes) that is rooted in an HSM and then wraps that value.\n**Note:** When you unwrap a wrapped data encryption key (WDEK) by using a rotated root key, the service returns a new ciphertext in the response entity-body. Each ciphertext remains available for `unwrap` actions. If you unwrap a DEK with a previous ciphertext, the service also returns the latest ciphertext in the response. Use the latest ciphertext for future unwrap operations.", "minLength": 0, "maxLength": 4096, "pattern": "^.{0,4096}$" } } }, "WrapUnwrapKeyCompatibility": { "description": "Properties associated with an out-dated specification of Wrap/Unwrap/Rewrap API. *NOTE*: This is only to be used in server side code generation for backwards compatibility, and should not be used by the client or referenced elsewhere in the API.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/WrapPlaintext" }, { "$ref": "#/components/schemas/UnwrapCiphertext" }, { "$ref": "#/components/schemas/WrapUnwrapRequestFields" } ] }, "WrapUnwrapRequestFields": { "description": "Properties associated with the request body of wrap, unwrap and rewrap actions.", "type": "object", "properties": { "aad": { "type": "array", "items": { "type": "string", "minLength": 0, "maxLength": 255, "pattern": "^.{0,255}$" }, "description": "The additional authentication data (AAD) used to further secure the key.\nIf you supply AAD when you make a `wrap` call, you must specify the same AAD during a subsequent `unwrap` call.", "minItems": 0, "maxItems": 126, "writeOnly": true } } } }, "requestBodies": { "CreateKeyBody": { "description": "The base request for creating a new key.", "required": true, "content": { "application/vnd.ibm.kms.key+json": { "schema": { "$ref": "#/components/schemas/CreateKeyOneOf" }, "examples": { "CreateRootKey": { "$ref": "#/components/examples/CreateRootKey" }, "ImportRootKey": { "$ref": "#/components/examples/ImportRootKey" }, "ImportRootKeyWithImportToken": { "$ref": "#/components/examples/ImportRootKeyWithImportToken" } } } } }, "CreateKeyWithPolicyOverridesBody": { "description": "The base request for creating a new key with policies.", "required": true, "content": { "application/vnd.ibm.kms.key+json": { "schema": { "$ref": "#/components/schemas/CreateKeyWithPolicyOverridesOneOf" }, "examples": { "CreateRootKey": { "$ref": "#/components/examples/CreateRootKeyWithPolicyOverrides" }, "ImportRootKey": { "$ref": "#/components/examples/ImportRootKeyWithPolicyOverrides" }, "ImportRootKeyWithImportToken": { "$ref": "#/components/examples/ImportRootKeyWithImportTokenWithPolicyOverrides" } } } } }, "EventAcknowledgeBody": { "description": "The base request for acknowledging a key action events.", "required": true, "content": { "application/vnd.ibm.kms.event_acknowledge+json": { "schema": { "$ref": "#/components/schemas/EventAcknowledge" }, "examples": { "SingleEvent": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.event_acknowledge+json", "collectionTotal": 1 }, "resources": [ { "eventId": "feddecaf-0000-0000-0000-1234567890ab", "adopterKeyState": "DEK_ENABLED", "timestamp": "2000-03-21T00:00:00Z", "keyStateData": { "keyVersion": "fadedbee-0000-0000-0000-1234567890ab" } } ] } }, "BatchEvents": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.event_acknowledge+json", "collectionTotal": 2 }, "resources": [ { "eventId": "feddecaf-0000-0000-0000-1234567890ab", "adopterKeyState": "DEK_ENABLED", "timestamp": "2000-03-21T00:00:00Z", "keyStateData": { "keyVersion": "fadedbee-0000-0000-0000-1234567890ab" } }, { "eventId": "addedace-0000-0000-0000-1234567890ab", "adopterKeyState": "DEK_ENABLED", "timestamp": "2000-03-21T00:00:00Z" }, { "eventId": "beadcafe-0000-0000-0000-1234567890ab", "adopterKeyState": "DEK_DISABLED", "timestamp": "2000-03-21T00:00:00Z" } ] } } } } } }, "InstanceCreateUpdatePolicyBody": { "description": "The base request for the create or update of instance level policies.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetInstancePoliciesOneOf" }, "examples": { "allowedNetwork": { "$ref": "#/components/examples/SetInstancePolicyAllowedNetwork" }, "dualAuthDelete": { "$ref": "#/components/examples/SetInstancePolicyDualAuthDelete" }, "allowedIP": { "$ref": "#/components/examples/SetInstancePolicyAllowedIP" }, "keyCreateImportAccess": { "$ref": "#/components/examples/SetInstancePolicyKeyCreateImportAccess" }, "metrics": { "$ref": "#/components/examples/SetInstancePolicyMetrics" }, "rotation": { "$ref": "#/components/examples/SetInstancePolicyRotation" }, "policies": { "$ref": "#/components/examples/SetMultipleInstancePolicies" } } } } }, "KeyActionBody": { "description": "The base request for key actions.", "required": true, "content": { "application/vnd.ibm.kms.key_action+json": { "schema": { "$ref": "#/components/schemas/KeyActionOneOf" }, "examples": { "WrapKey": { "$ref": "#/components/examples/WrapKey" }, "UnwrapKey": { "$ref": "#/components/examples/UnwrapKey" }, "RewrapKey": { "$ref": "#/components/examples/RewrapKey" }, "RotateKey": { "$ref": "#/components/examples/RotateKey" }, "SecureRotateKey": { "$ref": "#/components/examples/SecureRotateKey" } } } } }, "KeyCreateUpdatePolicyBody": { "description": "The base request for key policy create or update.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetKeyPoliciesOneOf" }, "examples": { "dualAuthDelete": { "$ref": "#/components/examples/SetKeyPolicyDualAuthDelete" }, "rotation": { "$ref": "#/components/examples/SetKeyPolicyRotation" }, "policies": { "$ref": "#/components/examples/SetMultipleKeyPolicies" } } } } }, "RegistrationActionBody": { "description": "The base request for registration actions.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationActionOneOf" }, "examples": { "DeactivateRegistration": { "$ref": "#/components/examples/DeactivateRegistration" } } } } } }, "responses": { "BadRequest": { "description": "The request is missing a required field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: The request is missing a required field." } ] } } } }, "Forbidden": { "description": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Your service is not authorized to make this request. Ensure that an authorization exists between your service and Key Protect. [Learn more](/docs/key-protect?topic=key-protect-integrate-services#grant-access)" } ] } } } }, "ForbiddenRegistration": { "description": "You are not authorized to make this request due to [missing authorization](/docs/key-protect?topic=key-protect-integrate-services#grant-access) between the service instance and Key Protect instance, requiring a service-to-service call, or a mismatch between the cloud service CRN and the resource CRN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Caller is not authorized to make this request.", "reasons": [ { "code": "RESOURCE_OWNER_ERR", "message": "The resource queried does not belong to the service.", "status": 403, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } } } }, "Gone": { "description": "The requested key was previously deleted and is no longer available. Delete references to this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: The requested key was previously deleted and is no longer available. Delete references to this key." } ] } } } }, "InternalServerError": { "description": "IBM Key Protect is currently unavailable. Your request could not be processed. Try again later.\nIf the problem persists, note the `correlation-ID` in the response header and contact [IBM Cloud support](https://watson.service-now.com/wcp).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Internal Server Error: IBM Key Protect is currently unavailable. Your request could not be processed. Try again later." } ] } } } }, "KMIPAdapterNotFound": { "description": "The kmip adapter with that id / name could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "examples": { "KMIPAdapterNotFound": { "$ref": "#/components/examples/KMIPAdapterNotFound" } } } } }, "NotFound": { "description": "The key could not be found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: The key could not be found. KEY_NOT_FOUND_ERR: Key does not exist" } ] } } } }, "TooManyRequests": { "description": "Too many requests. Wait a few minutes and try again.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Too Many Requests: Wait a few minutes and try again." } ] } } } }, "Unauthorized": { "description": "Your credentials are invalid or do not have the necessary permissions to make this request. Verify that the given IBM Cloud access token and instance ID are correct. If the error persists, contact the account owner to check your permissions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollection" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Unauthorized: The user does not have access to the specified resource." } ] } } } } }, "examples": { "CreateRootKey": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "A Key Protect key", "extractable": false } ] } }, "CreateRootKeyWithPolicyOverrides": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Root-key", "description": "A Key Protect key" } ] } }, "CreateKMIPAdapter": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.kmip_adapter+json", "collectionTotal": 1 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "profile": "native_1.0", "profile_data": { "crk_id": "beddecaf-0000-0000-0000-1234567890ab" }, "name": "kmip-adapter-123", "description": "our 123rd kmip adapter", "created_at": "2023-01-23T04:56:07.000Z", "created_by": "IBMid-0000000000", "updated_at": "2023-01-23T04:56:07.000Z", "updated_by": "IBMid-0000000000" } ] } }, "CreateKMIPClientCertificate": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.kmip_client_certificate+json", "collectionTotal": 1 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "name": "kmip-client-certificate", "certificate": "-----BEGIN CERTIFICATE-----\\nAAA\\n-----END CERTIFICATE-----", "created_at": "2000-01-23T04:56:07.000Z", "created_by": "IBMid-0000000000" } ] } }, "DeactivateRegistration": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.resource_crn+json", "collectionTotal": 1 }, "resources": [ { "resourceCrn": "crn:v1:bluemix:public:::a/:::" } ] } }, "GetInstancePolicyAllowedIP": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "allowedIP", "policy_data": { "enabled": true, "attributes": { "allowed_ip": [ "X.X.X.X/N", "X.X.X.X/N" ] } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" } ] } }, "GetInstancePolicyAllowedNetwork": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": true, "attributes": { "allowed_network": "private-only" } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" } ] } }, "GetInstancePolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "dualAuthDelete", "policy_data": { "enabled": true }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" } ] } }, "GetInstancePolicyKeyCreateImportAccess": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": true, "attributes": { "create_root_key": true, "create_standard_key": true, "import_root_key": true, "import_standard_key": true, "enforce_token": false } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" } ] } }, "GetInstancePolicyMetrics": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "metrics", "policy_data": { "enabled": true }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" } ] } }, "GetInstancePolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "rotation", "policy_data": { "enabled": true, "attributes": { "interval_month": 3 } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" } ] } }, "GetKeyPolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms::::policy:feddecaf-0000-0000-0000-1234567890ab", "dualAuthDelete": { "enabled": true }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "2000-03-21T00:00:00Z" } ] } }, "GetKeyPolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "id": "beadcafe-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms::::policy:beadcafe-0000-0000-0000-1234567890ab", "rotation": { "enabled": true, "interval_month": 3 }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "2000-03-21T00:00:00Z" } ] } }, "GetKMIPAdapters": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.kmip_adapter+json", "collectionTotal": 1, "totalCount": 3 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "profile": "native_1.0", "profile_data": { "crk_id": "beddecaf-0000-0000-0000-1234567890ab" }, "name": "kmip-adapter-123", "description": "our 123rd kmip adapter", "created_at": "2023-01-23T04:56:07.000Z", "created_by": "IBMid-0000000000", "updated_at": "2023-01-23T04:56:07.000Z", "updated_by": "IBMid-0000000000" } ] } }, "GetKMIPClientCertificates": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.kmip_client_certificate+json", "collectionTotal": 2, "totalCount": 4 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "name": "kmip-client-certificate", "created_at": "2000-01-23T04:56:07.000Z", "created_by": "IBMid-0000000000" }, { "id": "beddecaf-0000-0000-0000-1234567890ab", "name": "kmip-client-certificate2", "created_at": "2001-01-23T04:56:07.000Z", "created_by": "IBMid-0000000001" } ] } }, "GetKMIPObject": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.kmip_object+json", "collectionTotal": 1 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "kmip_object_type": 2, "state": 3, "created_at": "2000-01-23T04:56:07.000Z", "created_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab", "created_by": "IBMid-0000000000", "updated_at": "2000-01-23T04:56:07.000Z", "updated_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab", "updated_by": "IBMid-0000000000" } ] } }, "GetKMIPObjects": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.kmip_object+json", "collectionTotal": 2, "totalCount": 4 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "kmip_object_type": 2, "state": 3, "created_at": "2000-01-23T04:56:07.000Z", "created_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab", "created_by": "IBMid-0000000001", "updated_at": "2000-02-23T08:19:00.000Z", "updated_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab", "updated_by": "IBMid-0000000001" }, { "id": "beddecaf-0000-0000-0000-1234567890ab", "kmip_object_type": 2, "state": 5, "created_at": "2000-01-23T04:56:07.000Z", "created_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab", "created_by": "IBMid-0000000001", "updated_at": "2000-03-25T04:56:07.000Z", "updated_by_kmip_client_cert_id": "beddecaf-0000-0000-0000-1234567890ab", "updated_by": "IBMid-0000000001", "destroyed_at": "2000-03-28T04:56:07.000Z", "destroyed_by": "IBMid-0000000001" } ] } }, "GetMultipleInstancePolicies": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 6 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": true, "attributes": { "allowed_network": "private-only" } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" }, { "policy_type": "dualAuthDelete", "policy_data": { "enabled": true }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" }, { "policy_type": "metrics", "policy_data": { "enabled": true }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" }, { "policy_type": "allowedIP", "policy_data": { "enabled": true, "attributes": { "allowed_ip": [ "X.X.X.X/N", "X.X.X.X/N" ] } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" }, { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": true, "attributes": { "create_root_key": true, "create_standard_key": true, "import_root_key": true, "import_standard_key": true, "enforce_token": false } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" }, { "policy_type": "rotation", "policy_data": { "enabled": true, "attributes": { "interval_month": 3 } }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdated": "2000-03-21T00:00:00Z" } ] } }, "GetMultipleKeyPolicies": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 2 }, "resources": [ { "id": "feddecaf-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms::::policy:feddecaf-0000-0000-0000-1234567890ab", "rotation": { "enabled": true, "interval_month": 3 }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "2000-03-21T00:00:00Z" }, { "id": "beadcafe-0000-0000-0000-1234567890ab", "crn": "crn:v1:bluemix:public:kms::::policy:beadcafe-0000-0000-0000-1234567890ab", "dualAuthDelete": { "enabled": true }, "createdBy": "IBMid-0000000000", "creationDate": "2000-03-21T00:00:00Z", "updatedBy": "IBMid-0000000000", "lastUpdateDate": "2000-03-21T00:00:00Z" } ] } }, "ImportRootKey": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Imported-root-key", "description": "A Key Protect key", "extractable": false, "payload": "x089YbmN9GSvpxEKe0LaqA==" } ] } }, "ImportRootKeyWithImportToken": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Encrypted-root-key", "description": "A Key Protect key", "extractable": false, "payload": "x089YbmN9GSvpxEKe0LaqA==", "encryptionAlgorithm": "RSAES_OAEP_SHA_256", "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==", "iv": "puQrzDX7gU1TcTTx" } ] } }, "ImportRootKeyWithImportTokenWithPolicyOverrides": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Encrypted-root-key", "description": "A Key Protect key", "payload": "x089YbmN9GSvpxEKe0LaqA==", "encryptionAlgorithm": "RSAES_OAEP_SHA_256", "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==", "iv": "puQrzDX7gU1TcTTx" } ] } }, "ImportRootKeyWithPolicyOverrides": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.key+json", "name": "Imported-root-key", "description": "A Key Protect key", "payload": "x089YbmN9GSvpxEKe0LaqA==" } ] } }, "KMIPAdapterBadId": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$", "status": 400, "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "id" } } ] } ] } }, "KMIPAdapterBadFullId": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "The KMIP Adapter id / name could not be validated. See `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `adapter_id` must be: a v4 UUID or string matching pattern ^[a-zA-Z0-9-_]{2,40}$", "status": 400, "moreInfo": "https://test.cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "adapter_id" } } ] } ] } }, "KMIPAdapterBadFieldValidation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: KMIP Adapter could not be created. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field '' has an invalid format. Please refer to https://cloud.ibm.com/apidocs/key-protect.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "" } } ] } ] } }, "KMIPAdapterNotFound": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Adapter(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_ADAPTER_NOT_FOUND_ERR", "message": "kmip_adapter does not exist", "status": 404 } ] } ] } }, "KMIPAdapterNotFoundCertPathRetrieve": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Client Certificate(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_ADAPTER_NOT_FOUND_ERR", "message": "kmip_adapter does not exist", "status": 404 } ] } ] } }, "KMIPAdapterNotFoundObjectPathRetrieve": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Object(s) could not be retrieved: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_ADAPTER_NOT_FOUND_ERR", "message": "kmip_adapter does not exist", "status": 404 } ] } ] } }, "KMIPAdapterNotFoundCertPathCreate": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Client Certificate could not be created: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_ADAPTER_NOT_FOUND_ERR", "message": "kmip_adapter does not exist", "status": 404 } ] } ] } }, "KMIPAdapterNotFoundCertPathDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Client Certificate could not be deleted: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_ADAPTER_NOT_FOUND_ERR", "message": "kmip_adapter does not exist", "status": 404 } ] } ] } }, "KMIPAdapterNotFoundObjectPathDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_ADAPTER_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_ADAPTER_NOT_FOUND_ERR", "message": "kmip_adapter does not exist", "status": 404 } ] } ] } }, "KMIPCertificateNotFound": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Client Certificate could not be retrieved: Please see `reasons` for more details (KMIP_CLIENT_CERTIFICATE_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_CLIENT_CERTIFICATE_NOT_FOUND_ERR", "message": "kmip_client_certificate does not exist", "status": 404 } ] } ] } }, "KMIPObjectNotFound": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Object(s) could not be retrieved: Please see `reasons` for more details (KMIP_OBJECT_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_OBJECT_NOT_FOUND_ERR", "message": "kmip_object does not exist", "status": 404 } ] } ] } }, "KMIPObjectNotFoundDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Not Found: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_OBJECT_NOT_FOUND_ERR)", "reasons": [ { "code": "KMIP_OBJECT_NOT_FOUND_ERR", "message": "kmip_object does not exist", "status": 404 } ] } ] } }, "KMIPObjectDeleted": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Gone: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_OBJECT_DELETED_ERR)", "reasons": [ { "code": "KMIP_OBJECT_DELETED_ERR", "message": "The kmip object has already been deleted: Please delete references to this kmip object", "status": 410 } ] } ] } }, "KMIPObjectNonDeletableState": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Conflict: KMIP Object could not be deleted: Please see `reasons` for more details (KMIP_OBJECT_NONDELETABLE_STATE_ERR)", "reasons": [ { "code": "KMIP_OBJECT_NONDELETABLE_STATE_ERR", "message": "The kmip object is not in pre-active, deactivated, or compromised state", "status": 409 } ] } ] } }, "KMIPAdapterBadProfile": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: KMIP Adapter could not be created. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field `profile` must be one of the following: [`native_1.0`]", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "profile" } } ] } ] } }, "KMIPAdapterBadProfileDataNotFound": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: KMIP Adapter could not be created. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field '' could not be found in the provided kms instance.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "" } } ] } ] } }, "KMIPAdapterDupNameError": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "KMIP Adapter could not be created. See 'reasons' for more details.", "reasons": [ { "code": "KMIP_ADAPTER_DUPLICATE_NAME_ERR", "message": "There is a kmip adapter in this kms instance with the same name. Please choose a different name.", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } }, "KMIPAdapterNativeCRKNotFoundError": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "KMIP Adapter could not be created. See 'reasons' for more details.", "reasons": [ { "code": "NATIVE_CRK_ID_NOT_FOUND_ERR", "message": "Root key in native profile body does not exist in the kms instance", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } }, "KMIPAdapterNativeCRKInvalidError": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "KMIP Adapter could not be created. See 'reasons' for more details.", "reasons": [ { "code": "NATIVE_INVALID_CRK_ERR", "message": "Key id in native profile body is either not a root key or is not in active state", "status": 409, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect" } ] } ] } }, "KMIPCertificateBadId": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "The name of the client certificate could not be validated. See `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `id` must be: a v4 UUID or a string matching pattern `^[a-zA-Z0-9-]*$`.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "id" } } ] } ] } }, "KMIPObjectBadId": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "The id of the kmip object could not be validated. See `reasons` for more details.", "reasons": [ { "code": "INVALID_PATH_PARAM_ERR", "message": "The path_param `id` must be: a valid UUID", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "path_param", "name": "id" } } ] } ] } }, "KMIPCertificateBadFieldValidation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Bad Request: KMIP Certificate could not be added. See 'reasons' for more details.", "reasons": [ { "code": "INVALID_FIELD_ERR", "message": "The field '' has an invalid format. Please refer to https://cloud.ibm.com/apidocs/key-protect.", "status": 400, "moreInfo": "https://cloud.ibm.com/apidocs/key-protect", "target": { "type": "field", "name": "" } } ] } ] } }, "RewrapKey": { "summary": "Rewrap key", "value": { "ciphertext": "", "aad": [ "", "" ] } }, "RotateKey": { "summary": "Rotate key", "value": { "payload": "aQFr+ry+ThyyHsV0QnyVOg==" } }, "SecureRotateKey": { "summary": "Rotate key using an import token", "value": { "payload": "aQFr+ry+ThyyHsV0QnyVOg==", "encryptionAlgorithm": "RSAES_OAEP_SHA_256", "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==", "iv": "puQrzDX7gU1TcTTx" } }, "SetKeyPolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": true } } ] } }, "SetKeyPolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "rotation": { "enabled": true, "interval_month": 1 } } ] } }, "SetInstancePolicyAllowedIP": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "allowedIP", "policy_data": { "enabled": true, "attributes": { "allowed_ip": [ "X.X.X.X/N", "X.X.X.X/N" ] } } } ] } }, "SetInstancePolicyAllowedNetwork": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": true, "attributes": { "allowed_network": "private-only" } } } ] } }, "SetInstancePolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "dualAuthDelete", "policy_data": { "enabled": true } } ] } }, "SetInstancePolicyKeyCreateImportAccess": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": true, "attributes": { "create_root_key": true, "create_standard_key": true, "import_root_key": true, "import_standard_key": true, "enforce_token": false } } } ] } }, "SetInstancePolicyMetrics": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "metrics", "policy_data": { "enabled": true } } ] } }, "SetInstancePolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "rotation", "policy_data": { "enabled": true, "attributes": { "interval_month": 3 } } } ] } }, "SetMultipleInstancePolicies": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 6 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": true, "attributes": { "allowed_network": "private-only" } } }, { "policy_type": "dualAuthDelete", "policy_data": { "enabled": true } }, { "policy_type": "metrics", "policy_data": { "enabled": true } }, { "policy_type": "allowedIP", "policy_data": { "enabled": true, "attributes": { "allowed_ip": [ "X.X.X.X/N", "X.X.X.X/N" ] } } }, { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": true, "attributes": { "create_root_key": true, "create_standard_key": true, "import_root_key": true, "import_standard_key": true, "enforce_token": false } } }, { "policy_type": "rotation", "policy_data": { "enabled": true, "attributes": { "interval_month": 3 } } } ] } }, "SetMultipleKeyPolicies": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 2 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "rotation": { "enabled": true, "interval_month": 1 } }, { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": true } } ] } }, "UnwrapKey": { "summary": "Unwrap key", "value": { "ciphertext": "", "aad": [ "", "" ] } }, "WrapKey": { "summary": "Wrap key", "value": { "plaintext": "", "aad": [ "", "" ] } } } } }