Overview

IBM Cloud® Hyper Protect Crypto Services is a dedicated key management service and hardware security module (HSM). This service allows you to take ownership of a cloud HSM to fully manage your encryption keys and to perform cryptographic operations. Hyper Protect Crypto Services is also the only service in the cloud industry that is built on FIPS 140-2 Level 4-certified hardware.

Installing the PKCS #11 files

The files contained in this repository allow clients to access a cloud HSM via the HPCS service using a PKCS #11 library and its associated configuration file. The files are categorized by releases, which can be accessed from the hpcs-pkcs11 repository's releases URL.

NOTE: The PKCS #11 library, for both the amd64 and s390x platforms, is currently supported only on Linux.

There are two files used along with your PKCS #11 application:

1. The PKCS #11 library: pkcs11-grep11-platform.so.major.minor.build

   • platform is amd64 or s390x

   • major.minor.build refers to the version of the library

   • NOTE: Refer to step 1 of the IBM Cloud HPCS documentation topic, Set up the PKCS #11 library, for instructions on where to place the PKCS #11 library file.

2. The PKCS #11 client configuration file: grep11client.yaml

   • Before you update the configuration file, PKCS #11 users must first be set up. Follow the steps outlined in the IBM Cloud Hyper Protect Crypto Services documentation topic, Best practices for setting up PKCS #11 user types, to complete the PKCS #11 user setup tasks.

   • Changes to the configuration file are needed after you download it. Update the grep11client.yaml configuration file by following step 3 of the IBM Cloud Hyper Protect Crypto Services documentation topic: Set up the PKCS #11 configuration file

   • NOTE: The grep11client.yaml configuration file must be moved into the same directory as the application (e.g., pkcs11-tool) using the PKCS #11 library or in the directory /etc/ep11client.

Verify the integrity and authenticity of the PKCS #11 library

For maximum security, you can optionally verify the integrity and authenticity of the PKCS #11 library. Hyper Protect Crypto Services enable signed code verification to ensure that the signature matches the original code. If the downloaded PKCS #11 library file is altered or corrupted, a different signature is produced and the verification fails. To make sure the files are not tampered with or corrupted during the download process, complete the following steps by using the OpenSSL command-line tool.

1. Download the latest version of the following files from the hpcs-pkcs11 repository's releases URL to the same directory where you store the PKCS #11 library:

   • pkcs11-grep11-<platform>.so.<version>.sig: The signed cryptographic hash of the PKCS #11 library, where platform is either amd64 or s390x and version is the major.minor.build (e.g., 2.3.4) of the signature file. Both platform and version must match the respective platform and version of the PKCS #11 library that is used.

   • signing_cert.pem: The signing certificate for the HPCS PKCS #11 files.

   • digicert_cert.pem: An intermediate code signing certificate to prove the Hyper Protect Crypto Services PKCS #11 files signing certificate.

2. Extract the public key from the signing certificate signing_cert.pem to the sigkey.pub file with the following command by using the OpenSSL command-line tool:

   openssl x509 -pubkey -noout -in signing_cert.pem -out sigkey.pub

3. Verify the integrity of the PKCS #11 library file with the following command:

   openssl dgst -sha256 -verify sigkey.pub -signature pkcs11-grep11-<platform>.so.<version>.sig pkcs11-grep11-<platform>.so.<version>

   NOTE: Replace platform with either amd64 or s390x and replace version with the major.minor.build (e.g., 2.3.4) of the library.

   When the verification is successful, Verified OK is displayed.

4. Verify the authenticity and validity of the signing certificate with the following command:

   openssl ocsp -no_nonce -issuer digicert_cert.pem -cert signing_cert.pem -VAfile digicert_cert.pem -text -url http://ocsp.digicert.com -respout ocsptest

   When the verification is successful, Response verify OK and signing_cert.pem: good are displayed in the output.

5. If the verification fails, cancel the installation and contact IBM for support.

Initializing the Keystores

Prior to using the PKCS #11 library, the keystores must be initialized. To initialize the keystores, the security officer (SO) user needs to perform a C_InitToken operation. Once the keystores have been initialized, normal and anonymous users can proceed with key operations such as C_GenerateKey or C_GenerateKeyPair.

A keystore becomes an authenticated keystore if it is configured with a password. For more details please check Performing cryptographic operations with the PKCS #11 API.

Getting started

