Certificate Pinning

Internal Documentation — This page contains security-sensitive implementation details. Do not share externally.

Overview

Thrust uses SSL certificate pinning to protect against man-in-the-middle attacks on critical API connections, especially banking APIs (GoCardless). The system supports dynamic hash updates via remote configuration to handle certificate rotation without app releases.

Architecture

iOS App

CertificatePinningManager — Validates SSL certificates
RemoteCertificateConfig — Fetches remote hashes

Server

/api/certificates.json — Current hashes endpoint
update-certificates.sh — Daily update script

How It Works

App Startup

On launch, the app calls refreshRemoteHashes() which fetches the latest hashes from thrust.finance/api/certificates.json.

Connection Validation

When connecting to a pinned domain, the certificate chain is validated against:

Remote hashes (if available and fresh)
Hardcoded fallback hashes (if remote unavailable)

Server Updates

A cron job runs daily at 6:00 AM to fetch fresh certificate hashes from all domains.

Pinned Domains

Domain	Service	Priority
`bankaccountdata.gocardless.com`	GoCardless Banking API	🔴 Critical
`accounts.google.com`	Google OAuth	Standard
`oauth2.googleapis.com`	Google OAuth API	Standard
`gmail.googleapis.com`	Gmail API	Standard
`login.microsoftonline.com`	Microsoft OAuth	Standard
`graph.microsoft.com`	Microsoft Graph API	Standard
`api.coingecko.com`	Crypto Prices	Standard
`api.twelvedata.com`	Stock Prices	Standard

API Endpoint

curl https://thrust.finance/api/certificates.json

Fallback Behavior

Scenario	Behavior
Remote config available	Uses remote hashes (updated daily)
Remote config unavailable	Uses hardcoded hashes in app
Pinning fails + graceful mode ON	Logs error, allows connection
Pinning fails + graceful mode OFF	Blocks connection (default)

iOS Implementation

Key Files

Thrust/Security/
├── CertificatePinningManager.swift  # Main pinning logic
└── RemoteCertificateConfig.swift    # Remote config fetcher

Startup Integration

Thrust.swift

// In runNonCriticalStartupTasks()
await CertificatePinningManager.shared.refreshRemoteHashes()

Enable Graceful Fallback

Only enable graceful fallback if you have monitoring in place!

CertificatePinningManager.shared.gracefulFallbackEnabled = true

Server Configuration

File Locations

File	Path
API Endpoint	`/volume1/Web/thrust/api/certificates.json`
Update Script	`/volume1/Web/thrust/scripts/update-certificates.sh`
Cron Log	`/volume1/Web/thrust/scripts/cron.log`
Backups	`/volume1/Web/thrust/scripts/backups/`

Cron Schedule

0 6 * * * Kondrick /volume1/Web/thrust/scripts/update-certificates.sh

Manual Update

ssh Kondrick@192.168.1.75
/volume1/Web/thrust/scripts/update-certificates.sh

Emergency Response

Users report banking connection failures

SSH to server: ssh Kondrick@192.168.1.75
Run update script: /volume1/Web/thrust/scripts/update-certificates.sh
Verify endpoint: curl https://thrust.finance/api/certificates.json
Users will get new hashes on next app launch

CI/CD Verification

Before each release, run:

./Scripts/verify-certificates.sh

This checks that all hardcoded hashes match current certificates.

Monitoring

When pinning fails with graceful fallback enabled, errors are logged to CrashReportingManager with:

Host that failed
Actual certificate chain hashes
Expected hashes

Monitor these logs to detect certificate rotations early.