FTPS Secure File Transfer — Xferity MFT Explicit TLS

FTPS

FTPS (FTP over TLS) is a file transfer protocol that combines legacy FTP with TLS encryption. Xferity supports FTPS for upload and download flows with explicit TLS mode.

This page explains the FTPS trust model, configuration, constraints, and operational behavior in Xferity.

What FTPS is in Xferity

FTPS is a transfer transport. It is used when a partner requires FTP-compatible behavior with TLS security.

FTPS is different from SFTP:

SFTP runs over SSH; FTPS runs over FTP with TLS
SFTP uses SSH host key verification; FTPS uses X.509 certificate validation
FTPS requires a data channel separate from the control channel (handled by passive mode)

Protocol constraints

Xferity supports:

Explicit TLS mode only — the connection starts unencrypted and upgrades to TLS via AUTH TLS. Implicit TLS (where the connection starts as TLS on port 990) is not supported.
Passive mode only — passive=true is required for all FTPS partners.

These constraints reflect real-world FTPS compatibility and firewall behavior. If a partner requires implicit mode, contact Xferity support.

Trust model

FTPS trust is based on TLS certificate validation.

Before exchanging data, Xferity verifies the server’s TLS certificate against a trusted CA. Optionally, you can pin to a specific server certificate fingerprint.

Configuration options:

CA certificate (tls.ca_cert): validate the server’s certificate against a specific CA
Server fingerprint (tls.server_cert_fingerprint): pin to a specific server certificate SHA-256 fingerprint
Skip verify (tls.insecure_skip_verify=true): disable verification (not recommended, rejected in hardened mode)

Partner definition example

id: insurance-ftps
display_name: Insurance Partner FTPS
protocol: ftps
ftps:
  connection:
    host: ftps.insurance-partner.example
    port: 21
    passive: true
  auth:
    username: xferity-transfer
    password: env:INSURANCE_FTPS_PASSWORD
  tls:
    mode: explicit
    ca_cert: file:/etc/xferity/certs/insurance-partner-ca.pem
    server_cert_fingerprint: ""
    insecure_skip_verify: false

Full configuration reference

Connection fields

Field	Required	Default	Description
`connection.host`	yes	—	FTPS server hostname or IP
`connection.port`	no	`21`	FTPS server port
`connection.passive`	yes	—	Must be `true`. Passive mode only.

Auth fields

Field	Required	Description
`auth.username`	yes	FTP login username
`auth.password`	no	Password or secret reference

TLS fields

Field	Default	Description
`tls.mode`	`explicit`	Must be `explicit`. Implicit mode not supported.
`tls.ca_cert`	—	`file:`, `env:`, or `vault:` reference to a PEM CA cert for server validation
`tls.client_cert`	—	PEM client certificate for mutual TLS
`tls.client_private_key`	—	PEM client private key for mutual TLS
`tls.client_key_passphrase`	—	Passphrase for the client private key
`tls.server_cert_fingerprint`	—	SHA-256 fingerprint to pin to specific server cert
`tls.insecure_skip_verify`	`false`	Skip TLS cert verification; rejected by hardened mode

Flow example: FTPS upload

flows:
  insurance-claims-upload:
    direction: upload
    enabled: true
    target:
      partner: insurance-ftps
      path: /incoming/claims
    local:
      path: ./storage/insurance/claims/outgoing
    files:
      - pattern: "*.xml"
    idempotency_mode: hash
    delete_after_upload: true
    schedule_cron: "0 0 8 * * 1-5"

Hardened mode behavior

In hardened mode, FTPS partners enforce:

auth.password must use a secret reference
tls.client_cert, tls.client_private_key, tls.client_key_passphrase must use secret references
tls.insecure_skip_verify=true is rejected — you cannot skip cert verification in hardened mode

Common failures

Symptom	Likely cause
TLS handshake failed	Server uses unsupported cipher or cert chain is wrong
Certificate validation error	Missing CA cert or CA cert chain incomplete
Connection refused	Firewall blocking port 21 or data channel ports
Passive mode error	Server passive port range not reachable through NAT/firewall
Authentication failed	Wrong credentials or account locked

Passive mode and firewalls

FTPS passive mode requires:

the client connects to the server’s control port (usually 21)
the server advertises a data channel port for the actual file transfer
the client connects to that data port

If there is a firewall between Xferity and the FTPS server, the firewall must allow both the control port and the data channel port range. If the server advertises internal IPs via PASV, you may need a proxy-aware firewall or NAT traversal.