Gateway Trust, Certificates and Rotation

Updated Jul 26, 2026

Hosted File Gateway

Gateway Trust, Certificates and Rotation

The Security tab holds the certificate authorities, the endpoint's own identity, and the connection audit. Reading is Builder or Viewer; changing anything here needs Builder or DataMagik - Security.

The Security tab: certificate authorities on the left, server identity and rotation on the right

Trust anchors

A trust anchor is a CA the gateway will accept certificates from. There are two kinds:

Kind	Use it when
Generate our own issuing CA	You want to issue certificates to partners yourself. The signing key is generated and stored encrypted; it never leaves DataMagik.
Trust a partner's CA	The partner already runs their own PKI. Paste their CA public key and DataMagik validates the certificates they present against it.

Each is scoped to a protocol: SFTP (SSH certificates) or FTPS (X.509 certificates).

You do not need a CA at all. Password and SSH-key logins work without one, and most partners never need more. Certificates earn their keep when a partner wants to rotate their own keys without telling you every time.

Validation is complete rather than cosmetic: signature, chain, validity dates, the identity the credential requires, and revocation. A certificate that merely parses is not trusted.

Revocation

For certificates you issued, DataMagik keeps its own revocation list. For a partner's CA, it honours their published CRL.

Fetching a partner's CRL is a network call on an authentication path, so the behaviour is deliberate: the last good list is cached and used, which means checking against real revocation data that may be slightly stale rather than locking out every partner over a network blip. A CRL that has never been fetched denies — claiming to have checked when you have not is worse than admitting you could not. "We could not check" and "it is revoked" are recorded as different reasons.

What a partner should pin — and what they should not

Protocol	Pin this	Never pin this
SFTP	The SSH host key fingerprint	—
FTPS	The CA fingerprint	The server certificate fingerprint

Why leaf pinning breaks on FTPS. A TLS server presents exactly one certificate. When that certificate is replaced — on expiry, or after a compromise — a partner pinned to the leaf stops connecting the instant it changes, and there is no way to offer both at once. Pinned to the CA, which is stable and signs every replacement, rotation is invisible to them. The console labels the leaf "informational — do not pin" for this reason.

SFTP is different, and better: SSH negotiates host keys per algorithm, so two keys of different algorithms can genuinely be offered at the same time. That is what makes a real rotation window possible on the SSH side.

Rotating the SSH host key

Rotation costs every pinned partner their fingerprint, so it is a managed change, never a side effect of a deploy.

Tell partners first. Send the new fingerprint and the date it takes effect.
Security tab → Rotate → SSH host key (SFTP).
Set the window in days (14 by default).
Fill in How were partners told? — for example "Emailed all partners 2026-07-24".
Press Rotate.

The rotation is refused without the note. An announcement nobody recorded is an announcement nobody made, and it is the first question asked after a partner fails to connect.

During the window both keys are genuinely offered and each partner's own known_hosts decides which it asks for, so a partner who has updated and one who has not both connect. The replacement deliberately uses the other algorithm (Ed25519 ↔ ECDSA P-256) — two keys of the same algorithm cannot both be advertised, and a window that silently served only one would be exactly the flag-day it exists to avoid.

The console marks which fingerprint to pin. Retire now ends the window immediately — for a suspected compromise, where breaking pinned clients is the lesser harm.

Rotating the FTPS certificate

This is a cutover, not a window, for the reason above: one certificate at a time. The old row is kept as a record of what was replaced and what partners were told, but it is not served.

The announcement has to precede the rotation rather than accompany it. Partners pinned to the CA are unaffected — which is the argument for telling them to pin the CA in the first place.

The endpoint's own identity

One endpoint serves every tenant, so its TLS certificate is signed by the platform CA, never by yours — signing it with one tenant's CA would make that tenant the issuer of everyone's server certificate. The host key and server certificate are generated once on first start and never regenerated, because a service that "helpfully" regenerated would hand every pinned client a new fingerprint without anyone deciding to.

Recent connection attempts

The connection audit listing successful certificate logins with usernames, addresses and times

Both successes and failures, with username, method, source address and time. A run of failures from one address is what a brute-force attempt looks like, and the Auth failures 24h counter on the Transfers tab is the number to watch.

A failure against a username that resolves to one of your credentials is attributed to you and counted. A failure against an unknown username stays unattributed on purpose — attributing it would let anyone write rows into any customer's audit log just by choosing a username.