IBM Cloud Docs
Setting up PKCS #11 API user types

Setting up PKCS #11 API user types

To align with industry-standard security requirements and Permitted object accesses by sessions, it is suggested to set up the PKCS #11 user types in your Hyper Protect Crypto Services instance when you use the PKCS #11 API.

PKCS #11 user types

The PKCS #11 standard defines two user types: security officer and normal user. If a user does not perform a C_Login function call, the user is considered as an anonymous user.

In the Hyper Protect Crypto Services PKCS #11 library configuration file grep11client.yaml, the following user types are predefined, with each assigned a service ID API key:

  • Security officer (SO): An SO user can be a person who owns the SO API key in an enterprise. This person is able to initialize the PKCS #11 token and delete all key objects in keystores. This person can be the one who sets up the Hyper Protect Crypto Services instance and the Cloud Identity and Access Management (IAM) roles. The PKCS #11 application can perform administrative Cryptoki function calls, such as C_InitToken, after it logs in as an SO user type.

  • Normal user: Normal users are the ones who have access to the normal user API key. The normal user API key needs to be distributed only to a limited group of people, who need access to the keystore where more sensitive keys are stored, such as keys for signing and encrypting contracts. In this case, the PKCS #11 application calls the C_Login function by using the normal user API key as the PIN and becomes a normal user to access the keystore.

  • Anonymous user: The anonymous user API key can be distributed to anyone in the enterprise so that anonymous users can access the keystore to perform daily work, such as signing a document. The API key is configured in the PKCS #11 library configuration file grep11client.yaml and the anonymous user does not need to call the C_Login function.

A PKCS #11 application works as only one of the three user types at any time, no matter how many sessions are opened. Each user type needs an API key for authentication. To create the API keys, you need to first create three custom IAM roles. And then, create service IDs for the three user types, and map the custom IAM roles to the service IDs.

To perform the following steps, you need to have the Administrator platform access in your IBM Cloud® account.

Step 1: Create custom IAM roles

You need to create three custom roles, one for performing crypto operations, one for managing keys, and the other for managing EP11 keystores.

1. Create a custom role for performing crypto operations

This role is used to generate key objects for performing crypto operations. However, this role does not have permission to use or manage Enterprise PKCS #11 (EP11) keystores.

  1. In the UI, go to Manage > Access (IAM), and select Roles.
  2. Click Create.
  3. Enter a name for your role; for example, Crypto operator. This name must be unique within the account. Users see this role name in the UI when they assign access to the service.
  4. Enter an ID for the role. This ID is used in the CRN, which is used when you assign access by using the API. The role ID must begin with a capital letter and use alphanumeric characters only; for example, CryptoOperator.
  5. Optional: Enter a succinct and helpful description that helps the users who are assigning access know what level of access this role assignment gives a user. This description also shows in the UI when a user assigns access to the service.
  6. From the list of services, select Hyper Protect Crypto Services.
  7. Select Add for the following 19 actions:
    • hs-crypto.crypto.decrypt
    • hs-crypto.crypto.derivekey
    • hs-crypto.crypto.digest
    • hs-crypto.crypto.digestkey
    • hs-crypto.crypto.encrypt
    • hs-crypto.crypto.generatekey
    • hs-crypto.crypto.generatekeypair
    • hs-crypto.crypto.generaterandom
    • hs-crypto.crypto.getattributevalue
    • hs-crypto.crypto.getmechanisminfo
    • hs-crypto.crypto.getmechanismlist
    • hs-crypto.crypto.rewrapkeyblob
    • hs-crypto.crypto.setattributevalue
    • hs-crypto.crypto.sign
    • hs-crypto.crypto.unwrapkey
    • hs-crypto.crypto.verify
    • hs-crypto.crypto.wrapkey
    • hs-crypto.discovery.listservers
    • hs-crypto.ep11.use
  8. Review the actions added under Summary, and then click Create.

2. Create a custom role for managing keys

This role is used to manage keys in the EP11 keystores. However, this role does not have permission to manage EP11 keystores or perform crypto operations.

  1. In the UI, go to Manage > Access (IAM), and select Roles.
  2. Click Create.
  3. Enter a name for your role; for example, Key operator. This name must be unique within the account. Users see this role name in the UI when they assign access to the service.
  4. Enter an ID for the role. This ID is used in the CRN, which is used when you assign access by using the API. The role ID must begin with a capital letter and use alphanumeric characters only; for example, KeyOperator.
  5. Optional: Enter a succinct and helpful description that helps the users who are assigning access know what level of access this role assignment gives a user. This description also shows in the UI when a user assigns access to the service.
  6. From the list of services, select Hyper Protect Crypto Services.
  7. Select Add for the following six actions:
    • hs-crypto.keystore.deletekey
    • hs-crypto.keystore.listkeysbyattributes
    • hs-crypto.keystore.listkeysbyids
    • hs-crypto.keystore.listkeystoresbyids
    • hs-crypto.keystore.storenewkey
    • hs-crypto.keystore.updatekey
  8. Review the actions added under Summary, and then click Create.

