This topic provides information about creating and validating digital signatures based on MAC keys.
A single key, shared by both the producer and the verifier, is used to compute a MAC tag from the input data. The MAC tag serves as a digital signature. When the verifier receives the message and its associated MAC tag, they generate their own tag from the message contents. The verifier can then compare the received tag with their generated tag to see whether they match. If the two tags match, the verifier knows that the message they received is the same as the message signed by the producer.
Before you begin
When creating MAC digital signatures, you must use a key that has the key purpose of
MAC
. When you create the key, useMAC
.Ensure that the file that you want to sign is within the file size limit. When using a Cloud HSM key to create or verify MAC signatures, the maximum file size is 16 KiB. For all other keys, the maximum file size is 64 KiB.
Required roles
To get the permissions that you need to create and verify signatures, ask your administrator to grant you the following IAM roles on the key:
-
To create signatures:
Cloud KMS CryptoKey Signer (
roles/cloudkms.signer
) -
To verify signatures:
Cloud KMS CryptoKey Verifier (
roles/cloudkms.verifier
) -
To create and verify signatures:
Cloud KMS CryptoKey Signer/Verifier (
roles/cloudkms.signerVerifier
)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Creating a MAC signature
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms mac-sign \ --version KEY_VERSION \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --input-file INPUT_FILE_PATH \ --signature-file SIGNED_FILE_PATH
Replace the following:
KEY_VERSION
: the key version number.KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.INPUT_FILE_PATH
: The local path to the file you want to sign.SIGNED_FILE_PATH
: The local path where you want to save the generated signature.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
Use the
CryptoKeyVersions.macSign
method to perform the signing. The response from this method contains the
base64-encoded signature.
Verifying a MAC signature
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms mac-verify \ --version KEY_VERSION \ --key KEY_NAME \ --keyring KEY_RING \ --location LOCATION \ --input-file INPUT_FILE_PATH \ --signature-file SIGNED_FILE_PATH
KEY_VERSION
: the key version number.KEY_NAME
: the name of the key.KEY_RING
: the name of the key ring that contains the key.LOCATION
: the Cloud KMS location of the key ring.INPUT_FILE_PATH
: The local path to the file that was signed.SIGNED_FILE_PATH
: The local path to the signature file to be verified.
For information on all flags and possible values, run the command with the
--help
flag.
C#
To run this code, first set up a C# development environment and install the Cloud KMS C# SDK.
Go
To run this code, first set up a Go development environment and install the Cloud KMS Go SDK.
Java
To run this code, first set up a Java development environment and install the Cloud KMS Java SDK.
Node.js
To run this code, first set up a Node.js development environment and install the Cloud KMS Node.js SDK.
Python
To run this code, first set up a Python development environment and install the Cloud KMS Python SDK.
Ruby
To run this code, first set up a Ruby development environment and install the Cloud KMS Ruby SDK.
API
These examples use curl as an HTTP client to demonstrate using the API. For more information about access control, see Accessing the Cloud KMS API.
Use the
CryptoKeyVersions.macVerify
method to perform the verification. The signature to be verified needs to be
base64-encoded. The response from this method contains a boolean indicating
whether or not the signature was verified successfully.