eHSM REST API Reference

Currently, the eHSM-KMS-Service now provides the following restful APIs to the customers :

Cryptographic Functionalities APIs Notes: These below Rest APIs are used to provide crypto functionalities for users.
Key Management APIs Notes: These below Rest APIs are used to manage CMK functionalities for users.
- GetVersion
- Enroll
- ListKey
- DeleteKey
- DeleteALLKey
- EnableKey
- DisableKey
Remote Attestation APIs Notes: These below Rest APIs are used to do the remote attestation.
Secret Manager APIs Notes: These below Rest APIs are used to do the secret management.

Common Prameters

This section describes the parameters that are common to all API requests and responses.

Name	Type	Reference Value	Description
appid	string	12345678-0123-4567-***	An unique id to request ehsm in a domain, which is requested from ehsm service maintainer
timestamp	string	1643050812444	The timestamp of sending request; 30 minute validity;Taking the current time as the benchmark, detect timestamp within 30 minutes, which cannot be repeated
nonce	string	2374462904	The nonce is optional which max length is 64 bytes, the caller can decide whether to pass it with the request data.
sign	string	iw6mkXDqNipxweCH****	The signature string of the current request. Notes: Before to request the ehsm-kms cryptographic APIs, the cutomer should to request the unique appid and APIKey from the ehsm kms service maintainer, and make sure they are securely stored. The API key will participate in the signature, but does not participate in the parameter transfer. Signature= base64(HMAC-SHA256(APIKey, RequestData)), where, RequestData=[appid=<appid>&nonce=<nonce>&payload=<payload>&timestamp=<timestamp>] ordered in ASCII ascending, and the parameter must also be ordered.
payload	Object	payload ={ "keyspec":"EH_RSA_3072", "origin": "EH_INTERNAL_KEY" }	The specific parameters of each method call.

Createkey

Create a customer master key(CMK) for the user, which can be a symmetric or an asymmetric key, for the symmetric cmk mainly used to wrap the datakey, also can be used to encrypted an arbitrary set of bytes data(<6KB). And for the asymmetric cmk mainly used to sign/verify or asymmetric encrypt/decrypt datas(not for the datakey.)

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=CreateKey

Request Payload:

Name	Type	Reference Value	Description
Keyspec	String	EH_AES_GCM_128	The keyspec the user want to create, it can be the following one: EH_AES_GCM_128 EH_AES_GCM_192 EH_AES_GCM_256 EH_RSA_2048 EH_RSA_3072 EH_RSA_4096 EH_EC_P224 EH_EC_P256 EH_EC_P256K EH_EC_P384 EH_EC_P521 EH_SM2 EH_SM4_CTR EH_SM4_CBC EH_HMAC Notes: EH_HMAC is not supported at present, and will be supported later.
origin	String	EH_INTERNAL_KEY	The source about the cmk comes from, it can be: EH_INTERNAL_KEY (generated from the eHSM inside) EH_EXTERNAL_KEY (generated by the customer and want to import into the eHSM) Notes: currently it only support the type of EH_INTERNAL_KEY.
keyusage	String	EH_KEYUSAGE_ENCRYPT_DECRYPT	Record the usage range of the cmk, it can be: EH_KEYUSAGE_ENCRYPT_DECRYPT EH_KEYUSAGE_SIGN_VERIFY

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	A uinque keyid of the cmk.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyspec"] = "EH_RSA_3072"
  payload["origin"] = "EH_INTERNAL_KEY"
  payload["keyusage"] = "EH_KEYUSAGE_ENCRYPT_DECRYPT"

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=CreateKey", data=json.dumps(params), headers=headers)

Response data

  Response= {
      "code": 200,
      "message": "success!",
      "result": {
          "keyid":"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"
      }
  }

(return to the Cryptographic Functionalities APIs.)

Encrypt

Encrypt an arbitrary set of bytes using the CMK.(only support symmetric types).

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=Encrypt

Request Payload:

