Retrieving a list of Key Protect keys

IBM® Key Protect for IBM Cloud® provides a centralized system to view, manage, and audit your encryption keys. Audit your keys and access restrictions to keys to ensure the security of your resources.

While you can assign fine-grained access to a single key, note that calling the list keys API does not return keys that you have assigned individual access to (that only you can access, in other words). Calling this API will however return the keys in key rings you have access to (if you have access to all of the keys in an instance, you will see all keys). You can, however, see the keys that only you have access to by following the instructions in Viewing fine-grain access keys through IAM to view the key through IAM or by using the API to pass the specific key ID.

It is a good practice to audit your key configuration regularly:

Examine when keys were created and determine whether it's time to rotate the key.
Monitor API calls to Key Protect with Activity Tracker.
Inspect which users have access to keys and if the level of access is appropriate.

For more information about auditing access to your resources, see Managing user access.

Viewing keys in the console

If you prefer to inspect the keys in your service by using a graphical interface, you can use the Key Protect dashboard.

After you create or import your existing keys into the service, complete the following steps to view your keys.

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
Click on Keys, which shows a list of all keys in your service instance. Keys can be filtered by their Key states (for example, to show only keys in the Enabled state) or by their Key ring ID using the drop-down lists. Additionally, the individual values (such as Last rotated date), can be sorted. The search bar can be used to search keys by their display name, key ID, and alias. Note that the quickest way to find a key is to search by its key ID. The fields found in the table can be customized using the Settings button. By default you can see:

Describes the Keys table.
Column	Description
Name	The display name you gave to your key.
Key ID	A unique key ID that was assigned to your key by the Key Protect service. You can use the ID value to make calls to the service with the Key Protect API.
Key ring ID	The key ring the keys are associated with. These states include Deactivated, Destroyed, Disabled, and Enabled.
Last rotated	The date the last time the key was rotated.
Key alias	The key alias (or aliases) of the key.
Type	The key type of the key (either a Root key or a Standard key).
State	The key state of the key, one of Deactivated, Destroyed, Disabled, or Enabled.

Other available fields in the table include:

Last modified: indicating the last time the key was changed in any way.
Created: the date the key was created.
Deleted: showing whether a key is in a deleted state (awaiting purge) or not.
Imported: indicating whether the key was created using key material supplied by the user.
Rotation policy: showing whether this key has a rotation policy attached to it.
Associated resources: shows whether the key is protecting any resources.

The search capability is limited to a volume of 5,000 keys. If you have more than 5,000 keys, and you cannot filter the number of keys that will be searched to less than 5,000 (for example, by filtering by key state to only look for Enabled keys), your search will fail unless it exactly matches a key ID or alias. For more information about the API spec for key search, check out GET /keys.

If you want to narrow the number of results returned by a search, try using one or a combination of the following parameters:

not: when specified, inverts the logic the search uses (for example, not:foo will search for keys that have aliases or names that do not contain foo).
escape: everything after this option is take as plaintext (example: escape:not: will search for keys that have an alias or name containing the substring not:).
exact: only looks for exact matches.
alias: only looks for key aliases.
name: only looks for key names.

Note that not:exact:foobar will look for keys where key name or alias is not exactly foobar, while exact:not:foobar will look for keys where key name or alias is exactly not:foobar

Search scopes behave in an OR manner. This means when using more than one search scope, a match in at least one of the scopes will result in the key being returned. By default (if no scopes are provided), the search is performed in both name and alias scopes.

Not seeing the full list of keys that are stored in your Key Protect instance? Verify with your administrator that you are assigned the correct role for the applicable Key Protect instance or individual key. For more information about roles, see Roles and permissions.

Retrieving keys by state

By filtering on the state of specific keys in your Key Protect instance, you can retrieve keys that are in the states that you specify.

For example, you might have keys in your Key Protect instance that are in the active, suspended, and destroyed states, but you only want to retrieve keys in the active state when you look through a list of keys.

