Managing user access

IBM Cloud Hyper Protect Crypto Services supports a centralized access control system, which is governed by IBM Cloud® Identity and Access Management, to help you manage users and access for your encryption keys.

Roles and permissions

The following table shows the roles that Hyper Protect Crypto Services supports.

Table 1. Roles and permissions
Roles	Permissions
Service administrator	Manages platform access and service access, grants access to keys, creates and deletes service instances, and manages keys. An IBM Cloud account owner is automatically assigned the service administrator permission.
Crypto unit administrator	Provides signature keys, and signs Trusted Key Entry (TKE) administrative commands such as for adding another crypto unit administrator. In some cases, a crypto unit administrator can also be a master key custodian.
Master key custodian	Provides master key parts for initializing a service instance. In some cases, a master key custodian can also be a crypto unit administrator.
Certificate administrator	Sets up and manages administrator signature keys and client certificates to enable the second layer of TLS authentication in GREP11 or PKCS #11 API connections. The administrator needs to be assigned the Certificate Manager IAM service access role to perform the corresponding actions.
Service user	Manages root keys and standard keys through user interface and the API, and performs cryptographic operations through the PKCS #11 API or the Enterprise PKCS #11 over gRPC (GREP11) API. Based on the platform access roles and service access roles, service users can be further categorized with various permissions.

The following diagram illustrates the roles and permissions.

Figure 1. Hyper Protect Crypto Services roles and responsibilities

IAM platform access roles

With Cloud Identity and Access Management (IAM), you, as an account owner or a service administrator, can manage and define access for service users and resources in your IBM Cloud account.

To simplify access, Hyper Protect Crypto Services aligns with IAM roles so that each user has a different view of the service, according to the role the user is assigned. If you are a service administrator, you can assign Cloud IAM roles that correspond to the specific Hyper Protect Crypto Services permissions you want to grant to members of your team.

The following table lists the IBM Cloud IAM roles in the context of Hyper Protect Crypto Services. For complete IAM documentation and how to assign access, see Managing access in IBM Cloud.

Use IBM Cloud platform access roles to grant permissions at the account level, such as the ability to create or delete instances in your IBM Cloud account.

Table 2. Lists platform management roles as they apply to Hyper Protect Crypto Services
Action	Viewer	Editor	Operator	Administrator
View Hyper Protect Crypto Services instances.
Create Hyper Protect Crypto Services instances.
Delete Hyper Protect Crypto Services instances.
Invite new users and manage access policies.

If you're an account owner, you are automatically assigned Administrator platform access to your Hyper Protect Crypto Services service instances so you can further assign roles and customize access policies for others.

IAM service access roles

As a service administrator, use the service access roles to grant permissions of service users at the service level, such as the ability to view, create, or delete Hyper Protect Crypto Services keys.

As a Reader, you can browse a high-level view of keys and use keys to perform wrap and unwrap actions. Readers cannot create, modify, or delete keys.
As a ReaderPlus, you have the same permissions as a Reader, with the additional ability to retrieve a standard key's material.
As a Writer, you can create, modify, rotate, and use keys. Writers cannot delete or disable keys.
As a Manager, you can perform all actions that a Reader, ReaderPlus and Writer can perform, including the ability to delete keys and set policies for keys. Managers cannot purge keys.
As a VMware KMIP Manager, you can configure KMIP for VMware with Hyper Protect Crypto Services to enable encryption with your own root keys.
As a KMS Key Purge role, you can purge a deleted key to permanently remove a key from your instance.
As a Certificate Manager role, you can manage administrator signature keys and client certificates for the second layer of authentication in GREP11 or PKCS #11 API connections.

The following table shows how service access roles map to Hyper Protect Crypto Services permissions. IAM roles are the default roles provided. Custom roles can be defined by the user.

