IBM Cloud Activity Tracker events

As a security officer, auditor, or manager, you can use the IBM Cloud® Activity Tracker service to track how users and applications interact with IBM® Key Protect for IBM Cloud®.

IBM Cloud Activity Tracker records service and user initiated activities that change the state of a service in IBM Cloud. You can use this service to investigate abnormal activity and critical actions and to comply with regulatory audit requirements. In addition, you can be alerted about actions as they happen. The events that are collected comply with the Cloud Auditing Data Federation (CADF) standard.

For more information regarding the IBM Cloud Activity Tracker service, see the getting started tutorial for IBM Cloud Activity Tracker.

To determine which Key Protect API requests correlate to the actions below, see Key Protect API reference doc.

Historical information regarding events

Table 1. Historical reference mapping of event names
Reference	Current event names
`kms.governance.configread`	`kms.governance-config.read`
`kms.importtoken.create`	`kms.import-token.create`
`kms.importtoken.read`	`kms.import-token.read`
`kms.importtoken.default`	`kms.import-token.request`
`kms.instance.readallowedipport`	`kms.instance-allowed-ip-port.read`
`kms.instance.readipwhitelistport`	`kms.instance-ip-allowlist-port.read`
`kms.instancepolicies.write`	`kms.instance-policies.write`
`kms.instancepolicies.read`	`kms.instance-policies.read`
`kms.instancepolicies.default`	`kms.instance-policies.request`
`kms.keyrings.create`	`kms.key-rings.create`
`kms.keyrings.delete`	`kms.key-rings.delete`
`kms.keyrings.list`	`kms.key-rings.list`
`kms.keyrings.default`	`kms.key-rings.request`
`kms.secrets.defaultalias`	`kms.secrets-alias.request`
`kms.secrets.createalias`	`kms.secrets-alias.create`
`kms.secrets.deletealias`	`kms.secrets-alias.delete`
`kms.secrets.eventack`	`kms.secrets-event.ack`
`kms.secrets.listkeyversions`	`kms.secrets-key-versions.list`
`kms.secrets.readmetadata`	`kms.secrets-metadata.read`

Key events

The following table lists the key actions that generate an event:

Table 2. Lifecycle Key Actions
Action	Description
`kms.secrets.create`	Create a key
`kms.secrets-alias.create`	Create a key alias
`kms.secrets.default`	Invalid key request event
`kms.secrets.delete`	Delete a key
`kms.secrets-alias.delete`	Delete a key alias
`kms.secrets.disable`	Disable operations for a key
`kms.secrets.enable`	Enable operations for a key
`kms.secrets-event.ack`	Acknowledge a lifecycle action on a key
`kms.secrets.expire`	Expire a key
`kms.secrets.head`	Retrieve key total
`kms.secrets.list`	List keys
`kms.secrets-key-versions.list`	List all the versions of a key
`kms.secrets.wrap`	Wrap a key
`kms.secrets.patch`	Patch a key
`kms.secrets.purge`	Purge a key
`kms.secrets.read`	Retrieve all key information
`kms.secrets-metadata.read`	Retrieve key metadata (excluding key payload, if applicable)
`kms.secrets.restore`	Restore a key
`kms.secrets.rewrap`	Rewrap a key
`kms.secrets.rotate`	Rotate a key
`kms.secrets.setkeyfordeletion`	Authorize deletion for a key with Dual Authorization policy
`kms.secrets.unsetkeyfordeletion`	Cancel deletion for a key with Dual Authorization policy
`kms.secrets.unwrap`	Unwrap a key

Key Ring events

The following table lists the key ring actions that generate an event:

Table 3. Key Ring actions
Action	Description
`kms.key-rings.create`	Create a key ring
`kms.key-rings.delete`	Delete a key ring
`kms.key-rings.list`	List key rings in an instance
`kms.key-rings.request`	Invalid key ring request

Policy events

The following table lists the policy actions that generate an event:

