En este tema se explica cómo crear y validar firmas digitales basadas en claves asimétricas.
Una firma digital se crea con la parte de clave privada de una clave asimétrica. La firma se valida mediante la parte de clave pública de la misma clave asimétrica.
Antes de empezar
Cuando crees firmas digitales, debes usar una clave que tenga el propósito de clave
ASYMMETRIC_SIGN
. Cuando crees la clave, usaASYMMETRIC_SIGN
.Para validar una firma, debes conocer el algoritmo completo que se usó al crear la clave. Para seguir las instrucciones de la línea de comandos que aparecen más abajo y que usan el comando
openssl
, debes proporcionar esta información a esos comandos.Concede el permiso
cloudkms.cryptoKeyVersions.useToSign
en la clave asimétrica al usuario o servicio que vaya a realizar la firma. Puedes consultar información sobre los permisos de Cloud Key Management Service en Permisos y roles.Si vas a validar una firma, concede permiso
cloudkms.cryptoKeyVersions.viewPublicKey
en la clave asimétrica al usuario o servicio que descargará la clave pública para usarla en la validación.Si vas a usar la línea de comandos, instala OpenSSL si aún no lo tienes. Si usas Cloud Shell, OpenSSL ya está instalado.
Datos frente a resumen
La entrada proporcionada para las solicitudes de AsymmetricSign se puede transferir a través del campo data
o del campo digest
. No se pueden especificar ambos campos al mismo tiempo. Hay algunos algoritmos que requieren el campo de datos, como los algoritmos sin procesar y la firma con una clave de Cloud External Key Manager.
Algoritmos sin procesar
Los algoritmos "sin formato", identificados por el prefijo RSA_SIGN_RAW_
, son una variante de la firma PKCS #1 que omite la codificación en un DigestInfo. En la variante:
- Se calcula un resumen del mensaje que se va a firmar.
- El relleno PKCS #1 se aplica directamente al resumen.
- Se calcula una firma del resumen con relleno mediante la clave privada RSA.
Para usar estos algoritmos, sigue estos pasos:
- Los datos sin procesar deben proporcionarse (en lugar de un resumen) como parte del campo
data
. - Los datos tienen un límite de longitud de 11 bytes menos que el tamaño de la clave RSA. Por ejemplo, PKCS #1 con una clave RSA de 2048 bits puede firmar un máximo de 245 bytes.
- Asigna el rol
cloudkms.expertRawPKCS1
al usuario o servicio correspondiente. Puedes consultar información sobre los permisos de Cloud Key Management Service en Permisos y roles.
Si usas algoritmos sin procesar, también puedes firmar un tipo de resumen para el que no haya disponible un algoritmo predefinido. Por ejemplo, puedes usar una clave RSA_SIGN_RAW_2048
para firmar una estructura SHA-512
PKCS #1 DigestInfo que ya hayas calculado externamente. Este proceso da los mismos resultados que un algoritmo RSA_SIGN_PKCS1_2048_SHA512
estándar.
Compatibilidad con ECDSA para otros algoritmos hash
Nuestros algoritmos de firma ECDSA tienen el siguiente formato general:
EC_SIGN_ELLIPTIC_CURVE_[DIGEST_ALGORITHM]
DIGEST_ALGORITHM tiene el valor SHA256
, SHA384
o SHA512
.
Como el hash se realiza antes de crear la firma, estos algoritmos de firma también se pueden usar con resúmenes distintos de SHA, como Keccak. Para usar un resumen de Keccak, proporcione un valor de hash de Keccak y use el algoritmo de resumen SHA con la misma longitud. Por ejemplo, puedes usar un resumen KECCAK256
en una solicitud con el algoritmo EC_SIGN_P256_SHA256
.
Crear una firma
gcloud
Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de la CLI de Google Cloud.
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
Sustituye key-version por la versión de la clave que quieras usar para firmar. Sustituye key por el nombre de la clave. Sustituye key-ring por el nombre del conjunto de claves en el que se encuentra la clave. Sustituye location por la ubicación de Cloud KMS del conjunto de claves. Sustituye digest-algorithm por el algoritmo que quieras usar. Omite digest-algorithm para enviar input-file a Cloud KMS para firmar. Sustituye input-file y signature-file por las rutas locales del archivo que se va a firmar y del archivo de firma.
Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con la marca --help
.
C#
Para ejecutar este código, primero debes configurar un entorno de desarrollo de C# e instalar el SDK de Cloud KMS para C#.
Go
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de Cloud KMS.
Java
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de Cloud KMS.
Node.js
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de Cloud KMS.
PHP
Para ejecutar este código, primero debes consultar información sobre cómo usar PHP en Google Cloud e instalar el SDK de PHP de Cloud KMS.
Python
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de Cloud KMS.
Ruby
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Ruby e instalar el SDK de Ruby de Cloud KMS.
API
En estos ejemplos se usa curl como cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.
Usa el método CryptoKeyVersions.asymmetricSign
para realizar la firma. La respuesta de este método contiene la firma codificada en base64.
Validar una firma de curva elíptica
gcloud
Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de la CLI de Google Cloud.
Obtener la clave pública
gcloud kms keys versions get-public-key key-version \ --key key \ --keyring key-ring \ --location location \ --output-file output-file
Sustituye key-version por la versión de la clave. Sustituye key por el nombre de la clave. Sustituye key-ring por el nombre del conjunto de claves en el que se encuentra la clave. Sustituye location por la ubicación de Cloud KMS del conjunto de claves. Sustituye output-file por la ruta del archivo para guardar la clave pública en el sistema local.
Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con la marca --help
.
Verificar la firma
Los comandos de OpenSSL para validar la firma dependen del tipo de firma que se haya creado. Por ejemplo, para validar una firma de curva elíptica SHA-256 con OpenSSL, debes especificar -sha256
. Para validar una firma de curva elíptica SHA-384, debes especificar -sha384
.
openssl dgst \ -sha256 \ -verify public-key-file \ -signature signature-file \ message-file
Sustituye las variables por tus propios valores:
public-key-file. Ruta a un archivo que contiene la clave pública (por ejemplo,
"./my-key.pub"
).signature-file. Ruta a un archivo que contiene la firma que se va a verificar (por ejemplo,
"./my-data.sig"
).message-file. Ruta a un archivo que contiene el mensaje (por ejemplo,
"./my-data.txt"
).
Si la firma es válida, el comando muestra la cadena Verified OK
.
Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con el subcomando help
.
C#
Para ejecutar este código, primero debes configurar un entorno de desarrollo de C# e instalar el SDK de Cloud KMS para C#.
Go
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de Cloud KMS.
Java
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de Cloud KMS.
Node.js
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de Cloud KMS.
PHP
Para ejecutar este código, primero debes consultar información sobre cómo usar PHP en Google Cloud e instalar el SDK de PHP de Cloud KMS.
Python
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de Cloud KMS.
Ruby
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Ruby e instalar el SDK de Ruby de Cloud KMS.
API
En estos ejemplos se usa curl como cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.
Usa el método CryptoKeyVersions.getPublicKey para recuperar la clave pública y, a continuación, usa los comandos que se muestran en el ejemplo de línea de comandos para validar la firma.
Validar una firma RSA
gcloud
Para usar Cloud KMS en la línea de comandos, primero instala o actualiza a la versión más reciente de la CLI de Google Cloud.
Obtener la clave pública
gcloud kms keys versions get-public-key key-version \ --key key \ --keyring key-ring \ --location location \ --output-file output-file
Sustituye key-version por la versión de la clave. Sustituye key por el nombre de la clave. Sustituye key-ring por el nombre del conjunto de claves en el que se encuentra la clave. Sustituye location por la ubicación de Cloud KMS del conjunto de claves. Sustituye output-file por la ruta para guardar la clave pública en el sistema local.
Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con la marca --help
.
Verificar la firma
Los comandos de OpenSSL para validar la firma dependen del tipo de firma que se haya creado. Por ejemplo, para validar una firma RSA SHA-256 con relleno PSS, debes especificar -sha256
y -sigopt rsa_padding_mode:pss
. Para validar una firma SHA-512
RSA con relleno PSS, debes especificar -sha512
y -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
Sustituye las variables por tus propios valores:
public-key-file. Ruta a un archivo que contiene la clave pública (por ejemplo,
"./my-key.pub"
).signature-file. Ruta a un archivo que contiene la firma que se va a verificar (por ejemplo,
"./my-data.sig"
).message-file. Ruta a un archivo que contiene el mensaje (por ejemplo,
"./my-data.txt"
).
Si la firma es válida, el comando muestra la cadena Verified OK
.
Para obtener información sobre todas las marcas y los valores posibles, ejecuta el comando con el subcomando help
.
C#
Para ejecutar este código, primero debes configurar un entorno de desarrollo de C# e instalar el SDK de Cloud KMS para C#.
Go
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Go e instalar el SDK de Go de Cloud KMS.
Java
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Java e instalar el SDK de Java de Cloud KMS.
Node.js
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Node.js e instalar el SDK de Node.js de Cloud KMS.
PHP
Para ejecutar este código, primero debes consultar información sobre cómo usar PHP en Google Cloud e instalar el SDK de PHP de Cloud KMS.
Python
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Python e instalar el SDK de Python de Cloud KMS.
Ruby
Para ejecutar este código, primero debes configurar un entorno de desarrollo de Ruby e instalar el SDK de Ruby de Cloud KMS.
API
En estos ejemplos se usa curl como cliente HTTP para mostrar cómo se usa la API. Para obtener más información sobre el control de acceso, consulta el artículo sobre cómo acceder a la API Cloud KMS.
Usa el método CryptoKeyVersions.getPublicKey
para obtener la clave pública y, a continuación, usa los comandos que se muestran en el ejemplo de línea de comandos para validar la firma.