Derive a key
This key management operation allows to derive a new key and save it inside the device's secure repository.
Derive a new key
https://my.ence.do/api/keymgmt/deriveDerive (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
- 400: Incorrect argument(s)
- 401: Missing or invalid JWT_TOKEN
- 403: Incorrect access scope
- 406: Operation failed
- 409: Incorrect internal state
- 411: Protocol error - Content-Length required
- 412: Protocol error - CORS validation failed
- 413: Protocol error - request body too big
- 418: TLS connection required
- 500: Internal server error
{
"kid":"bd0958e1499ecfd51ea62a3f49a84cad"
}
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
No response body.
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.
Possible type values
| Value | Description |
|---|---|
| SECP256R1 | NIST P-256 ECC key |
| SECP384R1 | NIST P-384 ECC key |
| SECP521R1 | NIST P-521 ECC key |
| SECP256K1 | SEC2-v2 ECC key |
| CURVE25519 | CURVE25519 ECC ECDH only key |
| CURVE448 | CURVE4ECC ECDH only key |
| ED25519 | ED25519 ECC EdDSA only key |
| ED448 | ED448 ECC EdDSA only key |
| SHA2-256 | SHA2-256 HMAC symmetric key |
| SHA2-384 | SHA2-384 HMAC symmetric key |
| SHA2-512 | SHA2-512 HMAC symmetric key |
| SHA3-256 | SHA3-256 HMAC symmetric key |
| SHA3-384 | SHA3-384 HMAC symmetric key |
| SHA3-512 | SHA3-512 HMAC symmetric key |
| AES128 | AES 128 bits symmetric key |
| AES192 | AES 192 bits symmetric key |
| AES256 | AES 256 bits symmetric key |
Possible mode values (NIST ECC keys only)
| Value | Description |
|---|---|
| ECDH | Limit usage to ECDH only. |
| ECDH,ExDSA | Allow both ECDH and ECDH mode. |
| ExDSA | Limit usage to ExDSA only. |
Response data for successful operation
| Name | Type | Description |
|---|---|---|
kid | String | Key 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_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 |