Table 4. Policy actions
Action	Description
`kms.policies.read`	List key policies
`kms.policies.write`	Set key policies
`kms.instance-policies.read`	List instance policies
`kms.instance-policies.write`	Set instance policies
`kms.policies.default`	Invalid policy request event
`kms.instance-policies.request`	Invalid policy request event

Import token events

The following table lists the import token actions that generate an event:

Table 5. Import token actions
Action	Description
`kms.import-token.create`	Create an import token
`kms.import-token.read`	Retrieve an import token
`kms.import-token.request`	Invalid import token request event

Registration events

The corresponding actions to both list registration for any key, or list registration for a specific key generate this event.

The following table lists the registration actions that generate an event:

Table 6. Registration actions
Action	Description
`kms.registrations.list`	List registrations for any key
`kms.registrations.default`	Invalid registration request event

Viewing events

Events that are generated by an instance of Key Protect are automatically forwarded to the IBM Cloud Activity Tracker instance that is available in the same location.

IBM Cloud Activity Tracker can have only one instance per location. To view events, you must access the web UI of the IBM Cloud Activity Tracker service in the same location where your Key Protect instance is available. For more information, see Launching the web UI through the IBM Cloud UI.

Table 7. IBM Cloud Activity Tracker regions
Deployment Region	IBM Cloud Activity Tracker Region
`au-syd`	`au-syd`
`br-sao`	`br-sao`
`ca-tor`	`ca-tor`
`eu-de`	`eu-de`
`eu-gb`	`eu-gb`
`jp-osa`	`jp-osa`
`jp-tok`	`jp-tok`
`us-east`	`us-east`
`us-south`	`us-south`

Analyzing successful events

Most successful requests have unique requestData and responseData associated with each related event. The following sections describe the data of each Key Protect service action event.

Fields are not guaranteed to appear unless the request is successful.

Common Fields

There are some common fields that Key Protect uses outside of the CADF event model to provide more insight into your data.

Table 8. Describes the common fields in IBM Cloud Activity Tracker events for Key Protect service actions.
Field	Description
requestData.requestURI	The URIA unique address that is used to identify content on the web. The most common form of URI is the web page address, which is a particular form or subset of URI called a Uniform Resource Locator (URL). A URI typically describes how to access the resource, the computer that contains the resource, and the location of the resource on that computer. of the API request that was made.
requestData.instanceID	The unique identifier of your Key Protect instance.
correlationId	The unique identifier of the API request that generated the event.

For more information on the event fields in the Cloud Auditing Data Federation (CADF) event model, see Event Fields

While initiator.host.address is a field that is part of the Cloud Auditing Data Federation model, the host address field will not be shown for requests made through private networks.

Conditional Common Fields

There are some conditional fields that Key Protect uses outside of the CADF event model to provide more insight into your data when you use the key ring feature. These fields will appear when using key rings in specific conditions.

Table 9. Describes conditional fields for use with key rings in IBM Cloud Activity Tracker events for Key Protect service actions.
Field	Description
requestData.keyRingId	The ID of the key ring if a key ring is specified in the header (`X-Kms-Key-Ring`) of the request.
responseData.keyRingId	The ID of the key ring if a key ring is specified in the request or in API methods where the key ID (or alias) is in the path of the request URIA unique address that is used to identify content on the web. The most common form of URI is the web page address, which is a particular form or subset of URI called a Uniform Resource Locator (URL). A URI typically describes how to access the resource, the computer that contains the resource, and the location of the resource on that computer..

Key action events

Due to the sensitivity of the information for an encryption key, when an event is generated as a result of an API call to the Key Protect service, the event that is generated does not include detailed information about the key, such as the payload and encrypted nonce.

The responseData.keyState field is an integer and corresponds to the Pre-activation = 0, Active = 1, Suspended = 2, Deactivated = 3, and Destroyed = 5 values. For more information on key states, see Key states and transitions.

Create Key

The following fields include extra information:

