IBM Cloud Docs
Auditing events for Hyper Protect Crypto Services with Unified Key Orchestrator

Auditing events for Hyper Protect Crypto Services with Unified Key Orchestrator

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

IBM Cloud Activity Tracker records 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.

To enable IBM Cloud Activity Tracker for your Hyper Protect Crypto Services instance, you need to provision an instance of the IBM Cloud Activity Tracker service in the same region where your Hyper Protect Crypto Services instance is located. For more information, see the getting started tutorial for IBM Cloud Activity Tracker.

To see which requests correlate to the following actions, check out the Unified Key Orchestrator API reference doc and TKE CLI reference.

Supported events

Key events

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

Table 1. Managed key actions
Action Description
hs-crypto.managed-keys.write Create or update a managed key.
hs-crypto.managed-keys.list Get a list of managed keys.
hs-crypto.managed-keys.read Retrieve information about a managed key.
hs-crypto.managed-keys.delete Delete a managed key.

Keystore events

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

Table 2. Keystore actions
Action Description
hs-crypto.target-keystores.write Create or update a keystore.
hs-crypto.target-keystores.list Get a list of keystores.
hs-crypto.target-keystores.read Retrieve information about a keystore.
hs-crypto.target-keystores.delete Delete a keystore.

Vault events

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

Table 3. Vault actions
Action Description
hs-crypto.vaults.list Get a list of vaults.
hs-crypto.vaults.write Create or update a vault.
hs-crypto.vaults.read Retrieve information about a vault.
hs-crypto.vaults.delete Delete a vault.

Template events

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

Table 4. Template actions
Action Description
hs-crypto.key-templates.write Create or update a template.
hs-crypto.key-templates.read Retrieve template information.
hs-crypto.key-templates.delete Delete a template.
hs-crypto.key-templates.list List all key templates.

Registration events

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

Table 5. Registration actions
Action Description
hs-crypto.registrations.list List registrations for any key.
hs-crypto.registrations.default Invalid registration request event.

Trusted Key Entry events

The following table lists the Trusted Key Entry (TKE) actions that generate an event.

Table 6. Trusted Key Entry actions
Action Description
hs-crypto.tke-cryptounit-admin.add Add a crypto unit administrator to the selected crypto units.
hs-crypto.tke-cryptounit-admin.remove Remove a crypto unit administrator from the selected crypto units.
hs-crypto.tke-cryptounit-threshold.set Set the signature thresholds for the selected crypto units.
hs-crypto.tke-cryptounit-master-key-register.add Load the new master key register.
hs-crypto.tke-cryptounit-master-key-register.commit Commit the new master key register.
hs-crypto.tke-cryptounit-master-key-register.activate Activate the current master key register.
hs-crypto.tke-cryptounit-new-master-key-register.clear Clear the new master key register.
hs-crypto.tke-cryptounit-current-master-key-register.clear Clear the current master key register.
hs-crypto.tke-cryptounit.reset Zeroize and reset the selected crypto units

Certificate manager events

The following table lists the certificate manager actions that generate an event.

Table 7. Certificate manager actions
Action Description
hs-crypto.mtlscert-admin-key.create Create the administrator signature key for the certificate administrator to connect to the certificate manager server.
hs-crypto.mtlscert-admin-key.update Refresh and update the administrator signature key for the certificate administrator.
hs-crypto.mtlscert-admin-key.read Get the administrator signature key of the certificate administrator.
hs-crypto.mtlscert-admin-key.delete Delete the administrator signature key of the certificate administrator.
hs-crypto.mtlscert-cert.set Create or update certificates by the certificate administrator.
hs-crypto.mtlscert-cert.list List all certificates that are managed by the certificate administrator.
hs-crypto.mtlscert-cert.read Get certificates by the certificate administrator.
hs-crypto.mtlscert-cert.delete Delete certificates by the certificate administrator.

KMIP for VMware events

When you manage keys for the KMIP for VMware® service, an event is generated.