For more information on key states, see Key states and transitions.

After you create or import your existing keys into the service, you have two options to view your keys. The first option, View keys through the resource list, works for all keys except those you have assigned fine-grained access to. For information about how to view keys with fine-grain access, check out Viewing fine-grain access keys IAM.

Viewing keys through the resource list

Log in to the IBM Cloud console.
Go to Menu > Resource List to view a list of your resources.
From your IBM Cloud resource list, select your provisioned instance of Key Protect.
On the application details page, click the filter icon and select the dropdown from the Status menu.
Select the key state of the keys that you would like to retrieve.
Click the Apply button.
Further, in the table row headings, you can click on Last Updated to sort the list by the date that the keys in the table were updated most recently, or click on Type to list all of the root keys and standard keys as groups.

Viewing fine-grain access keys through IAM

From the menu bar, click Manage > Access (IAM), and select Users to browse the existing users in your account.
Select a table row, and click the ⋯ icon to open a list of options for that user. Then select Manage Access from the drop down list.
Here you can see all of the IAM information for this user, including the Access groups they belong to. To specifically see the access policies for this user, click the Access policies tab.

An account owner or user with the appropriate privileges can see all of the policies assigned to this user, including any fine-grained access over keys.

Viewing keys with the API

You can retrieve the contents of your keys by using the Key Protect API.

Retrieving a list of keys

For a high-level view, you can browse keys that are managed in your provisioned instance of Key Protect by making a GET call to the following endpoint.

https://<region>.kms.cloud.ibm.com/api/v2/keys

Retrieve your authentication credentials to work with keys in the service.
View general characteristics about your keys by running the following curl command.
```
$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>" \
    -H "x-kms-key-ring: <key_ring_ID>" \
    -H "correlation-id: <correlation_ID>"
```
Replace the variables in the example request according to the information in Table 1. For more information about optional parameters available when viewing collections of keys, including the ability to search your keys, see the API documentation regarding the List keys method.

Describes the variables that are needed to view keys with the Key Protect API.
Variable	Description
region	Required. The region abbreviation, such as `us-south` or `eu-gb`, that represents the geographic area where your Key Protect instance resides. For more information, see Regional service endpoints.
keyID_or_alias	Required. The unique identifier or alias for the key that you want to inspect.
IAM_token	Required. Your IBM Cloud access token. Include the full contents of the IAM token, including the Bearer value, in the curl request. For more information, see Retrieving an access token.
instance_ID	Required. The unique identifier that is assigned to your Key Protect service instance. For more information, see Retrieving an instance ID.
key_ring_ID	Optional. The unique identifier of the target key ring. If unspecified, the response will include all resources that the user has access to in the specified instance. If provided, the response will only include resources that the user has access to in the specified key ring. For more information, see Grouping keys.
correlation_ID	Optional.The unique identifier that is used to track and correlate transactions.

A successful GET api/v2/keys request returns a collection of keys that are available in your Key Protect service instance.

{
    "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 2
    },
    "resources": [
        {
            "id": "02fd6835-6001-4482-a892-13bd2085f75d",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Root-key",
            "state": 1,
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
            "createdBy": "...",
            "creationDate": "2020-03-11T16:30:06Z",
            "lastUpdateDate": "2020-03-11T16:30:06Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": false,
            "imported": true,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        },
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Standard-key",
            "state": 1,
            "expirationDate": "2020-03-14T03:50:12Z",
            "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "createdBy": "...",
            "creationDate": "2020-03-12T03:50:12Z",
            "lastUpdateDate": "2020-03-12T03:50:12Z",
            "algorithmMetadata": {
                "bitLength": "256",
                "mode": "Deprecated"
            },
            "extractable": true,
            "imported": false,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        }
    ]
}

By default, GET api/v2/keys returns your first 200 keys, but you can adjust this limit by using the limit parameter at query time. To learn more about limit and offset, see Retrieving a subset of keys.

