Skip to content

Latest commit

 

History

History
548 lines (458 loc) · 42.5 KB

user_guide.md

File metadata and controls

548 lines (458 loc) · 42.5 KB
Raw

PKCS #11 Library for Cloud KMS User Guide

Table of Contents

  1. Getting started
  2. Authentication and authorization
  3. Configuration
  4. Functions
  5. Cryptographic operations
    1. Elliptic curve keypair generation
    2. ECDSA signing and verification
    3. RSA keypair generation
    4. RSA-OAEP encryption and decryption
    5. RSA-PKCS1 signing and verification
    6. RSA-PSS signing and verification
  6. Limitations

Getting started

This library provides access to Google Cloud HSM through the industry standard PKCS #11 API. Official Google-built releases of this library are covered by the Google Cloud Platform Terms of Service.

If you are upgrading from a previous version of the library, be sure to check the change log for changes that might affect your usage.

Linux system requirements

The library is built and tested on Ubuntu 16.04 LTS Linux, on the amd64 architecture. The shared object file libkmsp11.so is compatible with any Linux distribution that contains glibc version 2.17 or greater. You do not need to compile the library yourself, and it does not require an installation routine.

Windows system requirements

The library is built and tested on Windows Server (semi-annual channel), on the amd64 architecture. The library is designed to be compatible with Windows Server 2012 R2, Windows 8.1 (x64), and all subsequent server and x64 desktop releases.

On Windows versions prior to Windows 10, the library requires the preinstallation of the Visual C++ 2022 x64 Redistributable package (14.34 or higher), which can be downloaded here.

Downloading and verifying the library

The library is available for download in GitHub Releases.

After you've downloaded the library, you can check the downloaded library for integrity by verifying the build signature against the preview release public signing key.

Save this key on your filesystem, for example, in a file named pkcs11-release-signing-key.pem:

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEtfLbXkHUVc9oUPTNyaEK3hIwmuGRoTtd
6zDhwqjJuYaMwNd1aaFQLMawTwZgR0Xn27ymVWtqJHBe0FU9BPIQ+SFmKw+9jSwu
/FuqbJnLmTnWMJ1jRCtyHNZawvv2wbiB
-----END PUBLIC KEY-----

You can then verify the library signature using OpenSSL:

openssl dgst -sha384 -verify pkcs11-release-signing-key.pem \
  -signature libkmsp11.so.sig libkmsp11.so

Authentication and Authorization

The library authenticates to GCP using service account credentials. You can use an existing service account associated with a GCE instance or GKE node, or you can follow the Getting Started with Authentication guide to create a service account for use with the library.

In order to use the library at all, you must grant the account a role or roles with the following IAM permissions:

  • cloudkms.cryptoKeys.list on all configured KeyRings.
  • cloudkms.cryptoKeyVersions.list on all CryptoKeys in each configured KeyRing.
  • cloudkms.cryptoKeyVersions.viewPublicKey for all asymmetric keys contained within all configured KeyRings.
  • cloudkms.cryptoKeyVersions.useToDecrypt or cloudkms.cryptoKeyVersions.useToSign for any keys to be used for decryption or signing.
  • cloudkms.cryptoKeys.create if you intend to create keys.
  • cloudkms.cryptoKeyVersions.destroy if you intend to destroy keys

You can learn more about managing access to Cloud KMS resources.

Configuration

The library requires a YAML configuration file in order to locate Cloud KMS resources. The YAML must at a minimum configure a single PKCS #11 token. Most configuration items are optional.

You can provide a library configuration file in either of the following ways:

  • By providing a null-terminated C string containing the path to the library configuration file in the field pInitArgs->pReserved during your call to C_Initialize.
  • By setting the environment variable KMS_PKCS11_CONFIG to the path to a configuration file.

You must set the permissions on the configuration file so that it is writable only by the file owner.

Sample configuration file

---
tokens:
  - key_ring: "projects/my-project/locations/us/keyRings/my-key-ring"
    label: "my key ring"
  - key_ring: "projects/my-project/locations/us/keyRings/second-ring"
log_directory: "/var/log/kmsp11"

Global configuration