Name	Type	Reference Value	Description
aad	String	"Y2hhbGxlbmdl"	Some extra datas input by the user, which could help to to ensure data integrity, and not be included in the cipherblobs. The aad stored in BASE64 string.
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	The keyid of the cmk you want to use which must be a symmetric key.
plaintext	String	"cGxhaW50ZXh0"	The datas of the plaintext which in based64 encoding.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
ciphertext	String	"uSDos6NLWNVp4sQZS2+mzLvDw***"	The result in json object for the Ciphertext which in based64 encoding.

Example

Request sample in python

  payload = OrderedDict()
  payload["aad"] = "Y2hhbGxlbmdl"
  payload["keyid"] = "aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"
  payload["plaintext"] = "cGxhaW50ZXh0"

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=Encrypt", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "ciphertext": "uSDos6NLWNVp4sQZS2+mzLvDw***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

Decrypt

Encrypt an arbitrary set of bytes using the CMK.(only support symmetric types).

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=Decrypt

Request Payload:

Name	Type	Reference Value	Description
aad	String	"Y2hhbGxlbmdl"	Some extra datas input by the user, which could help to to ensure data integrity, and not be included in the cipherblobs. The aad stored in BASE64 string.
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	The keyid of the symmetric cmk which used to decryt the ciphertext.
ciphertext	String	"uSDos6NLWNVp4sQZS2+mzLvDw***"	Ciphertext to be decrypted in BASE64 string.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
plaintext	String	"VGVzdDEyMzQtQU***"	Plain data after decrypt and stored in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["aad"] = "Y2hhbGxlbmdl"
  payload["keyid"] = "aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"
  payload["ciphertext"] = "uSDos6NLWNVp4sQZS2+mzLvDw***"

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=Decrypt", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "plaintext": "VGVzdDEyMzQtQU***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

AsymmetricEncrypt

Encrypt an arbitrary set of bytes using the CMK.(only support asymmetric types).

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=AsymmetricEncrypt

Request Payload:

Name	Type	Reference Value	Description
keyid	String	"ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"	A unique keyid for asymmetric key.
plaintext	String	"cGxhaW50ZXh0"	The datas of the plaintext which in based64 encoding.
padding mode	String	EH_RSA_PKCS1	The padding mode users can use: EH_RSA_PKCS1 EH_RSA_PKCS1_OAEP EH_PAD_NONE Notes: for RSA keys, it support EH_RSA_PKCS1 and EH_RSA_PKCS1_OAEP for SM2, it should be EH_PAD_NONE. Currently, ecc keypair does not support this function.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
ciphertext	String	"EhGpx8pMYFRDr28xT4dJvrMg5***"	The data of the ciphertext stores in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = "ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"
  payload["plaintext"] = "cGxhaW50ZXh0"
  payload["padding_mode"] = "EH_RSA_PKCS1"

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=AsymmetricEncrypt", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "ciphertext": "EhGpx8pMYFRDr28xT4dJvrMg5***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

AsymmetricDecrypt

Decrypt an arbitrary set of bytes using the CMK.(only support asymmetric types).

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=AsymmetricDecrypt

Request Payload:

Name	Type	Reference Value	Description
keyid	String	"ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"	The keyid of the asymmetric cmk.
ciphertext	String	"EhGpx8pMYFRDr28xT4dJvrMg5***"	The data of the ciphertext in BASE64 string.
padding mode	String	EH_RSA_PKCS1	The padding mode users can use: EH_RSA_PKCS1 EH_RSA_PKCS1_OAEP EH_PAD_NONE Notes: for RSA keys, it support EH_RSA_PKCS1 and EH_RSA_PKCS1_OAEP for SM2, it should be EH_PAD_NONE. Currently, ecc keypair does not support this function.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
plaintext	String	"VGVzdFJTQS0zMDcyAAAAAAAAAAAAAA***"	Plaint data after decrypt and stored in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = "ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"
  payload["ciphertext"] = "EhGpx8pMYFRDr28xT4dJvrMg5***"
  payload["padding_mode"] = "EH_PAD_PKCS1"

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=AsymmetricDecrypt", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "plaintext": "VGVzdFJTQS0zMDcyAAAAAAAAAAAAAA***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

