Criar e validar assinaturas digitais MAC

Esta página mostra-lhe como criar e validar assinaturas digitais com base em chaves MAC.

É usada uma única chave, partilhada pelo produtor e pelo validador, para calcular uma etiqueta MAC a partir dos dados de entrada. A etiqueta MAC funciona como uma assinatura digital. Quando o validador recebe a mensagem e a respetiva etiqueta MAC associada, gera a sua própria etiqueta a partir do conteúdo da mensagem. Em seguida, o validador pode comparar a etiqueta recebida com a etiqueta gerada para ver se correspondem. Se as duas etiquetas corresponderem, o validador sabe que a mensagem que recebeu é a mesma que a mensagem assinada pelo produtor.

Antes de começar

  • Ao criar assinaturas digitais MAC, tem de usar uma chave com o objetivo da chave de MAC. Quando criar a chave, use MAC.

  • Certifique-se de que o ficheiro que quer assinar está dentro do limite de tamanho do ficheiro.Quando usa uma chave do Cloud HSM, o tamanho máximo do ficheiro para o qual pode criar uma assinatura MAC é de 16 KiB. Para todas as outras chaves, o tamanho máximo do ficheiro é de 64 KiB.

Funções necessárias

Para obter as autorizações de que precisa para criar e validar assinaturas, peça ao seu administrador que lhe conceda as seguintes funções de IAM na chave:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Criar uma assinatura MAC

gcloud

Para usar o Cloud KMS na linha de comandos, primeiro instale ou atualize para a versão mais recente da CLI do Google Cloud.

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

Substitua o seguinte:

  • KEY_VERSION: o número da versão da chave.
  • KEY_NAME: o nome da chave.
  • KEY_RING: o nome do conjunto de chaves que contém a chave.
  • LOCATION: a localização do Cloud KMS do conjunto de chaves.
  • INPUT_FILE_PATH: o caminho local para o ficheiro que quer assinar.
  • SIGNED_FILE_PATH: o caminho local onde quer guardar a assinatura gerada.

Para ver informações sobre todas as flags e valores possíveis, execute o comando com a flag --help.

C#

Para executar este código, primeiro configure um ambiente de desenvolvimento C# e instale o SDK C# do Cloud KMS.


using Google.Cloud.Kms.V1;
using Google.Protobuf;

public class SignMacSample
{
    public byte[] SignMac(
      string projectId = "my-project", string locationId = "us-east1", string keyRingId = "my-key-ring", string keyId = "my-key", string keyVersionId = "123",
      string data = "Sample data")
    {
        // Create the client.
        KeyManagementServiceClient client = KeyManagementServiceClient.Create();

        // Build the key version name.
        CryptoKeyVersionName keyVersionName = new CryptoKeyVersionName(projectId, locationId, keyRingId, keyId, keyVersionId);

        // Convert the data into a ByteString.
        ByteString dataByteString = ByteString.CopyFromUtf8(data);

        // Call the API.
        MacSignResponse result = client.MacSign(keyVersionName, dataByteString);

        // The data comes back as raw bytes, which may include non-printable
        // characters. To print the result, you could encode it as base64.
        // string encodedSignature = result.Mac.ToBase64();

        // Get the signature.
        byte[] signature = result.Mac.ToByteArray();

        // Return the result.
        return signature;
    }
}

Go

Para executar este código, primeiro configure um ambiente de desenvolvimento Go e instale o SDK Go do Cloud KMS.

import (
	"context"
	"encoding/base64"
	"fmt"
	"io"

	kms "cloud.google.com/go/kms/apiv1"
	"cloud.google.com/go/kms/apiv1/kmspb"
)

// signMac will sign a plaintext message using the HMAC algorithm.
func signMac(w io.Writer, name string, data string) error {
	// name := "projects/my-project/locations/us-east1/keyRings/my-key-ring/cryptoKeys/my-key/cryptoKeyVersions/123"
	// data := "my data to sign"

	// Create the client.
	ctx := context.Background()
	client, err := kms.NewKeyManagementClient(ctx)
	if err != nil {
		return fmt.Errorf("failed to create kms client: %w", err)
	}
	defer client.Close()

	// Build the request.
	req := &kmspb.MacSignRequest{
		Name: name,
		Data: []byte(data),
	}

	// Generate HMAC of data.
	result, err := client.MacSign(ctx, req)
	if err != nil {
		return fmt.Errorf("failed to hmac sign: %w", err)
	}

	// The data comes back as raw bytes, which may include non-printable
	// characters. This base64-encodes the result so it can be printed below.
	encodedSignature := base64.StdEncoding.EncodeToString(result.Mac)

	fmt.Fprintf(w, "Signature: %s", encodedSignature)
	return nil
}

Java

Para executar este código, primeiro configure um ambiente de desenvolvimento Java e instale o SDK Java do Cloud KMS.

import com.google.cloud.kms.v1.CryptoKeyVersionName;
import com.google.cloud.kms.v1.KeyManagementServiceClient;
import com.google.cloud.kms.v1.MacSignResponse;
import com.google.protobuf.ByteString;
import java.io.IOException;
import java.util.Base64;

public class SignMac {

  public void signMac() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String locationId = "us-east1";
    String keyRingId = "my-key-ring";
    String keyId = "my-key";
    String keyVersionId = "123";
    String data = "Data to sign";
    signMac(projectId, locationId, keyRingId, keyId, keyVersionId, data);
  }

  // Sign data with a given mac key.
  public void signMac(
      String projectId,
      String