The following table provides the actions that generate and send events for KMIP for VMware. These actions are performed by an initiator from VMware vCenter Server® and do not include the initiator's IP address. The requests for these actions run from within the IBM Cloud private network.

The initiator ID is derived from the TLS (Transport Layer Security) certificate of the vCenter Server that is used to authenticate the connection to the KMIP server. The initiator ID is in the format CertificateID-<value>, where the value matches the fingerprint of the corresponding TLS certificate. Using the fingerprint, you can identify the vCenter Server that triggered the action.

Table 8. Description of actions that generate events for the KMIP for VMware service
Action Description
hs-crypto.kmip-key.create A KMIP key is created.
hs-crypto.kmip-key.read A KMIP key is retrieved.
hs-crypto.kmip-key-attributes.retrieve A KMIP key's attributes are retrieved.
hs-crypto.kmip-key.activate A KMIP key is activated.
hs-crypto.kmip-key.revoke A KMIP key is revoked.
hs-crypto.kmip-key.destroy A KMIP key is destroyed.

EP11 keystore events

The following table lists the Enterprise PKCS #11 (EP11) keystore actions that generate an event:

Table 9. EP11 keystore actions
Action Description
hs-crypto.keystore.createkeystore Create an EP11 keystore.
hs-crypto.keystore.deletekey Delete an EP11 key.
hs-crypto.keystore.deletekeystore Delete an EP11 keystore.
hs-crypto.keystore.listkeysbyattributes View EP11 keys.
hs-crypto.keystore.listkeysbyids View EP11 keys.
hs-crypto.keystore.listkeystoresbyattributes View EP11 keystores.
hs-crypto.keystore.listkeystoresbyids View EP11 keystores.
hs-crypto.keystore.storenewkey Store an EP11 key.
hs-crypto.keystore.updatekey Update an EP11 key.

EP11 crypto events

The following table lists the EP11 crypto actions that generate an event:

Table 10. EP11 crypto actions
Action Description
hs-crypto.ep11.use Cryptographic operation

Viewing events

Events that are generated by an instance of Hyper Protect Crypto Services are automatically forwarded to the IBM Cloud Activity Tracker service 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 service instance is available. For more information, see Launching the web UI through the IBM Cloud UI.

Table 11. Activity Tracker regions
Deployment region Activity Tracker region
au-syd au-syd
br-sao br-sao
ca-tor ca-tor
eu-de eu-de
eu-es eu-es
eu-gb eu-gb
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. In requestData and responseData properties there are available full payloads from requests and responses except sensitive data. The list of field, endpoints, and payloads is available in API docs.

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

The list of sensitive field values that are hidden using the [redacted] placeholder:

  • service_principal_password
  • secret_access_key
  • access_key_id
  • api_key

Common fields

Some common fields are available for Hyper Protect Crypto Services to use outside of the CADF event model to provide more insight into your data.

Table 12. Common fields in Activity Tracker events for Hyper Protect Crypto Services service actions
Field Description
requestData.requestURI The URI of the API request that was made.
requestData.instanceID The unique identifier of your Hyper Protect Crypto Services service instance.

For more information about 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 is not shown for requests made through private networks.

Registration events

List registrations

The following field includes extra information:

  • The responseData.totalResources field includes the total number of registrations that are returned in the response.

Trusted Key Entry events

The following table lists the returned values that indicate a successful TKE event.

Table 13. Returned values of a successful TKE event
Field name Returned value
outcome success
reason.reasonCode 200
reason.reasonType OK

The following common fields for TKE events include extra information:

  • The requestData.location field includes the specific location of the crypto unit. The location follows this format:

    [region].[availability zone].[hardware security module (HSM) module index].[HSM domain index].

    For example, if you provision your instance in the us-east region, the value that is returned is similar to [us-east].[AZ2-CSSTAG2].[03].[22].

  • The target.id field includes the Cloud Resource Name (CRN) of the crypto unit.

  • The target.name field also includes the location of the crypto unit.

  • The target.typeURI field includes the URI of the object that the action is targeting at. For example, if you perform the hs-crypto.tke-cryptounit-master-key-register.add action, the value that is returned is hs-crypto/tke-cryptounit/master-key-register.