3. Create a custom role for managing keystores

This role is used to create and delete EP11 keystores but does not have permissions to manage keys.

  1. In the UI, go to Manage > Access (IAM), and select Roles.
  2. Click Create.
  3. Enter a name for your role; for example, Keystore operator. This name must be unique within the account. Users see this role name in the UI when they assign access to the service.
  4. Enter an ID for the role. This ID is used in the CRN, which is used when you assign access by using the API. The role ID must begin with a capital letter and use alphanumeric characters only; for example, KeystoreOperator.
  5. Optional: Enter a succinct and helpful description that helps the users who are assigning access know what level of access this role assignment gives a user. This description also shows in the UI when a user assigns access to the service.
  6. From the list of services, select Hyper Protect Crypto Services.
  7. Select Add for the following four actions:
    • hs-crypto.keystore.createkeystore
    • hs-crypto.keystore.deletekeystore
    • hs-crypto.keystore.listkeystoresbyattributes
    • hs-crypto.keystore.listkeystoresbyids
  8. Review the actions added under Summary, and then click Create.

For more information about how to create custom roles, see Creating custom roles.

Step 2: Create service IDs and API keys for the SO user, normal user, and anonymous user

1. Create service IDs and API keys for the SO user

To create a service ID for the SO user and the corresponding API key, complete the following steps:

  1. In the UI, go to Manage > Access (IAM), and select Service IDs.

  2. To create the service ID for the SO user, follow these steps:

    1. Click Create.
    2. Create a name SO user and description for the SO user service ID.
    3. Click Create.

  3. To create an API key for the service ID, follow these steps:

    1. Click the API keys tab on the SO user service ID page.
    2. Click Create.
    3. Add a name and description to easily identify the API key. For example, SO user API key.
    4. Click Create.
    5. Save your API key by copying or downloading it to a secure location.

    The API key is to be used as the PIN for the SO user logins for and cannot be retrieved. Make sure to make a copy of it in this step.

2. Create service IDs and API keys for the normal user

To create a service ID for the normal user and the corresponding API key, complete the following steps:

  1. In the UI, go to Manage > Access (IAM), and select Service IDs.

  2. To create the service ID for the normal user, follow these steps:

    1. Click Create.
    2. Create a name Normal user and description for the normal user service ID.
    3. Click Create.

  3. To create an API key for the service ID, follow these steps:

    1. Click the API keys tab on the Normal user service ID page.
    2. Click Create.
    3. Add a name and description to easily identify the API key. For example, Normal user API key.
    4. Click Create.
    5. Save your API key by copying or downloading it to a secure location.

    The API key is to be used as the PIN for the normal user logins, and cannot be retrieved. Make sure to make a copy of it in this step.

3. Create service IDs and API keys for the anonymous user

To create a service ID for the anonymous user and the corresponding API key, complete the following steps:

  1. In the UI, go to Manage > Access (IAM), and select Service IDs.

  2. To create the service ID for the anonymous user, follow these steps:

    1. Click Create.
    2. Create a name Anonymous user and description for the anonymous user service ID.
    3. Click Create.

  3. To create an API key for the service ID, follow these steps:

    1. Click the API keys tab on the Anonymous user service ID page.
    2. Click Create.
    3. Add a name and description to easily identify the API key. For example, Anonymous user API key.
    4. Click Create.
    5. Save your API key by copying or downloading it to a secure location.

    The API key is to be used to perform crypto operations and access the public keystore for the anonymous user, which cannot be retrieved. Make sure to make a copy of it in this step.

For more information about creating service IDs, see Creating and working with service IDs. For detailed instructions on creating service ID API keys, see Managing service ID API keys.

Step 3: Assign IAM roles to the service IDs

You can grant access to service IDs within a Hyper Protect Crypto Services service instance by using the UI.

1. Assign the custom roles to the SO user service ID

To assign the custom roles that are defined in Step 1 to the SO user service ID, follow these steps:

To assign access to the keystores for the SO user, follow these steps:

  1. From the menu bar, click Manage > Access (IAM), and select Service IDs to browse the existing service IDs in your account.

  2. Hover your mouse over the SO user service ID, and click the Actions icon Actions icon to open a list of options.

  3. From the options menu, click Assign access.

  4. Click Access policy.

  5. Under Service, select Hyper Protect Crypto Services and click Next.

  6. Under Resources, select Specific resources.

  7. Select the Service Instance ID attribute type, enter the Hyper Protect Crypto Services service instance ID that you want to grant access to, and click Next.

  8. Under Roles and actions, check the boxes for the following roles and click Next:

    • Crypto operator
    • Key operator
    • Keystore operator

  9. (Optional) Under Conditions (optional), click Review to check the access policy.

  10. Click Add.

  11. Review the roles and actons added under Summary, and then click Assign.

