{ "openapi": "3.0.0", "info": { "title": "IBM Cloud Hyper Protect Crypto Services KMS API", "description": "## Introduction\n\nIBM Cloud Hyper Protect Crypto Services is a dedicated key management service and hardware security module (HSM). It is designed to enable you to take control of your cloud data encryption keys and cloud hardware security models, and is the only service in the industry built on FIPS 140-2 Level 4-certified hardware. Hyper Protect Crypto Services is integrated with the IBM® Key Protect for IBM Cloud® REST API, so that you can store, retrieve, and generate encryption keys.\n\nFor more information about using Hyper Protect Crypto Services, see the IBM Cloud [docs](https://cloud.ibm.com/docs/hs-crypto).\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```\nGitHub\n\nhttps://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\nhttps://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\nhttps://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\nhttps://github.com/IBM/keyprotect-java-client\n\n## Endpoint URLs\n\nUse the **Retrieve the API endpoint URL** method first to retrieve the URL for the dedicated API endpoint for key management operations. When you call the API, use the URL that corresponds to the region where your service instance is deployed.\n\n* Dallas: `https://broker.us-south.hs-crypto.cloud.ibm.com/crypto_v2/`\n* Frankfurt: `https://broker.eu-de.hs-crypto.cloud.ibm.com/crypto_v2/`\n* London: `https://broker.eu-gb.hs-crypto.cloud.ibm.com/crypto_v2/`\n* Madrid: `https://broker.eu-es.hs-crypto.cloud.ibm.com/crypto_v2/`\n* São-Paulo: `https://broker.br-sao.hs-crypto.cloud.ibm.com/crypto_v2/`\n* Tokyo: `https://broker.jp-tok.hs-crypto.cloud.ibm.com/crypto_v2/`\n* Toronto: `https://broker.ca-tor.hs-crypto.cloud.ibm.com/crypto_v2/`\n* Washington DC:`https://broker.us-east.hs-crypto.cloud.ibm.com/crypto_v2/`\n\nTo call other API methods, use the endpoint URL that is returned in the **kms** section when you call the **Retrieve the API endpoint URL** method. The returned URL contains the region and port information. Note the URLs vary depending on whether you are using the public or private endpoint.\n\nIf you create your instances after April 12 2024 in certain regions, you might need to use the new API endpoints with the new format as `.api..hs-crypto.appdomain.cloud`. The availability date varies by region. For more information about the supported regions, the availability dates, and the new endpoint URLs, see [New endpoints](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions#new-service-endpoints).\n\n* `\"public\": \"api..hs-crypto.cloud.ibm.com:\"`\n* `\"private\": \"api.private..hs-crypto.cloud.ibm.com:\"`\n\nYou can also use the [Global Search and Tagging (GhoST) API](https://cloud.ibm.com/apidocs/search) to retrieve your instance endpoint URL. Take the following request as an example:\n\n```\ncurl -X POST\n 'https://api.global-search-tagging.cloud.ibm.com/v3/resources/search?limit=50&account_id='\n -H 'Authorization: Bearer '\n -H 'Content-Type: application/json'\n -d '{\n \"query\": \"(type:resource-instance AND doc.sub_type:kms)\"\n }'\n```\n\nUse the same token that you use to create you Hyper Protect Crypto Services instance and replace the `account_ID` with your IBM Cloud account ID. The following JSON output shows an example service instance. From the response, you can see the endpoint information.\n\n```json\n{\n ...,\n \"doc\": {\n ...,\n \"id\": \"crn:v1:public:hs-crypto:us-south:a/80e35ac1582a2b1a7b633e6107f9295a:67be47c6-cac0-415d-b298-0e6d45d6cb51::\",\n \"sub_type\": \"kms\",\n \"extensions\": {\n ...,\n \"endpoints\": {\n \"public\": \"\",\n \"private\": \"\"\n }\n },\n ...\n },\n ...\n}\n```\n\n## Authentication\n\nTo call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles,\nsee [Managing access for Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-manage-access).\n\nTo work with the API, authenticate your app or service by including your [IBM Cloud IAM access token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token) and [instance ID](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-instance-ID) in API requests.\n\nYou can build your API request by pairing a [service endpoint](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions#service-endpoints) with your authentication credentials:\n\n```bash\ncurl -X GET \\\n \"https://api..hs-crypto.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 the prefix that represents the geographic area where your service instance resides. For more information, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).\n\nReplace `` with the port number of the API endpoint.\n\nReplace `` with your Cloud IAM token, and `` with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.\n\nYou can retrieve an access token by first creating an API key, and then exchanging your API key for a IBM Cloud IAM token. For more information, see [Retrieving an access token programmatically](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token#retrieve-token-api).\n\nTo find out more about setting up the Hyper Protect Crypto Services key management service API, see [Accessing the API](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-set-up-kms-api).\n\nTo retrieve your access token:\n\n```bash\ncurl -X POST \\\n\"https://iam.cloud.ibm.com/identity/token\" \\\n -H \"Content-Type: application/x-www-form-urlencoded\" \\\n -H \"Accept: application/json\" \\\n -d \"grant_type=urn%3Aibm%3Aparams%3Aoauth%3Agrant-type%3Aapikey&apikey=\" > token.json\n```\n\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token#retrieve-token-api). Then use the full\n`access_token` value, prefixed by the _Bearer_token type, to authenticate 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 Hyper Protect Crypto Services instance. The `GUID` value in the JSON output represents the instance ID for the service.\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services API.\nThe SDK provides client configuration initialization method in which you will need to replace `Key management endpoint URL` with a service endpoint, the `API_KEY` with the API key associated with your application, the `TokenURL` with your Cloud IAM token, and `InstanceID` with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services\ninstance. The value `kp.DefaultTokenURL` for `TokenURL` defaults to IAM production URL. Use the client configuration options in the method to create a new Hyper Protect Crypto Services client. The method handles the authentication procedure with\nthe provided API_KEY.\n\nTo authenticate to Hyper Protect Crypto Services key management service API:\n\n```go\nimport (\n\t\"context\"\n\t\"encoding/json\"\n\t\"fmt\"\n\n\t\"github.com/IBM/keyprotect-go-client\"\n)\n\nfunc getConfigAPIKey() kp.ClientConfig {\n\treturn kp.ClientConfig{\n\t\tBaseURL: ,\n\t\tAPIKey: ,\n\t\tTokenURL: kp.DefaultTokenURL,\n\t\tInstanceID: ,\n\t\tVerbose: kp.VerboseFailOnly,\n\t}\n}\n\nfunc main() {\n\toptions := getConfigAPIKey()\n\tapi, err := kp.New(options, kp.DefaultTransport())\n\tif err != nil {\n\t\tfmt.Println(\"Error creating kp client\")\n\t\treturn\n\t}\n}\n```\n\nReplace the `` with the API endpoint.\nAPI endpoint\n\n```bash\nhttps://api..hs-crypto.cloud.ibm.com:\n```\n\nReplace `` with the prefix that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more informaton, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).\n\nReplace `` with the port number of the API endpoint.\n\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token#retrieve-token-api).\n\nReplace the `` with the Hyper Protect Crypto Services instance ID.\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 Hyper Protect Crypto Services instance. The `GUID` value in the JSON output represents the instance ID for the service.\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services 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/hs-crypto?topic=hs-crypto-retrieve-access-token#retrieve-token-api), the `IAM_AUTH_URL` term with the appropriate URL like 'https://iam.cloud.ibm.com/identity/token', the `KP_SERVICE_URL` term with the endpoint including the region and port, such as `https://api.us-south.hs-crypto.cloud.ibm.com:9371`, and the `KP_INSTANCE_ID` term with the instance ID that identifies your Hyper Protect Crypto Services service instance.\n\nTo retrieve your instance ID:\n\n```bash\nibmcloud resource service-instance --output JSON\n```\n\nTo authenticate to Hyper Protect Crypto Services 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/hs-crypto?topic=hs-crypto-regions).\n\nIBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services API. The SDK provides a client configuration setup, in which, you need to replace the `IBMCLOUD_API_KEY` with the API key associated with your application, and `KP_INSTANCE_ID` with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services service\ninstance.\n\nTo authenticate to Hyper Protect Crypto Services key management service 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(\"HPCS_INSTANCE_ID\")\n endpoint_url=\"\"\n)\n```\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token#retrieve-token-api).\n\nReplace `` with the prefix that represents the geographic area where your Hyper Protect Crypto Services instance resides. For more information, see [Regions and locations](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-regions).\n\nReplace `HPCS_INSTANCE_ID` with the UUID that identifies your Hyper Protect Crypto Services instance.\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 Hyper Protect Crypto Services instance. The `GUID` value in the JSON output represents the instance ID for the service.\n\nReplace `` with your [service instance endpoint URL](#endpoint-urls). \n\nIBM Cloud Identity and Access Management (IAM) is the primary method to authenticate to the Hyper Protect Crypto Services key management service API.\nThe software development kit provides a client configuration setup, in which, you need to replace the `IAM_API_KEY` with the API key\nassociated with your application, `IAM_AUTH_URL` with your Cloud IAM token, `KEY_MANAGEMENT_ENDPOINT_URL` with a service endpoint, and `INSTANCE_ID` with the IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.\n\nTo authenticate to Hyper Protect Crypto Services 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```\nReplace `` with the UUID that identifies your Hyper Protect Crypto Services instance.\n\nReplace `` with your [service credentials](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token#retrieve-token-api).\n\nReplace `` with your [IAM token](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-retrieve-access-token).\n\nReplace `` with the service endpoint that you want to make requests to.\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 Hyper Protect Crypto Services instance. The `GUID` value in the JSON output represents the instance ID for the service.\n\n## Auditing\n\nYou can monitor API activity within your account by using the Activity Tracker service. Whenever an API method is called, an event is generated that you can then track and audit from within Activity Tracker. The specific event type is listed for each individual method.\n\nFor more information about how to track Hyper Protect Crypto Services activity, see [Auditing Events for Hyper Protect Crypto Services](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-at-events).\n\n## Error handling\n\nHyper Protect Crypto Services uses standard HTTP response codes to indicate whether a method completed successfully. A `200` response always indicates success. A `400` type response is some sort of failure, 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 Hyper Protect Crypto Services's end. |\n\n## Metadata\n\nWhen you create or store keys in Hyper Protect Crypto Services, you can attach key-value data to your resources for easy identification of your keys.\n\nThe `name`, `description`, and `tag` parameters are useful for storing information on your resources. For example, you can store corresponding unique identifiers from your app or system on a Hyper Protect Crypto Services key.\n\nTo protect your privacy, do not store any personally identifiable information, such 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/hs-crypto?topic=hs-crypto-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\nFor a complete list of changes and improvements to this API, see the [Hyper Protect Crypto Services key management service API change log](https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-kms-api-change-log).", "version": "23.11", "contact": { "name": "IBM Cloud Hyper Protect Crypto Services", "url": "https://cloud.ibm.com/docs/hs-crypto" }, "license": { "name": "IBM-License", "url": "http://ibm.com/LICENSE-IBM" }, "x-ibm-name": "hs-crypto", "x-sdk-supported-languages": [ "curl", "python", "node", "java", "go" ], "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 Hyper Protect Crypto Services KMS API." } ], "x-github": "https://github.ibm.com/cloud-api-docs/hyper-protect-crypto-services", "x-github-issues": "https://github.ibm.com/cloud-api-docs/hyper-protect-crypto-services/issues/new", "x-last-updated": "2024-06-05" }, "servers": [ { "url": "https://api.{region}.hs-crypto.cloud.ibm.com/", "description": "The key management service server for IBM Cloud Hyper Protect Crypto Services.", "variables": { "region": { "description": "The region prefix that represents the geographic area where your Hyper Protect Crypto Services instance resides.", "default": "us-south", "enum": [ "au-syd", "ca-tor", "br-sao", "eu-de", "eu-es", "eu-gb", "jp-tok", "us-east", "us-south" ] } } } ], "paths": { "/instances/{id}": { "get": { "operationId": "getInstance", "summary": "Retrieve the API endpoint URL", "tags": [ "API endpoint" ], "description": "Retrieves the URL for the dedicated API endpoint for key management operations\non a Hyper Protect Crypto Services instance. The endpoint URL varies depending on which\nregional service endpoint you are using.\n- Dallas: `https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n- Frankfurt: `https://eu-de.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n- London: `https://eu-gb.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n- Madrid: `https://eu-es.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n- São-Paulo: `https://br-sao.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n- Tokyo: `https://jp-tok.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n- Toronto: `https://ca-tor.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n- Washington DC: `https://us-east.broker.hs-crypto.cloud.ibm.com/crypto_v2/`\n\nDepending on whether you are using the public or private endpoint, choose the proper\nendpoint URL in the **kms** section that is returned in the following formats.\nRefer to the right-side example pane for an example:\n- `\"public\": \"api..hs-crypto.cloud.ibm.com:\"`\n- `\"private\": \"api.private..hs-crypto.cloud.ibm.com:\"`", "parameters": [ { "name": "id", "in": "path", "description": "The IBM Cloud UUID that uniquely identifies the instance. For how to retrieve your instance ID, see [Retrieving your instance ID](/docs/services/hs-crypto?topic=hs-crypto-retrieve-instance-ID) for instructions.", "required": true, "schema": { "type": "string" } } ], "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/{id} \\\n -H 'Authorization: Bearer {access_token}'" ] } ] } ], "go": [ { "name": "Example request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\nimport (\n \"fmt\"\n \"io/ioutil\"\n \"net/http\"\n)\n\nfunc main() {\n instanceID := \"\"\n region := \"\"\n bearerToken := \"Bearer \"\n method := \"GET\"\n\n url := fmt.Sprintf(\"https://%s.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/%s\", region, instanceID)\n\n client := &http.Client{}\n req, err := http.NewRequest(method, url, nil)\n\n if err != nil {\n fmt.Println(err)\n return\n }\n req.Header.Add(\"Authorization\", bearerToken)\n\n res, err := client.Do(req)\n if err != nil {\n fmt.Println(err)\n return\n }\n defer res.Body.Close()\n\n body, err := ioutil.ReadAll(res.Body)\n if err != nil {\n fmt.Println(err)\n return\n }\n fmt.Println(string(body))\n}" ] } ] } ], "node": [ { "name": "Example request", "example": [ { "type": "code", "lang": "node", "source": [ "let fetch = require('node-fetch');\n\nfetch('https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/{id}', {\n method: ‘GET’,\n headers: {'Content-Type': 'application/json'},\n body: '{}'\n}).then(response => {\n return response.json();\n}).catch(err => {console.log(err);});" ] } ] } ], "python": [ { "name": "Example request", "example": [ { "type": "code", "lang": "python", "source": [ "import requests\n\nurl = \"https://us-south.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/{id}\"\n\nheaders = {\n'Authorization': 'Bearer {access_token}',\n}\n\nresponse = requests.request('GET', url, headers=headers)\n\nprint(response.text)" ] } ] } ], "java": [ { "name": "Example request", "example": [ { "type": "code", "lang": "java", "source": [ "package hpcs;\n\nimport java.io.IOException;\n\nimport com.squareup.okhttp.*;\n\npublic class sampleGetInstanceEndpoints {\n public static void main(String[] args) {\n String instanceID = \"\";\n String region = \"\";\n String bearerToken = \"Bearer \";\n String url = String.format(\"https://%s.broker.hs-crypto.cloud.ibm.com/crypto_v2/instances/%s\", region, instanceID);\n\n OkHttpClient client = new OkHttpClient();\n\n Request request = new Request.Builder()\n .url(url)\n .method(\"GET\", null)\n .addHeader(\"Authorization\", bearerToken)\n .build();\n\n try {\n Response response = client.newCall(request).execute();\n System.out.println(response.body().string());\n } catch (IOException e) {\n e.printStackTrace();\n }\n\n }\n\n}" ] } ] } ] } }, "responses": { "200": { "description": "The instance connection info was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InstanceConnectionRead" }, "example": { "instance_id": "4ec51d44-d94d-4200-bc2c-fcfb04b1287c", "kms": { "public": "api.us-south.hs-crypto.cloud.ibm.com:9371", "private": "api.private.us-south.hs-crypto.cloud.ibm.com:9372" }, "ep11": { "public": "ep11.us-south.hs-crypto.cloud.ibm.com:9371", "private": "ep11.private.us-south.hs-crypto.cloud.ibm.com:9372" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "The instance could not be found. Verify that the instance ID specified is valid." }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/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.\nHyper Protect Crypto Services designates the resource as either a root key or a standard key based on the `extractable` value that you specify. A successful `POST /keys` operation adds the key to the service and returns the details of the request in the response entity-body, if the Prefer header is 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": "hs-crypto.secrets.create" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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\": \"...\",\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 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 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# Initialize the 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}" ] } ] } ] } }, "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": "...", "name": "Root-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": false, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "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 (resources[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. Hyper Protect Crypto Services only permits the creation or\nimport of keys in your Hyper Protect Crypto Services 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 service\ninstance.\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", "maxLength": 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 - `7f194e42-4261-452d-82ee-21cd3d9ccaae` (a valid key id) - find keys where the id the key is `7f194e42-4261-452d-82ee-21cd3d9ccaae`, or the name or any of its aliases contain `7f194e42-4261-452d-82ee-21cd3d9ccaae`, 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", "maxLength": 256, "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": "hs-crypto.secrets.list" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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 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 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 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 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 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}" ] } ] } ] } }, "responses": { "200": { "description": "The list of keys was successfully retrieved.", "headers": { "Key-Total": { "description": "The number of keys in your service instance.", "schema": { "type": "integer" } } }, "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": "...", "name": "Root-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": true, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false }, { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Standard-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": true, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false }, { "type": "application/vnd.ibm.kms.key+json", "id": "...", "name": "Deleted-Standard-key", "aliases": [ "..." ], "description": "...", "state": 5, "extractable": true, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": true, "deletionDate": "YYYY-MM-DDTHH:MM:SSZ", "restoreAllowed": true, "restoreExpirationDate": "YYYY-MM-DDTHH:MM:SSZ", "purgeAllowed": false, "purgeAllowedFrom": "YYYY-MM-DDTHH:MM:SSZ", "purgeScheduledOn": "YYYY-MM-DDTHH:MM:SSZ" } ] } } } }, "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": "hs-crypto.secrets.head" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.head" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -I HEAD \\\n https://api..hs-crypto.cloud.ibm.com:/api/v2/keys \\\n -H 'accept: application/vnd.ibm.kms.key+json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: ' \\" ] } ] } ] } }, "responses": { "200": { "description": "The metadata was successfully retrieved.", "headers": { "Key-Total": { "description": "The number of keys in your service instance.", "schema": { "type": "integer" } } } }, "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.\nHyper Protect Crypto Services 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": "hs-crypto.secrets-with-policy-overrides.create" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets-with-policy-overrides.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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 }'" ] } ] } ] } }, "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 management service key", "state": 1, "keyRingID": "default", "crn": "crn:v1:bluemix:public:kms::::key:fadedbee-0000-0000-0000-1234567890ab", "imported": false, "creationDate": "YYYY-MM-DDTHH:mm:SSZ", "createdBy": "IBMid-0000000000", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:mm:SSZ", "keyVersion": { "id": "fadedbee-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" }, "rotation": { "interval_month": 3 }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:mm:SSZ" }, "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 (resources[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. Hyper Protect Crypto Services only permits the creation or\nimport of keys in your Hyper Protect Crypto Services 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": "hs-crypto.secrets.read" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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 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 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 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}" ] } ] } ] } }, "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": "...", "name": "Standard-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": true, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": false, "payload": "..." } ] } } } }, "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- `wrap`: Use a root key to [wrap or encrypt a data encryption key](/docs/hs-crypto?topic=hs-crypto-wrap-keys)\n- `unwrap`: Use a root key to [unwrap or decrypt a data encryption key](/docs/hs-crypto?topic=hs-crypto-unwrap-keys)\n- `rewrap`: Use a root key to [rewrap or reencrypt a data encryption key](/docs/hs-crypto?topic=hs-crypto-rewrap-keys)\n- `rotate`: [Create a new version](/docs/hs-crypto?topic=hs-crypto-rotate-keys) of a root key\n- `disable`: [Disable operations](/docs/hs-crypto?topic=hs-crypto-disable-keys) for a key\n- `enable`: [Enable operations](/docs/hs-crypto?topic=hs-crypto-disable-keys#enable-api) for a key\n- `setKeyForDeletion`: [Authorize deletion](/docs/hs-crypto?topic=hs-crypto-delete-dual-auth-keys#set-key-deletion-api) for a key with a dual authorization policy\n- `unsetKeyForDeletion`: [Remove an authorization](/docs/hs-crypto?topic=hs-crypto-delete-dual-auth-keys#unset-key-deletion-api) for a key with a dual authorization policy\n- `restore`: [Restore a previously deleted key](/docs/hs-crypto?topic=hs-crypto-restore-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" ] }, "required": true }, { "$ref": "#/components/parameters/Prefer" } ], "requestBody": { "$ref": "#/components/requestBodies/KeyActionBody" }, "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.wrap" }, { "name": "hs-crypto.secrets.unwrap" }, { "name": "hs-crypto.secrets.rotate" }, { "name": "hs-crypto.secrets.rewrap" }, { "name": "hs-crypto.secrets.setkeyfordeletion" }, { "name": "hs-crypto.secrets.unsetkeyfordeletion" }, { "name": "hs-crypto.secrets.disable" }, { "name": "hs-crypto.secrets.enable" }, { "name": "hs-crypto.secrets.restore" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.wrap" }, { "name": "hs-crypto.secrets.unwrap" }, { "name": "hs-crypto.secrets.rotate" }, { "name": "hs-crypto.secrets.rewrap" }, { "name": "hs-crypto.secrets.setkeyfordeletion" }, { "name": "hs-crypto.secrets.unsetkeyfordeletion" }, { "name": "hs-crypto.secrets.disable" }, { "name": "hs-crypto.secrets.enable" }, { "name": "hs-crypto.secrets.restore" } ] }, "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": "..." } } } } } } }, "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": "...", "name": "Root-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": false, "keyRingID": "default", "crn": "...", "imported": true, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "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://api..hs-crypto.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 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": "hs-crypto.secrets.patch" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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" } } } }, "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": "...", "name": "Root-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": false, "keyRingID": "new-key-ring-id", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "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.", "$ref": "#/components/responses/NotFound" }, "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, Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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": "hs-crypto.secrets.delete" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://api..hs-crypto.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 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 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 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}" ] } ] } ] } }, "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": "...", "name": "Root-key", "aliases": [ "..." ], "description": "...", "state": 5, "extractable": false, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": true, "deletionDate": "YYYY-MM-DDTHH:MM:SSZ", "deletedBy": "...", "restoreAllowed": true, "restoreExpirationDate": "YYYY-MM-DDTHH:MM:SSZ", "purgeAllowed": false, "purgeAllowedFrom": "YYYY-MM-DDTHH:MM:SSZ", "purgeScheduledOn": "YYYY-MM-DDTHH:MM:SSZ" } ] } } } }, "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/hs-crypto?topic=hs-crypto-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/hs-crypto?topic=hs-crypto-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/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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": "hs-crypto.secrets.readmetadata" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets-metadata.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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 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}" ] } ] } ] } }, "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": "...", "name": "Standard-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": true, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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": "hs-crypto.secrets.purge" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.purge" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://api..hs-crypto.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 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}" ] } ] } ] } }, "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": "...", "name": "Root-key", "aliases": [ "..." ], "description": "...", "state": 5, "extractable": false, "keyRingID": "default", "crn": "...", "imported": false, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "lastRotateDate": "YYYY-MM-DDTHH:MM:SSZ", "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "deleted": true, "deletionDate": "YYYY-MM-DDTHH:MM:SSZ", "deletedBy": "...", "purgeAllowed": true, "purgeAllowedFrom": "YYYY-MM-DDTHH:MM:SSZ", "purgeScheduledOn": "YYYY-MM-DDTHH:MM:SSZ" } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-restore-keys) that has been deleted.", "operationId": "restoreKey", "tags": [ "Keys" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" } ], "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.restore" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.restore" } ] }, "x-codegen-request-body-name": "KeyRestoreBody", "requestBody": { "description": "The base request parameters for restore key action. ", "required": false, "content": { "application/vnd.ibm.kms.key_action_restore+json": { "schema": { "$ref": "#/components/schemas/RestoreKeyOneOf" }, "examples": { "RestoreKey": { "$ref": "#/components/examples/RestoreKey" }, "SecureRestoreKey": { "$ref": "#/components/examples/RestoreKeySecure" } } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example restore key request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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' \\\n -d '{\n \"metadata\": {\n \"collectionType\": \"application/vnd.ibm.kms.key_action_restore+json\",\n \"collectionTotal\": 1\n },\n \"resources\": [\n {\n \"payload\": \"\"\n }\n ]\n }'" ] } ] }, { "name": "Example secure import restore key request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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' \\\n -d '{\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\": \"RSAES_OAEP_SHA_1\"\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 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}" ] } ] } ] } }, "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": "...", "name": "Root-key", "aliases": [ "..." ], "description": "...", "state": 1, "extractable": false, "keyRingID": "default", "crn": "...", "imported": true, "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "...", "algorithmType": "Deprecated", "algorithmMetadata": { "bitLength": 256, "mode": "Deprecated" }, "algorithmBitSize": 256, "algorithmMode": "Deprecated", "lastUpdateDate": "YYYY-MM-DDTHH:MM:SSZ", "keyVersion": { "id": "...", "creationDate": "YYYY-MM-DDTHH:MM:SSZ" }, "dualAuthDelete": { "enabled": true, "keySetForDeletion": true, "authExpiration": "YYYY-MM-DDTHH:MM:SSZ" }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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": "hs-crypto.secrets.listkeyversions" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets-key-versions.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.cloud.ibm.com:/api/v2/keys/key_ID_or_alias>/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 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}" ] } ] } ] } }, "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": "YYYY-MM-DDTHH:mm:SSZ" }, { "id": "addedace-0000-0000-0000-1234567890ab", "creationDate": "YYYY-MM-DDTHH:mm:SSZ" } ] } } } }, "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/hs-crypto?topic=hs-crypto-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.", "operationId": "wrapKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.wrap" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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": "" } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example wrap request (generated DEK)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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://api..hs-crypto.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 }'" ] } ] } ], "go": [ { "name": "Example wrap request", "example": [ { "type": "code", "lang": "go", "source": [ "package main\nimport (\n \"context\"\n \"fmt\"\n\n kp \"github.com/IBM/keyprotect-go-client\"\n)\nfunc main() {\n // Initialize the client as specified in Authentication\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 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 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\")" ] } ] } ] } }, "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": "...", "creationDate": "2010-01-12T05:23:19+0000" } } } } }, "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/hs-crypto", "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/hs-crypto" } ] } ] } } } }, "409": { "description": "The key is not in the `Active` (1) [state](/docs/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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": "hs-crypto.secrets.unwrap" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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": "" } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example unwrap request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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 }'" ] } ] } ], "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 client as specified in Authentication\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 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" ] } ] } ] } }, "responses": { "200": { "description": "Successfully unwrapped key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnwrapKeyResponseBody" }, "example": { "plaintext": "tF9ss0W9HQUVkddcjSeGg/MqZFs2CVh/FFKLPLLnOwY=", "keyVersion": { "id": "...", "creationDate": "2010-01-12T05:23:19+0000" } } } } }, "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/hs-crypto", "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/hs-crypto" } ] } ] } } } }, "409": { "description": "The key is not in the `Active` (1) or `Deactivated` (3) [state](/docs/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-rewrap-keys).", "operationId": "rewrapKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.rewrap" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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": "" } } } }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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 }'" ] } ] } ] } }, "responses": { "200": { "description": "The key was successfully rewrapped.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewrapKeyResponseBody" }, "example": { "ciphertext": "eyJjaXBoZXJ0ZXh0Ijoic1ZZRnZVcjdQanZXQ0tFakMwRFFWZktqQ3AyRmtiOFJOSDJSTkpZRzVmU1hWNDJScD\\ RDVythU0h3Y009IiwiaGFzaCI6IjVWNzNBbm9XdUxxM1BvZEZpd1AxQTdQMUZrTkZOajVPMmtmMkNxdVBxL0NRdFlOZnBvemp\\ iYUxjRDNCSWhxOGpKZ2JNR0xhMHB4dDA4cTYyc0RJMGRBPT0iLCJpdiI6Ilc1T2tNWFZuWDFCTERDUk51M05EUlE9PSIsInZl\\ cnNpb24iOiIzLjAuMCIsImhhbmRsZSI6IjRkZjg5ZGVlLWU3OTMtNGY5Ny05MGNjLTc1ZWQ5YjZlNWM4MiJ9\"", "keyVersion": { "id": "...", "creationDate": "2010-01-12T05:23:19+0000" }, "rewrappedKeyVersion": { "id": "...", "creationDate": "2010-01-12T05:23:19+0000" } } } } }, "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/hs-crypto", "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/hs-crypto" } ] } ] } } } }, "409": { "description": "The key is not in the `Active` (1) or `Deactivated` (3) [state](/docs/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-rotate-keys) of a root key.", "operationId": "rotateKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Prefer" } ], "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.rotate" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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_1\"\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 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}" ] } ] } ] } }, "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/hs-crypto", "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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": "hs-crypto.secrets.setkeyfordeletion" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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 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}" ] } ] } ] } }, "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.\n\nDUAL_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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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": "hs-crypto.secrets.unsetkeyfordeletion" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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 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}" ] } ] } ] } }, "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:\nKEY_NOT_FOUND_ERR: The key could not be found.\nDUAL_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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-disable-keys#enable-api) for a key.", "operationId": "enableKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.enable" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.enable" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example enable key request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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 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}" ] } ] } ] } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-disable-keys) for a key.", "operationId": "disableKey", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.disable" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets.disable" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example disable key request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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 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}" ] } ] } ] } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "409": { "description": "The requested key is not in the `Active` (1) [state](/docs/hs-crypto?topic=hs-crypto-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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-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. Hyper Protect Crypto Services 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 Hyper Protect Crypto Services KMS API.", "operationId": "syncAssociatedResources", "tags": [ "Key actions" ], "security": [ { "BearerAuth": [] } ], "parameters": [], "x-ibm-permissions": { "actions": [ { "name": "hs-crypto.secrets.sync" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.cloud.ibm.com:/api/v2/keys//actions/sync \\\n -H 'accept: application/json' \\\n -H 'authorization: Bearer ' \\\n -H 'bluemix-instance: '" ] } ] } ] } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-set-rotation-policy)\nor a\n[dual authorization policy](/docs/hs-crypto?topic=hs-crypto-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": "hs-crypto.policies.write" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.policies.write" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://api..hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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 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 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 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}" ] } ] } ] } }, "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto?topic=hs-crypto-set-rotation-policy)\nor a\n[dual authorization policy](/docs/hs-crypto?topic=hs-crypto-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": "hs-crypto.policies.read" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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 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 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 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}" ] } ] } ] } }, "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, Hyper Protect Crypto Services 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": "hs-crypto.instancepolicies.write" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.instance-policies.write" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://api..hs-crypto.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\": 5\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\": \"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://api..hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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 (key create and import access policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X PUT \\\n https://api..hs-crypto.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://api..hs-crypto.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 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 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 (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 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 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 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 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 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}" ] } ] } ] } }, "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 Hyper Protect Crypto Services.\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": "hs-crypto.instancepolicies.read" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.instance-policies.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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 (allowed network policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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 (key create and import access policy)", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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://api..hs-crypto.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://api..hs-crypto.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 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 (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 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 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 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 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}" ] } ] } ] } }, "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" }, "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/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/hs-crypto?topic=hs-crypto-importing-keys#using-import-tokens).\n\nWhen you call `POST /import_token`, Hyper Protect Crypto Services 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": "hs-crypto.importtoken.create" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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 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}" ] } ] } ] } }, "responses": { "200": { "description": "The import token was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportToken" }, "example": { "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "expirationDate": "YYYY-MM-DDTHH:MM:SSZ", "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`, Hyper Protect Crypto Services 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": "hs-crypto.importtoken.read" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.import-token.read" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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 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}" ] } ] } ] } }, "responses": { "200": { "description": "The import token was successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetImportToken" }, "example": { "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "expirationDate": "YYYY-MM-DDTHH:MM:SSZ", "maxAllowedRetrievals": 10, "remainingRetrievals": 9, "payload": "...", "nonce": "..." } } } }, "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, Hyper Protect Crypto Services 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": "hs-crypto.registrations.list" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.registrations.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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 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": "7f19bee1-4fdf-4646-866e-111c80f94478", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-203BRNKPR5", "creationDate": "2019-12-03T05:23:19+0000", "updatedBy": "IBMid-203BRNKPR5", "lastUpdated": "2019-12-03T05:23:19+0000", "description": "Registration between a bucket and root key", "preventKeyDeletion": false, "keyVersion": { "id": "4a0225e9-17a0-46c1-ace7-f25bcf4237d4", "creationDate": "2019-12-03T05:23:19+0000" } }, { "keyId": "7f19bee1-4fdf-4646-866e-111c80f94478", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-203BRNKPR5", "creationDate": "2019-12-02T06:15:00+0000", "updatedBy": "IBMid-203BRNKPR5", "lastUpdated": "2019-12-02T06:15:00+0000", "description": "Registration between the root key and a different bucket", "preventKeyDeletion": false, "keyVersion": { "id": "4a0225e9-17a0-46c1-ace7-f25bcf4237d4", "creationDate": "2019-12-02T06:15:00+0000" } } ] } } } }, "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/hs-crypto", "target": { "type": "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/hs-crypto" } ] } ] } } } }, "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, Hyper Protect Crypto Services 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": "hs-crypto.registrations.list" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.registrations.list" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X GET \\\n https://api..hs-crypto.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 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": "7f19bee1-4fdf-4646-866e-111c80f94478", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-203BRNKPR5", "creationDate": "2019-12-03T05:23:19+0000", "updatedBy": "IBMid-203BRNKPR5", "lastUpdated": "2019-12-03T05:23:19+0000", "description": "Registration between a bucket and root key", "preventKeyDeletion": false, "keyVersion": { "id": "4a0225e9-17a0-46c1-ace7-f25bcf4237d4", "creationDate": "2019-12-03T05:23:19+0000" } }, { "keyId": "fcc3567c-793e-455f-b576-e2989e2bb170", "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:", "createdBy": "IBMid-203BRNKPR5", "creationDate": "2019-12-02T06:15:00+0000", "updatedBy": "IBMid-203BRNKPR5", "lastUpdated": "2019-12-02T06:15:00+0000", "description": "Registration between a bucket and root key", "preventKeyDeletion": false, "keyVersion": { "id": "f58a7cfb-2b8d-4bba-b388-cfb90c3fbf31", "creationDate": "2019-12-02T06:15:00+0000" } } ] } } } }, "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/hs-crypto", "target": { "type": "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": "hs-crypto.secrets.createalias" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets-alias.create" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X POST \\\n https://api..hs-crypto.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 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" } } } }, "201": { "description": "A new alias was successfully created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyAlias" } } } }, "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/hs-crypto", "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/hs-crypto" } ] } ] } } } }, "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/hs-crypto" } ] } ] } } } }, "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": "hs-crypto.secrets.deletealias" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.secrets-alias.delete" } ] }, "x-sdk-operations": { "request-examples": { "curl": [ { "name": "Example request", "example": [ { "type": "code", "lang": "curl", "source": [ "curl -X DELETE \\\n https://api..hs-crypto.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 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/hs-crypto", "target": { "type": "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/hs-crypto" } ] } ] } } } }, "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": "hs-crypto.keyrings.list" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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 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}" ] } ] } ] } }, "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": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "..." }, { "id": "key-ring-name-2", "creationDate": "YYYY-MM-DDTHH:MM:SSZ", "createdBy": "..." } ] } } } }, "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": "hs-crypto.keyrings.create" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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 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}" ] } ] } ] } }, "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://cloud.ibm.com/apidocs/hs-crypto", "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": { "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://cloud.ibm.com/apidocs/hs-crypto" } ] } ] } } } }, "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": "hs-crypto.keyrings.delete" } ] }, "x-ibm-events": { "events": [ { "name": "hs-crypto.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://api..hs-crypto.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 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}" ] } ] } ] } }, "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://cloud.ibm.com/apidocs/hs-crypto", "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": { "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://cloud.ibm.com/apidocs/hs-crypto" } ] } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "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 Hyper Protect Crypto Services. 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. \nAn 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 an Hyper Protect Crypto Services reserved name: `allowed_ip`, `key`, `keys`, `metadata`, `policy`, `policies`, `registration`, `registrations`, `ring`, `rings`, `rotate`, `wrap`, `unwrap`, `rewrap`, `version`, `versions`. ", "schema": { "type": "string" }, "required": true }, "KeyId": { "name": "id", "in": "path", "description": "The v4 UUID that uniquely identifies the key.", "schema": { "type": "string" }, "required": true }, "KeyIdOrAlias": { "name": "id", "in": "path", "description": "The v4 UUID or alias that uniquely identifies the key.", "schema": { "type": "string" }, "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 KMS service.", "schema": { "$ref": "#/components/schemas/KeyRingID" }, "required": true }, "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" }, "required": true, "example": "crn%3av1%3abluemix%3apublic%3acloud-object-storage%3aglobal%3aa%2f59bcbfa6ea2f006b4ed7094c1a08dcdd%3a1a0ec336-f391-4091-a6fb-5e084a4c56f4%3a%3abucket" }, "ExtractableParam": { "name": "extractable", "in": "query", "schema": { "type": "boolean", "nullable": true }, "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", "maxLength": 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: “2022-01-01T12:00:00Z”\n- `deletionDate`\n * Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”\n- `expirationDate`\n * Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”\n- `extractable`\n * Boolean true or false without quotes, case-insensitive\n- `lastRotateDate`\n * Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”\n- `lastUpdateDate`\n * Date in RFC 3339 format in double-quotes: “2022-01-01T12:00:00Z”\n- `state`\n * A list of comma-separated integers with no space in between: 0,1,2,3,5\n- `hasMigrationIntent`\n * Boolean true or false without quotes, case-insensitive\n\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`, Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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", "keyCreateImportAccess", "metrics", "rotation" ], "type": "string" } }, "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" } }, "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", "nullable": true }, "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", "nullable": true }, "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`." }, "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", "nullable": true }, "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" ] }, "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 ] }, "default": [ 0, 1, 2, 3 ] }, "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", "nullable": true }, "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" }, "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/hs-crypto?topic=hs-crypto-view-protected-resources#crn-query-examples).", "example": "crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F274074dce64e9c423ffc238516c755e1%3A29caf0e7-120f-4da8-9551-3abf57ebcfc7%3A*%3A*" }, "UrlEncodedResourceCRNQueryOptional": { "name": "urlEncodedResourceCRNQuery", "in": "query", "schema": { "type": "string" }, "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 service instance are returned.", "example": "crn%3Av1%3Abluemix%3Apublic%3Adatabases-for-postgresql%3Aus-south%3Aa%2F274074dce64e9c423ffc238516c755e1%3A29caf0e7-120f-4da8-9551-3abf57ebcfc7%3A*%3A*" }, "CorrelationId": { "name": "Correlation-Id", "in": "header", "schema": { "type": "string" }, "description": "The v4 UUID used to correlate and track transactions.", "required": false }, "ETag": { "name": "ETag", "in": "header", "schema": { "type": "string" }, "description": "ETag header is for internal use only.", "required": false }, "If-Match": { "name": "If-Match", "in": "header", "schema": { "type": "string" }, "description": "ETag is a hash value generated based on attributes representing a specific state/version of a Hyper Protect Crypto Services registration. It is only generated when a single registration is returned from a service to service call. This value can be passed in an If-Match header of a PUT/PATCH request to determine if there are any version conflicts during the process of updating registrations, preventing the problem of losing updated registration data. The If-Match header does a weak comparison between registration versions and is capable of handling multiple comma separated ETags.", "required": false, "example": "W/\"c8f7e349e5a1f8d7255de81f2508e5914667fg5e4aeb88945002286f753064b7\"" }, "InstanceParam": { "name": "Bluemix-Instance", "in": "header", "schema": { "type": "string" }, "description": "The IBM Cloud instance ID that identifies your Hyper Protect Crypto Services instance.", "required": true }, "KeyRingDefault": { "name": "X-Kms-Key-Ring", "in": "header", "schema": { "type": "string", "default": "default" }, "description": "The ID of the key ring that the specified key belongs to. When the header is not specified, Hyper Protect Crypto Services 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" }, "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" }, "description": "The ID of the key ring that the specified key is a part of. When the header is not specified, Hyper Protect Crypto Services 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" ] }, "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, Hyper Protect Crypto Services 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": { "InstanceConnectionRead": { "properties": { "instance_id": { "description": "The v4 UUID used to uniquely identify the instance in IBM Cloud.", "type": "string", "format": "byte" }, "apiConnectionInfo": { "description": "Specifies the URI (url:port) where the API can be used.", "type": "string" } } }, "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" }, "adopterKeyState": { "description": "The adopter's reported key state at time of processing the event.", "type": "string", "enum": [ "DEK_ENABLED", "DEK_DISABLED", "DEK_NOT_FOUND" ] }, "timestamp": { "description": "The date the event was processed by the adopter service. The date format follows RFC 3339.", "type": "string", "format": "date-time" }, "keyStateData": { "$ref": "#/components/schemas/KeyStateData" }, "deleteRegistration": { "description": "A boolean that determines whether Hyper Protect Crypto Services 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, Hyper Protect Crypto Services 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.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_action+json", "application/vnd.ibm.kms.key+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.migration_intent+json" ] }, "collectionTotal": { "description": "The number of elements in the resource array.", "type": "integer", "format": "int64", "example": 1 } } }, "CollectionMetadataListKeys": { "description": "The metadata that describes the list keys response", "type": "object", "allOf": [ { "$ref": "#/components/schemas/CollectionMetadata" }, { "$ref": "#/components/schemas/ListKeysMetadataProperties" } ] }, "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", "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" } } } }, "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", "items": { "allOf": [ { "$ref": "#/components/schemas/CreateKeyWithPolicyOverrides" } ] } } } }, "CreateKeyImportWithPolicies": { "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" ] } ] }, "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" } } } }, "DeleteKeyResource": { "allOf": [ { "$ref": "#/components/schemas/KeyWithPayload" }, { "$ref": "#/components/schemas/DeleteProperties" } ] }, "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", "nullable": true, "format": "date-time", "readOnly": true, "example": "2019-01-01T05:23:19+0000" }, "deletedBy": { "description": "The unique identifier for the resource that deleted the key.", "type": "string", "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": "2019-01-30T05:23:19+0000" }, "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": "2019-01-01T09:23:19+0000" }, "purgeScheduledOn": { "description": "The date the deleted key will be automatically purged from Hyper Protect Crypto Services system.", "type": "string", "nullable": true, "format": "date-time", "example": "2019-04-01T05:23:19+0000" } } }, "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": "2010-01-12T05:23:19+0000" } } }, "ErrorCIP": { "description": "An error that occurred during a `/governance/v1/configs` request.", "required": [ "code", "message" ], "type": "object", "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 standardized for programmatic error checking.", "type": "string" }, "more_info": { "description": "A link to relevant documentation.", "type": "string" } } }, "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": { "type": "object", "$ref": "#/components/schemas/Error" } } } }, "ErrorCollectionCIP": { "description": "The base schema for error responses from `/governance/v1/configs`.", "required": [ "errors" ], "properties": { "trace": { "description": "A v4 UUID that can be used to trace a request. Equivalent to the given `Transaction-Id` and `Correlation-Id`.", "type": "string" }, "errors": { "description": "A collection of errors.", "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/ErrorCIP" } } } }, "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": { "type": "object", "$ref": "#/components/schemas/ErrorWithReason" } } } }, "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": "object" }, "type": "array" } }, "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", "maxLength": 4096, "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", "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", "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" } } } }, "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" } ] } } } }, "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" } ] } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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 Hyper Protect Crypto Services 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 Hyper Protect Crypto Services, check out [Data encryption](/docs/hs-crypto?topic=hs-crypto-security-and-compliance#data-security).", "type": "string", "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" } } } }, "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" } } } }, "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": { "type": "object", "$ref": "#/components/schemas/KeyAliasResource" } } } }, "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": "2010-01-12T05:23:19+0000" }, "createdBy": { "description": "The unique identifier for the user that created the key ring.", "type": "string" } } }, "KeyRingID": { "description": "An ID that identifies the key ring. Each ID is unique only within the given instance and is not reserved across the Hyper Protect Crypto Services 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", "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" } } } }, "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" } } } }, "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", "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" } } } }, "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" } } }, "PatchKeyResponseBody": { "description": "The base schema for patch key response body.", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "An array of resources.", "type": "array", "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", "items": { "$ref": "#/components/schemas/KeyFullRepresentation" } } } }, "RestoreKey": { "description": "The base schema for the resource given in the Restore key request body.", "allOf": [ { "type": "object", "required": [ "payload" ], "properties": { "payload": { "$ref": "#/components/schemas/ImportPayload" } } } ] }, "RestoreKeyOneOf": { "oneOf": [ { "$ref": "#/components/schemas/RestoreKeyRequestBody" } ] }, "RestoreKeyRequestBody": { "description": "The base schema for the request body of a `POST /keys/:id/restore`.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/RestoreKey" } } } }, "RestoreKeyWithImportToken": { "description": "The base schema for the resource given in the Restore Key With Import Token request body.", "allOf": [ { "$ref": "#/components/schemas/SecureImport" } ] }, "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`, Hyper Protect Crypto Services 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" }, "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", "deprecated": true } } }, "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" } } }, "CIPResource": { "description": "Resource config information for the purpose of config monitoring.", "type": "object", "required": [ "next", "account_id", "service_name", "resource_kind", "config_request_id", "timestamp", "config_state" ], "properties": { "next": { "type": "object", "description": "URL to obtain the next set of data during pagination, given further resources matching the query can be found.", "required": [ "href" ], "properties": { "href": { "type": "string" } } }, "account_id": { "type": "string", "description": "ID of account that requested instance belongs to.", "pattern": "[0-9a-f]{32}" }, "service_name": { "type": "string", "description": "Hyper Protect Crypto Services service name", "enum": [ "kms" ], "example": "kms" }, "resource_kind": { "type": "string", "description": "The resource kind matching the resource request.", "enum": [ "instance", "key" ] }, "config_request_id": { "type": "string", "description": "Unique identifier for this request and any related pagination requests." }, "timestamp": { "type": "string", "description": "Time the resource state was collected. Timestamps are in UTC.", "example": "YYYY-MM-DDTHH:MM:SSZ" }, "config_state": { "type": "array", "description": "Container array for one or more resources and associated state.", "items": { "type": "object", "required": [ "resource_crn", "resource_group_id", "current_config", "additional_target_attributes" ], "properties": { "resource_crn": { "type": "string", "description": "CRN of resource" }, "resource_group_id": { "type": "string", "description": "ID of resource group in which service instance or resource resides" }, "additional_target_attributes": { "description": "Container for one or more custom target attributes", "type": "object", "properties": { "resource_id": { "description": "Instance ID (if requested `resource_kind` is `instance`) or key ID (if requested `resource_kind` is `key`)", "type": "string" }, "location": { "description": "Location that the resource resides in", "type": "string" }, "instance_id": { "description": "Instance ID (if requested `resource_kind` is `key`)", "type": "string" } } }, "current_config": { "type": "array", "description": "Container for one or more resources.", "items": { "type": "object", "$ref": "#/components/schemas/CurrentConfig" } } } } } } }, "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", "example": "crn:v1:bluemix:public:cloud-object-storage:global:a/::bucket:" } } }, "CreateMigrationIntent": { "description": "The schema for the request body of create a Migration Intent.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/CreateMigrationIntentObject" } } } }, "CreateMigrationIntentObject": { "description": "The schema for the resources object in the body of a create Migration Intent.", "type": "object", "required": [ "targetCRK" ], "properties": { "targetCRK": { "description": "The CRN of the Customer Root Key (CRK) which is the target of the migration.", "nullable": false, "type": "string" } } }, "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", "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 Hyper Protect Crypto Services must prevent deletion of a root key. This policy should only be set if a WORM policy must be satisfied.\nIf set to `true`, Hyper Protect Crypto Services 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 }, "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 } } }, "CurrentConfig": { "oneOf": [ { "$ref": "#/components/schemas/SimpleProperty" }, { "$ref": "#/components/schemas/NestedProperty" } ] }, "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", "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`, Hyper Protect Crypto Services enables a dual authorization deletion policy for your service instance.\nBy default, Hyper Protect Crypto Services 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", "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" }, "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": [ "param", "header", "field" ] }, "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/GetInstancePolicyKeyCreateImportAccess" }, { "$ref": "#/components/schemas/GetInstancePolicyMetrics" }, { "$ref": "#/components/schemas/GetInstancePolicyRotation" }, { "$ref": "#/components/schemas/GetMultipleInstancePolicies" } ] }, "GetInstancePolicyAllowedNetwork": { "description": "Properties that are associated with retrieving 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", "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, "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/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "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/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "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, "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/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "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/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "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, "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": "2010-01-12T05:23:19+0000" }, "createdBy": { "description": "The unique identifier for the resource that created the policy.", "type": "string", "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": "2010-01-12T05:23:19+0000" }, "updatedBy": { "description": "The unique identifier for the resource that updated the policy.", "type": "string", "readOnly": true } } }, "GetMigrationIntent": { "description": "The base schema for retrieving a Migration Intent.", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "items": { "$ref": "#/components/schemas/MigrationIntent" } } } }, "GetMultipleInstancePolicies": { "description": "Properties that are associated with the instance level policies.", "type": "object", "required": [ "metadata", "resources" ], "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "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", "format": "date-time", "example": "2018-04-12T23:20:50.52Z", "readOnly": true }, "expirationDate": { "description": "The date the import token expires. The date format follows RFC 3339.", "type": "string", "format": "date-time", "example": "2018-12-01T23:20:50.52Z", "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, "allOf": [ { "$ref": "#/components/schemas/AllowedNetworkPolicyProperties" }, { "$ref": "#/components/schemas/KeyCreateImportAccessProperties" }, { "$ref": "#/components/schemas/RotationProperties" } ] }, "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 } } } ] }, "InstancePolicyEnabledProperty": { "required": [ "enabled" ], "description": "Property that determines whether an instance policy is active", "properties": { "enabled": { "description": "If set to `true`, Hyper Protect Crypto Services enables the specified policy for your service instance. If set to `false`, Hyper Protect Crypto Services disables the specified policy for your service instance, and the policy will no longer affect Hyper Protect Crypto Services 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, "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": "2010-01-12T05:23:19+0000" }, "createdBy": { "description": "The unique identifier for the resource that created the policy.", "type": "string", "readOnly": true }, "updatedBy": { "description": "The unique identifier for the resource that updated the policy.", "type": "string", "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": "2010-01-12T05:23:19+0000" } } }, "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, "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 } } } ] }, "Key": { "description": "Properties associated with a key response.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "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/RestoreKeyRequestBody" }, { "$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": "84a53643-9ca8-4ff2-9c68-d7842526167b", "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": "...", "readOnly": true }, "creationDate": { "description": "The date the alias was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2010-10-12T05:23:19+0000" } } }, "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 Hyper Protect Crypto Services to create root keys in the specified service instance. If set to `true`, Hyper Protect Crypto Services 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 Hyper Protect Crypto Services to create standard keys in the specified service instance. If set to `true`, Hyper Protect Crypto Services 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`, Hyper Protect Crypto Services 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`, Hyper Protect Crypto Services 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`, Hyper Protect Crypto Services 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": "2018-04-12T23:20:50.52Z" }, "createdBy": { "description": "The unique identifier for the resource that created the key.", "type": "string", "readOnly": true }, "algorithmType": { "deprecated": true, "description": "Deprecated.", "type": "string", "enum": [ "AES" ], "default": "AES", "readOnly": true }, "algorithmMetadata": { "deprecated": true, "description": "Deprecated.", "type": "object", "readOnly": true, "nullable": true, "properties": { "bitLength": { "description": "Deprecated.", "type": "string", "enum": [ "128", "192", "256" ], "default": "256" }, "mode": { "description": "Deprecated.", "type": "string", "enum": [ "CBC_PAD" ], "default": "CBC_PAD" } } }, "algorithmBitSize": { "deprecated": true, "description": "Deprecated.", "type": "integer", "enum": [ 128, 192, 256 ], "default": 256 }, "algorithmMode": { "deprecated": true, "description": "Deprecated.", "type": "string", "enum": [ "CBC_PAD" ], "default": "CBC_PAD" }, "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": "2018-04-12T23:20:50.52Z" }, "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": "2018-04-12T23:20:50.52Z" }, "keyVersion": { "$ref": "#/components/schemas/KeyVersion" } } }, "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" ] }, "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`, Hyper Protect Crypto Services enables a dual authorization policy on a single key.\nAfter you enable the policy, Hyper Protect Crypto Services 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`, Hyper Protect Crypto Services enables a dual authorization policy on a single key.\nAfter you enable the policy, Hyper Protect Crypto Services 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" ] }, "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`, Hyper Protect Crypto Services 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`, Hyper Protect Crypto Services 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", "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", "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 an Hyper Protect Crypto Services 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 }, "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", "items": { "type": "string" } }, "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 ] }, "expirationDate": { "description": "The date the key material expires. The date format follows RFC 3339. You can set an expiration date on any key on its creation. If you create a key without specifying an expiration date, the key does not expire.", "type": "string", "format": "date-time", "writeOnly": true, "nullable": true, "example": "2018-12-01T23:20:50.52Z" }, "extractable": { "description": "A boolean that determines whether the key material can leave the service.\nIf set to `false`, Hyper Protect Crypto Services designates the key as a nonextractable root key used for `wrap` and `unwrap` actions. If set to `true`, Hyper Protect Crypto Services 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", "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 Hyper Protect Crypto Services. The value is set by Hyper Protect Crypto Services 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 Hyper Protect Crypto Services 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" }, "migrationIntent": { "$ref": "#/components/schemas/MigrationIntent" } } }, "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": "4a0225e9-17a0-46c1-ace7-f25bcf4237d4" }, "creationDate": { "description": "The date that the version of the key was created.", "type": "string", "format": "date-time", "nullable": true, "readOnly": true, "example": "2010-01-12T05:23:19+0000" } } }, "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`, Hyper Protect Crypto Services 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 } } }, "MigrationIntent": { "description": "Migration intent.", "type": "object", "required": [ "sourceCRK", "targetCRK", "creationDate", "createdBy", "id" ], "nullable": true, "properties": { "sourceCRK": { "description": "The full CRN of the CRK which is the source of this Migration Intent.", "type": "string" }, "targetCRK": { "description": "The full CRN of the CRK which is the target of this Migration Intent.", "type": "string" }, "creationDate": { "description": "The date the Migration Intent was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "example": "2023-01-12T05:23:19+0000" }, "createdBy": { "description": "The unique identifier for the user that created the Migration Intent.", "type": "string" }, "id": { "description": "Internal v4 UUID of the Migration Intent.", "type": "string" } } }, "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" } } } ] }, "NestedProperty": { "description": "Config properties that contain a nested config value.", "type": "object", "required": [ "property" ], "properties": { "property": { "type": "string" }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/SimpleProperty" } } } }, "Registration": { "description": "Properties associated with a registration response.", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CollectionMetadata" }, "resources": { "description": "A collection of resources.", "type": "array", "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": "84a53643-9ca8-4ff2-9c68-d7842526167b", "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 }, "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:cloud-object-storage:global:a/::bucket:", "readOnly": true }, "createdBy": { "description": "The unique identifier for the resource that created the registration.", "type": "string", "example": "examplecreator@ibm.com", "readOnly": true }, "creationDate": { "description": "The date the registration was created. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2010-01-12T05:23:19+0000" }, "updatedBy": { "description": "The unique identifier for the resource that updated the registration.", "type": "string", "example": "exampleupdater@ibm.com", "readOnly": true }, "lastUpdated": { "description": "Updates when the registration is modified. The date format follows RFC 3339.", "type": "string", "format": "date-time", "readOnly": true, "example": "2010-01-12T05:23:19+0000" }, "description": { "description": "Description of the purpose of the registration.", "type": "string", "example": "Example description", "readOnly": true }, "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 }, "preventKeyDeletion": { "description": "A boolean that determines whether Hyper Protect Crypto Services 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", "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", "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 Hyper Protect Crypto Services. 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" }, { "required": [ "ciphertext" ] } ] }, "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" }, { "required": [ "ciphertext" ] } ] }, "RewrappedKeyVersion": { "description": "Properties that are associated with the rewrapped key version.", "type": "object", "properties": { "rewrappedKeyVersion": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/KeyVersion" }, { "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 Hyper Protect Crypto Services, omit the `payload` property and pass in an empty request entity-body.", "type": "string", "writeOnly": true } } }, "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/hs-crypto?topic=hs-crypto-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", "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.\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", "format": "byte", "writeOnly": true }, "iv": { "description": "The optional initialization vector (IV) that is generated by the AES-GCM algorithm when you encrypt a nonce. The IV value is required to decrypt the encrypted nonce value that you optionally provided when you make a key import request to the service.\n\nTo generate an IV, encrypt the `nonce` value by using an AES-GCM\nencryption method that is compatible with your environment. Then,\nsupply the generated IV value when you import a key to the service.", "type": "string", "format": "byte", "writeOnly": true, "minLength": 12 }, "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_1` is supported.", "type": "string", "example": "RSAES_OAEP_SHA_1", "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/SetInstancePolicyKeyCreateImportAccess" }, { "$ref": "#/components/schemas/SetInstancePolicyMetrics" }, { "$ref": "#/components/schemas/SetInstancePolicyRotation" }, { "$ref": "#/components/schemas/SetMultipleInstancePolicies" } ] }, "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", "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" ] }, "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", "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" ] }, "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", "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" ] }, "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", "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" ] }, "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", "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" ] }, "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", "items": { "type": "object", "$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", "items": { "type": "object", "$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", "items": { "type": "object", "required": [ "policy_type", "policy_data" ], "properties": { "policy_type": { "description": "The type of policy to be set.", "type": "string", "enum": [ "allowedNetwork", "dualAuthDelete", "keyCreateImportAccess", "metrics", "rotation" ] }, "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 } } } ], "nullable": true } } } } } }, "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", "items": { "$ref": "#/components/schemas/SetMultipleKeyPoliciesResource" } } } }, "SimpleProperty": { "description": "Base config properties", "type": "object", "required": [ "property" ], "properties": { "property": { "type": "string" }, "value": { "type": "string" } } }, "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 Hyper Protect Crypto Services.", "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 Hyper Protect Crypto Services. The value is base64 encoded." } } }, "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" }, { "required": [ "ciphertext" ] } ] }, "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" }, { "required": [ "plaintext" ] } ] }, "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", "items": { "$ref": "#/components/schemas/ModifiableRegistrationResourceBody" } } } }, "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" }, { "required": [ "ciphertext" ] } ] }, "WrappedKeyVersion": { "description": "Properties that are associated with the wrapped key version.", "type": "object", "properties": { "keyVersion": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/KeyVersion" }, { "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. Hyper Protect Crypto Services 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.", "maxLength": 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" }, "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.", "minLength": 0, "maxLength": 255, "minItems": 0, "maxItems": 126, "writeOnly": true } } } }, "requestBodies": { "CreateImportTokenBody": { "description": "The base request for creating an import token.", "content": { "application/vnd.ibm.kms.import_token+json": { "schema": { "$ref": "#/components/schemas/ImportToken" } } }, "required": true }, "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": "e4f229a2-abbf-43f6-8e25-42335e0b1b94", "adopterKeyState": "DEK_ENABLED", "timestamp": "YYYY-MM-DDTHH:MM:SSZ", "keyStateData": { "keyVersion": "350a4ac2-118f-4c65-88f2-42392ff0b198" } } ] } }, "BatchEvents": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.event_acknowledge+json", "collectionTotal": 2 }, "resources": [ { "eventId": "e4f229a2-abbf-43f6-8e25-42335e0b1b94", "adopterKeyState": "DEK_ENABLED", "timestamp": "YYYY-MM-DDTHH:MM:SSZ", "keyStateData": { "keyVersion": "350a4ac2-118f-4c65-88f2-42392ff0b198" } }, { "eventId": "a201241f-8d5e-4efa-8313-9d1c6d40daac", "adopterKeyState": "DEK_ENABLED", "timestamp": "YYYY-MM-DDTHH:MM:SSZ" }, { "eventId": "4d9bba95-a162-4ebd-93bb-11db5bb468ee", "adopterKeyState": "DEK_DISABLED", "timestamp": "YYYY-MM-DDTHH:MM:SSZ" } ] } } } } } }, "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" }, "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" }, "RestoreKey": { "$ref": "#/components/examples/RestoreKey" }, "RestoreKeySecure": { "$ref": "#/components/examples/RestoreKeySecure" }, "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 Hyper Protect Crypto Services. [Learn more](/docs/hs-crypto?topic=hs-crypto-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/hs-crypto?topic=hs-crypto-integrate-services#grant-access)" } ] } } } }, "ForbiddenRegistration": { "description": "You are not authorized to make this request due to [missing authorization](/docs/hs-crypto?topic=hs-crypto-integrate-services#grant-access) between the service instance and Hyper Protect Crypto Services 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/hs-crypto" } ] } ] } } } }, "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": "Hyper Protect Crypto Services 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: Hyper Protect Crypto Services is currently unavailable. Your request could not be processed. Try again later." } ] } } } }, "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" } ] } } } }, "PreconditionFailed": { "description": "Provided ETag does not match generated ETag.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorCollectionWithReason" }, "example": { "metadata": { "collectionType": "application/vnd.ibm.kms.error+json", "collectionTotal": 1 }, "resources": [ { "errorMsg": "Precondition Failed for the following request.", "reasons": [ { "code": "PRECONDITION_FAILED_ERR", "message": "Provided ETag does not match generated ETag for the specified registration.", "status": 412, "moreInfo": "https://cloud.ibm.com/apidocs/hs-crypto" } ] } ] } } } }, "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": "...", "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": "..." } ] } }, "DeactivateRegistration": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.resource_crn+json", "collectionTotal": 1 }, "resources": [ { "resourceCrn": "crn:v1:bluemix:public:cloud-object-storage:global:a/684b6eb4-33b6-42e7-9b82-ca6cb8b59dac:b016015c-95b3-4ffd-b5ab-8316ee83ba79:bucket:mybucket" } ] } }, "GetInstancePolicyAllowedNetwork": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": "", "attributes": { "allowed_network": "" } }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." } ] } }, "GetInstancePolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "dualAuthDelete", "policy_data": { "enabled": "" }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." } ] } }, "GetInstancePolicyKeyCreateImportAccess": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": "", "attributes": { "create_root_key": "", "create_standard_key": "", "import_root_key": "", "import_standard_key": "", "enforce_token": "" } }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." } ] } }, "GetInstancePolicyMetrics": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "metrics", "policy_data": { "enabled": "" }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." } ] } }, "GetInstancePolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "rotation", "policy_data": { "enabled": "", "attributes": { "interval_month": 3 } }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." } ] } }, "GetKeyPolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "id": "...", "crn": "...", "dualAuthDelete": { "enabled": "" }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdateDate": "..." } ] } }, "GetKeyPolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "id": "...", "crn": "...", "rotation": { "enabled": "", "interval_month": 3 }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdateDate": "..." } ] } }, "GetMultipleInstancePolicies": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 5 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": "", "attributes": { "allowed_network": "" } }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." }, { "policy_type": "dualAuthDelete", "policy_data": { "enabled": "" }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." }, { "policy_type": "metrics", "policy_data": { "enabled": "" }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." }, { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": "", "attributes": { "create_root_key": "", "create_standard_key": "", "import_root_key": "", "import_standard_key": "", "enforce_token": "" } }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." }, { "policy_type": "rotation", "policy_data": { "enabled": "", "attributes": { "interval_month": 3 } }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdated": "..." } ] } }, "GetMultipleKeyPolicies": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 2 }, "resources": [ { "id": "...", "crn": "...", "rotation": { "enabled": "", "interval_month": 3 }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdateDate": "..." }, { "id": "...", "crn": "...", "dualAuthDelete": { "enabled": "" }, "createdBy": "...", "creationDate": "...", "updatedBy": "...", "lastUpdateDate": "..." } ] } }, "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": "...", "extractable": false, "payload": "..." } ] } }, "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": "...", "extractable": false, "payload": "...", "encryptionAlgorithm": " ", "encryptedNonce": "...", "iv": "..." } ] } }, "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": "...", "payload": "...", "encryptionAlgorithm": " ", "encryptedNonce": "...", "iv": "..." } ] } }, "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": "...", "payload": "..." } ] } }, "RestoreKey": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "payload": "..." } ] } }, "RestoreKeySecure": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.key+json", "collectionTotal": 1 }, "resources": [ { "payload": "...", "encryptionAlgorithm": " ", "encryptedNonce": "...", "iv": "..." } ] } }, "RewrapKey": { "summary": "Rewrap key", "value": { "ciphertext": "", "aad": [ "", "" ] } }, "RotateKey": { "summary": "Rotate key", "value": { "payload": "" } }, "SecureRotateKey": { "summary": "Rotate key using an import token", "value": { "payload": "", "encryptionAlgorithm": "RSAES_OAEP_SHA_1", "encryptedNonce": "...", "iv": "..." } }, "SetKeyPolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": "" } } ] } }, "SetKeyPolicyDualAuthDeleteResponse": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": "" } } ] } }, "SetKeyPolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "rotation": { "enabled": "", "interval_month": 1 } } ] } }, "SetKeyPolicyRotationResponse": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "type": "application/vnd.ibm.kms.policy+json", "rotation": { "enabled": "", "interval_month": 1 } } ] } }, "SetInstancePolicyAllowedNetwork": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": "", "attributes": { "allowed_network": "" } } } ] } }, "SetInstancePolicyDualAuthDelete": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "dualAuthDelete", "policy_data": { "enabled": "" } } ] } }, "SetInstancePolicyKeyCreateImportAccess": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": "", "attributes": { "create_root_key": "", "create_standard_key": "", "import_root_key": "", "import_standard_key": "", "enforce_token": "" } } } ] } }, "SetInstancePolicyMetrics": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "metrics", "policy_data": { "enabled": "" } } ] } }, "SetInstancePolicyRotation": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 1 }, "resources": [ { "policy_type": "rotation", "policy_data": { "enabled": "", "attributes": { "interval_month": 3 } } } ] } }, "SetMultipleInstancePolicies": { "value": { "metadata": { "collectionType": "application/vnd.ibm.kms.policy+json", "collectionTotal": 5 }, "resources": [ { "policy_type": "allowedNetwork", "policy_data": { "enabled": "", "attributes": { "allowed_network": "" } } }, { "policy_type": "dualAuthDelete", "policy_data": { "enabled": "" } }, { "policy_type": "metrics", "policy_data": { "enabled": "" } }, { "policy_type": "keyCreateImportAccess", "policy_data": { "enabled": "", "attributes": { "create_root_key": "", "create_standard_key": "", "import_root_key": "", "import_standard_key": "", "enforce_token": "" } } }, { "policy_type": "rotation", "policy_data": { "enabled": "", "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": "", "interval_month": 1 } }, { "type": "application/vnd.ibm.kms.policy+json", "dualAuthDelete": { "enabled": "" } } ] } }, "UnwrapKey": { "summary": "Unwrap key", "value": { "ciphertext": "", "aad": [ "", "" ] } }, "WrapKey": { "summary": "Wrap key", "value": { "plaintext": "", "aad": [ "", "" ] } } } } }