For the following TKE events, some specific fields indicate more information.

Add a crypto unit administrator

  • The requestData.adminId field includes the SHA-256 hash of the signature key file that is associated with the administrator to be added.
  • The responseData.adminIds field lists the SHA-256 hashes of the signature key files associated with all the administrators that are added to the crypto unit.

Remove a crypto unit administrator

  • The requestData.adminId field includes the SHA-256 hash of the signature key file that is associated with the administrator to be removed.
  • The responseData.adminIds field lists the SHA-256 hashes of the signature key files associated with all the administrators that are added to the crypto unit.

Set the signature thresholds

Load the new master key register

  • The requestData.masterKeyIds field lists the SHA-256 hashes of all the master key parts files that you select to load to the crypto unit.
  • The responseData.verificationPattern field includes the SHA-256 hash of the master key that is composed of the selected master key parts and is loaded to the new master key register.

Commit the new master key register

  • The requestData.verificationPattern field includes the SHA-256 hash of the master key that is loaded to the new master key register.
  • The responseData.masterKeyIds field lists the SHA-256 hashes of all the master key parts files that compose the master key.

Activate the current master key register

  • The requestData.verificationPattern field includes the SHA-256 hash of the master key that is loaded and committed to the new master key register.
  • The responseData.verificationPattern field includes the SHA-256 hash of the master key that is activated.

Certificate manager events

The following table lists the returned values that indicate a successful certificate manager event.

Table 14. Returned values of a successful mTLS certificate manager event
Field name Returned value
outcome success
reason.reasonCode 200
reason.reasonType OK

The following common fields for certificate manager events include extra information:

  • The target.id field includes the Cloud Resource Name (CRN) of the event.
  • The target.name field indicates the target name of the event, such as "mtlscert-admin-key" or "mtlscert-cert".
  • The target.typeURI field includes the URI of the object that the action is targeting at. For example, if you perform the hs-crypto.mtlscert-admin-key.create action, the value that is returned is hs-crypto/mtlscert-admin-key.

The specified fields of the following certificate manager events can indicate more information.

Create the administrator signature key for the certificate administrator

The following fields include extra information:

  • The requestData.accountId field includes the current user ID.
  • The responseData.action field includes the action details of the current user.

Update the administrator signature key for the certificate administrator

The following fields include extra information:

  • The requestData.accountId field includes the current user ID.
  • The responseData.action field includes the action details of the current user.

Remove the administrator signature key of the certificate administrator

The following fields include extra information:

  • The requestData.accountId field includes the current user ID.
  • The responseData.action field includes the action details of the current user.

Get the administrator signature key of the certificate administrator

The following fields include extra information:

  • The requestData.accountId field includes the current user ID.
  • The responseData.action field includes the action details of the current user.

Create or updating certificates by the certificate administrator

The following fields include extra information:

  • The requestData.certificateId field indicates the target certificate.
  • The responseData.action field indicates that the certificate is to be created or updated.

List certificates by the certificate administrator

The following field includes extra information:

  • The responseData.action field indicates all certificates that are managed by current administrator are to be listed.

Get certificates by the certificate administrator

The following fields include extra information:

  • The requestData.certificateId field indicates the target certificate.
  • The responseData.action field indicates that the certificate is to be fetched and displayed.

Remove certificates by the certificate administrator

The following fields include extra information:

  • The requestData.certificateId field indicates the target mTLS certificate.
  • The responseData.action field indicates that the certificate is to be deleted.

EP11 keystore events

The following table lists the returned values that indicate a successful EP11 keystore event:

Table 15. Returned values of a successful EP11 keystore event
Field name Returned value
outcome success
reason.reasonCode 200
reason.reasonType OK

