This repository contains some example best practices for open source repositories:
Warning
Disclaimer: The software provided here is for the Key Protect product with the "Dedicated" pricing plan.
IBM Cloud® Key Protect has a dedicated key management offering. This service allows you to take ownership of a cloud HSM to fully manage your encryption keys and to perform cryptographic operations.
The files contained in this repository allow clients to access a cloud HSM via the Key Protect service using a PKCS #11 library and its associated configuration file. The files are categorized by releases, which can be accessed from the key-protect-pkcs11 repository's releases URL.
NOTE: The PKCS #11 library is currently supported only on Linux amd64(GLIBC distros only, so not compatible with Alpine for now) and Darwin arm64.
There are two files used along with your PKCS #11 application:
-
The PKCS #11 library: pkcs11-grep11-platform.so.major.minor.build (Linux) or pkcs11-grep11-platform.major.minor.build.dylib (macOS)
-
platform is amd64 or arm64
-
major.minor.build refers to the version of the library
-
-
The PKCS #11 header files, included in the release alongside the library:
-
pkcs11.h: The main PKCS #11 header. It includes pkcs11t.h and pkcs11f.h.
-
pkcs11t.h: The standard PKCS #11 types and constants.
-
pkcs11f.h: The standard PKCS #11 function prototypes.
-
libpkcs11-kms.h: The header for the library's own declarations.
-
The headers are needed only when you build your own application against the PKCS #11 library. Add the directory that contains them to your compiler's include path (e.g.,
-I<path-to-headers>) and use#include "pkcs11.h". -
Applications that load the library at runtime, such as pkcs11-tool, do not need the header files.
-
For maximum security, you can optionally verify the integrity and authenticity of the PKCS #11 library. The library is published with a detached GPG signature. If the downloaded PKCS #11 library file is altered or corrupted, the signature check fails. To make sure the files are not tampered with or corrupted during the download process, complete the following steps by using the GnuPG command-line tool.
-
Download the following files from the
key-protect-pkcs11repository's releases URL to the same directory where you store the PKCS #11 library:-
libpkcs11-kms.so.sig: The detached signature of the PKCS #11 library. Use the signature file that matches the library file you downloaded.- only applies to the Linux
-
libpubkey-pkcs11.asc: The public key used to verify the signature.
-
-
Import the public key:
gpg --import libpubkey-pkcs11.asc -
Verify the integrity and authenticity of the PKCS #11 library file with the following command:
gpg --verify libpkcs11-kms.so.sig libpkcs11-kms.soWhen the verification is successful,
Good signature from "International Business Machines Corporation <psirt@us.ibm.com>"is displayed.NOTE: GPG also prints
WARNING: This key is not certified with a trusted signature!unless you have marked the key as trusted. This is expected. Confirm that the key fingerprint in the output isB640 FE80 0920 AD9A EB69 401C 6055 7144 A18B 07BE. -
If the verification fails, cancel the installation and contact IBM for support.
Prior to using the PKCS #11 library, the keystores must be initialized. Please see Managing a keystore
Once the keystores have been initialized, normal and anonymous users can proceed with key operations such as C_GenerateKey or C_GenerateKeyPair.
All source files must include a Copyright and License header. The SPDX license header is preferred because it can be easily scanned.
If you would like to see the detailed LICENSE click here.
#
# Copyright IBM Corp. 2026 - 2026
# SPDX-License-Identifier: Apache-2.0
#
Optionally, you may include a list of authors, though this is redundant with the built-in GitHub list of contributors.
- Author: Timothy Yao Timothy.Yao@ibm.com