Backend credential encryption

To call a SOAP backend, a service needs connection credentials. The product stores those credentials encrypted at rest and is careful never to expose them in plaintext through the API or the logs.

---

How credentials are stored

Backend credentials live in the product's own PostgreSQL database, on the backend-profile row, inside an encrypted envelope. Encryption uses PostgreSQL's pgcrypto extension with AES-256 symmetric encryption (pgp_sym_encrypt). The encrypted envelope is a small JSON structure of the shape:

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

The plaintext credential material is never persisted unencrypted.

The encryption key

The symmetric key is held by the application, not baked into the database. It is supplied via the S2R_CREDENTIAL_KEY environment variable, sourced from your secret store (on the GCP-native deployment this is bound from Secret Manager). The admin API and the runtime both read this key — admin to encrypt on write, runtime to decrypt on demand when executing a backend call.

Key-handling rules:

• The key must be present at startup. If it is unset, the service refuses to operate on credentials rather than falling back to a weak default:
  • admin API raises S2R-ADM-0419
  • runtime raises S2R-RUN-0419
• The key is the same value across the services that need it; rotating the key invalidates every existing encrypted credential row, so it must be re-applied on every deploy with the current value (see your deployment runbook). Treat it as an operator-critical secret.
• The product performs a preflight round-trip at startup to confirm pgcrypto is available and the key is well-formed before accepting traffic.

---

Plaintext is never returned or logged

Credential values are write-only from the API's perspective:

• When you create or update a backend profile, you pass the plaintext credential in the request body; it is encrypted and stored.
• The API never echoes the plaintext back. Responses carry only a metadata envelope, for example:

  {
    "credentials": {
      "set": true,
      "lastUpdatedAt": "2026-04-18T14:02:11Z",
      "lastUpdatedBy": "alice@example.gov.il"
    }
  }
  

• Plaintext credential values are never written to logs.

This means the UI and API can tell you whether a credential is set and when it last changed, but never reveal the value itself.

---

Credential shapes per auth type

The shape of the credential payload depends on the backend's authentication type. All shapes below are stored encrypted under S2R_CREDENTIAL_KEY:

| Auth type | Credential payload (plaintext on the wire only) | |---|---| | none | empty | | basic | { username, password } | | bearer | { bearerToken } | | api_key_header | { apiKeyHeaderName, apiKeyValue } | | oauth2_client_credentials | { oauth2ClientSecret } — the non-secret OAuth2 fields (oauth2TokenEndpoint, oauth2ClientId, oauth2Scope, oauth2ExtraParams) are stored as plain columns on the profile row | | mutual TLS | credentials.mtls = { certPem, keyPem }, activated by mtlsEnabled = true (independent of the auth type above) |

mTLS material can be combined with any of the auth types — for example, basic over a mutually-authenticated TLS channel.

The inbound SOAP-facade (Consume direction) and the WS-Security token material it accepts are covered separately in the conversion documentation. This page is about how the backend connection credentials are encrypted and handled.

---

Operational notes

• Because the key lives in your secret store and the ciphertext lives in your database, the credentials never leave your VPC.
• A connection profile can be exercised safely with POST /admin/v1/backend-profiles/{profileId}:test-connection (DNS / TCP / WSDL reachability) without exposing the stored secret.
• If you see S2R-ADM-0419 / S2R-RUN-0419 after a deploy, the key binding was dropped on the new revision — re-apply S2R_CREDENTIAL_KEY and redeploy. See Troubleshooting.

---

All Specaria SOAP to REST docs