The following common fields for EP11 keystore events include extra information:

  • The target.name field includes the IDs of the keystore or key.

EP11 crypto events

The following table lists the returned values that indicate a successful EP11 crypto event:

Table 16. Returned values of a successful EP11 crypto event
Field name Returned value
outcome success
reason.reasonCode 200
reason.reasonType OK

Analyzing failed events

All failed events contain the message field with detailed description of the problem.

Lifecycle action on a key with registrations did not complete

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

If the event has a reason.reasonCode of 409, the action cannot be completed due to the adopting service's key state conflicting with the key state that Hyper Protect Crypto Services has.

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

Unable to perform Trusted Key Entry actions

Failed TKE events have an outcome of failure. The reason.reasonType and reason.reasonForFailure fields contain information about why the action wasn't able to be completed.

If the event has a reason.reasonCode of 400, the action cannot be completed because the operation to the crypto units is not supported or is not valid. Check whether the TKE command that you use is valid by referring to the TKE CLI reference.

If the event has a reason.reasonCode of 401 or 403, the action cannot be completed because your access token is not valid or does not have the necessary permissions to access this instance. Refresh your access token and check whether you have appropriate permissions to perform the corresponding actions.

If the event has a reason.reasonCode of 500, check out the value of reason.reasonForFailure to identify the reasons of failure and the corresponding actions that you need to take.

Event severity

The severity for all Activity Tracker events with Hyper Protect Crypto Services is based on the type of request that was made, then status code. For example, you might request to create a key with an invalid key and are not authenticated in the service instance. The unauthentication takes precedence and the event is evaluated as a 401 bad request call with a severity of critical.

The severity level for all TKE events is critical due to the sensitivity of the actions.

The following table lists the actions that are associated with each severity level.

Table 17. Severity level for Hyper Protect Crypto Services service actions
Severity Actions
Critical hs-crypto.target-keystores.delete

hs-crypto.managed-keys.delete

hs-crypto.vaults.delete

hs-crypto.registrations.delete

hs-crypto.tke-cryptounit-admin.add

hs-crypto.tke-cryptounit-admin.remove

hs-crypto.tke-cryptounit-current-master-key-register.clear

hs-crypto.tke-cryptounit-new-master-key-register.clear

hs-crypto.tke-cryptounit-master-key-register.add

hs-crypto.tke-cryptounit-master-key-register.commit

hs-crypto.tke-cryptounit-master-key-register.activate

hs-crypto.tke-cryptounit-threshold.set

hs-crypto.tke-cryptounit.reset

hs-crypto.mtlscert-admin-key.create

hs-crypto.mtlscert-admin-key.update

hs-crypto.mtlscert-admin-key.delete

hs-crypto.mtlscert-cert.set

hs-crypto.mtlscert-cert.set

hs-crypto.keystore.deletekey

hs-crypto.keystore.deletekeystore

hs-crypto.keystore.updatekey
Warning hs-crypto.managed-keys.write

Note that when this event is triggered to change the key state to destroyed, the severity level is Critical instead of Warning.
Normal hs-crypto.managed-keys.list

hs-crypto.managed-keys.read

hs-crypto.target-keystores.write

hs-crypto.target-keystores.list

hs-crypto.target-keystores.read

hs-crypto.vaults.list

hs-crypto.vaults.write

hs-crypto.vaults.read

hs-crypto.keystore.createkeystore

hs-crypto.keystore.listkeysbyattributes

hs-crypto.keystore.listkeysbyids

hs-crypto.keystore.listkeystoresbyattributes

hs-crypto.keystore.listkeystoresbyids

hs-crypto.keystore.storenewkey

hs-crypto.ep11.use

The following table lists the status codes that are associated with each severity level.

Table 18. Severity level for Hyper Protect Crypto Services response status codes
Severity Status code
Critical 400 (For TKE events only), 401, 403, 500, 503, 507
Warning 400, 409, 424, 502, 504, 505