Secure Secret Management and Resolution in Platform Gateway

[nimsara66]

Overview

Platform administrators must be able to configure LLM provider API keys securely when creating and managing LLM providers. To achieve this, the gateway platform must support:

1. Secure secret management via the Gateway REST API
2. Secure secret resolution via the Gateway Controller at deployment time

This design ensures that sensitive credentials are never persisted in plain text within deployment artifacts or policy configurations.

Example LLM Provider Definition

apiVersion: gateway.api-platform.wso2.com/v1alpha1
kind: LlmProvider
metadata:
  name: wso2-openai-provider
spec:
  displayName: WSO2 OpenAI Provider
  version: v1.0
  template: openai
  vhost: openai
  upstream:
    url: https://webhook.site/f4aeeaeb-291e-47ed-a0e5-587cd553f2b0
    auth:
      type: api-key
      header: Authorization
      value: "Bearer $secret{wso2-openai-key}"
  accessControl:
    mode: allow_all

In this configuration, the API key is referenced using a secure secret placeholder: $secret{wso2-openai-key}. The actual secret value is resolved securely at deployment time.

1. Secure Secret Management via Gateway REST API

The Gateway REST API must expose administrator-only endpoints to Create, Read, Update, and Delete (CRUD) secrets.

Key Requirements

• Secrets must be encrypted before persistence.
• Encryption and persistence providers must be pluggable.
• The default configuration should use:
  • Encryption: AES-GCM-256
  • Persistence: Built-in SQLite database

Sample Secret Creation Request

curl --location 'http://localhost:9090/secrets' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ADMIN_TOKEN>' \
  --data '{
    "id": "wso2-openai-key",
    "value": "sk-xxx"
  }'

Once stored, the secret can be referenced in API policy configurations using:

$secret{wso2-openai-key}

---

2. Secure Secret Resolution via Gateway Controller

Secrets must never be persisted in resolved (plain-text) form within deployment artifacts. Instead, secret resolution must occur just before the compiled policy configuration is sent to the policy engine.

To support this, the Gateway Controller must be able to:

• Identify which policy parameters require secret resolution
• Resolve only those fields at deployment time
• Inject the resolved values into the final runtime configuration

Vendor Extension: x-resolve

A vendor extension named x-resolve is introduced in policy definitions to declare which parameter fields require secret resolution.

Sample Policy Definition

name: modify-headers
version: v0.1.0
description: Header modification policy
parameters:
  type: object
  properties:
    requestHeaders:
      type: array
      description: Request header modification rules
      items:
        type: object
        properties:
          action:
            type: string
            description: Header action (SET, APPEND, DELETE)
          name:
            type: string
            description: Header name
          value:
            type: string
            description: Header value (required for SET and APPEND, ignored for DELETE)
            maxLength: 8192
        required:
          - action
          - name
        x-resolve:
          - value

    responseHeaders:
      type: array
      description: Response header modification rules
      items:
        type: object
        properties:
          action:
            type: string
            description: Header action (SET, APPEND, DELETE)
          name:
            type: string
            description: Header name
          value:
            type: string
            description: Header value (required for SET and APPEND, ignored for DELETE)
            maxLength: 8192
        required:
          - action
          - name
        x-resolve:
          - value

Resolution Flow

1. Gateway Startup

   • The controller scans all policy definitions.
   • It identifies parameters marked with the x-resolve vendor extension.
   • It compiles and caches the parameter paths that require secret resolution.

2. API Deployment

   • Before sending the compiled policy configuration to the policy engine:
     • The controller resolves all $secret{...} placeholders found in x-resolve fields.
     • Resolved values are injected into the final configuration.
     • Plain-text secrets are never persisted.

Example Resolution

Input configuration:

Authorization: "Bearer $secret{wso2-openai-key}"

Resolved at deployment time:

Authorization: "Bearer sk-xxx"

[nimsara66]

Secret Creation API Design Considerations

A key design decision is whether secret creation should use a simple JSON-based REST payload or follow the same YAML artifact model used by other Gateway resources.

1. Simple JSON REST Payload
2. YAML Artifact-Based Secret Resource

Reference: Kubernetes Secret Encryption Model

apiVersion: apiserver.config.k8s.io/v1
kind: EncryptionConfiguration
resources:
  - resources:
      - secrets
    providers:
      - aesgcm: # Use AES-GCM provider
          keys:
            - name: key1
              secret: <BASE64_KEY>
      - identity: {} # Fallback for existing unencrypted secrets

[tharindu1st]

@nimsara66 how it handles when APIS created from control plane.
We have to pass the values to gateway in raw format and encrypt at the gateway, since control plane doesn't know about the encryption key for gateway

[nimsara66]

@tharindu1st,
Yes, because the encryption key or algorithm is not shared between the gateway and the control plane.

That said, would it be an issue if the communication between the gateway and the control plane is secure?