Item Name Type Required Default Description
tokens list Yes None A list of token configuration items, as specified in the next section. The tokens will be assigned to increasing slot numbers in the order they are defined, starting with 0.
refresh_interval_secs int No 0 The interval (in seconds) between attempts to update the key change in this library with the latest state from Cloud KMS. A value of 0 means never refresh.
rpc_timeout_secs int No 30 The timeout (in seconds) for RPCs made to Cloud KMS.
log_directory string No None A directory where application logs should be written. If unspecified, application logs will be written to standard error rather than to the filesystem.
log_filename_suffix string No None A suffix that will be appended to application log file names.
generate_certs bool No false Whether to generate certificates at runtime for asymmetric KMS keys. The certificates are regenerated each time the library is intiailized, and they do not chain to a public root of trust. They are intended to provide compatibility with the Sun PKCS #11 JCA Provider which requires that all private keys have an associated certificate. Other use is discouraged.
require_fips_mode bool No false Whether to enable an initialization time check that requires that BoringSSL or OpenSSL have been built in FIPS mode, and that FIPS self checks pass.
skip_fork_handlers bool No false Whether to skip fork handlers registration, for applications that don't need the PKCS#11 library to work in the child process.
allow_software_keys bool No false Whether the library may be used to act on crypto key versions with protection level = SOFTWARE.

Experimental global configuration options

Item Name Type Required Default Description
experimental_create_multiple_versions bool No false Enables an experiment that allows multiple versions of a CryptoKey to be created.

Per token configuration

Item Name Type Required Default Description
key_ring string Yes None The full name of the KMS key ring whose keys will be made accessible.
label string No Empty The label to use for this token's CK_TOKEN_INFO structure. Setting a value here may help an application disambiguate tokens at runtime.
certs list of strings No Empty Exposes the provided PEM X.509 certificate(s) alongside any KMS keys they match.

Functions

The library conforms to the PKCS #11 Extended Provider Profile, and implements all of the functions defined by that profile. In addition, the library supports single-part Encryption, Decryption, Signing, and Verification for the asymmetric key types supported in Cloud KMS.

Function Status Notes
C_Initialize ✅ Library initialization requires a configuration file. If pInitArgs is specified, then the flag CKF_OS_LOCKING_OK must be set, and the flag CKF_LIBRARY_CANT_CREATE_OS_THREADS must not be set. If pInitArgs is not specified, the library assumes that it may use mutexes and create threads.
C_Finalize ✅
C_GetInfo ✅
C_GetFunctionList ✅
C_GetSlotList ✅
C_GetSlotInfo ✅
C_GetTokenInfo ✅
C_WaitForSlotEvent ❌
C_GetMechanismList ✅
C_GetMechanismInfo ✅
C_InitToken ❌
C_InitPIN ❌
C_SetPIN ❌
C_OpenSession ✅ The flag CKF_SERIAL_SESSION must be supplied. The library does not make callbacks, so the arguments pApplication and Notify are ignored.
C_CloseSession ✅
C_CloseAllSessions ✅
C_GetSessionInfo ✅
C_GetOperationState ❌
C_SetOperationState ❌
C_Login ✅ Login is not required, and is implemented only to provide compatibility with clients that expect to log in. Login is only permitted for the user role (CKU_USER). Any supplied PIN is ignored.
C_Logout ✅
C_CreateObject ❌
C_CopyObject ❌
C_DestroyObject ✅
C_GetObjectSize ❌
C_GetAttributeValue ✅
C_SetAttributeValue ❌
C_FindObjectsInit ✅
C_FindObjects ✅
C_FindObjectsFinal ✅
C_EncryptInit ✅ Consult the cryptographic operations documentation for details on which encryption algorithms are supported.
C_Encrypt ✅
C_EncryptUpdate ✅ Consult the cryptographic operations documentation for details on which encryption algorithms support multi-part encryption. See other notes for additional insights.
C_EncryptFinal ✅ Consult the cryptographic operations documentation for details on which encryption algorithms support multi-part encryption. See other notes for additional insights.
C_DecryptInit ✅ Consult the cryptographic operations documentation for details on which decryption algorithms are supported.
C_Decrypt ✅
C_DecryptUpdate ✅ Consult the cryptographic operations documentation for details on which decryption algorithms support multi-part decryption. See other notes for additional insights.
C_DecryptFinal ✅ Consult the cryptographic operations documentation for details on which decryption algorithms support multi-part decryption. See other notes for additional insights.
C_DigestInit ❌
C_Digest ❌
C_DigestUpdate ❌
C_DigestKey ❌
C_DigestFinal ❌
C_SignInit ✅ Consult the cryptographic operations documentation for details on which signing algorithms are supported.
C_Sign ✅
C_SignUpdate ✅ Consult the cryptographic operations documentation for details on which signing algorithms support multi-part signing. See other notes for additional insights.
C_SignFinal ✅ Consult the cryptographic operations documentation for details on which signing algorithms support multi-part signing. See other notes for additional insights.
C_SignRecoverInit ❌
C_SignRecover ❌
C_VerifyInit ✅ Consult the cryptographic operations documentation for details on which verification algorithms are supported.
C_Verify ✅
C_VerifyUpdate ✅ Consult the cryptographic operations documentation for details on which signing algorithms support multi-part verification. See other notes for additional insights.
C_VerifyFinal ✅ Consult the cryptographic operations documentation for details on which signing algorithms support multi-part verification. See other notes for additional insights.
C_VerifyRecoverInit ❌
C_VerifyRecover ❌
C_DigestEncryptUpdate ❌
C_DecryptDigestUpdate ❌
C_SignEncryptUpdate ❌
C_DecryptVerifyUpdate ❌
C_GenerateKey ✅ When using this function, the template must specify the attributes CKA_LABEL and CKA_KMS_ALGORITHM (required). The template may also optionally specify the attribute CKA_KMS_PROTECTION_LEVEL. No other attributes are supported. This function creates a Cloud KMS CryptoKey with HSM protection level (unless otherwise specified in the CKA_KMS_PROTECTION_LEVEL attribute) and a first version. This mechanism cannot be used to create additional versions in an existing CryptoKey, unless the experimental_create_multiple_versions option is enabled.
C_GenerateKeyPair ✅ When using this function, a public key template must not be specified. The private key template must specify the attributes CKA_LABEL and CKA_KMS_ALGORITHM (required). The template may also optionally specify the attribute CKA_KMS_PROTECTION_LEVEL. No other attributes are supported. This function creates a Cloud KMS CryptoKey with HSM protection level (unless otherwise specified in the CKA_KMS_PROTECTION_LEVEL attribute) and a first version. This mechanism cannot be used to create additional versions in an existing CryptoKey, unless the experimental_create_multiple_versions option is enabled.
C_WrapKey ❌
C_UnwrapKey ❌
C_DeriveKey ❌
C_SeedRandom ❌
C_GenerateRandom ✅ Retrieves between 8 and 1024 bytes of randomness from Cloud HSM.
C_GetFunctionStatus ❌
C_CancelFunction ❌

