Client SDK 5 configure tool
Use the Client SDK 5 configure tool to update client-side configuration files.
Each component in Client SDK 5 includes a configure tool with a designator of the component
in the file name of the configure tool. For example, the PKCS #11 library for Client SDK 5 includes a
configure tool named configure-pkcs11 on Linux or
configure-pkcs11.exe on Windows.
Syntax
Advanced configurations
For a list of advanced configurations specific to the Client SDK 5 configure tool, refer to Advanced configurations for the Client SDK 5 configure tool.
Important
After making any changes to your configuration, you need to restart your application for the changes to take effect.
Examples
These examples show how to use the configure tool for Client SDK 5.
This example uses the -a parameter to update the HSM data for
Client SDK 5. To use the -a parameter, you must have the IP address
for one of the HSMs in your cluster.
Note
you can use the –-cluster-id parameter in place of -a <HSM_IP_ADDRESSES>. To see requirements for using –-cluster-id, see Client SDK 5 configure tool.
For more information about the -a parameter, see Parameters.
This example uses the cluster-id parameter to bootstrap Client SDK 5 by making
a DescribeClusters call.
You can use the --region and --endpoint parameters in combination with
the cluster-id parameter to specify how the system makes the
DescribeClusters call. For instance, if the region of the cluster is different than
the one configured as your AWS CLI default, you should use the --region parameter to
use that region. Additionally, you have the ability to specify the AWS CloudHSM API endpoint to use for
the call, which might be necessary for various network setups, such as using VPC interface
endpoints that don’t use the default DNS hostname for AWS CloudHSM.
For more information about the --cluster-id, --region,
and --endpoint parameters, see Parameters.
This examples shows how to use the --server-client-cert-file and --server-client-key-file parameters to reconfigure
SSL by specifying a custom key and SSL certificate for AWS CloudHSM
For more information about the --server-client-cert-file and
--server-client-key-file parameters, see Parameters.
This examples shows how to use the --client-cert-hsm-tls-file and --client-key-hsm-tls-file parameters to reconfigure
SSL by specifying a custom key and SSL certificate for AWS CloudHSM
For more information about the --client-cert-hsm-tls-file and
--client-key-hsm-tls-file parameters, see Parameters.
This example uses the --disable-key-availability-check parameter to
disable client key durability settings. To run a cluster with a single HSM, you must
disable client key durability settings.
For more information about the --disable-key-availability-check
parameter, see Parameters.
Client SDK 5 uses the log-file, log-level,
log-rotation, and log-type parameters to manage logging.
Note
To configure your SDK for serverless environments such as AWS Fargate or AWS Lambda, we recommend you configure your AWS CloudHSM log type to term.
The client logs will be output to stderr and captured in the CloudWatch Logs log group configured for that environment.
For more information about the log-file, log-level,
log-rotation,and log-type parameters, see Parameters.
This example uses the --hsm-ca-cert parameter to update the location of the
issuing certificate for Client SDK 5.
For more information about the --hsm-ca-cert parameter, see Parameters.
Parameters
- -a
<ENI IP address> -
Adds the specified IP address to Client SDK 5 configuration files. Enter any ENI IP address of an HSM from the cluster. For more information about how to use this option, see Bootstrap Client SDK 5.
Required: Yes
- --hsm-ca-cert
<customerCA certificate file path> -
Path to the directory storing the certificate authority (CA) certificate use to connect EC2 client instances to the cluster. You create this file when you initialize the cluster. By default, the system looks for this file in the following location:
Linux
/opt/cloudhsm/etc/customerCA.crtWindows
C:\ProgramData\Amazon\CloudHSM\customerCA.crtFor more information about initializing the cluster or placing the certificate, see Place the issuing certificate on each EC2 instance and Initialize the cluster.
Required: No
- --cluster-id
<cluster ID> -
Makes a
DescribeClusterscall to find all of the HSM elastic network interface (ENI) IP addresses in the cluster associated with the cluster ID. The system adds the ENI IP addresses to the AWS CloudHSM configuration files.Note
If you use the
--cluster-idparameter from an EC2 instance within a VPC that does not have access to the public internet, then you must create an interface VPC endpoint to connect with AWS CloudHSM. For more information about VPC endpoints, see AWS CloudHSM and VPC endpoints.Required: No
- --endpoint
<endpoint> -
Specify the AWS CloudHSM API endpoint used for making the
DescribeClusterscall. You must set this option in combination with--cluster-id.Required: No
- --region
<region> -
Specify the region of your cluster. You must set this option in combination with
--cluster-id.If you don’t supply the
--regionparameter, the system chooses the region by attempting to read theAWS_DEFAULT_REGIONorAWS_REGIONenvironment variables. If those variables aren’t set, then the system checks the region associated with your profile in your AWS config file (typically~/.aws/config) unless you specified a different file in theAWS_CONFIG_FILEenvironment variable. If none of the above are set, the system defaults to theus-east-1region.Required: No
- --server-client-cert-file
<client certificate file path> -
Path to the client certificate used for TLS client-server mutual authentication.
Only use this option if you don’t wish to use the default key and SSL/TLS certificate we include with Client SDK 5. You must set this option in combination with
--server-client-key-file.Required: No
- --server-client-key-file
<client key file path> -
Path to the client key used for TLS client-server mutual authentication.
Only use this option if you don’t wish to use the default key and SSL/TLS certificate we include with Client SDK 5. You must set this option in combination with
--server-client-cert-file.Required: No
- --client-cert-hsm-tls-file
<client certificate hsm tls path> -
Path to the client certificate used for TLS client-HSM mutual authentication.
Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with
--client-key-hsm-tls-file.Required: No
- --client-key-hsm-tls-file
<client key hsm tls path> -
Path to the client key used for TLS client-HSM mutual authentication.
Only use this option if you have registered at least one trust anchor onto HSM with CloudHSM CLI. You must set this option in combination with
--client-cert-hsm-tls-file.Required: No
- --log-level
<error | warn | info | debug | trace> -
Specifies the minimum logging level the system should write to the log file. Each level includes the previous levels, with error as the minimum level and trace the maximum level. This means that if you specify errors, the system only writes errors to the log. If you specify trace, the system writes errors, warnings, informational (info) and debug messages to the log. For more information, see Client SDK 5 Logging.
Required: No
- --log-rotation
<daily | weekly> -
Specifies the frequency with which the system rotates logs. For more information, see Client SDK 5 Logging.
Required: No
- --log-file
<file name with path> -
Specifies where the system will write the log file. For more information, see Client SDK 5 Logging.
Required: No
- --log-type
<term | file> -
Specifies whether the system will write the log to a file or terminal. For more information, see Client SDK 5 Logging.
Required: No
- -h | --help
-
Displays help.
Required: No
- -v | --version
-
Displays version.
Required: No
- --disable-key-availability-check
-
Flag to disable key availability quorum. Use this flag to indicate AWS CloudHSM should disable key availability quorum and you can use keys that exist on only one HSM in the cluster. For more information about using this flag to set key availability quorum, see Managing client key durability settings.
Required: No
- --enable-key-availability-check
-
Flag to enable key availability quorum. Use this flag to indicate AWS CloudHSM should use key availability quorum and not allow you to use keys until those keys exist on two HSMs in the cluster. For more information about using this flag to set key availability quorum, see Managing client key durability settings.
Enabled by default.
Required: No
- --disable-validate-key-at-init
-
Improves performance by specifying that you can skip an initialization call to verify permissions on a key for subsequent calls. Use with caution.
Background: Some mechanisms in the PKCS #11 library support multi-part operations where an initialization call verifies if you can use the key for subsequent calls. This requires a verification call to the HSM, which adds latency to the overall operation. This option enables you to disable the subsequent call and potentially improve performance.
Required: No
- --enable-validate-key-at-init
-
Specifies that you should use an initialization call to verify permissions on a key for subsequent calls. This is the default option. Use
enable-validate-key-at-initto resume these initialization calls after you usedisable-validate-key-at-initto suspend them.Required: No
Related topics
-
DescribeClusters API operation
-
describe-clusters AWS CLI
-
Get-HSM2Cluster PowerShell cmdlet