Trusted Key Entry (TKE) uses either smart cards or software CLI plug-in with IAM authentication. Commands that deals with managing keys locally on the smart card or CLI are not included. Those commands do not interact with the HSM domain.
The key management service API is used for envelope encryption and deals with root keys that are used by IBM Cloud services for encrypting data-at-rest.
HSM APIs (the PKCS #11 API and the GREP11 API) are used for application-level encryption.
Key Management Interoperability Protocol (KMIP) adapter is used to configure the KMIP for VMware service with Hyper Protect Crypto Services to enable vSphere encryption or vSAN encryption by using your own root keys.
Certificate Manager Server receives and processes requests for setting up certificate administrator signature keys and client certificates to enable the second layer of authentication in GREP11 or PKCS #11 API connections.

Table 3. Lists service access roles as they apply to Hyper Protect Crypto Services TKE commands
Action	Reader	ReaderPlus	Writer	Manager	Crypto unit administrator
TKE view state: `ibmcloud tke cryptounit-admins`,`ibmcloud tke cryptounit-compare`,`ibmcloud tke cryptounit-thrhlds`,`ibmcloud tke cryptounit-mk`.
TKE set context: `ibmcloud tke-cryptounit-add`, `ibmcloud tke-cryptounit-rm`.
TKE admin add or remove: `ibmcloud tke cryptounit-admin-add`, `ibmcloud tke cryptounit-admin-rm`.
TKE Set Admin Quorum Threshold: `ibmcloud tke -cryptounit-thrhld-set.`
TKE Master Key operations (load, rotate, clear, zeroize, recover): `ibmcloud tke cryptounit-mk-*`, `ibmcloud tke auto-init`, `ibmcloud tke auto-mk-rotate`, `ibmcloud tke auto-recover`.

Table 4. Lists service access roles as they apply to Hyper Protect Crypto Services key resources
Action	Reader	ReaderPlus	Writer	Manager	KMS Key Purge
Create a key.
Import a key.
Retrieve a key.
Retrieve key metadata.
Retrieve key total.
List keys.
Wrap a key.
Unwrap a key.
Rewrap a key.
Patch a key.
Rotate a key.
Disable a key.
Enable a key.
Schedule deletion for a key.
Cancel deletion for a key.
Delete a key.
Purge a key.
Restore a key.
Set key policies.
List key policies.
Set instance policies.
List instance policies.
Create an import token.
Retrieve an import token.
Create a registration.¹
List registrations for a key.
List registrations for any key.
Update a registration.¹
Replace a registration.¹
Delete a registration.¹
Create a key ring.
List key rings.
Delete a key ring.
Create a key alias.
Delete a key alias.

1: This action is performed on your behalf by an integrated service that enables support for key registration. Learn more.

Table 5. Lists service access roles as they apply to HSM APIs
Action	Reader	ReaderPlus	Writer	Manager
Get mechanism list and information
Create or delete keystore
List keystores
Generate key
Generate key pair
Store key
Generate random
List keys
Get or set key attribute
Wrap key
Rewrap key
Unwrap key
Update key
Encrypt
Decrypt
Sign
Verify
Digest

Table 6. Lists service access roles as they apply to KMIP adapter
Action	Reader	ReaderPlus	Writer	Manager	VMware KMIP Manager
Activate KMIP endpoint.
Deactivate KMIP endpoint.
Get status of KMIP endpoint.
Add client certificates to KMIP endpoint for usage of mutual TLS.
Delete client certificates from KMIP endpoint for usage of mutual TLS.

Table 7. Lists service access roles as they apply to Certificate Manager
Action	Reader	ReaderPlus	Writer	Manager	Certificate Manager
Create the administrator signature key.
Refresh and update the administrator signature key.
Retrieve the administrator signature key of the certificate administrator.
Delete the administrator signature key of the certificate administrator.
Create or update the client certificates.
List all client certificates that are managed by the certificate administrator.
Retrieve client certificates.
Delete client certificates.

Managing access to multiple instances

If you have multiple Hyper Protect Crypto Services instances in different accounts, you might need to leverage IBM Cloud enterprises to manage accounts and user access.

Create the enterprise hierarchy

With IBM Cloud enterprises, you can centrally manage multiple accounts and resources. You can create an enterprise hierarchy as needed by nesting account groups or accounts within the enterprise account. The access management to the enterprise and the child accounts is isolated to provide greater security. To learn how to create an enterprise and add accounts to an enterprise, see Best practices for organizing resources and assigning access.
Organize account resources in resource groups

Hyper Protect Crypto Services instances are associated with child accounts of the enterprise. Within each account, you can organize service instances in resource groups so that you can assign different access policies to each resource group to enable independent access control. For how to create resource groups and organize resources, see Best practices for organizing resources.
Assign access to manage the enterprise and resources

Based on the Hyper Protect Crypto Services IAM platform roles and service roles that are listed, you can assign users respective access to each tier of the enterprise hierarchy. You can also group users or service IDs by defining access groups to streamline the process of assigning access. For more information about assigning access, Access management in the cloud.
Use IBM Cloud API keys

You can create IBM Cloud API keys for users or services to track and control API usage. The user API key is associated with the user identity and inherits all access that the user is assigned. The service API key is granted the access that is associated with a specific service ID. API keys can also be used to generate IAM tokens for API calls authentication. For how to manage API keys, see Managing user API keys and Managing service ID API keys.

The following example shows how to use the enterprise to manage multiple instances and user access. Assume that your organization has two Hyper Protect Crypto Services instances for development and production, and two separate teams are managing and operating these instances. you can create the following enterprise hierarchy to better manage accounts, instances, and user access:

Figure 2. An example of the enterprise hierarchy and user access management

Use separate accounts and distinct resource groups to manage instances for development purpose and production purpose.
Assign users the minimum access to the corresponding resources. For example, assign the enterprise managers the administrator role for accounts and billing management. Assign the developer team members the editor and manager roles for performing operations toward the development instance. Assign other members the viewer and reader role for viewing only instance resources.

What's next

Account owners and admins can invite users and set service policies that correspond to the Hyper Protect Crypto Services actions the users can perform. For more information about assigning user roles, see Managing access to resources.