Cryptographic Operations

Elliptic Curve Keypair Generation

The library may be used to create new elliptic curve keypairs. See the function notes for C_GenerateKeyPair for invocation requirements.

Compatibility Compatible With
PKCS #11 Function C_GenerateKeyPair
PKCS #11 Mechanism CKM_EC_KEY_PAIR_GEN
PKCS #11 Mechanism Parameters None
Cloud KMS Algorithm EC_SIGN_P256_SHA256, EC_SIGN_P384_SHA384

ECDSA Signing and Verification

The library may be used for ECDSA signing and verification. The expected input for a signing or verification operation varies by mechanism, and is either a message digest of the appropriate length for the Cloud KMS algorithm, or plain input data.

Compatibility Compatible With
PKCS #11 Functions C_Sign, C_Verify
PKCS #11 Mechanism CKM_ECDSA, CKM_ECDSA_SHA256, CKM_ECDSA_SHA384
PKCS #11 Mechanism Parameter None
Cloud KMS Algorithm EC_SIGN_P256_SHA256, EC_SIGN_P384_SHA384
Compatibility Compatible With
PKCS #11 Functions C_SignUpdate, C_SignFinal, C_VerifyUpdate, C_VerifyFinal
PKCS #11 Mechanism CKM_ECDSA_SHA256, CKM_ECDSA_SHA384
PKCS #11 Mechanism Parameter None
Cloud KMS Algorithm EC_SIGN_P256_SHA256, EC_SIGN_P384_SHA384

RSA Keypair Generation

The library may be used to create new elliptic curve keypairs. See the function notes for C_GenerateKeyPair for invocation requirements.

Compatibility Compatible With
PKCS #11 Function C_GenerateKeyPair
PKCS #11 Mechanism CKM_RSA_PKCS_KEY_PAIR_GEN
PKCS #11 Mechanism Parameters None
Cloud KMS Algorithm RSA_DECRYPT_OAEP_2048_SHA256, RSA_DECRYPT_OAEP_3072_SHA256, RSA_DECRYPT_OAEP_4096_SHA256, RSA_DECRYPT_OAEP_4096_SHA512, RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PKCS1_3072_SHA256, RSA_SIGN_PKCS1_4096_SHA256, RSA_SIGN_PKCS1_4096_SHA512, RSA_SIGN_PSS_2048_SHA256, RSA_SIGN_PSS_3072_SHA256, RSA_SIGN_PSS_4096_SHA256, RSA_SIGN_PSS_4096_SHA512, RSA_SIGN_RAW_PKCS1_2048, RSA_SIGN_RAW_PKCS1_3072, RSA_SIGN_RAW_PKCS1_4096

