Concepts and Security¶

Portal Credential: how it works¶

Portal Credential combines three complementary security mechanisms to secure the retrieval of secrets by application containers.

Mutual TLS Authentication (mTLS)¶

The portal and the container authenticate each other using certificates issued by a dedicated internal PKI. The portal presents its server certificate; the container presents its client certificate. No communication is possible if mutual authentication fails. Only legitimate Reemo containers can reach the portal, and vice versa.

Ephemeral Key Pair¶

The container generates an in-memory key pair at request time, with a default validity of 5 minutes. This pair is never persisted to disk and is regenerated on each credential retrieval.

Temporary Vault Token¶

An ephemeral Vault token, valid for 5 minutes by default, serves as an authorization token. Generated on the fly, it expires automatically and cannot be renewed beyond its duration. Its access is limited to the permissions granted for the specific container.

Reduced Attack Surface¶

The combination of these three mechanisms creates multiple lines of defense:

External attacker without client certificate: blocked at TLS handshake.
Compromised container: the Vault token limited to 5 minutes reduces the exploitation window.
Traffic capture: the payload is encrypted with the container’s ephemeral public key.
Replay attack: the key pair is regenerated on each request, making it impossible to replay a previous request.
Network access: only container runtime environments can reach the Portal Credential services.

Why Vault must be unsealed after a restart¶

For security reasons, Vault never stores the keys that encrypt its data in plaintext on disk. At startup, Vault is “sealed” and cannot read its own secrets. It must be provided with unseal keys to become operational. This process repeats on every restart: server reboot, Docker restart, container recreation, or crash.