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.
Remote Attestation APIs Notes: These below Rest APIs are used to do the remote attestation.
- GenerateQuote
- VerifyQuote

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
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>&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_256 EH_RSA_3072 EH_RSA_4096 EH_EC_P256 EH_EC_P512 EH_EC_SM2 EH_SM4 Notes: currently on support the keyspec(EH_AES_GCM_128 and EH_RSA_3072), for others will support later.
origin	String	EH_INTERNAL_KEY	The source about the cmk comes from, it can be: EH_INTERNAL_KEY (generated from the eHSM inside) EXTERNAL_KEY (generated by the customer and want to import into the eHSM) Notes: currently it only support the type of EH_INTERNAL_KEY.

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.
cmk	String	"AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwAA***"	The result in json object for the cmk which in based64 encoding.

Example

Request sample in python

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

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

  sign_string = urllib.parse.unquote(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": {
          "cmk":"AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"
      }
  }

(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.
cmk	String	"AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"	A symmetric cmk in BASE64 string.
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["cmk"] = "AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"
  payload["plaintext"] = "cGxhaW50ZXh0"

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

  sign_string = urllib.parse.unquote(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.
cmk	String	"AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"	A symmetric cmk in BASE64 string.
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["cmk"] = "AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"
  payload["ciphertext"] = "uSDos6NLWNVp4sQZS2+mzLvDw***"

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

  sign_string = urllib.parse.unquote(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
cmk	String	"AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"	An asymmetric cmk in BASE64 string.
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	"EhGpx8pMYFRDr28xT4dJvrMg5***"	The data of the ciphertext stores in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["cmk"] = "AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"
  payload["plaintext"] = "cGxhaW50ZXh0"

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

  sign_string = urllib.parse.unquote(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
cmk	String	"AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"	An asymmetric cmk in BASE64 string.
ciphertext	String	"EhGpx8pMYFRDr28xT4dJvrMg5***"	The data of the ciphertext 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	"VGVzdFJTQS0zMDcyAAAAAAAAAAAAAA***"	Plaint data after decrypt and stored in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["cmk"] = "AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"
  payload["ciphertext"] = "EhGpx8pMYFRDr28xT4dJvrMg5***"

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

  sign_string = urllib.parse.unquote(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
cmk	String	"AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"	An asymmetric cmk in BASE64 string.
digest	String	"ZGlnZXN0"	The hash of datas want to be signed, and stored 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.
signature	String	"KkUO2y2IJVdsahlUL4GA0fYf4y9wPaaocdEtfG3***"	The calculated signature value stores in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["cmk"] = "AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"
  payload["digest"] = "ZGlnZXN0"

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

  sign_string = urllib.parse.unquote(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
cmk	String	"AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"	An asymmetric cmk in BASE64 string.
digest	String	"ZGlnZXN0"	The hash of datas want to be signed, and stored in BASE64 string.
signature	String	"KkUO2y2IJVdsahlUL4GA0fYf4y9wPaaocdEtfG3***"	The signature of the digest signed by the cmk 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.
result	bool	true	True or False: indicate whether the signature passed the verification.

Example

Request sample in python

  payload = OrderedDict()
  payload["cmk"] = "AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"
  payload["digest"] = "ZGlnZXN0"
  payload["signature"] = "KkUO2y2IJVdsahlUL4GA0fYf4y9wPaaocdEtfG3***"

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

  sign_string = urllib.parse.unquote(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.
cmk	String	"AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"	A specified symmetric CMK in BASE64 string.
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["cmk"] = "AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"
  payload["keylen"] = 16

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

  sign_string = urllib.parse.unquote(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.
cmk	String	"AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"	A specified symmetric CMK in BASE64 string.
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["cmk"] = "AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"
  payload["keylen"] = 16

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

  sign_string = urllib.parse.unquote(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.
cmk	String	"AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwAA***"	A specified symmetric CMK in BASE64 string.
olddatakey	String	"J/qC8IwEnhsjFjzIf***"	The ciphertext of the datakey wrapped by the cmk in BASE64 string.
ukey	String	"AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"	An asymmetric use specified key 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.
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["cmk"] = "AAAAAAAAAAAAAAAAAAAAAGCcKdP/fwA***"
  payload["olddatakey"] = "J/qC8IwEnhsjFjzIf***"
  payload["ukey"] = "AwAAAAAAAAAAJ9EXav7ngTocodwxFwPz/xWGh***"

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

  sign_string = urllib.parse.unquote(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.)

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"
    }
  }

(return to the Key Management APIs.)

ListKey

Query all the CMKs generated by the current account.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=ListKey

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.
list	JsonArray	[ { "keyid": "2de54366-30f9-6829-8391-c4eba∗∗∗", "creationDate": 1645152619225, "expireTime": 1676688619225, "alias": "alias_name", "keyspec": "EH_RSA_3072", "keyState": 1 } ]	The information of each CMK is a JsonObject. keyid: ID of CMK creationDate: Creation date of CMK expireTime: Expire time of CMK alias: Alias of CMK keyspec: keyspec of CMK keyState: State of CMK, 1 (Enable) \| 0 (Disable).

Example

Request sample in python

  params = OrderedDict()
  params["appid"] = appid
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote(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["sign"] = sign
  
  requests.post(url="<ehsm_srv_address>/ehsm?Action=ListKey", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
       "list": [
           {
              "keyid": "2de54366-30f9-6829-8391-c4eba***", 
              "creationDate": 1645152619225, 
              "expireTime": 1676688619225, 
              "alias": "alias_name", 
              "keyspec": "EH_RSA_3072", 
              "keyState": 1
           }
       ]
    }
  }

(return to the Key Management APIs.)

DeleteKey

Delete a specific CMK generated by the current account.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=DeleteKey
Request Payload:

Name Type Reference Value Description

keyid String "2de54366-30f9-6829-8391-c4eba∗∗∗" ID of the CMK you want to delete

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.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = "2de54366-30f9-6829-8391-c4eba***"

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

  sign_string = urllib.parse.unquote(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=DeleteKey", data=json.dumps(params), headers=headers)

Response data

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

(return to the Key Management APIs.)

DeleteALLKey

Delete all the CMKs generated by the current account.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=DeleteALLKey
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

  params = OrderedDict()
  params["appid"] = appid
  params["timestamp"] = str(int(time.time() * 1000))

  sign_string = urllib.parse.unquote(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["sign"] = sign
  
  requests.post(url="<ehsm_srv_address>/ehsm?Action=DeleteALLKey", data=json.dumps(params), headers=headers)

Response data

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

(return to the Key Management APIs.)

EnableKey

Enable a CMK for the current account.
Only when the CMK is enabled, it could be used to perform cryptographic operations.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=EnableKey
Request Payload:

Name Type Reference Value Description

keyid String "2de54366-30f9-6829-8391-c4eba∗∗∗" ID of the CMK you want to enable

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.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = "2de54366-30f9-6829-8391-c4eba***"

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

  sign_string = urllib.parse.unquote(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=EnableKey", data=json.dumps(params), headers=headers)

Response data

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

(return to the Key Management APIs.)

DisableKey

Disables a specified CMK.
If a CMK is disabled, it can't be used until you re-enable it by the EnableKey API.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=DisableKey
Request Payload:

Name Type Reference Value Description

keyid String "2de54366-30f9-6829-8391-c4eba∗∗∗" ID of the CMK you want to disable

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.

Example

Request sample in python

  payload = OrderedDict()
  payload["keyid"] = "2de54366-30f9-6829-8391-c4eba***"

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

  sign_string = urllib.parse.unquote(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=DisableKey", data=json.dumps(params), headers=headers)

Response data

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

(return to the Key Management APIs.)

GenerateQuote

Generate a quote of the eHSM-KMS core enclave for user used to do the SGX DCAP Remote Attestation. User may send it to a remote reliable third party or directly send it to eHSM-KMS via VerifyQuote API to do the quote verification.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=GenerateQuote
Request Payload:

Name Type Reference Value Description

challenge String "Y2hhbGxlbmdl"

A challenge 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.
quote	String	"AwACAAAAAAAHAAwAk5pB∗∗∗"	A quote for the eHSM-KMS core enclave format in BASE64 string.

Example

Request sample in python

  payload = OrderedDict()
  payload["challenge"] = "Y2hhbGxlbmdl"

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

  sign_string = urllib.parse.unquote(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=DisableKey", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
       "quote": "AwACAAAAAAAHAAwAk5pB***"
    }
  }

(return to the Key Management APIs.)

VerifyQuote

Users are expected already got a valid DCAP format QUOTE. And it could use this API to send it to eHSM-KMS to do a quote verification.

Rest API format:

POST <ehsm_srv_address>/ehsm?Action=VerifyQuote
Request Payload:

Name Type Reference Value Description

quote String "AwACAAAAAAAHAAwAk5pB∗∗∗" A valid DCAP quote in BASE64 string.

nonce String "bm9uY2U=" A nonce 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.
result	bool	"true or false"	The result of quote verification
nonce	String	"bm9uY2U="	The nonce in BASE64 string.
sign	String	"T4DRCEZAPLBbb+d3ObD∗∗∗"	The HAMC sign of result and nonce calculated by the API Key.

Example

Request sample in python

  payload = OrderedDict()
  payload["nonce"] = "bm9uY2U="

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

  sign_string = urllib.parse.unquote(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=DisableKey", data=json.dumps(params), headers=headers)

Response data

  Response= {
    "code": 200,
    "message": "success!",
    "result": {
       "result": true,
       "nonce": "bm9uY2U=",
       "sign": "T4DRCEZAPLBbb+d3ObD***"
    }
  }

(return to the Key Management APIs.)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API_Reference.md

API_Reference.md

eHSM REST API Reference

Common Prameters

Createkey

Encrypt

Decrypt

AsymmetricEncrypt

AsymmetricDecrypt

Sign

Verify

Generatedatakey

Generatedatakeywithoutplaintext

ExportDataKey

GetVersion

ListKey

DeleteKey

DeleteALLKey

EnableKey

DisableKey

GenerateQuote

VerifyQuote

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

GetVersion

ListKey

DeleteKey

DeleteALLKey

EnableKey

DisableKey

GenerateQuote

VerifyQuote