LocalCloud Cloud KMS Local Emulator
Get started
local.cloud / agents
Read this page as Markdown ↗
local.cloud — Cloud KMS Local Emulator .md Open tab

Cloud KMS

Cloud KMS manages cryptographic keys and their versions. Applications use keys to encrypt data, sign messages, or verify authenticity without storing key material in application code.

When to use Cloud KMS

Typical uses

Use when applications encrypt, decrypt, sign, or verify data using managed keys and explicit key versions. Keep cryptographic key lifecycle separate from application payloads.

Examples

  • Encryption and decryption
  • Signing, MACs, and key lifecycle tests

Explore another service

View all

Example usage

Service ID: kms. Starts by default. Use an already running LocalCloud runtime for the examples below.

Export the local project and mapped endpoints in your client process, then use the client settings below. First-time setup

# Export GOOGLE_CLOUD_PROJECT and CLOUD_KMS_EMULATOR_HOST
eval "$(localcloud env)"

REST gateway examples use the generated HTTP address in SERVICE_USAGE_EMULATOR_HOST; native SDKs can use a different protocol.

Java · REST

List key rings

List key rings; Cloud KMS organizes the cryptographic keys used to encrypt data and sign messages.

Call the Google Cloud REST API with the JDK HTTP client. Requires JDK 17+. Results reflect resources already created in your local project.

Discovery check · reads existing local state.

Save as Hello.java

import java.net.URI;
import java.net.http.*;
import java.time.Duration;
import java.util.Objects;

public class Hello {
  public static void main(String[] args) throws Exception {
    var project = Objects.requireNonNull(System.getenv("GOOGLE_CLOUD_PROJECT"));
    var endpoint = Objects.requireNonNull(System.getenv("SERVICE_USAGE_EMULATOR_HOST"));
    var url = URI.create(endpoint.replaceAll("/+$", "") + "/v1/projects/" + project + "/locations/us-central1/keyRings");
    var request = HttpRequest.newBuilder(url).timeout(Duration.ofSeconds(30)).GET().build();
    var client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(10)).build();
    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() >= 400) {
      throw new IllegalStateException(response.statusCode() + ": " + response.body());
    }
    System.out.println(response.body());
  }
}

Run the example

java Hello.java

Verify the result

The request succeeds. An empty list or no printed rows is valid before matching resources exist. Continue with the documented workflows for a resource test.

Verify a resource workflow by creating isolated state, performing the operation, and reading the result back. Run cleanup even after a failure; delete only test-owned resources.

Connection failed? Check localcloud status --verbose, enabled services, and client exports. Stop accidental Google Cloud calls; correct local routing before retrying.

Documented workflows

  • Locations, random bytes, keys/versions, rotation, destruction/restoration, and eligible deletion

    Create a key ring, key, and version; rotate or schedule destruction and restore the eligible version. Inspect state transitions and test how the application handles unavailable key material.

  • SOFTWARE symmetric/asymmetric cryptography, public keys, and MACs

    Encrypt and decrypt a fixture, verify an asymmetric signature, or compute and check a MAC with a SOFTWARE key. Assert plaintext or signature bytes and rejected inputs.

  • Supported post-quantum signing/decapsulation and wrapped key imports

    Use a supported post-quantum key type or create an import job and submit correctly wrapped key material. Check the resulting version and operation-specific errors.

  • Strict IAM, conditions, audits, metrics, and authenticated Workflows connectors

    Apply a strict IAM policy and exercise allowed and denied cryptographic calls. Inspect local audit events and metrics, or invoke the authenticated KMS Workflows connector.

  • Secret Manager CMEK, project Inventory, and Autokey/KeyHandles

    Protect a Secret Manager secret with CMEK, then inspect its project-owned inventory entry. Exercise Autokey or KeyHandles for the supported global Secret Manager resource scope.

Service boundaries

  • SOFTWARE keys; hardware custody and Google authority require Google Cloud
  • Inventory/Autokey covers project-owned global Secret Manager resources; no folder ancestry or other protected types
  • KeyRing deletion differs from Google Cloud
Agent testing

Use Cloud KMS with an AI agent

Before the agent changes application logic, have it create local Cloud KMS state, read it back with the project SDK, and note which feature the check covered. That first local call catches accidental production routing and needs no GCP account, service-account key, or billing project.

Configure this repo

Set up this repository to use LocalCloud for local GCP development. First read https://local.cloud/ai/agents.md, then inspect this repo, identify the GCP services and SDK language, configure emulator environment variables, and run the narrowest integration test against localhost. Do not use real GCP credentials or production endpoints.

Production endpoints, auth, IAM, quotas, regional behavior, and final release validation still need the target Google Cloud project.

Agent resources has more prompts and the AGENTS.md template.

Related guides

Desktop view