Sign

Performs sign operation using the cmk(only support asymmetric keyspec).

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=Sign

Request Payload:

Name	Type	Reference Value	Description
keyid	String	"ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"	A unique keyid of asymmetric cmk.
padding mode	String	EH_RSA_PKCS1	The padding mode users can use: EH_RSA_PKCS1 EH_RSA_PKCS1_PSS EH_PAD_NONE Notes: padding_mode is necessary when keyspec is RSA.
digest mode	String	EH_SHA_256(RSA/ECC) EH_SM3(SM2)	The digest mode users can use: EH_SHA_224 EH_SHA_256 EH_SHA_384 EH_SHA_512 EH_SM3 Notes: If digest mode is not provided, the default digest mode will be used. EH_SHA_SHA256 will be used for rsa and ecc, and EH_SM3 will be used for sm2. If use sm2 keypair, digest mode must be EH_SM3.
message type	String	EH_RAW	The digest mode users can use: EH_RAW, KMS will calculate the digest with digest mode for your message EH_DIGEST, users need to fill in a digest value calculated using the digest mode
message	String	"ZGlnZXN0"	Input raw string for messgae type EH_RAW or digest string for messgae type EH_DIGEST. Notes: Message must be a base64 string.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
signature	String	"KkUO2y2IJVdsahlUL4GA0fYf4y9wPaaocdEtfG3***"	The calculated signature value stores in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = "ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"
  payload["message"] = "ZGlnZXN0"
  payload["message_type"] = "EH_RAW"
  payload["digest_mode"] = "EH_SHA_256"
  payload["padding_mode"] = "EH_RSA_PKCS1" #necessary when keyspec is RSA

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=Sign", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "signature": "KkUO2y2IJVdsahlUL4GA0fYf4y9wPaaocdEtfG3***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

Verify

Performs verify operation using the cmk(only support asymmetric keyspec).

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=Verify

Request Payload:

Name	Type	Reference Value	Description
keyid	String	"ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"	The keyid of the asymmetric cmk.
padding mode	String	EH_RSA_PKCS1	The padding mode users can use: EH_RSA_PKCS1 EH_RSA_PKCS1_PSS EH_PAD_NONE Notes: padding_mode is necessary when keyspec is RSA.
digest mode	String	EH_SHA_256(RSA/ECC) EH_SM3(SM2)	The digest mode users can use: EH_SHA_224 EH_SHA_256 EH_SHA_384 EH_SHA_512 EH_SM3 Notes: If digest mode is not provided, the default digest mode will be used. EH_SHA_SHA256 will be used for rsa and ecc, and EH_SM3 will be used for sm2. If use sm2 keypair, digest mode must be EH_SM3.
message type	String	EH_RAW	The digest mode users can use: EH_RAW, KMS will calculate the digest with digest mode for your message EH_DIGEST, users need to fill in a digest value calculated using the digest mode
message	String	"ZGlnZXN0"	Input raw string for messgae type EH_RAW or digest string for messgae type EH_DIGEST. Notes: Message must be a base64 string.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
result	bool	true	True or False: indicate whether the signature passed the verification.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = "ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"
  payload["message"] = "ZGlnZXN0"
  payload["message_type"] = "EH_RAW"
  payload["digest_mode"] = "EH_SHA_256"
  payload["padding_mode"] = "EH_RSA_PKCS1" #necessary when keyspec is RSA
  payload["signature"] = "KkUO2y2IJVdsahlUL4GA0fYf4y9wPaaocdEtfG3***"

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=Verify", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "result": true
    }
  }

(return to the Cryptographic Functionalities APIs.)

Generatedatakey

Generates a random data key that is used to locally encrypt data. the DataKey will be wrapped by the specified CMK(only support asymmetric keyspec), and it will return the plaintext and ciphertext of the data key.