The requestData.keyType field includes the type of key that was created.
The responseData.keyId field includes the unique identifier associated with the key.
The responseData.keyVersionId field includes the unique identifier of the current key version used to wrap input ciphertext on wrap requests.
The responseData.keyVersionCreationDate field includes the date that the current version of the key was created.
The responseData.keyState field includes the integer that correlates to the state of the key.
The responseData.expirationDate includes the date that the key will expire on.

Delete Key

The following field includes extra information:

The responseData.keyState field includes the integer that correlates to the state of the key.

Expire Key

The following field includes extra information:

The requestData.keyType field includes the type of key that was created.
The responseData.keyId field includes the unique identifier associated with the key.
The requestData.expirationDate field includes the date that the key expired on.
The responseData.initialValue.keyState field includes the integer that correlates to the previous state of the key.
The responseData.newValue.keyState field includes the integer that correlates to the current state of the key.

Wrap or unwrap key

The following field includes extra information:

The responseData.keyVersionId field includes the unique identifier of the current key version used to wrap input ciphertext on wrap requests.
The responseData.expirationDate includes the date that the key will expire on.

Rewrap key

The following field includes extra information:

The responseData.keyVersionId field includes the unique identifier of the current key version used to wrap input ciphertext on wrap requests.
The responseData.rewrappedKeyVersionId field includes the unique identifier of the new key version used to wrap input ciphertext on wrap requests.

Restore key

The following field includes extra information:

The responseData.keyVersionId field includes the unique identifier of the current key version used to wrap input ciphertext on wrap requests.

Rotate key

Rotate key doesn't have any additional fields outside of those from the Common Fields section

Patch key

The following fields include extra information:

The requestData.initialValue.keyRingId field includes the ID of the key ring that the key previously was a part of.
The requestData.newValue.keyRingId field includes the ID of the key ring that the key is currently a part of.

Purge key

The following fields include extra information:

The responseData.deletionDate field represents the date the key was deleted.
The responseData.purgeAllowedFrom field represents the date from which the purge action was allowed.
The responseData.purgeEligibleOn field represents the date on which the key metadata is eligible to be permanently removed from the system by Key Protect.

Get key total

The following field includes extra information:

The responseData.totalResources field includes the total amount of keys within the Key Protect instance.

List keys

The following field includes extra information:

The responseData.totalResources field includes the total amount of keys returned in the response.

Get key or key metadata

The following fields include extra information:

The requestData.keyType field includes the type of key that was retrieved.
The responseData.keyState field includes the integer that correlates to the state of the key.
The responseData.keyVersionId field includes the unique identifier of the key version used to wrap input ciphertext on wrap requests.
The responseData.keyVersionCreationDate field includes the date that the current version of the key was created.
The responseData.expirationDate includes the date that the key will expire on.

List key versions

The following field includes extra information:

The responseData.totalResources field includes the total amount of key versions returned in the response.

Set or Unset key for deletion

The following fields include extra information:

The responseData.initialValue.authID field includes the initiator ID of the person who set the dual authorization policy.
The responseData.initialValue.authExpiration field includes the expiration date for the dual authorization policy.
The responseData.newValue.authID field includes the initiator ID of the person who set the dual authorization policy.
The responseData.newValue.authExpiration field includes the expiration date for the dual authorization policy.

initialValue is the initiatorID of the person who last set the dual authorization policy and newValue is the new initiatorID of the person who set the dual authorization policy.

Policy events

Set instance policies

Allowed Network Policies

The following fields include extra information:

The requestData.initialValue.policyAllowedNetworkEnabled field includes if your allowed network policy was previously enabled or disabled.
The requestData.initialValue.policyAllowedNetworkAttribute field includes if your allowed network policy was previously only for public networks or both public and private networks.
The requestData.newValue.policyAllowedNetworkEnabled field includes if your allowed network policy is currently enabled or disabled.
The requestData.newValue.policyAllowedNetworkAttribute field includes if your allowed network policy is currently only for public networks or both public and private networks.

Dual Auth Delete Policies