Not seeing the full list of keys? You might need to use limit and offset or check with your administrator to ensure you're assigned the correct level access to keys in your instance. To learn more, see Unable to view or list keys.

Retrieving a subset of keys

By specifying the limit and offset parameters at query time, you can retrieve a subset of your keys, starting with the offset value that you specify.

For example, you might have 3000 total keys that are stored in your Key Protect instance, but you want to retrieve keys 200 - 300 when you make a GET /keys request.

You can use the following example request to retrieve a different set of keys.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?offset=<offset>&limit=<limit>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Replace the limit and offset variables in your request according to the following table.

Table 2. Describes usage of the limit and offset variables.
Variable	Description
offset	The number of keys to skip. For example, if you have 50 keys in your instance, and you want to list keys 26 - 50, use `../keys?offset=25`. You can also pair offset with limit to page through your available resources.
limit	The number of keys to retrieve. For example, if you have 100 keys in your instance, and you want to list only 10 keys, use `../keys?limit=10`. The maximum value for limit is 5000.

Offset is the location of a particular key in a data set. The offset value is zero-based, which means that the 10th encryption key in a data set is at offset 9.

Retrieving keys by state

By specifying the state parameter at query time, you can retrieve keys that are in the states that you specify.

The state query parameter takes in a list of integers from 0 to 5 delimited by commas with no whitespace or trailing commas. For more information on key states, see Key states and transitions.

You can use the following example request to retrieve a different set of keys.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?state=<state_integers>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Replace the state variable in your request according to the following table.

Describes the state variable.
Variable	Description
state	The states of the keys to be retrieved. States are integers, where Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. For example, if you want to only list keys in the active state in your Key Protect instance, use `../keys?state=1`. You can also pair states with offsets and limits to page through your available resources.

For usage notes, check out the following examples for setting your state query parameter.

Provides usage notes for the stage query parameter.
URL	Description
`.../keys`	Lists all of your available resources, up to the first 200 keys.
`.../keys?state=5`	Lists keys in the deleted state.
`.../keys?state=2,3`	Lists keys in the suspended and deactivated state.

Retrieving keys by Extractable value

By specifying the extractable parameter at query time, you can retrieve keys whose material can leave the service.

For example, you might have both standard and root keys in your Key Protect instance, but you only want to retrieve keys with extractable key material when you make a GET /keys request.

The extractable query parameter takes in a boolean.

You can use the following example request to retrieve a different set of keys.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?extractable=<extractable>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Replace the extractable variable in your request according to the following table.

Describes the extractable variable.
Variable	Description
extractable	The type of keys to be retrieved. Filters keys based on the extractable property. You can use this query parameter to search for keys whose material can leave the service. If set to true, standard keys will be retrieved. If set to false, root keys will be retrieved. If omitted, both root and standard keys will be retrieved. For example, if you want to only list keys with extractable material in your Key Protect instance, use `../keys?extractable=true`. You can also pair extractable with `offset`, `limit`, and `state` to page through your available resources.

For usage notes, check out the following examples for setting your extractable query parameter.

Provides usage notes for the extractable query parameter.
URL	Description
`../keys`	Lists all of your available resources, up to the first 200 keys.
`../keys?extractable=true`	Lists standard keys.
`../keys?extractable=false`	Lists root keys.

Sorting a list of keys

Using the sort parameter in the query string sorts the list of keys returned based on one or more key properties. To sort on a property in descending order, prefix the term with "-". To sort on multiple key properties, use a comma to separate each properties. The first property in the comma-separated list will be evaluated before the next.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?sort=<sort-value>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Usage notes for the sort query parameter.
Variable	Description
sort-value	The list of properties for sorting. The key properties that can be sorted at this time are: id state extractable imported creationDate lastUpdateDate lastRotateDate deletionDate expirationDate