You can use the plaintext of the data key to locally encrypt your data without using KMS and store the encrypted data together with the ciphertext of the data key, then clear the plaintext data from memory as soon as possible.

when you want to obtain the plaintext of datakey again, you can call the Decrypt with the cmk to get the plaintext data.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=GenerateDataKey

Request Payload:

Name	Type	Reference Value	Description
aad	String	"Y2hhbGxlbmdl"	Some extra datas input by the user, which could help to to ensure data integrity, and not be included in the cipherblobs. The aad stored in BASE64 string.
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	A unique id of the specified symmetric CMK.
keylen	int	16	Specifies the length of the plaintext, length is 0~1024 bytes.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
plaintext	String	"JzoxG7io20MgbbvVnbDhquaZ9nZtZXwRlA***"	Plain data key stores in BASE64 string.
ciphertext	String	"J/qC8IwEnhsjFjzIf***"	The cipher text of the data key stores in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["aad"] = "Y2hhbGxlbmdl"
  payload["keyid"] = "aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"
  payload["keylen"] = 16

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=GenerateDataKey", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "plaintext": "JzoxG7io20MgbbvVnbDhquaZ9nZtZXwRlA***",
        "ciphertext": "J/qC8IwEnhsjFjzIf***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

Generatedatakeywithoutplaintext

The same as GenerateDataKey, but it doesn’t return plaintext of generated DataKey.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=GenerateDataKeyWithoutPlaintext

Request Payload:

Name	Type	Reference Value	Description
aad	String	"Y2hhbGxlbmdl"	Some extra datas input by the user, which could help to to ensure data integrity, and not be included in the cipherblobs. The aad stored in BASE64 string.
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	The unique keyid of the specified symmetric CMK.
keylen	int	16	Specifies the length of the plaintext, length is 0~1024 bytes.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
ciphertext	String	"J/qC8IwEnhsjFjzIf***"	The cipher text of the data key stores in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["aad"] = "Y2hhbGxlbmdl"
  payload["keyid"] = "AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"
  payload["keylen"] = 16

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign

  requests.post(url="<ehsm_srv_address>/ehsm?Action=GenerateDataKeyWithoutPlaintext", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "ciphertext": "J/qC8IwEnhsjFjzIf***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

ExportDataKey

ehsm-core enclave will decrypt user-supplied ciphertextblob with specified CMK to get the plaintext of DataKey, then use the user-supplied Public key to encrypt this DataKey(aka ExportedDataKey). This ExportedDataKey (ciphertext) will be returned to caller.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=ExportDataKey

Request Payload:

Name	Type	Reference Value	Description
aad	String	"Y2hhbGxlbmdl"	Some extra datas input by the user, which could help to to ensure data integrity. The aad stored in BASE64 string.
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	The unique keyid of specified symmetric CMK.
olddatakey	String	"J/qC8IwEnhsjFjzIf***"	The ciphertext of the datakey wrapped by the cmk in BASE64 string.
ukeyid	String	"ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"	The unique keyid of the asymmetric CMK which used to export.
padding mode	String	EH_PAD_RSA_PKCS1	The padding mode users can use: EH_PAD_RSA_PKCS1 EH_PAD_RSA_PKCS1_OAEP EH_PAD_RSA_PKCS1_PSS NE Notes: Currently, the padding mode is used only for RSA encryption, decryption, and RSA signature verify. RSA encryption and decryption use EH_PAD_RSA_PKCS1_OAEP and EH_PAD_RSA_PKCS1. RSA signature and verify use EH_PAD_RSA_PKCS1_PSS and EH_PAD_RSA_PKCS1. EH_PAD_RSA_NONE Currently not supported.

Notes: for the common request parameters, please refer to the common params

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
newdatakey	String	"a4cN1k8QcXLhxm8dUoVHbXWB4P1v/kr***"	The ciphertext of the datakey wrapped by the ukey stores in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["aad"] = "Y2hhbGxlbmdl"
  payload["keyid"] = "aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"
  payload["olddatakey"] = "J/qC8IwEnhsjFjzIf***"
  payload["ukeyid"] = "ec1ccb09-4dd5-4af9-b04b-a97c4613cd7e"
  payload["padding_mode"] = "EH_PAD_RSA_PKCS1"

  params = OrderedDict()
  params["appid"] = appid
  params["payload"] = urllib.parse.unquote_plus(urllib.parse.urlencode(payload))
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  params["payload"] = payload
  params["sign"] = sign
  
  requests.post(url="<ehsm_srv_address>/ehsm?Action=ExportDataKey", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "newdatakey": "a4cN1k8QcXLhxm8dUoVHbXWB4P1v/kr***"
    }
  }

