Skip to main content
The Public Keys service provides methods for managing encryption public keys used in the Cross-Media Measurement system.

​
Resource

​
PublicKey

Singleton resource representing an encryption public key. Resource Patterns:
  • dataProviders/{data_provider}/publicKey
  • measurementConsumers/{measurement_consumer}/publicKey
Each parent resource has exactly one PublicKey singleton resource.
​
name
string
required
Resource name.Format:
  • dataProviders/{data_provider}/publicKey
  • measurementConsumers/{measurement_consumer}/publicKey
​
public_key
SignedMessage
required
Serialized EncryptionPublicKey for the parent resource, which can be verified using certificate.The version of the EncryptionPublicKey message must match the API version used to last update this resource.
​
certificate
string
required
Resource name of the Certificate that can be used to verify public_key.This must have the same parent as the PublicKey.Format: {parent}/certificates/{certificate}

​
EncryptionPublicKey

The public_key field contains a signed EncryptionPublicKey message:
​
format
Format
required
Format of data for this public key.Values:
  • FORMAT_UNSPECIFIED - Default value
  • TINK_KEYSET - Tink Keyset format
​
data
bytes
required
The format-specific key data.For TINK_KEYSET format: Serialized google.crypto.tink.Keyset message. Encrypted message values use Tink’s wire format.format and data together must specify all necessary information to decrypt messages given a private key.

​
Methods

​
UpdatePublicKey

Updates the PublicKey for the specified parent.
This method performs a full replacement update. Partial updates are not supported.
​
public_key
PublicKey
required
Resource to update.Must include the resource name to identify which PublicKey to update.
​
response
PublicKey
The updated PublicKey resource.

​
Example Request

message UpdatePublicKeyRequest {
  PublicKey public_key = 1;
}

message PublicKey {
  string name = 1;              // "measurementConsumers/mc-123/publicKey"
  SignedMessage public_key = 2;  // Signed EncryptionPublicKey
  string certificate = 3;        // "measurementConsumers/mc-123/certificates/cert-456"
}

​
SignedMessage Structure

message SignedMessage {
  google.protobuf.Any message = 4;      // Contains EncryptionPublicKey
  bytes signature = 2;                   // Digital signature
  string signature_algorithm_oid = 3;    // e.g., "1.2.840.113549.1.1.11" for SHA256withRSA
}

​
EncryptionPublicKey Structure

message EncryptionPublicKey {
  Format format = 1;  // TINK_KEYSET
  bytes data = 2;     // Serialized Tink Keyset
}

enum Format {
  FORMAT_UNSPECIFIED = 0;
  TINK_KEYSET = 1;
}

​
Error Conditions

  • NOT_FOUND - Parent resource or certificate not found
  • INVALID_ARGUMENT - Invalid public key data, signature, or mismatched parent
  • PERMISSION_DENIED - Caller lacks permission to update the public key
  • FAILED_PRECONDITION - Certificate cannot verify the signature

​
Usage Patterns

​
Creating a Signed Public Key

  1. Generate encryption key pair:
Generate a public/private key pair using your cryptographic library (e.g., Google Tink).
  1. Serialize the public key:
EncryptionPublicKey {
  format: TINK_KEYSET
  data: <serialized Tink Keyset bytes>
}
  1. Sign the serialized key:
Sign the serialized EncryptionPublicKey using the private key associated with your certificate.
  1. Create the SignedMessage:
SignedMessage {
  message: {
    type_url: "type.googleapis.com/wfa.measurement.api.v2alpha.EncryptionPublicKey"
    value: <serialized EncryptionPublicKey>
  }
  signature: <digital signature bytes>
  signature_algorithm_oid: "1.2.840.113549.1.1.11"  // SHA256withRSA
}
  1. Update the PublicKey resource:
UpdatePublicKeyRequest {
  public_key: {
    name: "measurementConsumers/mc-123/publicKey"
    public_key: <SignedMessage from step 4>
    certificate: "measurementConsumers/mc-123/certificates/cert-456"
  }
}

​
Rotating Public Keys

To rotate encryption keys:
  1. Generate new key pair
  2. Create new certificate (if needed) via Certificates API
  3. Update PublicKey with new key and certificate reference
  4. Update local systems to use new private key for decryption
  5. Maintain old private key temporarily to decrypt in-flight messages
// Step 3: Update with new public key
UpdatePublicKeyRequest {
  public_key: {
    name: "dataProviders/dp-789/publicKey"
    public_key: <new SignedMessage>
    certificate: "dataProviders/dp-789/certificates/cert-new"
  }
}

​
Verifying a Public Key

When receiving encrypted data:
  1. Fetch the PublicKey resource:
// Use a Get operation on the parent resource to get the publicKey field
name: "measurementConsumers/mc-123/publicKey"
  1. Fetch the referenced Certificate:
GetCertificateRequest {
  name: "measurementConsumers/mc-123/certificates/cert-456"
}
  1. Verify the signature:
Use the certificate’s public key to verify the signature in the SignedMessage.
  1. Extract and use the public key:
Deserialize the EncryptionPublicKey from the message field and use it to encrypt data for the parent resource.

​
Tink Keyset Format

When using TINK_KEYSET format:

​
Example Tink Keyset Usage

// Generate a new keyset
KeysetHandle keysetHandle = KeysetHandle.generateNew(
    KeyTemplates.get("AES128_GCM"));

// Serialize public keyset
ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
CleartextKeysetHandle.write(keysetHandle.getPublicKeysetHandle(),
    BinaryKeysetWriter.withOutputStream(outputStream));
byte[] publicKeysetBytes = outputStream.toByteArray();

// Create EncryptionPublicKey
EncryptionPublicKey encryptionPublicKey = EncryptionPublicKey.newBuilder()
    .setFormat(EncryptionPublicKey.Format.TINK_KEYSET)
    .setData(ByteString.copyFrom(publicKeysetBytes))
    .build();

​
Signature Algorithms

Common signature algorithm OIDs:
AlgorithmOID
SHA256withRSA1.2.840.113549.1.1.11
SHA384withRSA1.2.840.113549.1.1.12
SHA512withRSA1.2.840.113549.1.1.13
SHA256withECDSA1.2.840.10045.4.3.2
SHA384withECDSA1.2.840.10045.4.3.3
SHA512withECDSA1.2.840.10045.4.3.4

​
Security Considerations

  • Always verify signatures before trusting public keys
  • Use strong signature algorithms (SHA256 or better)
  • Rotate keys regularly
  • Keep private keys secure and never transmit them
  • Ensure certificates are valid and not revoked
The PublicKey resource is a singleton - each parent has exactly one. Updating it replaces the previous key entirely.

​
Best Practices

  1. Certificate Management: Ensure the referenced certificate is valid before updating the public key
  2. Version Matching: The EncryptionPublicKey message version must match the API version
  3. Signature Verification: Always verify the signature using the referenced certificate
  4. Key Rotation: Plan for key rotation by maintaining old private keys during transition
  5. Format Consistency: Use TINK_KEYSET format for compatibility with Tink cryptographic library

Build docs developers (and LLMs) love

Get started for freeTalk to us