CredentialsCipher: Symmetric Encryption for Backend Credentials

Overview

The CredentialsCipher service provides symmetric encryption for sensitive credentials associated with backend profiles. It ensures that credentials, such as API keys or tokens for upstream services, are stored securely at rest in the platform's database.

This component leverages the pgcrypto extension in PostgreSQL to perform all cryptographic operations directly within the database server. The encryption key is supplied to the service at startup and is never persisted, logged, or exposed in query plans.

The CredentialsCipher service is an internal component of the Admin API. It is invoked when API publishers create or update backend profiles that require credentials. Its primary functions are to encrypt plaintext credentials before they are written to the database and to decrypt them when they are read for use or management.

How It Works

The service manages the entire lifecycle of credential encryption, from startup validation to runtime operations.

Initialization and Preflight Check

On application startup, the CredentialsCipher component performs a critical preflight check to ensure it is configured correctly and the database environment is ready.

The startup sequence is as follows:

1. The service reads the encryption key from the S2R_CREDENTIAL_KEY environment variable.
2. It connects to the PostgreSQL database and performs a self-test by encrypting and then decrypting a known plaintext string ({"probe":"s2r-preflight"}).
3. This round-trip test validates two conditions:
   • The pgcrypto extension is available and functioning correctly in the database.
   • The provided encryption key is well-formed and accepted by pgcrypto.
4. If the test fails for any reason, the application will fail to start, logging error S2R-ADM-0419 with details about the cause (e.g., pgcrypto unavailable or key invalid).
5. A successful test is logged with the message CredentialsCipher preflight OK.

Encryption Process

When a caller needs to store a credential, the encrypt method is used.

1. The service receives the credential as a plaintext JSON string.
2. It executes the SQL statement select encode(pgp_sym_encrypt(?, ?), 'base64') against the database.
3. The plaintext and the encryption key are passed as bound parameters to the query. This prevents the key from being exposed in database logs, pg_stat_statements, or query execution plans.
4. Inside PostgreSQL, the pgp_sym_encrypt function encrypts the data using the AES-256 algorithm. The result is a bytea (byte array).
5. The encode function then converts this bytea ciphertext into a Base64-encoded string.
6. The CredentialsCipher service wraps this Base64 string in a JSON object called an "envelope," which includes metadata about the encryption.
7. This final JSON envelope string is returned to the caller, ready to be stored in a jsonb database column.

Decryption Process

When a stored credential needs to be accessed, the decrypt method is used.

1. The service receives the JSON envelope string from the database.
2. It parses the envelope and extracts the Base64-encoded ciphertext from the enc field. The parser is designed to defensively handle malformed input or raw ciphertext strings that are not wrapped in an envelope.
3. It executes the SQL statement select pgp_sym_decrypt(decode(?, 'base64'), ?) against the database.
4. The Base64 ciphertext and the encryption key are passed as bound parameters.
5. Inside PostgreSQL, the decode function converts the Base64 string back into a bytea.
6. The pgp_sym_decrypt function uses the key to decrypt the bytea, returning the original plaintext JSON string.
7. This plaintext string is returned to the caller.

Data Flow Diagram

The following diagram illustrates the encryption and decryption flows.

flowchart TD
    subgraph Encryption
        direction LR
        A[Admin API with<br/>Plaintext Credential] --> B(CredentialsCipher Service);
        B -- "1. encrypt(plaintext)" --> C{PostgreSQL Database};
        C -- "2. pgp_sym_encrypt" --> D[Base64 Ciphertext];
        D -- "3. Wrap in envelope" --> B;
        B -- "4. Return JSON envelope" --> E[Stored in DB];
    end

    subgraph Decryption
        direction LR
        F[Admin API reads<br/>Encrypted Credential] --> G(CredentialsCipher Service);
        G -- "1. decrypt(envelope)" --> H{PostgreSQL Database};
        H -- "2. pgp_sym_decrypt" --> I[Plaintext Credential];
        I -- "3. Return plaintext" --> G;
        G -- "4. Return to caller" --> F;
    end

Configuration

The CredentialsCipher service is configured via a single, mandatory property, which can be provided as a Spring property or an environment variable.

Storage Envelope Format

Encrypted credentials are stored in the database as a JSON object, referred to as an "envelope." This format provides versioning and algorithm information alongside the ciphertext.

Example Envelope:

{
  "v": 1,
  "alg": "pgcrypto-aes256",
  "enc": "<base64 pgp_sym_encrypt output>"
}

The fields of the envelope are described below.

API Reference

The CredentialsCipher component exposes several Java methods for internal use by the Admin API.

Troubleshooting

The most common issues with this service occur at application startup.

See Also

• Backend Profile Management: This service is a core part of securing credentials for backend profiles.
• Database Requirements: The CredentialsCipher service depends on the PostgreSQL pgcrypto extension.
• Credential Migration: The isEnvelope and decryptSecret methods support a gradual migration from legacy plaintext credentials to encrypted ones. See the guide on migrating legacy credentials for more information.

All SOAP-to-REST docs