Use this topic to migrate your AWS CloudHSM PKCS #11 library from Client SDK 3 to Client SDK 5. For benefits on migrating, see Benefits of AWS CloudHSM 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 AWS CloudHSM 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
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
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.
$sudo yum remove cloudhsm-client-pkcs11 -
Uninstall the Client Daemon for Client SDK 3.
$sudo yum remove cloudhsm-clientNote
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 AWS CloudHSM 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.
Related topics