RSA-OAEP Encryption and Decryption

The library may be used for RSAES-OAEP encryption or decryption.

Compatibility Compatible With
PKCS #11 Functions C_Encrypt, C_Decrypt
PKCS #11 Mechanism CKM_RSA_PKCS_OAEP
PKCS #11 Mechanism Parameter CK_RSA_PKCS_OAEP_PARAMS
Cloud KMS Algorithm RSA_DECRYPT_OAEP_2048_SHA256, RSA_DECRYPT_OAEP_3072_SHA256, RSA_DECRYPT_OAEP_4096_SHA256, RSA_DECRYPT_OAEP_4096_SHA512

RSA-PKCS1 Signing and Verification

The library may be used for RSASSA-PKCS1 single-part or multi-part signing and verification.

For Cloud KMS keys with an algorithm name that includes a digest type, the expected input for a signing or verification operation varies by mechanism and is either a PKCS #1 DigestInfo with the appropriate digest algorithm, or plain input data. For Cloud KMS keys without a digest type ("Raw PKCS#1" keys), arbitrary input is accepted.

Compatibility Compatible With
PKCS #11 Functions C_Sign, C_Verify
PKCS #11 Mechanism CKM_RSA_PKCS, CKM_RSA_PKCS_SHA256, CKM_RSA_PKCS_SHA512
PKCS #11 Mechanism Parameter None
Cloud KMS Algorithm RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PKCS1_3072_SHA256, RSA_SIGN_PKCS1_4096_SHA256, RSA_SIGN_PKCS1_4096_SHA512, RSA_SIGN_RAW_PKCS1_2048, RSA_SIGN_RAW_PKCS1_3072, RSA_SIGN_RAW_PKCS1_4096
Compatibility Compatible With
PKCS #11 Functions C_SignUpdate, C_SignFinal, C_VerifyUpdate, C_VerifyFinal
PKCS #11 Mechanism CKM_RSA_PKCS_SHA256, CKM_RSA_PKCS_SHA512
PKCS #11 Mechanism Parameter None
Cloud KMS Algorithm RSA_SIGN_PKCS1_2048_SHA256, RSA_SIGN_PKCS1_3072_SHA256, RSA_SIGN_PKCS1_4096_SHA256, RSA_SIGN_PKCS1_4096_SHA512, RSA_SIGN_RAW_PKCS1_2048, RSA_SIGN_RAW_PKCS1_3072, RSA_SIGN_RAW_PKCS1_4096

RSA-PSS Signing and Verification

The library may be used for RSASSA-PSS single-part or multi-part signing and verification. The expected input for a signing or verification operation varies by mechanism and is either a message digest of the appropriate length for the Cloud KMS algorithm, or plain input data.

Compatibility Compatible With
PKCS #11 Functions C_Sign, C_Verify
PKCS #11 Mechanism CKM_RSA_PKCS_PSS
PKCS #11 Mechanism Parameter CK_RSA_PKCS_PSS_PARAMS
Cloud KMS Algorithm RSA_SIGN_PSS_2048_SHA256, RSA_SIGN_PSS_3072_SHA256, RSA_SIGN_PSS_4096_SHA256, RSA_SIGN_PSS_4096_SHA512
Compatibility Compatible With
PKCS #11 Functions C_SignUpdate, C_SignFinal, C_VerifyUpdate, C_VerifyFinal
PKCS #11 Mechanism CKM_RSA_PKCS_PSS_SHA256, CKM_RSA_PKCS_PSS_SHA512
PKCS #11 Mechanism Parameter CK_RSA_PKCS_PSS_PARAMS
Cloud KMS Algorithm RSA_SIGN_PSS_2048_SHA256, RSA_SIGN_PSS_3072_SHA256, RSA_SIGN_PSS_4096_SHA256, RSA_SIGN_PSS_4096_SHA512

Generic Secret Key Generation

The library may be used to create new generic secret keys (symmetric keys). See the function notes for C_GenerateKey for invocation requirements.

Compatibility Compatible With
PKCS #11 Function C_GenerateKey
PKCS #11 Mechanism CKM_GENERIC_SECRET_KEY_GEN, CKM_AES_KEY_GEN
PKCS #11 Mechanism Parameters None
Cloud KMS Algorithm AES_128_GCM, AES_256_GCM, AES_128_CTR, AES_256_CTR, AES_128_CBC, AES_256_CBC, HMAC_SHA1, HMAC_SHA224, HMAC_SHA256, HMAC_SHA384, HMAC_SHA512

