Open Secrets Language (OSL) Standard Specification v0.1-draft

This document outlines the DCDR Open Standard, a developer-friendly specification for a unified API to interact with multiple secret management backends. It is intended to be a practical guide that can evolve into a more formal RFC.

1. Philosophy

The standard defines a common interface for secret lifecycle operations, abstracting the complexities of underlying providers (like Vault, OpenBao, AWS Secrets Manager, etc.). A compliant server enables applications to create, retrieve, and manage secrets without being tied to a specific backend implementation.

2. Authentication

Clients MUST authenticate by providing a bearer token in the Authorization header of each request.

Authorization: Bearer <your-token>

An initial token can be obtained by authenticating against the /api/dcdrAuth endpoint.

3. Core Secret Operations

These endpoints form the core of the standard for managing secrets.

---

Create or Update a Secret

Creates a new secret or updates an existing one in the specified backend.

• Endpoint: POST /api/dcdrCreateSecret
• Permissions: Root or authorized Application User.

Request Body:

{
  "app_id": "your-app-id",
  "secret_name": "my-database-credentials",
  "backend": "aws-1",
  "mount_path": "production",
  "data": {
    "username": "db_user",
    "password": "super_secret_password"
  }
}

Responses:

• 200 OK: The secret was successfully created or updated.
• 400 Bad Request: The request body is invalid or incomplete.
• 403 Forbidden: The provided token does not have permission.
• 500 Internal Server Error: The server failed to write the secret to the backend.

---

Retrieve a Secret

Retrieves the data associated with a secret.

• Endpoint: POST /api/dcdrGet
• Permissions: Root or authorized Application User.

Request Body:

{
  "app_id": "your-app-id",
  "secret_name": "my-database-credentials"
}

Responses:

• 200 OK: Returns the secret data.

  {
    "username": "db_user",
    "password": "super_secret_password"
  }

• 403 Forbidden: Permission denied or the secret is currently tainted.
• 404 Not Found: The secret does not exist for the given application.

---

Taint a Secret

Suspends access to a secret at the DCDR server level without deleting it from the backend. A tainted secret cannot be retrieved via dcdrGet.

• Endpoint: POST /api/dcdrTaint
• Permissions: Root or authorized Application User.

Request Body:

{
  "app_id": "your-app-id",
  "secret_name": "my-database-credentials"
}

Responses:

• 200 OK: The secret was successfully tainted.
• 403 Forbidden: Permission denied.
• 404 Not Found: The secret does not exist.

---

Untaint a Secret

Restores access to a tainted secret.

• Endpoint: POST /api/dcdrUntaint
• Permissions: Root or authorized Application User.

Request Body:

{
  "app_id": "your-app-id",
  "secret_name": "my-database-credentials"
}

Responses:

• 200 OK: The secret was successfully untainted.
• 403 Forbidden: Permission denied.
• 404 Not Found: The secret does not exist.

---

Delete a Secret

Permanently deletes a secret from the backend provider. This action is irreversible.

• Endpoint: POST /api/dcdrDestroy
• Permissions: Root or authorized Application User.

Request Body:

{
  "app_id": "your-app-id",
  "secret_name": "my-database-credentials"
}

Responses:

• 200 OK: The secret was successfully deleted.
• 403 Forbidden: Permission denied.
• 404 Not Found: The secret does not exist.

---

Check if Secret is Tainted

Checks the tainted status of a secret.

• Endpoint: POST /api/dcdrIsTainted
• Permissions: Root or authorized Application User.

Request Body:

{
  "app_id": "your-app-id",
  "secret_name": "my-database-credentials"
}

Responses:

• 200 OK: Returns the tainted status.

  {
    "tainted": true
  }

• 404 Not Found: The secret does not exist.

4. Management API

These endpoints are for managing server resources like applications and users. They typically require root privileges.

List Applications

• Endpoint: GET /api/dcdrListApps
• Description: Lists all registered applications.

Responses:

• 200 OK:

  [
    {
      "app_id": "app-id-1",
      "app_name": "app-1"
    }
  ]

List Secrets for an Application

• Endpoint: POST /api/dcdrListSecrets
• Description: Lists all secrets associated with a specific application.

Request Body:

{
  "app_id": "your-app-id"
}

Responses:

• 200 OK:

  [
    {
      "secret_name": "secret-1",
      "backend": "vault-1",
      "mount_path": "secret",
      "tainted": false
    }
  ]

List Backends

• Endpoint: GET /api/dcdrListBackends
• Description: Lists all configured secret backends and their stats.

Responses:

• 200 OK:

  [
    {
      "backend": "vault-1",
      "num_applications": 1,
      "num_secrets": 1,
      "type": "vault"
    }
  ]