(return to the Cryptographic Functionalities APIs.)

GetParametersForImport

Queries the parameters that are used to import key material for a customer master key (CMK).

Usage notes

The returned parameters can be used to call the ImportKeyMaterial operation.
You can import key material only for CMKs whose Origin parameter is set to EXTERNAL.
The public key and token that are returned by the GetParametersForImport operation must be used together. The public key and token can be used to import key material only for the CMK that is specified when you call the operation.
The public key and token that are returned vary each time you call the GetParametersForImport operation.

You must specify the type of the public key and the encryption algorithm that are used to encrypt key material. The following table lists the types of public keys and the encryption algorithms allowed for each type.

Public key type	Encryption padding	Description
EH_RSA_2048 EH_RSA_3072 EH_RSA_4096	EH_RSA_PKCS1 EH_RSA_PKCS1_OAEP	CMKs of all regions and all protection levels are supported.
EH_SM2	EH_PAD_NONE EH_RSA_PKCS1

Parameters Data:

Name	Type	Reference Value	Description
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	The unique keyid of import CMK.
keyspec	String	EH_RSA_2048	The type of the public key that is used to encrypt key material.

Return Data:

Name	Type	Reference Value	Description
ImportToken	String	Base64String	The token that is used to import key material. The token is valid for 24 hours. The value of this parameter is required when you call the ImportKeyMaterial operation.
pubkey	String		The public key that is used to encrypt key material. The public key is Base64-encoded.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = keyid
  payload["keyspec"] = keyspec
  params = _utils_.init_params(payload)

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  requests.post(url="<ehsm_srv_address>/ehsm?Action=GetParametersForImport", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "pubkey": "-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEApWpfw/aooQ725uIE92wjZOihyKClYojsScnmSOdAVeQSZqt/C95W\n3eGJoXMvMJ9Jguhc0QisVYIcyi3urw8d1sWwCEvI3jceQzprR6seDBLquqm5vNJu\nenxnnjeEHdLhaWcBpp4nl0a14KZ0XYSqNuEjjQW9R66+dw+XqP46uPiXFnJPcMB2\nr4qA5oVZIGDMzDWcQ4p9NNnAvTeyqywOH9ux1uMomT3FqicnfFPGvCCwIStLLQWF\npRRttq9rXJxC2SZAA1YR19xjzasUpHYD+dD3mGGa51BcJuNaYFphGk4SHpBUcWnj\nlKNDwG7OmXrJus9zPpZM1nmaIfDsdN+2sQIDAQAB\n-----END RSA PUBLIC KEY-----\n"
    }
  }

(return to the Cryptographic Functionalities APIs.)

ImportKeyMaterial

Call the ImportKeyMaterial operation to import the key material.

Call CreateKey when creating a CMK, you can select its key material source as external. Origin set to EXTERNAL. This API is used to import the key material into the CMK.

Request Payload:

