SDK Version: 2.03
Available Ciphers:
AES_128
AES_256
3DES
RSA (non-CRT. modulus size can be 2048/3072)
RSA_CRT (same as RSA)
For RSA, Exponent will be 65537
Current FIPS mode is: 00000002
Enter the number of thread [1-10]: 1
Enter the cipher: AES_256
Enter the data size [1-16200]: 8192
Enter time duration in Secs: 60
Starting non-blocking speed test using data length of 8192 bytes...
```
```
c:\Program Files\Amazon\CloudHSM>pkpspeed_blocking.exe -s CU user name -p password
login as USER
Initializing Cfm2 library
SDK Version: 2.03
Current FIPS mode is: 00000002
Please enter the number of threads [MAX=400] : 1
Please enter the time in seconds to run the test [MAX=600]: 20
Please select the test you want to run
RSA non-CRT------------------->A
RSA CRT----------------------->B
Basic 3DES CBC---------------->C
Basic AES--------------------->D
FIPS Random------------------->H
Random------------------------>I
AES GCM ---------------------->K
eXit------------------------>X
D
Running 1 threads for 20 sec
Enter the key size(128/192/256):256
Enter the size of the packet in bytes[1-16200]:8192
OPERATIONS/second 9/1
OPERATIONS/second 10/1
OPERATIONS/second 11/1
OPERATIONS/second 10/1
OPERATIONS/second 10/1
OPERATIONS/second 10/...
```
# AWS CloudHSM Client SDK 5 user contains inconsistent values
The `user list` command in AWS CloudHSM Client SDK 5 returns a list of all users, and user properties, in your cluster. If any of a user’s properties have the value "**inconsistent**", this user is not synchronized across your cluster. This means that the user exists with different properties on different HSMs in the cluster. Based on which property is inconsistent, different repair steps can be taken.
The following table includes steps to resolve inconsistencies for a single user. If a single user has multiple inconsistencies, resolve them by following these steps from top to bottom. If there are multiple users with inconsistencies, work through this list for each user, fully resolving the inconsistencies for that user before moving on the next.
**Note**
To perform these steps you should ideally be logged in as an admin. If your admin account is not consistent, go through these steps logging in with the admin and repeating the steps until all properties are consistent. After your admin account is consistent, you can proceed to use that admin to synchronize other users in the cluster.
| Inconsistent property | Example output of user list | Implication | Recovery method |
| --- | --- | --- | --- |
| User "role" is "inconsistent" | {
"username":
"test_user",
"role": "inconsistent",
"locked": "false",
"mfa": [],
"cluster-coverage": "full"
} | This user is a CryptoUser on some HSMs, and an Admin on other HSMs. This can happen if two SDKs attempt to create the same user, at the same time, with different roles.You must remove this user, and re-create it with the desired role. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshoot-sdk5-inconsistent-value.html) |
| User "cluster-coverage" is "inconsistent" | {
"username": "test_user",
"role": "crypto-user",
"locked": "false",
"mfa": [],
"cluster-coverage": "inconsistent"
} | This user exists on a subset of HSMs in the cluster.This can happen if a **user create** partially succeeded, or if a **user delete** partially succeeded. You must finish your previous operation, either creating or removing this user from your cluster. | If the user should not exist, follow these steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshoot-sdk5-inconsistent-value.html) If the user should exist, follow these steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshoot-sdk5-inconsistent-value.html) |
| User "locked" parameter is "inconsistent" or "true" | {
"username":
"test_user",
"role": "crypto-user",
"locked": inconsistent,
"mfa": [],
"cluster-coverage": "full"
} | This user is locked out on a subset of HSMs. This can happen if a user uses the wrong password and only connects to a subset of HSMs in the cluster. You must change the user's credentials to be consistent across the cluster. | If the user has MFA activated, follow these steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshoot-sdk5-inconsistent-value.html) If MFA should be active for the user, follow these steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshoot-sdk5-inconsistent-value.html) |
| MFA status is "inconsistent" | {
"username": "test_user",
"role": "crypto-user",
"locked": "false",
"mfa": [
{
"strategy": "token-sign",
"status": "inconsistent"
}
],
"cluster-coverage": "full"
} | This user has different MFA flags on different HSMs in the cluster. This can happen if an MFA operation only completed on a subset of HSMs. You must reset the user's password, and allow them to re-enable MFA. | If the user has MFA activated, follow these steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshoot-sdk5-inconsistent-value.html) If MFA should be active for the user, follow these steps: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshoot-sdk5-inconsistent-value.html) |
# AWS CloudHSM Client SDK 5 user replicate failures
The `user replicate` command in the CloudHSM CLI replicates a user between cloned AWS CloudHSM clusters. This guide addresses failures due to user inconsistencies within the source cluster or between the source and destination clusters. User replicate verifies that users are consistent by checking the following attributes:
+ User Role
+ Account Lock Status
+ Quorum Status
+ Multi-Factor Authentication (MFA) Status
## Problem: The selected user is not synchronized throughout the cluster
The user replication process checks for user synchronization throughout the source cluster. If a user's attribute has the value "inconsistent", this means the user isn't synchronized across the cluster. User replication fails with the following error message:
```
{
"error_code": 1,
"data": "Specified user is inconsistent across the cluster"
}
```
To check for user desynchronization in the source cluster:
+ Run the `user list` command in the CloudHSM CLI.
```
aws-cloudhsm > user list
{
"error_code": 0,
"data": {
"users": [
{
"username": "admin",
"role": "admin",
"locked": "false",
"mfa": [],
"quorum": [],
"cluster-coverage": "full"
},
{
"username": "example-inconsistent-user",
"role": "admin",
"locked": "false",
"mfa": [],
"quorum": [],
"cluster-coverage": "inconsistent"
},
{
"username": "app_user",
"role": "internal(APPLIANCE_USER)",
"locked": "false",
"mfa": [],
"quorum": [],
"cluster-coverage": "full"
}
]
}
}
```
**Resolution: Synchronize user attributes throughout the source cluster**
+ To synchronize user information throughout the source cluster, refer to the following: [AWS CloudHSM Client SDK 5 user contains inconsistent values](troubleshoot-sdk5-inconsistent-value.md).
## Problem: User exists on the destination cluster with different attributes
If a user already exists with the same reference exists in one or more HSMs in the destination cluster but has different user attributes, the following error may occur:
```
{
"error_code": 1,
"data": "User replicate failed on 1 of 3 connections"
}
```
**Resolution**
1. Determine which version of the user should be kept.
1. Delete the unwanted user in the appropirate cluster by running the `user delete` command. See [Delete an AWS CloudHSM user with CloudHSM CLI](cloudhsm_cli-user-delete.md) for more information.
1. Replicate the user by running the `user replicate` command.
## Problem: User replicate from hsm2m.medium to hsm1.medium fails
User replicate from hsm2m.medium to hsm1.medium is not supported. If replicating a user from a hsm2m.medium source cluster to a hsm1.medium destination cluster, the following error will occur:
```
{
"error_code": 1,
"data": "User replicate failed on 1 of 1 connections"
}
```
**Resolution**
+ Use [user management](manage-hsm-users-chsm-cli.md) with CloudHSM CLI to manually recreate the missing users.
# AWS CloudHSM Client SDK 5 key replicate failures
The `key replicate` command in the CloudHSM CLI replicates a key from a source AWS CloudHSM cluster to a destination AWS CloudHSM cluster. This guide addresses failures caused by inconsistencies within the source cluster or between the source and destination clusters.
## Problem: The selected key is not synchronized throughout the cluster
The key replication process checks for key synchronization throughout the source cluster. If any key information or attributes have the value "inconsistent", this means the key isn't synchronized across the cluster. Key replication fails with the following error message:
```
{
"error_code": 1,
"data": "The selected key is not synchronized throughout the cluster"
}
```
To check for key desynchronization in the source cluster:
1. Run the `key list` command in the CloudHSM CLI.
1. Use the `--filter `flag to specify the key.
1. Add the `--verbose` flag to see the full output with key coverage information.
```
aws-cloudhsm > key list --filter attr.label=example-desynchronized-key-label --verbose
{
"error_code": 0,
"data": {
"matched_keys": [
{
"key-reference": "0x000000000048000f",
"key-info": {
"key-owners": [
{
"username": "cu1",
"key-coverage": "full"
}
],
"shared-users": [],
"key-quorum-values": {
"manage-key-quorum-value": 0,
"use-key-quorum-value": 0
},
"cluster-coverage": "full"
},
"attributes": {
"key-type": "aes",
"label": "example-desynchronized-key-label",
"id": "0x",
"check-value": "0xbe79db",
"class": "secret-key",
"encrypt": false,
"decrypt": false,
"token": true,
"always-sensitive": true,
"derive": false,
"destroyable": true,
"extractable": true,
"local": true,
"modifiable": true,
"never-extractable": false,
"private": true,
"sensitive": true,
"sign": "inconsistent",
"trusted": false,
"unwrap": false,
"verify": true,
"wrap": false,
"wrap-with-trusted": false,
"key-length-bytes": 16
}
}
],
"total_key_count": 1,
"returned_key_count": 1
}
}
```
**Resolution: Synchronize key information and attributes throughout the source cluster**
To synchronize key information and attributes throughout the source cluster:
1. For inconsistent key attributes: Use the `key set-attribute` command to set the desired attribute for the specific key.
1. For inconsistent shared user coverage: Use the `key share` or `key unshare` commands to adjust key sharing with the desired users.
## Problem: Key with same reference exists in destination cluster with different information or attributes
If a key with the same reference exists in the destination cluster but has different information or attributes, the following error may occur:
```
{
"error_code": 1,
"data": "Key replicate failed on 1 of 3 connections"
}
```
**Resolution**
1. Determine which version of the key should be kept.
1. Delete the unwanted key version using the `key delete` command in the appropriate cluster.
1. Replicate the key from the cluster that has the correct version.
# AWS CloudHSM error seen during key availability check
**Problem**: An AWS CloudHSM hardware security module (HSM) is returning the following error:
```
Key does not meet the availability requirements - The key must be available on at least 2 HSMs before being used.
```
**Cause**: Key availability checks look for keys that, under rare but possible conditions, could be lost. This error usually occurs in clusters with only one HSM or in clusters with two HSMs during a period in which one of them is being replaced. In these situations, the following customer operations likely prompted the above error:
+ A new key was generated using a command like **[The generate-symmetric category in CloudHSM CLI](cloudhsm_cli-key-generate-symmetric.md)** or **[The generate-asymmetric-pair category in CloudHSM CLI](cloudhsm_cli-key-generate-asymmetric-pair.md)**.
+ A **[List keys for a user with CloudHSM CLI](cloudhsm_cli-key-list.md)** operation was started.
+ A new instance of the SDK was started.
**Note**
OpenSSL frequently forks new instances of the SDK.
**Resolution/recommendation**: Choose from the following actions to prevent this error from occurring:
+ Use the **--disable-key-availability-check** parameter to set key availability to false in the configure file of your [configure tool](configure-tool.md). For more information, see the [AWS CloudHSM Client SDK 5 configuration parameters](configure-tool-params5.md) section of the Configure tool.
+ If using a cluster with two HSMs, avoid using the operations that prompted the error, except during initialization code.
+ Increase the amount of HSMs in your cluster to at least three.
# AWS CloudHSM extracting keys using JCE
Use the following sections to troubleshoot issues extracting AWS CloudHSM keys using JCE.
## getEncoded, getPrivateExponent, or getS returns null
`getEncoded`, `getPrivateExponent`, and `getS` will return null because they are by default disabled. To enable them, refer to [Key extraction using JCE for AWS CloudHSM](java-lib-configs-getencoded.md).
If `getEncoded`, `getPrivateExponent`, and `getS` return null after being enabled, your key does not meet the right prerequisites. For more information, refer to [Key extraction using JCE for AWS CloudHSM](java-lib-configs-getencoded.md).
## getEncoded, getPrivateExponent, or getS return key bytes outside of the HSM
You or someone with access to your system has enabled clear key extraction. See the following pages for more information, including how to reset this configuration to the default disabled state.
+ [Key extraction using JCE for AWS CloudHSM](java-lib-configs-getencoded.md)
+ [Protecting and extracting keys from an HSM](bp-hsm-key-management.md#best-practices-key-protection)
# HSM throttling
When your workload exceeds your AWS CloudHSM cluster’s hardware security module (HSM) capacity, you will receive error messages stating HSMs are busy or throttled. When this happens, you may see reduced throughput or an increased rate of rejection requests from HSMs. Additionally, HSMs may send the following busy errors.
## For Client SDK 5
+ In PKCS11, busy errors map to `CKR_FUNCTION_FAILED`. This error can happen for multiple reasons, but if HSM throttling causes this error the following log lines will appear in your log:
+ `[cloudhsm_provider::hsm1::hsm_connection::e2e_encryption::error] Failed to prepare E2E response. Error: Received error response code from Server. Response Code: 187`
+ `[cloudhsm_pkcs11::decryption::aes_gcm] Received error from the server. Error: This operation is already in progress. Internal error code: 0x000000BB`
+ In JCE, busy errors map to `com.amazonaws.cloudhsm.jce.jni.exception.InternalException: Unexpected error with the Provider: The HSM could not queue the request for processing.`
+ Other SDKs' busy errors print out the following message: `Received error response code from Server. Response Code: 187`.
## For Client SDK 3
+ In PKCS11, busy errors map to `CKR_OPERATION_ACTIVE` errors.
+ In JCE, busy errors map to `CFM2Exception` with status of `0xBB (187)`. Applications can use `getStatus()` function on `CFM2Exception` to check what status is returned by the HSM.
+ Other SDKs busy errors will print out the following message: `HSM Error: HSM is already busy generating the keys(or random bytes) for another request.`
## Resolution
You can resolve these issues by completing one or more of the following actions:
+ Add retry commands for rejected HSM operations in your application layer. Before enabling retry commands, ensure your cluster is adequately sized to meet peak loads.
**Note**
For Client SDK 5.8.0 and above, retry commands are turned on by default. For details on each SDK’s retry command configuration, refer to [Advanced configurations for the Client SDK 5 configure tool](configure-sdk5-advanced-configs.md).
+ Add more HSMs to your cluster by following the instructions in [Scaling HSMs in an AWS CloudHSM cluster](add-remove-hsm.md).
**Important**
We recommend load testing your cluster to determine the peak load you should anticipate, and then add one more HSM to it to ensure high availability.
# Keep HSM users in sync across HSMs in the AWS CloudHSM cluster
To [manage your HSM's users](manage-hsm-users.md), you use a AWS CloudHSM command line tool known as cloudhsm\$1mgmt\$1util. It communicates only with the HSMs that are in the tool's configuration file. It's not aware of other HSMs in the cluster that are not in the configuration file.
AWS CloudHSM synchronizes the keys on your HSMs across all other HSMs in the cluster, but it doesn't synchronize the HSM's users or policies. When you use cloudhsm\$1mgmt\$1util to [manage HSM users](manage-hsm-users.md), these user changes might affect only some of the cluster's HSMs—the ones that are in the cloudhsm\$1mgmt\$1util configuration file. This can cause problems when AWS CloudHSM syncs keys across HSMs in the cluster, because the users that own the keys might not exist on all HSMs in the cluster.
To avoid these problems, edit the cloudhsm\$1mgmt\$1util configuration file *before* managing users. For more information, see [Prerequisites for user management in AWS CloudHSM Management Utility](understand-users.md).
# Lost connection to the AWS CloudHSM cluster
When you [configured the AWS CloudHSM client](cmu-install-and-configure-client-linux.md#cmu-edit-client-configuration), you provided the IP address of the first HSM in your cluster. This IP address is saved in the configuration file for the AWS CloudHSM client. When the client starts, it tries to connect to this IP address. If it can't—for example, because the HSM failed or you deleted it—you might see errors like the following:
```
LIQUIDSECURITY: Daemon socket connection error
```
```
LIQUIDSECURITY: Invalid Operation
```
To resolve these errors, update the configuration file with the IP address of an active, reachable HSM in the cluster.
**To update the configuration file for the AWS CloudHSM client**
1. Use one of the following ways to find the IP address of an active HSM in your cluster.
+ View the **HSMs** tab on the cluster details page in the [AWS CloudHSM console](https://console.aws.amazon.com/cloudhsm/home).
+ Use the AWS Command Line Interface (AWS CLI) to issue the [https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html](https://docs.aws.amazon.com/cli/latest/reference/cloudhsmv2/describe-clusters.html) command.
You need this IP address in a subsequent step.
1. Use the following command to stop the client.
------
#### [ Amazon Linux ]
```
$ sudo stop cloudhsm-client
```
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ CentOS 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo service cloudhsm-client stop
```
------
#### [ Windows ]
+ For Windows client 1.1.2\$1:
```
C:\Program Files\Amazon\CloudHSM>net.exe stop AWSCloudHSMClient
```
+ For Windows clients 1.1.1 and older:
Use **Ctrl**\$1**C** in the command window where you started the AWS CloudHSM client.
------
1. Use the following command to update the client's configuration file, providing the IP address that you found in a previous step.
```
$ sudo /opt/cloudhsm/bin/configure -a
```
1. Use the following command to start the client.
------
#### [ Amazon Linux ]
```
$ sudo start cloudhsm-client
```
------
#### [ Amazon Linux 2 ]
```
$ sudo service cloudhsm-client start
```
------
#### [ CentOS 7 ]
```
$ sudo service cloudhsm-client start
```
------
#### [ CentOS 8 ]
```
$ sudo service cloudhsm-client start
```
------
#### [ RHEL 7 ]
```
$ sudo service cloudhsm-client start
```
------
#### [ RHEL 8 ]
```
$ sudo service cloudhsm-client start
```
------
#### [ Ubuntu 16.04 LTS ]
```
$ sudo service cloudhsm-client start
```
------
#### [ Ubuntu 18.04 LTS ]
```
$ sudo service cloudhsm-client start
```
------
#### [ Windows ]
+ For Windows client 1.1.2\$1:
```
C:\Program Files\Amazon\CloudHSM>net.exe start AWSCloudHSMClient
```
+ For Windows clients 1.1.1 and older:
```
C:\Program Files\Amazon\CloudHSM>start "cloudhsm_client" cloudhsm_client.exe C:\ProgramData\Amazon\CloudHSM\data\cloudhsm_client.cfg
```
------
# Missing AWS CloudHSM audit logs in CloudWatch
If you created an AWS CloudHSM cluster before January 20th, 2018, you will need to manually configure a [service-linked role](service-linked-roles.md) in order to enable the delivery of that cluster's audit logs. For instructions on how to enable a service-linked role on an HSM cluster, see [Understanding Service-Linked Roles](service-linked-roles.md), as well as [Creating a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role) in the IAM User Guide.
# Custom IVs with non-compliant length for AES key wrap in AWS CloudHSM
This troubleshooting topic helps you determine if your application generates irrecoverable wrapped keys. If you are impacted by this issue, use this topic to address the problem.
**Topics**
+ [
## Determine whether your code generates irrecoverable wrapped keys
](#troubleshooting-problem1)
+ [
## Actions you must take if your code generates irrecoverable wrapped keys
](#troubleshooting-problem2)
## Determine whether your code generates irrecoverable wrapped keys
You are impacted only if you meet *all* the conditions below:
****
| Condition | How do I know? |
| --- | --- |
| Your application uses PKCS \$111 library | The PKCS \$111 library is installed as the `libpkcs11.so` file in your `/opt/cloudhsm/lib` folder. Applications written in the C language generally use the PKCS \$111 library directly, while application written in Java may be using the library indirectly via a Java abstraction layer. If you're using Windows, you are NOT affected, as PKCS \$111 library is not presently available for Windows. |
| Your application specifically uses version 3.0.0 of the PKCS \$111 library | If you received an email from the AWS CloudHSM team, you are likely using version 3.0.0 of the PKCS \$111 library. To check the software version on your application instances, use this command: rpm -qa | grep ^cloudhsm
|
| You wrap keys using AES key wrapping | AES key wrapping means you use an AES key to wrap out some other key. The corresponding mechanism name is `CKM_AES_KEY_WRAP`. It is used with the function `C_WrapKey`. Other AES based wrapping mechanisms that use initialization vectors (IVs), such as `CKM_AES_GCM` and` CKM_CLOUDHSM_AES_GCM`, are not affected by this issue. [Learn more about functions and mechanisms](pkcs11-mechanisms.md). |
| You specify a custom IV when calling AES key wrapping, and the length of this IV is shorter than 8 | AES key wrap is generally initialized using a `CK_MECHANISM` structure as follows: `CK_MECHANISM mech = {CKM_AES_KEY_WRAP, IV_POINTER, IV_LENGTH};` This issue applies to you only if: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/cloudhsm/latest/userguide/troubleshooting-aes-keys.html) |
If you do not meet all the conditions above, you may stop reading now. Your wrapped keys can be unwrapped properly, and this issue does not impact you. Otherwise, see [Actions you must take if your code generates irrecoverable wrapped keys](#troubleshooting-problem2).
## Actions you must take if your code generates irrecoverable wrapped keys
You should take the following three steps:
1. **Immediately upgrade your PKCS \$111 library to a newer version**
+ [Latest PKCS \$111 library for Amazon Linux, CentOS 6 and RHEL 6](client-upgrade.md)
+ [Latest PKCS \$111 library for Amazon Linux 2, CentOS 7 and RHEL 7](client-upgrade.md)
+ [Latest PKCS \$111 library for Ubuntu 16.04 LTS](client-upgrade.md)
1. **Update your software to use a standards-compliant IV **
We strongly recommend you follow our sample code and simply specify a NULL IV, which causes the HSM to utilize the standards-compliant default IV. Alternatively, you may explicitly specify the IV as `0xA6A6A6A6A6A6A6A6` with a corresponding IV length of `8`. We do not recommend using any other IV for AES key wrapping, and will explicitly disable custom IVs for AES key wrapping in a future version of the PKCS \$111 library.
Sample code for properly specifying the IV appears in [aes\$1wrapping.c](https://github.com/aws-samples/aws-cloudhsm-pkcs11-examples/blob/master/src/wrapping/aes_wrapping.c#L72) on GitHub.
1. **Identify and recover existing wrapped keys**
You should identify any keys you wrapped using version 3.0.0 of the PKCS \$111 library, and then contact support for assistance ([https://aws.amazon.com/support](https://aws.amazon.com/support)) in recovering these keys.
**Important**
This issue only impacts keys wrapped with version 3.0.0 of the PKCS \$111 library. You can wrap keys using earlier versions (2.0.4 and lower-numbered packages) or later versions (3.0.1 and higher-numbered packages) of the PKCS \$111 library.
# Resolving AWS CloudHSM cluster creation failures
When you create a cluster, AWS CloudHSM creates the AWSServiceRoleForCloudHSM service-linked role, if the role does not already exist. If AWS CloudHSM cannot create the service-linked role, your attempt to create a cluster might fail.
This topic explains how to resolve the most common problems so you can create a cluster successfully. You need to create this role only one time. Once the service-linked role is created in your account, you can use any of the supported methods to create additional clusters and to manage them.
The following sections offer suggestions to troubleshoot cluster creation failures that are related to the service-linked role. If you try them but are still unable to create a cluster, contact [Support](https://aws.amazon.com/contact-us/). For more information about the AWSServiceRoleForCloudHSM service-linked role, see [Service-linked roles for AWS CloudHSM](service-linked-roles.md).
**Topics**
+ [
## Add the missing permission
](#missing-permission)
+ [
## Create the service-linked role manually
](#api-call-failure)
+ [
## Use a non-federated user
](#non-federated-user)
## Add the missing permission
To create a service-linked role, the user must have the `iam:CreateServiceLinkedRole` permission. If the IAM user who is creating the cluster does not have this permission, the cluster creation process fails when it tries to create the service-linked role in your AWS account.
When a missing permission causes the failure, the error message includes the following text.
```
This operation requires that the caller have permission to call iam:CreateServiceLinkedRole to create the CloudHSM Service Linked Role.
```
To resolve this error, give the IAM user who is creating the cluster the `AdministratorAccess` permission or add the `iam:CreateServiceLinkedRole` permission to the user's IAM policy. For instructions, see [Adding Permissions to a New or Existing User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#w2ab1c19c19c26b9).
Then try to [create the cluster](create-cluster.md) again.
## Create the service-linked role manually
You can use the IAM console, CLI, or API to create the AWSServiceRoleForCloudHSM service-linked role. For more information, see [Creating a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role) in the *IAM User Guide*.
## Use a non-federated user
Federated users, whose credentials originate outside of AWS, can perform many of the tasks of a non-federated user. However, AWS does not allow users to make the API calls to create a service-linked role from a federated endpoint.
To resolve this problem, [create a non-federated user](create-iam-user.md) with the `iam:CreateServiceLinkedRole` permission, or give an existing non-federated user the `iam:CreateServiceLinkedRole` permission. Then have that user [create a cluster](create-cluster.md) from the AWS CLI. This creates the service-linked role in your account.
Once the service-linked role is created, if you prefer, you can delete the cluster that the non-federated user created. Deleting the cluster does not affect the role. Thereafter, any user with the required permissions, included federated users, can create AWS CloudHSM clusters in your account.
To verify that the role was created, open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/) and choose **Roles**. Or use the IAM [get-role](https://docs.aws.amazon.com/cli/latest/reference/iam/get-role.html) command in the AWS CLI.
```
$ aws iam get-role --role-name AWSServiceRoleForCloudHSM
{
"Role": {
"Description": "Role for CloudHSM service operations",
role policy statement
"RoleId": "AROAJ4I6WN5QVGG5G7CBY",
"CreateDate": "2017-12-19T20:53:12Z",
"RoleName": "AWSServiceRoleForCloudHSM",
"Path": "/aws-service-role/cloudhsm.amazonaws.com/",
"Arn": "arn:aws:iam::111122223333:role/aws-service-role/cloudhsm.amazonaws.com/AWSServiceRoleForCloudHSM"
}
}
```
# Retrieving AWS CloudHSM client configuration logs
AWS CloudHSM offers tools for Client SDK 3 and Client SDK 5 to gather information about your environment for AWS Support to troubleshoot problems.
**Topics**
+ [
# AWS CloudHSM Client SDK 5 support tool
](support-tool-sdk5.md)
+ [
# AWS CloudHSM Client SDK 3 support tool
](support-tool-sdk3.md)
# AWS CloudHSM Client SDK 5 support tool
The script for AWS CloudHSM Client SDK 5 extracts the following information:
+ The configuration file for the Client SDK 5 component
+ Available log files
+ Current version of the operating system
+ Package information
## Running the info tool for Client SDK 5
Client SDK 5 includes a client support tool for each component, but all tools function the same. Run the tool to create an output file with all the gathered information.
The tools use a syntax like this:
```
[ pkcs11 | dyn | jce | ksp | cli]_info
```
For example, to gather information for support from a Linux host running PKCS \$111 library and have the system write to the default directory, you would run this command:
```
/opt/cloudhsm/bin/pkcs11_info
```
The tool creates the output file inside the `/tmp` directory.
------
#### [ AWS CloudHSM CLI ]
**To gather support data for AWS CloudHSM CLI on Linux**
+ Use the support tool to gather data.
```
/opt/cloudhsm/bin/cli_info
```
**To gather support data for AWS CloudHSM on Windows**
+ Use the support tool to gather data.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\cli_info.exe"
```
------
#### [ PKCS \$111 library ]
**To gather support data for PKCS \$111 library on Linux**
+ Use the support tool to gather data.
```
/opt/cloudhsm/bin/pkcs11_info
```
**To gather support data for PKCS \$111 library on Windows**
+ Use the support tool to gather data.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\pkcs11_info.exe"
```
------
#### [ OpenSSL Dynamic Engine ]
**To gather support data for OpenSSL Dynamic Engine on Linux**
+ Use the support tool to gather data.
```
/opt/cloudhsm/bin/dyn_info
```
------
#### [ JCE provider ]
**To gather support data for JCE provider on Linux**
+ Use the support tool to gather data.
```
/opt/cloudhsm/bin/jce_info
```
**To gather support data for JCE provider on Windows**
+ Use the support tool to gather data.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\jce_info.exe"
```
------
#### [ Key Storage Provider ]
**To gather support data for Key Storage Provider on Windows**
+ Use the support tool to gather data.
```
PS C:\> & "C:\Program Files\Amazon\CloudHSM\bin\ksp_info.exe"
```
------
## Retrieving logs from a serverless environment
To configure for serverless environments, like Fargate or Lambda, we recommend you configure your AWS CloudHSM log type to `term`. Once configured to `term`, the serverless environment will be able to output to CloudWatch.
To get the client logs from CloudWatch, see [Working with log groups and log streams](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/Working-with-log-groups-and-streams.html) in the Amazon CloudWatch Logs User Guide.
# AWS CloudHSM Client SDK 3 support tool
The script for the AWS CloudHSM Client SDK 3 extracts the following information:
+ Operating system and its current version
+ Client configuration information from `cloudhsm_client.cfg`, `cloudhsm_mgmt_util.cfg`, and `application.cfg` files
+ Client logs from the location specific to the platform
+ Cluster and HSM information by using cloudhsm\$1mgmt\$1util
+ OpenSSL information
+ Current client and build version
+ Installer version
## Running the info tool for Client SDK 3
The script creates an output file with all the gathered information. The script creates the output file inside the `/tmp` directory.
**Linux**: `/opt/cloudhsm/bin/client_info`
**Windows**: `C:\Program Files\Amazon\CloudHSM\client_info`
**Warning**
This script has a known issue for Client SDK 3 versions 3.1.0 through 3.3.1. We strongly recommend you upgrade to version 3.3.2 which includes a fix for this issue. Please refer to the [Known Issues](https://docs.aws.amazon.com/cloudhsm/latest/userguide/ki-all.html#ki-all-9) page for more information before using this tool.