### Verify CNG Provider Signature with OpenSSL Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmscng/docs/user_guide.md Verify the integrity of the downloaded MSI installer using OpenSSL and the public signing key. Ensure the provider has not been tampered with. ```sh openssl dgst -sha384 -verify cng-release-signing-key.pem \ -signature kmscng.msi.sig kmscng.msi ``` -------------------------------- ### Install OpenSC Package Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Install the 'opensc' package, which provides pkcs11-tool and pkcs11-spy, on Debian-based systems. ```bash sudo apt-get update sudo apt-get install opensc ``` -------------------------------- ### Sample PKCS #11 Integration Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/README.md A sample C code demonstrating how to dynamically load the PKCS #11 library for integration with new applications. This is useful when migrating existing applications or building new ones that require PKCS #11 support. ```c #include #include #include #include typedef void* (*dlopen_t)(const char*, int); typedef void* (*dlsym_t)(void*, const char*); typedef int (*dlclose_t)(void*); int main(int argc, char **argv) { void *handle; dlopen_t dlopen_func; dlsym_t dlsym_func; dlclose_t dlclose_func; char *error; handle = dlopen("libkmsp11.so", RTLD_NOW); if (!handle) { fprintf(stderr, "%s\n", dlerror()); exit(EXIT_FAILURE); } dlerror(); dlopen_func = (dlopen_t) dlsym(handle, "dlopen"); if ((error = dlerror()) != NULL) { fprintf(stderr, "%s\n", error); exit(EXIT_FAILURE); } dlsym_func = (dlsym_t) dlsym(handle, "dlsym"); if ((error = dlerror()) != NULL) { fprintf(stderr, "%s\n", error); exit(EXIT_FAILURE); } dlclose_func = (dlclose_t) dlsym(handle, "dlclose"); if ((error = dlerror()) != NULL) { fprintf(stderr, "%s\n", error); exit(EXIT_FAILURE); } printf("Successfully loaded libkmsp11.so.\n"); // Example of calling a function from the library // Replace with actual PKCS #11 function calls // C_GetFunctionList_t C_GetFunctionList = (C_GetFunctionList_t) dlsym_func(handle, "C_GetFunctionList"); if (dlclose_func(handle) != 0) { fprintf(stderr, "%s\n", dlerror()); exit(EXIT_FAILURE); } printf("Successfully unloaded libkmsp11.so.\n"); return 0; } ``` -------------------------------- ### C_VerifyInit Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Initializes a verification operation. Consult the cryptographic operations documentation for details on which verification algorithms are supported. ```APIDOC ## C_VerifyInit ### Description Initializes a verification operation. Consult the cryptographic operations documentation for details on which verification algorithms are supported. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### Sign a Digest with pkcs11-tool Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Sign a SHA256 digest of 'hello world' using pkcs11-tool with an ECDSA key. The path to libkmsp11.so must be absolute. ```bash echo -n "hello world" | openssl dgst -binary -sha256 > data.txt pkcs11-tool --module /path/to/libkmsp11.so --sign --mechanism ECDSA --slot 0 --label test-key-ec \ --type privkey -i data.txt -o signature.sig ``` -------------------------------- ### Sample KMS PKCS#11 Configuration File Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md This YAML configuration defines tokens and a log directory for the KMS PKCS#11 library. It specifies key rings for tokens and a path for log files. ```yaml --- 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" ``` -------------------------------- ### Build with OpenSSL Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/BUILDING.md Use this option to build the PKCS #11 library using OpenSSL instead of BoringSSL. This is only supported on Linux and FreeBSD. ```sh bazel build --config openssl //kmsp11/main:libkmsp11.so ``` -------------------------------- ### View PKCS #11 Spy Log for GetInfo Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Sample log output from PKCS #11 Spy detailing the C_GetInfo function call and its parameters/return values. ```text *************** OpenSC PKCS#11 spy ***************** Loaded: "/path/to/libkmsp11.so" 0: C_GetFunctionList 2021-04-12 21:43:35.549 Returned: 0 CKR_OK 1: C_Initialize 2021-04-12 21:43:35.549 [in] pInitArgs = (nil) Returned: 0 CKR_OK 2: C_GetInfo 2021-04-12 21:43:35.762 [out] pInfo: cryptokiVersion: 2.40 manufacturerID: 'Google ' flags: 0 libraryDescription: 'Cryptoki Library for Cloud KMS ' libraryVersion: 0.21 Returned: 0 CKR_OK 3: C_GetSlotList 2021-04-12 21:43:35.762 [in] tokenPresent = 0x0 [out] pSlotList: Count is 1 [out] *pulCount = 0x1 Returned: 0 CKR_OK 4: C_GetSlotList 2021-04-12 21:43:35.762 [in] tokenPresent = 0x0 [out] pSlotList: Slot 0 [out] *pulCount = 0x1 Returned: 0 CKR_OK 5: C_GetSlotInfo 2021-04-12 21:43:35.762 [in] slotID = 0x0 [out] pInfo: slotDescription: 'A virtual slot mapped to a key r' 'ing in Google Cloud KMS ' manufacturerID: 'Google ' hardwareVersion: 0.0 firmwareVersion: 0.0 flags: 1 CKF_TOKEN_PRESENT Returned: 0 CKR_OK 6: C_Finalize 2021-04-12 21:43:35.762 Returned: 0 CKR_OK ``` -------------------------------- ### Build 32-bit Binaries Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/BUILDING.md Specify building 32-bit binaries on 64-bit Linux and FreeBSD systems. Note that not all tests can run in this configuration. ```sh bazel test --config m32 ... ``` -------------------------------- ### Verify Library Signature with OpenSSL Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Use OpenSSL to verify the signature of the downloaded library against the public signing key. ```sh openssl dgst -sha384 -verify pkcs11-release-signing-key.pem \ -signature libkmsp11.so.sig libkmsp11.so ``` -------------------------------- ### Sample CNG Provider Configuration File Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmscng/docs/user_guide.md A sample YAML configuration file for the CNG provider. This file is required if your application makes NCryptEnumKeys calls and specifies the Cloud KMS resources to be accessed. ```yaml --- resources: - crypto_key_version: "projects/my-project/locations/us/keyRings/key-ring/cryptoKeys/my-key/cryptoKeyVersions/1" - crypto_key_version: "projects/my-project/locations/us/keyRings/other-key-ring/cryptoKeys/other-key/cryptoKeyVersions/2" ``` -------------------------------- ### Run pkcs11-tool with PKCS #11 Spy Module Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Execute pkcs11-tool using the pkcs11-spy.so module to capture all PKCS #11 function calls and return values in a log file. ```bash pkcs11-tool --module /usr/lib/x86_64-linux-gnu/pkcs11/pkcs11-spy.so -I ``` -------------------------------- ### Download roots.pem and set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmscng/docs/user_guide.md Use this PowerShell command to download the roots.pem file and set the GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable. This resolves errors related to gRPC not finding the root of trust for SSL. ```powershell @powershell -NoProfile -ExecutionPolicy unrestricted -Command \ (new-object System.Net.WebClient).Downloadfile( \ 'https://pki.google.com/roots.pem', 'roots.pem') set GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=%cd%\roots.pem ``` -------------------------------- ### List Slots with OpenSC Debug Enabled Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Use pkcs11-tool to list available slots, with the OpenSC debug level set to 9 via the OPENSC_DEBUG environment variable for verbose output. ```bash OPENSC_DEBUG=9 pkcs11-tool --list-slots ``` -------------------------------- ### Test KMS Library Information with pkcs11-tool Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Use pkcs11-tool to retrieve basic information about the PKCS #11 Cloud KMS Library. Ensure the library path is correct. ```bash pkcs11-tool --module /path/to/libkmsp11.so -I ``` -------------------------------- ### Enable PKCS #11 Spy Logging Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Configure PKCS #11 Spy by setting the PKCS11SPY environment variable to the KMS library path and optionally PKCS11SPY_OUTPUT for the log file path. ```bash export PKCS11SPY="/path/to/libkmsp11.so" # Optional, stderr will be used for logging if not set export PKCS11SPY_OUTPUT="/path/to/pkcs11-spy.log" ``` -------------------------------- ### Export KMS PKCS #11 Configuration Path Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/pkcs11_spy_setup.md Set the KMS_PKCS11_CONFIG environment variable to point to your PKCS #11 configuration file. ```bash export KMS_PKCS11_CONFIG="/path/to/pkcs11-config.yaml" ``` -------------------------------- ### Build with FIPS BoringSSL Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/BUILDING.md Use this option to build the PKCS #11 library with the FIPS-validated version of BoringSSL. This is only supported on Linux and FreeBSD with the amd64 architecture. ```sh bazel build --config fips //kmsp11/main:libkmsp11.so ``` -------------------------------- ### C_GenerateKeyPair Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Generates a new key pair. 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`. If protection level `HSM_SINGLE_TENANT` is specified, `CKA_KMS_CRYPTO_KEY_BACKEND` must also be specified. 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. ```APIDOC ## C_GenerateKeyPair ### Description Generates a new key pair. 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`. If protection level `HSM_SINGLE_TENANT` is specified, `CKA_KMS_CRYPTO_KEY_BACKEND` must also be specified. 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. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### C_Sign Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Initiates a signing operation. ```APIDOC ## C_Sign ### Description Initiates a signing operation. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### C_Verify Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Verifies a signature against a message. ```APIDOC ## C_Verify ### Description Verifies a signature against a message. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### C_VerifyFinal Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Finalizes a multi-part verification operation. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part verification. See other notes for additional insights. ```APIDOC ## C_VerifyFinal ### Description Finalizes a multi-part verification operation. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part verification. See other notes for additional insights. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### C_SignUpdate Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Updates a multi-part signing operation with additional data. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part signing. See other notes for additional insights. ```APIDOC ## C_SignUpdate ### Description Updates a multi-part signing operation with additional data. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part signing. See other notes for additional insights. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### Save Public Signing Key Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Save the public signing key to a file for verifying the library's integrity. ```text -----BEGIN PUBLIC KEY----- MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEtfLbXkHUVc9oUPTNyaEK3hIwmuGRoTtd 6zDhwqjJuYaMwNd1aaFQLMawTwZgR0Xn27ymVWtqJHBe0FU9BPIQ+SFmKw+9jSwu /FuqbJnLmTnWMJ1jRCtyHNZawvv2wbiB -----END PUBLIC KEY----- ``` -------------------------------- ### C_VerifyUpdate Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Updates a multi-part verification operation with additional data. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part verification. See other notes for additional insights. ```APIDOC ## C_VerifyUpdate ### Description Updates a multi-part verification operation with additional data. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part verification. See other notes for additional insights. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### C_GenerateKey Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Generates a new cryptographic key. 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`. If protection level `HSM_SINGLE_TENANT` is specified, `CKA_KMS_CRYPTO_KEY_BACKEND` must also be specified. 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. ```APIDOC ## C_GenerateKey ### Description Generates a new cryptographic key. 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`. If protection level `HSM_SINGLE_TENANT` is specified, `CKA_KMS_CRYPTO_KEY_BACKEND` must also be specified. 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. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### C_GenerateRandom Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Retrieves between 8 and 1024 bytes of randomness from Cloud HSM. ```APIDOC ## C_GenerateRandom ### Description Retrieves between 8 and 1024 bytes of randomness from Cloud HSM. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### C_SignFinal Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmsp11/docs/user_guide.md Finalizes a multi-part signing operation. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part signing. See other notes for additional insights. ```APIDOC ## C_SignFinal ### Description Finalizes a multi-part signing operation. Consult the cryptographic operations documentation for details on which signing algorithms support multi-part signing. See other notes for additional insights. ### Method [Not specified in source] ### Endpoint [Not specified in source] ### Parameters [Not specified in source] ### Request Example [Not specified in source] ### Response #### Success Response (200) [Not specified in source] #### Response Example [Not specified in source] ``` -------------------------------- ### Specify Custom Log Directory Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/TROUBLESHOOTING.md Set the `log_directory` field in your YAML configuration to specify a custom location for application logs. This aids in troubleshooting by centralizing log files. ```yaml log_directory: "/var/log/kmsp11" ``` -------------------------------- ### Public Key for CNG Provider Verification Source: https://github.com/googlecloudplatform/kms-integrations/blob/master/kmscng/docs/user_guide.md The public key used to verify the signature of the CNG provider release. Save this key to a file for use with OpenSSL. ```pem -----BEGIN PUBLIC KEY----- MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEtfLbXkHUVc9oUPTNyaEK3hIwmuGRoTtd 6zDhwqjJuYaMwNd1aaFQLMawTwZgR0Xn27ymVWtqJHBe0FU9BPIQ+SFmKw+9jSwu /FuqbJnLmTnWMJ1jRCtyHNZawvv2wbiB -----END PUBLIC KEY----- ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.