Managing KMS Master Keys and Secrets Vault

KMS & Secrets Vault Overview

Lynio IAM provides an integrated Key Management Service (KMS) and Secrets Vault module. This allows tenants to securely store sensitive credentials (database passwords, API tokens, service account credentials) using Envelope Encryption powered by AES-256-GCM authenticated symmetric cryptography.

Key Management Service (KMS)

The KMS module manages 256-bit symmetric Master Keys per tenant. Master keys encrypt data encryption keys (DEKs) or sensitive tenant payloads at rest.

Key Management Features

1. Generating Master Keys: Administrators can generate new 32-byte (256-bit) AES keys.
2. Primary Key Selection: One key per tenant is designated as the Primary Key. All newly created secrets in the Vault automatically use the active Primary Key for encryption.
3. Key Revocation: Revoking a key marks its status as revoked. Revoked keys cannot be used for new encryption requests, but existing secrets encrypted with a revoked key remain decryptable for historical access.
4. Permanent Deletion (Crypto-Shredding): Deleting a KMS Master Key permanently removes it from the database. Any secret or payload encrypted with that key becomes permanently unrecoverable (Crypto-Shredding).

Managing Master Keys in the Console

Navigate to Secrets Vault > KMS Master Keys (/vault):

• Click Generate Master Key to create a new key.
• Click Make Primary to switch the primary active key for new encryptions.
• Click Revoke to disable a key for future encryptions (requires double confirmation).
• Click Delete to perform crypto-shredding (requires checkbox confirmation).

Secrets Vault & Credentials

The Secrets Vault allows users to store sensitive key-value pairs, passwords, and service URLs encrypted with the tenant's primary KMS key.

Storing a New Secret

1. Navigate to Secrets Vault under the Secrets Vault tab.
2. Click Add Secret.
3. Fill in the required fields:
   • Secret Name: Human-readable title (e.g., Production PostgreSQL Password).
   • Category: Select an existing category or enter a custom folder name.
   • Username / Account: Account identifier or email.
   • Password / Secret Value: The raw sensitive credential value.
   • URL & Notes: Optional service URLs and metadata.
4. Click Encrypt & Save. The password payload is encrypted with AES-256-GCM using the tenant's primary KMS key before saving to the database.

Revealing and Decrypting Secrets

Secrets are decrypted on demand using the exact KMS Master Key ID stored alongside the secret:

1. Click Reveal next to a secret entry.
2. The server authenticates your permission, fetches the corresponding KMS key, decrypts the payload in real-time, and displays the plaintext secret in a secure modal with a copy-to-clipboard button.

Custom Categories & Fine-Grained Access Control (RBAC)

To prevent broad access to all tenant credentials, Lynio IAM supports Custom Categories with granular role-based permissions.

Creating & Managing Categories

1. Open the Categories tab inside Secrets Vault (/vault).
2. Click Create Category and enter a custom category name (e.g., Databases, API Keys, Infrastructure).
3. You can manage or delete custom categories at any time.

Category-Specific Permissions Syntax

Administrators can restrict user or group access to specific categories using namespaced permissions:

API Quick Reference

List Secrets

curl -X GET https://iam.lynio.cloud/api/v1/vault/secrets \
  -H "Authorization: Bearer <TOKEN>"

Create Secret

curl -X POST https://iam.lynio.cloud/api/v1/vault/secrets \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Redis Cluster Auth Token",
    "category": "Databases",
    "username": "default",
    "password": "super-secret-passphrase",
    "url": "redis://cache.prod.lynio.internal:6379"
  }'

Reveal Secret Password

curl -X GET https://iam.lynio.cloud/api/v1/vault/secrets/<SECRET_ID>/reveal \
  -H "Authorization: Bearer <TOKEN>"