The following fields include extra information:

The requestData.initialValue.policyDualAuthDeleteEnabled field includes if your dual auth delete policy was previously enabled or disabled.
The requestData.newValue.policyDualAuthDeleteEnabled field includes if your dual auth delete policy is currently enabled or disabled.

Allowed IP Policies

The following fields include extra information:

The requestData.initialValue.policyAllowedIPAttribute field includes if your allowed IP policy was previously enabled or disabled.
The requestData.newValue.policyAllowedIPAttribute field includes if your allowed IP policy is currently enabled or disabled.

Key Creation and Importation Access Policies

The following fields include extra information:

The requestData.initialValue.PolicyKCIAEnabled field includes if your key creation and importation policy was previously enabled or disabled.
The requestData.newValue.PolicyKCIAEnabled field includes if your key creation and importation policy is currently enabled or disabled.
The requestData.initialValue.PolicyKCIAAttrCRK field includes if your key creation and importation policy previously allowed the creation of root keys.
The requestData.newValue.PolicyKCIAAttrCRK field includes if your key creation and importation policy allows the creation of root keys.
The requestData.initialValue.PolicyKCIAAttrCSK field includes if your key creation and importation policy previously allowed the creation of standard keys.
The requestData.newValue.PolicyKCIAAttrCSK field includes if your key creation and importation policy allows the creation of standard keys.
The requestData.initialValue.PolicyKCIAAttrIRK field includes if your key creation and importation policy previously allowed imported root keys.
The requestData.newValue.PolicyKCIAAttrIRK field includes if your key creation and importation policy allows imported root keys.
The requestData.initialValue.PolicyKCIAAttrISK field includes if your key creation and importation policy previously allowed imported standard keys.
The requestData.newValue.PolicyKCIAAttrISK field includes if your key creation and importation policy allows imported standard keys.
The requestData.initialValue.PolicyKCIAAttrET field includes if your key creation and importation policy previously required keys to be imported via import token.
The requestData.newValue.PolicyKCIAAttrET field includes if your key creation and importation policy requires keys to be imported via import token.

Import token events

Create import token

The following fields include extra information:

The responseData.expirationDate field includes the expiration date of the import token.
The responseData.maxAllowedRetrievals field includes the maximum amount of times the import token can be retrieved within its expiration time before it is no longer accessible.

Retrieve import token

The following fields include extra information:

The responseData.maxAllowedRetrievals field includes the maximum amount of times the import token can be retrieved within its expiration time before it is no longer accessible.
The responseData.remainingRetrievals field includes the number of times the import token can be retrieved within its expiration time before it is no longer accessible.

Completed action of a key rotation

The following fields include extra information:

The responseData.eventAckData.eventId field includes the unique identifier that is associated with the event.
The responseData.eventAckData.eventType field includes the type of lifecycle action that is associated with the event.
The responseData.eventAckData.newKeyVersionId field includes the unique identifier of the latest key version used to wrap input ciphertext on wrap requests.
The responseData.eventAckData.newKeyVersionCreationDate field includes the date that the latest key version was created.
The responseData.eventAckData.oldKeyVersionId field includes the unique identifier of the previous key version used to wrap input ciphertext on wrap requests.
The responseData.eventAckData.oldKeyVersionCreationDate field includes the date that the previous key version was created.

Completed action of key restoration

The following fields include extra information:

The responseData.eventAckData.eventId field includes the unique identifier that is associated with the event.
The responseData.eventAckData.eventType field includes the type of lifecycle action that is associated with the event.
The responseData.eventAckData.keyState field includes the integer that correlates to the state of the key associated with the event.
The responseData.eventAckData.eventAckTimeStamp field includes the date and time that the event was acknowledged.

Completed action of an enabled key

The following fields include extra information:

The responseData.eventAckData.eventId field includes the unique identifier that is associated with the event.
The responseData.eventAckData.eventType field includes the type of lifecycle action that is associated with the event.
The responseData.eventAckData.keyState field includes the integer that correlates to the state of the key associated with the event.
The responseData.eventAckData.eventAckTimeStamp field includes the date and time that the event was acknowledged.

