Prepare by addressing breaking changes Migrate to Client SDK 5 Related topics

Migrate your PKCS #11 library from Client SDK 3 to Client SDK 5

Use this topic to migrate your PKCS #11 library from Client SDK 3 to Client SDK 5. For benefits on migrating, see Benefits of Client SDK 5.

In AWS CloudHSM, customer applications perform cryptographic operations using the AWS CloudHSM Client Software Development Kit (SDK). Client SDK 5 is the primary SDK that continues to have new features and platform support added to it.

To review migration instructions for all providers, see Migrating from Client SDK 3 to Client SDK 5.

Prepare by addressing breaking changes

Review these breaking changes and update your application in your development environment accordingly.

Wrap mechanisms have changed

Client SDK 3 mechanism	Equivalent Client SDK 5 mechanism
`CKM_AES_KEY_WRAP`	`CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`
`CKM_AES_KEY_WRAP_PAD`	`CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`
`CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`	`CKM_CLOUDHSM_AES_KEY_WRAP_PKCS5_PAD`
`CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD`	`CKM_CLOUDHSM_AES_KEY_WRAP_NO_PAD`
`CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`	`CKM_CLOUDHSM_AES_KEY_WRAP_ZERO_PAD`

ECDH

In Client SDK 3, you can use ECDH and specify a KDF. This functionality is not currently available in Client SDK 5. If your application needs this functionality, please reach out to support.

Key handles are now session-specific

To successfully use key handles in Client SDK 5, you must obtain key handles each time you run an application. If you have existing applications that will use the same key handles across different sessions, you must modify your code to obtain the key handle each time you run the application. For information on retrieving key handles, see this AWS CloudHSM PKCS #11 example. This change is in compliance with the PKCS #11 2.40 specification.

Migrate to Client SDK 5

Follow the instructions in this section to migrate from Client SDK 3 to Client SDK 5.

Note

Amazon Linux, Ubuntu 16.04, Ubuntu 18.04, CentOS 6, CentOS 8, and RHEL 6 are not currently supported with Client SDK 5. If you are currently using one of these platforms with Client SDK 3, you will need to choose a different platform when migrating to Client SDK 5.

Uninstall the PKCS #11 library for Client SDK 3.

Uninstall the Client Daemon for Client SDK 3.

Note

Custom configurations need to be enabled again.

Install the Client SDK PKCS #11 library by following the steps in Install the PKCS #11 library for Client SDK 5.
Client SDK 5 introduces a new configuration file format and command-line bootstrapping tool. To bootstrap your Client SDK 5 PKCS #11 library, follow the instructions listed in the user guide under Bootstrap the Client SDK.
In your development environment, test your application. Make updates to your existing code to resolve your breaking changes before your final migration.