This topic provides information about creating and validating digital signatures based on asymmetric keys.
A digital signature is created using the private key portion of an asymmetric key. The signature is validated using the public key portion of the same asymmetric key.
Before you begin
-
When creating digital signatures, you must use a key that has the key purpose of
ASYMMETRIC_SIGN
. When you create the key, useASYMMETRIC_SIGN
. To validate a signature, you need to know the full algorithm that was used when creating the key. For command-line instructions below that use the
openssl
command, you need to pass this information to those commands.Grant the
cloudkms.cryptoKeyVersions.useToSign
permission on the asymmetric key to the user or service that will perform the signing. You can learn about permissions in Cloud Key Management Service at Permissions and roles.If you are going to validate a signature, grant
cloudkms.cryptoKeyVersions.viewPublicKey
permission on the asymmetric key to the user or service that will download the public key to use for validation.If you are going to use the command line, install OpenSSL if you do not already have it. If you use Cloud Shell, OpenSSL is already installed.
Data versus digest
The input provided for AsymmetricSign requests can be passed through the
data
field or the digest
field. These fields cannot be both specified at
the same time. There are some algorithms that require the data field, such as
raw algorithms and signing
with a Cloud External Key Manager key.
Raw algorithms
"Raw" algorithms, identified by the RSA_SIGN_RAW_
prefix, are a
variant of PKCS #1 signing that omits encoding into a DigestInfo. In the
variant:
- A digest is computed over the message that will be signed.
- PKCS #1 padding is applied to the digest directly.
- A signature of the padded digest is computed, using the RSA private key.
To use these algorithms:
- The raw data needs to be provided (instead of a digest) as part of the
data
field. - The data has a length limit of 11 bytes fewer than the RSA key size. For example, PKCS #1 with a 2048-bit RSA key can sign at most 245 bytes.
- Grant the
cloudkms.expertRawPKCS1
role to the appropriate user or service. You can learn about permissions in Cloud Key Management Service at Permissions and roles.
ECDSA support for other hash algorithms
Our ECDSA signing algorithms have the general format:
EC_SIGN_ELLIPTIC_CURVE_[DIGEST_ALGORITHM]
DIGEST_ALGORITHM has the value SHA256
, SHA384
, or SHA512
.
Because the hash is performed before you create the signature, these signing
algorithms can also be used with digests other than SHA, such as Keccak. To use
a Keccak digest, provide a Keccak hash value and use the SHA digest algorithm
with the same length. For example, you can use a KECCAK256
digest in a request
with the EC_SIGN_P256_SHA256
algorithm.
Creating a signature
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
gcloud kms asymmetric-sign \ --version key-version \ --key key \ --keyring key-ring \ --location location \ --digest-algorithm digest-algorithm \ --input-file input-file \ --signature-file signature-file
Replace key-version with the version of the key to to use for signing. Replace key with the key name. Replace key-ring with the name of the key ring where the key is located. Replace location with the Cloud KMS location the key ring. Replace digest-algorithm with the algorithm to use. Omit digest-algorithm to send input-file to Cloud KMS to sign. Replace input-file and signature-file with the local paths for the file to sign and the signature file.
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.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP 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.asymmetricSign
method to perform the signing. The response from this method contains the
base64-encoded signature.
Validating an elliptic curve signature
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
Get the public key
gcloud kms keys versions get-public-key key-version \ --key key \ --keyring key-ring \ --location location \ --output-file output-file
Replace key-version with the key version. Replace key with the name of the key. Replace key-ring with the name of the key ring where the key is located. Replace location with the Cloud KMS location for the key ring. Replace output-file with the file path to save the public key on the local system.
For information on all flags and possible values, run the command with the
--help
flag.
Verify the signature
The OpenSSL commands to validate the signature depend on what signature
type was created. For example, to validate a SHA-256 elliptic curve
signature using OpenSSL, you must specify -sha256
. To validate a SHA-384
elliptical curve signature, you must specify -sha384
.
openssl dgst \ -sha256 \ -verify public-key-file \ -signature signature-file \ message-file
Replace the variables with your own values:
public-key-file. Path to a file that contains the public key (e.g.
"./my-key.pub"
).signature-file. Path to a file that contains the signature to verify (e.g.
"./my-data.sig"
).message-file. Path to a file that contains the message (e.g.
"./my-data.txt"
).
If the signature is valid, the command outputs the string Verified OK
.
For information on all flags and possible values, run the command with the
help
subcommand.
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.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP 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.getPublicKey method to retrieve the public key, and then use the commands shown for the command-line example to validate the signature.
Validating an RSA signature
gcloud
To use Cloud KMS on the command line, first Install or upgrade to the latest version of Google Cloud CLI.
Get the public key
gcloud kms keys versions get-public-key key-version \ --key key \ --keyring key-ring \ --location location \ --output-file output-file
Replace key-version with the key version. Replace key with the name of the key. Replace key-ring with the name of the key ring where the key is located. Replace location with the Cloud KMS location for the key ring. Replace output-file with the path to save the public key on the local system.
For information on all flags and possible values, run the command with the
--help
flag.
Verify the signature
The OpenSSL commands to validate the signature depend on what signature type was
created. For example, to validate a SHA-256 RSA signature with PSS padding, you
must specify -sha256
and -sigopt rsa_padding_mode:pss
. To validate a SHA-512
RSA signature with PSS padding, you must specify -sha512
and -sigopt
rsa_padding_mode:pss
.
openssl dgst \ -sha256 \ -sigopt rsa_padding_mode:pss \ -sigopt rsa_pss_saltlen:-1 \ -verify public-key-file \ -signature signature-file \ message-file
Replace the variables with your own values:
public-key-file. Path to a file that contains the public key (e.g.
"./my-key.pub"
).signature-file. Path to a file that contains the signature to verify (e.g.
"./my-data.sig"
).message-file. Path to a file that contains the message (e.g.
"./my-data.txt"
).
If the signature is valid, the command outputs the string Verified OK
.
For information on all flags and possible values, run the command with the
help
subcommand.
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.
PHP
To run this code, first learn about using PHP on Google Cloud and install the Cloud KMS PHP 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.getPublicKey
method to retrieve the public key, and then use the commands shown for the
command-line example to validate the signature.