Completed action of a disabled key

The following fields include extra information:

The responseData.eventAckData.eventId field includes the unique identifier that is associated with the event.
The responseData.eventAckData.eventType field includes the type of lifecycle action that is associated with the event.
The responseData.eventAckData.keyState field includes the integer that correlates to the state of the key associated with the event.
The responseData.eventAckData.eventAckTimeStamp field includes the date and time that the event was acknowledged.

Analyzing failed events

Unable to delete a key

If the delete key event has a reason.reasonCode of 409, the key could not be deleted because it is possibly protecting one or more cloud resources that have a retention policy. Make a GET request to /keys/{id}/registrations to learn which resources this key is associated with. A registration with "preventKeyDeletion": true indicates that the associated resource has a retention policy. To enable deletion, contact an account owner to remove the retention policy on each resource that is associated with this key.

A delete key event could also receive a reason.reasonCode of 409 due to a dual auth deletion policy on the key. Make a GET request to /api/v2/keys/{id}/policies to see if there is a dual authorization policy associated with your key. If there is a policy set, contact the other authorized user to schedule the key for deletion.

Unable to authenticate while make a request

If the event has a reason.reasonCode of 401, you do not have the correct authorization to perform Key Protect actions in the specified Key Protect instance. Verify with an administrator that you are assigned the correct platform and service access roles in the applicable service instance. For more information about roles, see Roles and permissions.

Check that you are using a valid token that is associated with an account authorized to perform the service action.

Unable to view or list keys in a Key Protect instance

If you make a call to GET api/v2/keys to list the keys that are available in your Key Protect instance and responseData.totalResources is 0, you may need to query for keys in the deleted state using the state parameter or adjust the offset and limit parameters in your request.

Lifecycle action on a key with registrations did not complete

The responseData.reasonForFailure and responseData.resourceCRN fields contain information on why the action wasn't able to be completed.

If the event has a reason.reasonCode of 409, the action could not be completed due to the adopting service's key state conflicting with the key state that Key Protect has.

If the event has a reason.reasonCode of 408, the action could not be completed because Key Protect was not notified that all appropriate actions were taken within 4 hours of the action request.

Event Severity

The severity for all IBM Cloud Activity Tracker events with Key Protect are based on the type of request that was made, then status code. For example, if you make a create key request with an invalid key, but you are also unauthenticated for the Key Protect instance that you included in the request, the unauthentication will take precedence and the event will be evaluated as a 401 bad request call with a severity of critical.

Key Protect returns a 401 reason.resasonCode for unauthorized/forbidden Key Protect service requests.

The following table lists the actions associated with each severity level:

Table 10. Describes the severity level for Key Protect service actions.
Severity	Actions
Critical	kms.secrets.delete kms.registrations.delete
Warning	kms.secrets.rotate, kms.secrets.restore kms.secrets.enable, kms.secrets.disable kms.secrets.setkeyfordeletion, kms.secrets.unsetkeyfordeletion kms.policies.write, kms.instance-policies.write
Normal	kms.secrets.create, kms.secrets.read kms.secrets-metadata.read, kms.secrets.head kms.secrets.list, kms.secrets.wrap kms.secrets.unwrap, kms.secrets.rewrap kms.secrets-key-versions.list, kms.secrets-event.ack kms.policies.read, kms.instance-policies.read kms.import-token.create, kms.import-token.read kms.registrations.create, kms.registrations.write kms.registrations.merge, kms.registrations.list kms.secrets.ack-delete, kms.secrets.ack-restore kms.secrets.ack-rotate, kms.secrets.ack-enable kms.secrets.ack-disable

The following table lists the status codes associated with each severity level:

Table 11. Describes the severity level for Key Protect response status codes.
Severity	Status Code
Critical	401, 403, 503, 507
Warning	400, 409, 424, 502, 504, 505