Derive a key

This key management operation allows to derive a new key and save it inside the device's secure repository.

Allowed users

User

Allowed

Master

ExtAuth

Required access scope

Main

keymgmt:ecdh

Alternative

Derive a new key

POST https://my.ence.do/api/keymgmt/derive

Derive (create) a new key using ECDH with a source key and save it.

Headers

Name	Type	Description
Authorization*	String	Bearer JWT_TOKEN
Content-Type*	String	application/json

Request Body

Name	Type	Description
descr	String	Base64 encoded additional description
ext_kid	String	External Key ID, 32 chars hex string
kid*	String	Key ID, 32 chars hex string
label*	String	Label of a key
mode	String	Key operation mode (for NIST ECC only)
pubkey	String	Base64 encoded external public key
type*	String	Type of key to create

Response status code

200: Operation successful

{
  "kid":"bd0958e1499ecfd51ea62a3f49a84cad"
}

400: Incorrect argument(s)

401: Missing or invalid JWT_TOKEN

403: Incorrect access scope

406: Operation failed

409: Incorrect internal state

418: TLS connection required

The key type pointed to ext_kid or represented by pubkey MUST be the same as the kid key type. Otherwise, indirect ECDH will fail.

To generate ECC keys (NISP & SECP only), the generated seed needs to be validated to ensure it is in the correct range. As a result, this endpoint can fail without being an error.

Response data for successful operation

Name	Type	Description
kid	String	Key ID, 32-character hex string

Possible key type

Please refer to the list here; note that ML-KEM and ML-DSA keys cannot be derived, only generated. These exceptions apply to the list.

Possible key mode (for NIST ECC keys only)

Check the list here.

Log entries

LOG_TYPE_FAILED_SCOPE_CHECK	LOG_RESULT_FAILED	403
LOG_TYPE_KEY_DERIVE	LOG_RESULT_ERROR	400
LOG_TYPE_KEY_DERIVE	LOG_RESULT_ERROR	406
LOG_TYPE_KEY_DERIVE	LOG_RESULT_OK	200