Introduction
Overview
Key Management Service is a key management service provided by Baidu AI Cloud, and you can manage the key information on the cloud conveniently, safely and reliably through such service.
If you first call the API of Baidu AI Cloud product, you can watch API Introduction Video Guide to quickly master the API calling method.
Service Domain Name
Currently, KMS service supports three regions, including "North China - Beijing", "South China - Guangzhou" and "East China - Suzhou".
Region | Access to Endpoint | Protocol |
---|---|---|
North China - Beijing | bkm.bj.baidubce.com | HTTPS |
South China - Guangzhou | bkm.gz.baidubce.com | HTTPS |
East China - Suzhou | bkm.su.baidubce.com | HTTPS |
API Authentication Mechanism
The security authentication of all APIs utilizes the Access Key and request signature mechanism. Access Key consists of Access Key ID and Secret Access Key, both of which are strings. For each HTTP request, the algorithm described below is utilized to generate one authentication string. The authentication string is submitted in the Authorization header. The server verifies the correctness of authentication string based on the generating algorithm. The format of the authentication string is bce-auth-v{version}/{accessKeyId}/{timestamp}/{expirationPeriodInSeconds}/{signedHeaders}/{signature}
.
- The version stands for a positive integer.
- The timestamp stands for the UTC time when the signature is generated.
- The expirationPeriodInSeconds stands for the expiration period of signature.
- The signedHeaders stands for the header list involved in the signature algorithm. The headers are separated by a semicolon (;), e.g. host; x-bce-date. The list is arranged in lexicographic order. (This API signature only utilizes two headers of host and x-bce-date.)
- The signature is the 256-bit signed sexadecimal notation, and composed of 64 lower-case letters.
After Baidu Cloud receives a request of users, the system will use the same SK and authentication mechanism to generate an authentication string, and compare it with the authentication string contained in the user request. If the two authentication strings are the same, the system considers that the user has the designated operation privilege, and executes the related operations; if the two authentication strings are different, the system will ignore the operation and return an error code.
Please refer to the Authentication for details of the authentication mechanism.
Idempotency
Users may try to resend a request if they encounter a request timeout or an internal server error when calling an interface. At this time, users can avoid creating more resources than expected by using the clientToken parameter to ensure the idempotency of the request.
Idempotency is based on clientToken, an ASCII string no longer than 64 bits usually placed in a query string such as http://bcc.bj.baidubce.com/v1/instance? clientToken=be31b98c-5e41-4838-9830-9be700de5a20
.
If the user calls the creation interface with the same clientToken value, the server will return the same request result. Therefore, when the user encounters an error and retries, he can provide the same clientToken value to ensure that only one resource is created. If the user provides a used clientToken, but other request parameters (including queryString and requestBody) are different or even URL path is different, the error code of IdempotentParameterMismatch will be returned.
The clientToken is valid for 24 hours, subject to the last time when the server receives the clientToken. That is, if the client continuously sends the same clientToken, the clientToken will be valid for a long time.
Date and Time Specification
There are various methods to express date and time. For the sake of uniformity, unless it is a convention or a corresponding specification, wherever the date and time is required, UTC time shall be used, ISO 8601 shall be followed , and the following constraints shall be met:
- Fields expressing the date all utilize the YYYY-MM-DD format, e.g.2014-06-01 which means June 1, 2014.
- Fields expressing time all utilize the hh:mm:ss format, with the capital letter Z added at the end, which means UTC time. E.g. 23:00:10Z means UTC time: 23:00:10.
- When the date and time is combined, the capital letter T is added between the two items, e.g. 2014-06-01T23:00:10Z means UTC time: 23:00:10 on June 1, 2014.
Public Request Header
Header | Type | Description |
---|---|---|
Authorization | String | Authentication information used to verify the validity of the request. Refer to authentication for more information |
Content-Length | String | Length of HTTP request content defined in RFC2616. |
Content-Type | String | Type of HTTP request content defined in RFC2616. |
Content-MD5 | String | MD5 digest of the HTTP request content defined by RFC2616 can carry this field to verify whether the file stored on the KMS side is consistent with the file expected by the user. |
Date | String | GMT time specified in HTTP 1.1 protocol, such as Wed, 06 Apr 2016 06:34:40 GMT |
Host | String | Access Host value, which shall be Endpoint corresponding to the access region |
x-bce-date | String | Current time follows ISO8601 specification, with format such as 2016-04-06T08: 23: 49Z |
Public Response Header
Header | Type | Description |
---|---|---|
Content-Length | String | Length of HTTP request content defined in RFC2616. |
Content-Type | String | Type of HTTP request content defined in RFC2616. |
Connection | String | Whether the server is disconnected. The value can be close or keep-alive. |
Date | String | GMT time specified in HTTP 1.1 protocol, such as Wed, 06 Apr 2016 06:34:40 GMT |
Server | String | Server name, with the value of BceKms |
x-bce-request-id | String | It is created by BCE KMS, and is the unique identity to request BceKms |
x-bce-debug-id | String | Created by BCE KMS, and is an identification ID used to help troubleshoot. If you encounter problem during the use of KMS, you can provide this field in work ticket to quickly locate the problem. |
Error Code
When the user's access fails, the error response body returned by KMS is as follows:
{
"code":"AccessDenied"
"message":"Access denied"
"requestId":"7ab2b34d-614d-478a-ba9b-3049ca7b6479"
}
Public Error Code
HTTP status code | Error code | Message | Semantics |
---|---|---|---|
403 Forbidden | AccessDenied | Access denied | Access denied |
403 Forbidden | SignatureDoesNotMatch | The request signature we calculated does not match the signature you provided | The signature appended in the header field of Authorization is not consistent with that calculated by server |
400 Bad Request | InvalidHttpAuthHeader | The HTTP authorization header is invalid | The format of Authorization header is wrong. |
400 Bad Request | MissingHttpAuthHeader | You must provide the authorization header | Missing Authorization header field |
403 Forbidden | RequestExpired | Request has expired | The requested timestamp expires. |
403 Forbidden | InvalidAccessKeyId | The Access Key ID you provided does not exist in our records | Invalid Access Key Id |
500 Internal Server Error | InternalError | We encountered an internal error Please try again | Internal server error. |
Error Code for Key Management Service
HTTP status code | Error code | Message | Semantics |
---|---|---|---|
400 Bad Request | MasterKeyNumExceed | You have attempted to create more master keys than allowed | The number of Master Key exceeds the limit |
400 Bad Request | InvalidPlaintext | The plaintext you provided is invalid | Invalid plaintext to be encrypted |
404 Not Found | NoSuchMasterKey | The specified master key does not exist | The master key does not exist |
400 Bad Request | InvalidDescription | The specified description is invalid | Invalid master key description |
400 Bad Request | NotImplemented | The API has not been implemented yet | The interface does not exist |
400 Bad Request | InvalidCiphertext | The specified ciphertext is invalid | Invalid ciphertext to be decrypted |
400 Bad Request | InvalidMasterKeyId | The specified master key id is invalid | Invalid Master Key Id |
400 Bad Request | MissingMasterKeyId | You must provide the master key id | Missing Master Key Id field |
400 Bad Request | PlaintextLengthExceed | The length of plaintext exceeds the limit | The length of the plaintext to be encrypted exceeds the limit |
400 Bad Request | MissingPlaintext | You must provide the plaintext | Missing plaintext field |
400 Bad Request | InvalidKeyUsage | The specified keyUsage is invalid | Invalid keyUsage |
400 Bad Request | InvalidPendingWindowInDays | The specified pending windows in days is invalid | The specified number of days to be deleted is invalid |
400 Bad Request | InvalidListKeysLimit | The specified limit of list keys is invalid | The number limit specified to enumerate master key is invalid |
400 Bad Request | MissingCiphertext | You must provide the ciphertext | Missing the ciphertext to be encrypted |
400 Bad Request | MissingNumberOfBytes | You must provide the numberOfBytes | Missing the field for generating the length of key |
400 Bad Request | InvalidKeySpec | The specified keySpec is invalid | Invalid keySpec |
400 Bad Request | InvalidNumberOfBytes | The specified numberOfBytes is invalid | Invalid numberOfBytes |
429 Too Many Requests | Throttling | The rate of your request exceed limit | The speed of access is limited |
400 Bad Request | InvalidState | The state of the specified key is invalid for your request | The state of specified key is invalid |
400 Bad Request | InvalidJson | The json is malformed or does not meet the requirements | The format of json is not correct, or does not meet the requirements of the interface |
400 Bad Request | InvalidMarker | The marker you provided is invalid | Invalid marker |
400 Bad Request | InvalidAction | The specified action is not supported | The value of action parameter in the request parameter is invalid |
400 Bad Request | inactivated | The account has not activated the kms service | KMS service is not activated |
400 Bad Request | chargeOverDue | this account charge is overdue | The account is overdue |