Skip to main content

Derive a key

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

Allowed usersUser✓Master✗ExtAuth✓
Required access scopekeymgmt:derivealternative:keymgmt:gen

Derive a new key​

POSThttps://my.ence.do/api/keymgmt/derive

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

Headers​

NameTypeDescription
Authorization*StringBearer JWT_TOKEN
Content-Type*Stringapplication/json

Request Body​

NameTypeDescription
descrStringBase64 encoded additional description
ext_kidStringExternal Key ID, 32 chars hex string
kid*StringKey ID, 32 chars hex string
label*StringLabel of a key
modeStringKey operation mode (for NIST ECC only)
pubkeyStringBase64 encoded external public key
type*StringType of key to create

Response status code​

{
"kid":"bd0958e1499ecfd51ea62a3f49a84cad"
}
info

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.

warning

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.

Possible type values​

ValueDescription
SECP256R1NIST P-256 ECC key
SECP384R1NIST P-384 ECC key
SECP521R1NIST P-521 ECC key
SECP256K1SEC2-v2 ECC key
CURVE25519CURVE25519 ECC ECDH only key
CURVE448CURVE4ECC ECDH only key
ED25519ED25519 ECC EdDSA only key
ED448ED448 ECC EdDSA only key
SHA2-256SHA2-256 HMAC symmetric key
SHA2-384SHA2-384 HMAC symmetric key
SHA2-512SHA2-512 HMAC symmetric key
SHA3-256SHA3-256 HMAC symmetric key
SHA3-384SHA3-384 HMAC symmetric key
SHA3-512SHA3-512 HMAC symmetric key
AES128AES 128 bits symmetric key
AES192AES 192 bits symmetric key
AES256AES 256 bits symmetric key

Possible mode values (NIST ECC keys only)​

ValueDescription
ECDHLimit usage to ECDH only.
ECDH,ExDSAAllow both ECDH and ECDH mode.
ExDSALimit usage to ExDSA only.

Response data for successful operation​

NameTypeDescription
kidStringKey ID, 32-character hex string

Possible type values​

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 mode values (NIST ECC keys only)​

Check the list here.

Log entries​

LOG_TYPE_FAILED_SCOPE_CHECKLOG_RESULT_FAILED403
LOG_TYPE_KEY_DERIVELOG_RESULT_ERROR400
LOG_TYPE_KEY_DERIVELOG_RESULT_ERROR406
LOG_TYPE_KEY_DERIVELOG_RESULT_OK200