kms_rpc.proto

// SPDX-FileCopyrightText: © 2024-2025 Phala Network <dstack@phala.network>
//
// SPDX-License-Identifier: Apache-2.0

syntax = "proto3";

import "google/protobuf/empty.proto";

package kms;

message GetAppKeyRequest {
  uint32 api_version = 1;
  string vm_config = 2;
}

message AppId {
  bytes app_id = 1;
}

message PublicKeyResponse {
  bytes public_key = 1;
  // Legacy signature without timestamp (for backward compatibility).
  // Signs: Keccak256("dstack-env-encrypt-pubkey" + ":" + app_id + public_key)
  bytes signature = 2;
  // Unix timestamp in seconds when the response was generated.
  uint64 timestamp = 3;
  // New signature with timestamp to prevent replay attacks.
  // Signs: Keccak256("dstack-env-encrypt-pubkey" + ":" + app_id + timestamp_be_bytes + public_key)
  bytes signature_v1 = 4;
}

message AppKeyResponse {
  // TLS CA certificate which is used as the trust anchor for all HTTPS RPCs in the system.
  string ca_cert = 1;
  // Disk encryption key used as the key phrase for the App's full disk encryption.
  bytes disk_crypt_key = 2;
  // X25519 key for decrypting secret environment variables.
  bytes env_crypt_key = 3;
  // ECDSA key for app's Ethereum-compatible signing operations.
  bytes k256_key = 4;
  // Signature of the k256 key signed by the root k256 key.
  bytes k256_signature = 5;
  // Reverse proxy app ID from DstackKms contract. (Deprecated. For backward compatibility)
  string tproxy_app_id = 6;
  // Reverse proxy app ID from DstackKms contract.
  string gateway_app_id = 7;
  // OS Image hash 
  bytes os_image_hash = 8;
}

message GetMetaResponse {
  string ca_cert = 1;
  bool allow_any_upgrade = 2;
  bytes k256_pubkey = 3;
  BootstrapResponse bootstrap_info = 4;
  bool is_dev = 5;
  optional string gateway_app_id = 6;
  optional string kms_contract_address = 7;
  optional uint64 chain_id = 8;
  optional string app_auth_implementation = 9;
}

message GetKmsKeyRequest {
  string vm_config = 1;
}

message KmsKeys {
  string ca_key = 1;
  bytes k256_key = 2;
}

message KmsKeyResponse {
  string temp_ca_key = 1;
  repeated KmsKeys keys = 2;
}

message GetTempCaCertResponse {
  string temp_ca_cert = 1;
  string temp_ca_key = 2;
  string ca_cert = 3;
}

message SignCertRequest {
  uint32 api_version = 1;
  bytes csr = 2;
  bytes signature = 3;
  string vm_config = 4;
}

message SignCertResponse {
  repeated string certificate_chain = 1;
}

// The kms public RPC service.
service KMS {
  // Request the app key given the app id and tdx quote
  rpc GetAppKey(GetAppKeyRequest) returns (AppKeyResponse);
  // KMS key handover
  rpc GetKmsKey(GetKmsKeyRequest) returns (KmsKeyResponse);
  // Request the app environment encryption public key given the app id
  rpc GetAppEnvEncryptPubKey(AppId) returns (PublicKeyResponse);
  // Request the KMS instance metadata for use as a probe and health check.
  rpc GetMeta(google.protobuf.Empty) returns (GetMetaResponse);
  // Request the temporary CA certificate and key
  rpc GetTempCaCert(google.protobuf.Empty) returns (GetTempCaCertResponse);
  // Sign a certificate
  rpc SignCert(SignCertRequest) returns (SignCertResponse);
  // Clear the image cache
  rpc ClearImageCache(ClearImageCacheRequest) returns (google.protobuf.Empty);
}

message ClearImageCacheRequest {
  string token = 1;
  string image_hash = 2;
  string config_hash = 3;
}

message BootstrapRequest {
  string domain = 1;
}

message BootstrapResponse {
  bytes ca_pubkey = 1;
  bytes k256_pubkey = 2;
  bytes attestation = 3;
}

message OnboardRequest {
  string source_url = 1;
  string domain = 2;
}

message OnboardResponse {
  // k256 public key (secp256k1) inherited from source KMS
  bytes k256_pubkey = 1;
}

// Attestation info needed for on-chain KMS authorization.
message AttestationInfoResponse {
  // Device ID (SHA256 of platform device identifier)
  bytes device_id = 1;
  // Aggregated measurement of the VM execution environment
  bytes mr_aggregated = 2;
  // OS image hash
  bytes os_image_hash = 3;
  // Attestation mode (e.g. "dstack-tdx", "dstack-gcp-tdx")
  string attestation_mode = 4;
  // Custom site name for display
  string site_name = 5;
  // Ethereum RPC URL from auth API
  string eth_rpc_url = 6;
  // KMS contract address from auth API
  string kms_contract_address = 7;
}

// The Onboard RPC service.
service Onboard {
  // Bootstrap a new KMS
  rpc Bootstrap(BootstrapRequest) returns (BootstrapResponse);
  // Onboard from existing KMS
  rpc Onboard(OnboardRequest) returns (OnboardResponse);
  // Get attestation info for on-chain KMS authorization
  rpc GetAttestationInfo(google.protobuf.Empty) returns (AttestationInfoResponse);
  // Finish onboarding
  rpc Finish(google.protobuf.Empty) returns (google.protobuf.Empty);
}