Name	Type	Reference Value	Description
keyid	String	"aac3e45a-d3dc-4791-89b6-4ada0e38e6ef"	The unique keyid of import CMK.
ImportToken	String	Base64String	The token that is used to import key material. The token is valid for 24 hours. The value of this parameter is required when you call the ImportKeyMaterial operation.
key_material	String	-----BEGIN PUBLIC KEY----- MIIBigKCAYEA1Kk+8GOwtm161+Mdk3woyaCl1NoxaSfPQlFg0NCN5rArDC1vgTWY 3LPu5OR8pJ1i/uc9sAYbCOEQ20/J/ulZjTBaWpLkXhpZ+X0NQCAcoShdG2v2F/w7 igGyOoOIA5HiR/Sa8Ee4sdOqLDDr6wG4GDeQplGGwVOhhTxxyGA5vauxS8KxTZlE 2SU6BRB0KYTe7aJR8GW7pcR0D8IZ3EWHimlJqlbdIziVW0oRjgVg49jzJ0n4IqEQ n0bs+5360hus9AYcSteJOiomTW3c1yUWFSItQt15s+336R384F4VmLN+P4mvIZ1U 5cG13kzZpGEUPBWEAOOAUxwUyRLZAEN/rA255tpAg4AERalriteNxHpZxemxrDPh kuZ6jK5sUGfervkKBYK8HJXmsmqsTyctemzZbCnOxYSjOJ+oQ9RVQVr/+vtylvid HXOr7Q4rihFeEFQhbX0R4xBlWGOgbeW9l3kfVa5BmE4Ff9ZFtt9MrrtXOBUMEma5 w0xCDVaiSMjPAgMBAAE= -----END PUBLIC KEY-----	The encrypted symmetric key.
padding_mode	String	EH_PAD_RSA_PKCS1	The padding mode that is used to encrypt key material.
KeyMaterialExpireUnix	String	0	The time when the key material expires. If this parameter is not specified or set this parameter to 0, the key material does not expire.

Response Data:

Name Type Reference Value Description

code int 200 The result of the method call, 200 is success, others are fail.

message String "success" The description of result.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = keyid
  payload["key_material"] = key_material
  payload["padding_mode"] = padding_mode
  params = _utils_.init_params(payload)

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  requests.post(url="<ehsm_srv_address>/ehsm?Action=ImportKeyMaterial", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!"
  }

(return to the Cryptographic Functionalities APIs.)

GetPublicKey

Get public key from asymmetric keypair.

Request Payload:

Name Type Reference Value Description

keyid String "aac3e45a-d3dc-4791-89b6-4ada0e38e6ef" The unique keyid of import CMK.

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
pubkey	String	-----BEGIN PUBLIC KEY----- MIIBigKCAYEA1Kk+8GOwtm161+Mdk3woyaCl1NoxaSfPQlFg0NCN5rArDC1vgTWY 3LPu5OR8pJ1i/uc9sAYbCOEQ20/J/ulZjTBaWpLkXhpZ+X0NQCAcoShdG2v2F/w7 igGyOoOIA5HiR/Sa8Ee4sdOqLDDr6wG4GDeQplGGwVOhhTxxyGA5vauxS8KxTZlE 2SU6BRB0KYTe7aJR8GW7pcR0D8IZ3EWHimlJqlbdIziVW0oRjgVg49jzJ0n4IqEQ n0bs+5360hus9AYcSteJOiomTW3c1yUWFSItQt15s+336R384F4VmLN+P4mvIZ1U 5cG13kzZpGEUPBWEAOOAUxwUyRLZAEN/rA255tpAg4AERalriteNxHpZxemxrDPh kuZ6jK5sUGfervkKBYK8HJXmsmqsTyctemzZbCnOxYSjOJ+oQ9RVQVr/+vtylvid HXOr7Q4rihFeEFQhbX0R4xBlWGOgbeW9l3kfVa5BmE4Ff9ZFtt9MrrtXOBUMEma5 w0xCDVaiSMjPAgMBAAE= -----END PUBLIC KEY-----	The public key that is used to encrypt key material. The public key is Base64-encoded.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = keyid
  params = _utils_.init_params(payload)

  sign_string = urllib.parse.unquote_plus(urllib.parse.urlencode(params))
  sign = str(base64.b64encode(hmac.new(appkey.encode('utf-8'), sign_string.encode('utf-8'), digestmod=sha256).digest()),'utf-8').upper()

  requests.post(url="<ehsm_srv_address>/ehsm?Action=GetPublicKey", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
        "pubkey": "-----BEGIN RSA PUBLIC KEY-----\nMIIBCgKCAQEApWpfw/aooQ725uIE92wjZOihyKClYojsScnmSOdAVeQSZqt/C95W\n3eGJoXMvMJ9Jguhc0QisVYIcyi3urw8d1sWwCEvI3jceQzprR6seDBLquqm5vNJu\nenxnnjeEHdLhaWcBpp4nl0a14KZ0XYSqNuEjjQW9R66+dw+XqP46uPiXFnJPcMB2\nr4qA5oVZIGDMzDWcQ4p9NNnAvTeyqywOH9ux1uMomT3FqicnfFPGvCCwIStLLQWF\npRRttq9rXJxC2SZAA1YR19xjzasUpHYD+dD3mGGa51BcJuNaYFphGk4SHpBUcWnj\nlKNDwG7OmXrJus9zPpZM1nmaIfDsdN+2sQIDAQAB\n-----END RSA PUBLIC KEY-----\n"
    }
  }