AES-CBC Encryption and Decryption

The library may be used for AES encryption or decryption.

Compatibility Compatible With
PKCS #11 Functions C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_Decrypt, C_DecryptUpdate, C_DecryptFinal
PKCS #11 Mechanism CKM_AES_CBC, CKM_AES_CBC_PAD
PKCS #11 Mechanism Parameter CK_BYTE (initialization vector)
Cloud KMS Algorithm AES_128_CBC, AES_256_CBC

AES-CTR Encryption and Decryption

The library may be used for AES encryption or decryption.

Compatibility Compatible With
PKCS #11 Functions C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_Decrypt, C_DecryptUpdate, C_DecryptFinal
PKCS #11 Mechanism CKM_AES_CTR
PKCS #11 Mechanism Parameter CK_AES_CTR_PARAMS
Cloud KMS Algorithm AES_128_CTR, AES_256_CTR

AES-GCM Encryption and Decryption

The library may be used for AES encryption or decryption.

Compatibility Compatible With
PKCS #11 Functions C_Encrypt, C_EncryptUpdate, C_EncryptFinal, C_Decrypt, C_DecryptUpdate, C_DecryptFinal
PKCS #11 Mechanism CKM_CLOUDKMS_AES_GCM
PKCS #11 Mechanism Parameter CK_GCM_PARAMS
Cloud KMS Algorithm AES_128_GCM, AES_256_GCM

MAC Signing and Verification

The library may be used for MAC single-part or multi-part signing and verification. The expected input for a signing or verification is plain input data.

Compatibility Compatible With
PKCS #11 Functions C_Sign, C_SignUpdate, C_SignFinal, C_Verify, C_VerifyUpdate, C_VerifyFinal
PKCS #11 Mechanism CKM_SHA1_HMAC, CKM_SHA224_HMAC, CKM_SHA256_HMAC, CKM_SHA384_HMAC, CKM_SHA512_HMAC
PKCS #11 Mechanism Parameter None
Cloud KMS Algorithm HMAC_SHA1, HMAC_SHA224, HMAC_SHA256, HMAC_SHA384, HMAC_SHA512

Limitations

Key purpose, protection level, and state

To use the library to act on a CryptoKeyVersion, the CryptoKeyVersion must meet these characteristics:

  • The purpose for the CryptoKey is ASYMMETRIC_SIGN, ASYMMETRIC_DECRYPT, RAW_ENCRYPT_DECRYPT, or MAC.
  • The protection level for the CryptoKeyVersion is HSM. The protection level for the CryptoKeyVersion may also be SOFTWARE if the YAML configuration file contains allow_software_keys: true.
  • The CryptoKeyVersion is in state ENABLED.

The PKCS #11 library ignores keys that don't conform to these requirements.

Caching

At library initialization time, the library uses KMS RPC calls to read the entire contents of each configured key ring. Those contents are cached in memory, so that subsequent calls like C_FindObjects do not require network access. The cache is periodically refreshed if the configuration option refresh_interval_secs is set to a non-zero value.

This means that:

  • You should expect initialization time (that is, the amount of time it takes for C_Initialize to complete) to increase with the number of keys that exist in your configured KeyRings.
  • Keys that are created or modified after the library is initialized will be stale if refresh_interval_secs is unspecified, or else will take up to that amount of time to become up-to-date in the library.

Other notes

Keys can be located with the CKA_LABEL attribute, which is the Cloud KMS CryptoKey identifier, or with the CKA_ID attribute, which is the full Cloud KMS CryptoKeyVersion name. As an example, a key might have a CKA_ID of projects/some_project/locations/some_location/keyRings/some_keyring/cryptoKeys/some_ck/cryptoKeyVersions/1 and a CKA_LABEL of some_ck. Some tools including pkcs11-tool hex-encode CKA_ID attribute values, so they seem different at first.

Note that the OpenSC libp11 engine used by OpenSSL has a 100-character limit on the PKCS#11 CKA_IDs that can be passed as input. For our library, this means that you won't be able to pass a specific CryptoKeyVersion to OpenSSL if the resource name is longer than 100 characters. See OpenSC/libp11#531. As a workaround, use short KeyRing and CryptoKey names, or use CKA_LABEL instead.

For multi-part crypto operations, the library caches input data and parameters in memory (up to a max buffer, depending on the specific crypto operation and algorithm), before sending the request to Cloud KMS. This is required for these operations to fit in the current APIs exposed by Cloud KMS.