# **Enable key**

## **Goal**
The objective of this feature is to suspend and resume the use of a key.

It is achieved by introducing:
- the enable and disable commands.
- "isEnabled" status of a key.

Note: we use term "disabled" to indicate that the "isEnabled == FALSE"

### Example

When a key is disabled and we are trying to perform signing using the key, the following error is returned to the caller:

{
    "type": "PERMISSION_DENIED",
    "title": "Key is disabled",
    "details": "Key is disabled",
    "status": "FORBIDDEN",
    "message": "Key is disabled"
}

## Interworking with other features
- This feature doesn't apply to keys in the Root partition.

- Upon the generation of a key, the key is enabled.

- When upgrading from the release that didn't have isEnabled key attribute, this attribute is set to isEnabled=TRUE.

- The "isEnabled" and "Key-state" attributes are orthogonal to each other. Changing the one doesn't depend on the value of the other and doesn't affect it.

- A disabled key can not be used in any cryptographic operation including operations that use only the public part of the key, such as "verify" and "encrypt".

- It is impossible to derive a new key from a disabled key.

- Rekey:
-- It is possible to rekey a disabled key. The new key becomes enabled.

-- The same applies to the disabled key scheduled for automatic rotation.

- Backup/Restore:
-- The "isEnabled" status is saved during the backup and restored when the backup file is used during DB restore.

- Roles:
-- To change the isEnabled status of a key, the user's role must contain DY_ENABLE operation in the permission applicable to the key's group.
-- The DY_ENABLE operation is includedd in the default USER role.

- Audit Log:
-- The enable/disable events are reflected in the Audit Log as the DyEnable operation.

## **APIs**
### REST

**Enable Request:**

POST /api/v1/keys/{keyId}/enable

**Response:**

{
    "id": "0x005d67beb52880667b",
    "uid": "0x005d67beb52880667b",
       .
       .
       .
    "isEnabled": true,
       .
       .
       .
    "activationDate": "2020-02-24T12:35:57Z"
}

**Disable Request:**

POST /api/v1/keys/{keyId}/disable

**Response:**

{
    "id": "0x005d67beb52880667b",
    "uid": "0x005d67beb52880667b",
       .
       .
       .
    "isEnabled": false,
       .
       .
       .
    "activationDate": "2020-02-24T12:35:57Z"
}

**Get keys Request:**
The /keys/ API allows to specify the query parameter isEnabled=<true|false>
It filters the list of the keys according to the required isEnabled status.

Example:

GET /api/v1/keys?limit=10&skip=0&isEnabled=true

**Response:**

{
"totalItems": 2,
    "limit": 10,
    "skip": 0,
    "items": [
        {
            "id": "rest",
            "uid": "0x00bd2667bc8432e382",
                .
                .
                .
            "isEnabled": true,
                .
                .
                .
        },
        {
            "id": "rest1",
            "uid": "0x00f2aac592ff47c4a0",
                .
                .
                .
            "isEnabled": true,
                .
                .
                .
        }
    ]
}

## **UCL**
The UCL supports enable/disable command

**Enable command:**

ucl enable -u bd2667bc8432e382 -p part1

Output:

The key is successfully enabled

**Disable command:**

ucl disable -u bd2667bc8432e382 -p part1

Output:

The key is successfully disabled

**Show command:**
It's possible to see the isEnabled attribute using ucl show command:

ucl show -u bd2667bc8432e382 -p part1

Output:

--------------
Private RSA key: UID=bd2667bc8432e382
    .
    .
    .
isEnabled = false
    .
    .
    .