2. Assign the custom roles to the normal user service ID

To assign the custom roles that are defined in Step 1 to the normal user service ID, follow these steps:

To assign access to the keystores for the normal user, follow these steps:

  1. From the menu bar, click Manage > Access (IAM), and select Service IDs to browse the existing service IDs in your account.
  2. Hover your mouse over the Normal user service ID, and click the Actions icon Actions icon to open a list of options.
  3. From the options menu, click Assign access.
  4. Click Access policy.
  5. Under Service, select Hyper Protect Crypto Services and click Next.
  6. Under Resources, select Specific resources.
  7. Select the Service Instance ID attribute type, enter the Hyper Protect Crypto Services service instance ID that you want to grant access to, and click Next.
  8. Under Roles and actions, check the boxes for Crypto operator and Key operator, and then click Next.
  9. (Optional) Under Conditions (optional), click Review to check the access policy.
  10. Click Add.
  11. Review the roles and actons added under Summary, and then click Assign.

3. Create access policies and assign custom roles to the anonymous user service ID

The anonymous user requires three access policies. The PKCS#11 specification specifies that the anonymous user can access the public keystore only. The following access policies are set up to restrict the anonymous user to the public keystore.

To assign the custom roles that are defined in Step 1 to the anonymous user service ID, follow these steps:

Create access policy for crypto operations

  1. From the menu bar, click Manage > Access (IAM), and select Service IDs to browse the existing service IDs in your account.
  2. Hover your mouse over the Anonymous user service ID, and click the Actions icon Actions icon to open a list of options.
  3. From the options menu, click Assign access.
  4. Click Access policy.
  5. Under Service, select Hyper Protect Crypto Services and click Next.
  6. Under Resources, select Specific resources.
  7. Select the Service Instance ID attribute type, enter the Hyper Protect Crypto Services service instance ID that you want to grant access to, and click Next.
  8. Under Roles and actions, check the box for Crypto operator and click Next.
  9. (Optional) Under Conditions (optional), click Review to check the access policy.
  10. Click Add.
  11. Review the roles and actons added under Summary, and then click Assign.

Create access policy for key access

  1. From the menu bar, click Manage > Access (IAM), and select Service IDs to browse the existing service IDs in your account.
  2. Hover your mouse over the Anonymous user service ID, and click the Actions icon Actions icon to open a list of options.
  3. From the options menu, click Assign access.
  4. Click Access policy.
  5. Under Service, select Hyper Protect Crypto Services and click Next.
  6. Under Resources, select Specific resources.
  7. Select the Service Instance ID attribute type, enter the Hyper Protect Crypto Services service instance ID that you want to grant access to, and click Add a condition.
  8. Select the Resource Type attribute type, enter key under the value field, and click Next.
  9. Under Roles and actions, check the box for Key operator and click Next.
  10. (Optional) Under Conditions (optional), click Review to check the access policy.
  11. Click Add.
  12. Review the roles and actons added under Summary, and then click Assign.

Create access policy for keystore access

  1. From the menu bar, click Manage > Access (IAM), and select Service IDs to browse the existing service IDs in your account.

  2. Hover your mouse over the Anonymous user service ID, and click the Actions icon Actions icon to open a list of options.

  3. From the options menu, click Assign access.

  4. Click Access policy.

  5. Under Service, select Hyper Protect Crypto Services and click Next.

  6. Under Resources, select Specific resources.

  7. Select the Service Instance ID attribute type, enter the Hyper Protect Crypto Services service instance ID that you want to grant access to, and click Add a condition.

  8. Select the Resource Type attribute type, enter keystore under the value field, and click Add a condition.

  9. Select the Resource ID attribute type, enter the value, and click Next.

    The value of the Resource ID attribute type must contain a valid Universally Unique IDentifier (UUID) of the PKCS#11 public keystore. You can generate the UUID with a third-party tool, such as UUID generator. The UUID string specified for the Resource ID attribute must match the UUID string specified for the anonymous user's public_keystore_spaceid configuration parameter within the grep11client.yaml configuration file in the PKCS#11 client library.

  10. Under Roles and actions, check the box for Key operator and click Next.

  11. (Optional) Under Conditions (optional), click Review to check the access policy.

  12. Click Add.

  13. Review the roles and actions added under Summary, and then click Assign.

What's next

Continue to read Performing cryptographic operations with the PKCS #11 API on how to use the PKCS #11 API.