The samples directory in this repository contains source code that could be used to test your HPCS instance, the PKCS11 library, and the PKCS11 library's configuration file. Follow the instructions inside pkcs11-crypto.c to get started.

The sample code performs the following operations:

• Intialize a token
• Open a session
• Login as a normal user
• Create an AES key
• Create an EC key pair
• Encrypt data and decrypt data using the AES key
• Sign and verify data using the EC key pair
• Logout, close session and finalize

pkcs11-dilithium.c demonstrates how to generate a Dilithium key pair, followed by signing and verifying data using the Dilithium key pair.

Attributes

We support a subset of attributes of the PKCS#11 specification. The following table shows:

1. Which attributes are allowed to be used for PKCS11 requests (key generation, unwrapping, and key derivation).
2. Data type of each attribute and the key types that are applicable.
3. What attributes are generated after key or key pairs are generated.

Attribute	Category	Applies to key types	Allowed in template	Value type	Library default	Filled by HPCS	Read only After generation
CKA_CLASS	1	All	y	Integer	Depends 1		y
CKA_TOKEN	3	All	y	Bool	FALSE		y
CKA_PRIVATE	3	All	y	Bool	Depends 2		y
CKA_MODIFIABLE	3	All	y	Bool	TRUE	y	Read only if FALSE
CKA_LABEL	4	All	y	Bytes	empty
CKA_KEY_TYPE	1	All	y	Integer			y
CKA_ID	4	All	y	Bytes	empty
CKA_DERIVE	1	All	y	Bool	FALSE
CKA_LOCAL	1	All but public key		Bool		y	y
CKA_KEY_GEN_MECHANISM	2	All		Integer		y	y
CKA_GREP11_WKID	2	private key secret key		Big integer		y	y
CKA_SUBJECT	4	public key private key	y	Bytes	empty
CKA_ENCRYPT CKA_DECRYPT CKA_SIGN CKA_VERIFY CKA_WRAP CKA_UNWRAP	1	All when allowed  by algorithm	y	Bool		y
CKA_SENSITIVE	2	private key secret key	y	Bool			y
CKA_ALWAYS_SENSITIVE	2	private key secret key		Bool		y	y
CKA_WRAP_WITH_TRUSTED	1	private key secret key	y	Bool	FALSE	y
CKA_EXTRACTABLE	1	private key secret key	y	Bool	FALSE	y	Read only if FALSE
CKA_NEVER_EXTRACTABLE	1	private key secret key		Bool		y	y
CKA_CHECK_VALUE	2	secret key		Bytes		y	y
CKA_TRUSTED	1	public key secret key	y	Bool		y
CKA_PUBLIC_KEY_INFO	2	public key	y	Bool		y	y
CKA_MODULUS_BITS	1	RSA public key	y	Integer			y
CKA_MODULUS	2	RSA public key RSA private key		Big integer		y	y
CKA_PUBLIC_EXPONENT	1	RSA public key RSA private key	y	Big integer			y
CKA_EC_PARAMS	1	EC public key EC private key	y	Bytes			y
CKA_EC_POINT	2	EC public key		Bytes		y	y
CKA_VALUE_LEN	1	Generate secret key AES key	y	integer			y
CKA_IBM_PQC_PARAMS	1	Dilithium public key	y	Bytes			y

1. Default value of CKA_CLASS is based on mechanisms and key types:

Function	Mechanism	Default value
GenerateKey	CKM_AES_KEY_GEN CKM_DES2_KEY_GEN CKM_DES3_KEY_GEN CKM_GENERIC_SECRET_KEY_GEN	CKO_SECRET_KEY
GenerateKeyPairs	CKM_EC_KEY_PAIR_GEN CKM_RSA_PKCS_KEY_PAIR_GEN CKM_RSA_X9_31_KEY_PAIR_GEN CKM_IBM_DILITHIUM	CKO_PUBLIC_KEY & CKO_PRIVATE_KEY
UnwrapKey	CKM_AES_CBC CKM_AES_CBC_PAD CKM_DES3_CBC CKM_DES3_CBC_PAD CKM_RSA_PKCS CKM_RSA_PKCS_OAEP	CKO_SECRET_KEY if key type is AES, DES2 or DES3. Otherwise, the default is CKO_PRIVATE_KEY
DeriveKey		CKO_SECRET_KEY

2. Default value of CKA_PRIVATE is TRUE if the Normal user is logged in, otherwise, it is FALSE