(return to the Cryptographic Functionalities APIs.)

GetVersion

Query the KMS server version.

Rest API format:

GET <ehsm_srv_address>/ehsm?Action=GetVersion

Response Data:

Name	Type	Reference Value	Description
code	int	200	The result of the method call, 200 is success, others are fail.
message	String	"success"	The description of result.
version	String	"0.2.0"	The version of eHSM-KMS server.
git_sha	String	"c14b8b8"	THe git_sha of the currently running code

Example

Request sample in Shell

  $ curl <ehsm_srv_address>/ehsm?Action=GetVersion

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
       "version": "0.2.0",
       "git_sha": "c14b8b8"
    }
  }

Name	Type	Reference Value	Description
quote	String	"AwACAAAAAAAHAAwAk5pB∗∗∗"	A valid DCAP quote in BASE64 string.
nonce	String	"bm9uY2U="	A nonce in random string (<64B).
policyId	String	"326f2049-56ab-474f-a1c0-516de230****"	quote policy ID.

Name	Type	Reference Value	Description
mr_enclave	String	"870c42c59bc74c7ad22869411709e4f78ac3c76add6693bb43296b03362e5038"	stores the hash value of the enclave measurement.
mr_signer	String	"c30446b4be9baf0f69728423ea613ef81a63e72acf7439fa0549001fd5482835"	stores the hash value of the enclave author’s public key.

Name	Type	Required	Reference Value	Description
secretName	String	Yes	"secretName01"	The name of the secret.
secretData	String	Yes	"secretData01"	The value of the secret.
encryptionKeyId	String	Optional	"0197ad2d-c4be-4948-996d-513c6f1e∗∗∗"	The ID of the CMK that is used to encrypt the secret value.
description	String	Optional	"desc01"	The description of the secret.
rotationInterval	String	Optional	"30d"	The interval for automatic rotation. format: integer[unit], unit can be d (day), h (hour), m (minute), or s (second) defalut='30d'

Files

API_Reference.md

Latest commit

History

API_Reference.md

File metadata and controls

eHSM REST API Reference

Common Prameters

Createkey

Encrypt

Decrypt

AsymmetricEncrypt

AsymmetricDecrypt

Sign

Verify

Generatedatakey

Generatedatakeywithoutplaintext

ExportDataKey

GetParametersForImport

ImportKeyMaterial

GetPublicKey

GetVersion

Enroll

ListKey

DeleteKey

DeleteALLKey

EnableKey

DisableKey

GenerateQuote

VerifyQuote

UploadQuotePolicy

GetQuotePolicy

CreateSecret

UpdateSecretDesc

PutSecretValue

ListSecretVersionIds

ListSecrets

DescribeSecret

DeleteSecret

GetSecretValue

RestoreSecret