Certificate Pinning — PPP Mobile App
⚠️ Status: currently DISABLED on every platform
Native SSL pinning is not active for production, UAT, iOS, or Android as of the date below. Placeholder SPKI hashes previously caused every HTTPS request to be rejected at the OS TLS layer, bricking release builds. The landmine has been defused; the security protection is deferred until real pins are generated.
| Surface | State | Why | Tracking |
|---|---|---|---|
| Android production | Disabled (enforced: false, pins: []) | Placeholder AAAA/BBBB hashes would have rejected every connection on a release build | #4888 (defusal) → #5110 (restore) |
| Android UAT | Disabled | Same placeholder problem on UAT release builds | #4964 / #5071 → #5110 |
| iOS (TrustKit) | No-op pass-through (no Info.plist mutation) | TrustKit swizzling hooked WKWebView and blocked Better Auth session cookies → blank-spinner bug | #5073 / #5074 → #5110 |
| localhost | Always off | Local dev never needs pinning | n/a |
Do not re-enable pinning without following the full runbook in Generating real pins and the gating checklist in #5110. A live outage caused by a silent cert rotation is worse than no pinning at all.
The JS-layer createPinnedFetch wrapper still runs in production builds: unknown hosts are fail-closed, and SSL errors from known hosts (once enforced: true again) will be wrapped with a clearer diagnostic message. While every host has enforced: false, the wrapper delegates straight to native fetch.
Overview
The PPP mobile app implements SPKI (Subject Public Key Info) SHA-256 certificate pinning to protect tRPC API communications against MITM attacks (OWASP Mobile M5: Insecure Communication). This is critical for medical data transmitted over hospital WiFi networks.
Architecture
Certificate pinning operates at two layers:
Native layer (primary enforcement, currently disabled):
- Android:
network_security_config.xmlgenerated by the Expo config plugin. With every domain currently commented out ofDEFAULT_CONFIG, the generated file contains only a<base-config cleartextTrafficPermitted="false">block — system trust anchors, no pinning, no cleartext — which is the safe no-op state. - iOS:
withCertificatePinning.jsis a no-op pass-through for iOS (see #5074). When re-enabled, it will patchInfo.plistwith TrustKitTSKConfigurationentries. - When re-enabled, the OS rejects TLS connections where the server certificate's public key hash does not match any pinned hash.
- Android:
JavaScript layer (defense-in-depth, always active):
lib/utils/certificatePinning.tsprovides a customfetchwrapper (pinnedFetch)- Validates requests go to known/pinned hosts only (fail-closed on unknown hosts in production)
- Reports SSL violations for monitoring
- Used by
trpcClient.tsvia thehttpBatchLink({ fetch: pinnedFetch })option
Configuration Files
| File | Purpose |
|---|---|
lib/utils/certificatePinning.ts | Pin hashes, JS-layer fetch wrapper, violation reporting |
plugins/withCertificatePinning.js | Expo config plugin — generates native pinning configs at prebuild |
app.config.js | References the config plugin |
Pinned Domains
| Domain | Environment | Enforced (current) | Enforced (target, #5110) |
|---|---|---|---|
api.professionalperformanceportfolio.com | Production | No — pins [] | Yes |
api-uat.professionalperformanceportfolio.com | UAT | No — pins [] | Yes |
localhost | Development | No | No |
Pin Format
Pins use SPKI SHA-256 format (base64-encoded). This pins the server's public key, not the full certificate, so pins survive certificate renewals as long as the same key pair is used.
Generating Pin Hashes
From a live server
# Extract the SPKI SHA-256 hash from the server's current certificate
openssl s_client -connect api.professionalperformanceportfolio.com:443 \
-servername api.professionalperformanceportfolio.com < /dev/null 2>/dev/null \
| openssl x509 -pubkey -noout \
| openssl pkey -pubin -outform DER \
| openssl dgst -sha256 -binary \
| base64Generate a backup pin (offline key pair)
# Generate a new EC key pair and compute its SPKI hash
# Store the private key securely — it will be needed if emergency rotation is required
openssl ecparam -genkey -name prime256v1 -out backup-key.pem
openssl pkey -in backup-key.pem -pubout -outform DER \
| openssl dgst -sha256 -binary \
| base64
# IMPORTANT: Store backup-key.pem in a secure vault (e.g. AWS Secrets Manager)
# Never commit it to source controlFor an RSA key
openssl genrsa 2048 -out backup-rsa-key.pem
openssl pkey -in backup-rsa-key.pem -pubout -outform DER \
| openssl dgst -sha256 -binary \
| base64Pin Rotation Process
Planned rotation (certificate renewal with same key)
No action needed — SPKI pins are tied to the public key, not the certificate. As long as the CSR uses the same key pair, the pin remains valid.
Planned rotation (new key pair)
Before the new certificate is deployed:
- Generate the SPKI hash of the new public key
- Add the new hash as an additional pin in both:
lib/utils/certificatePinning.ts(thepinsarray)plugins/withCertificatePinning.js(theDEFAULT_CONFIG)
- Ship an app update with both old and new pins
- Wait for sufficient user adoption of the new app version (check analytics)
Deploy the new certificate on the server
After deployment:
- Verify the app connects successfully with the new certificate
- In a subsequent app release, remove the old pin hash
- Update the backup pin if the previous backup was promoted to primary
Emergency rotation (compromised key)
- Deploy the server with the backup key (whose hash is already pinned)
- Generate a new backup key pair and compute its hash
- Ship an urgent app update replacing the compromised pin with the new backup hash
- Store the new backup key securely in AWS Secrets Manager
Timeline
| Step | Action | Duration |
|---|---|---|
| T-30 days | Add new pin hash to app, ship update | 1-2 days |
| T-14 days | Verify >90% user adoption of new app version | Monitor |
| T-0 | Deploy new certificate on server | Minutes |
| T+7 days | Remove old pin hash, ship update | 1-2 days |
Expiration
Pin configurations include an optional expirationDate field (format: YYYY-MM-DD). After this date:
- Android: The OS ignores the pin-set and allows any valid certificate
- iOS (TrustKit): Pinning is not enforced
- JS layer:
isPinningEnforced()returnsfalse
This is a safety net to prevent app lockout if pins expire before an update can be shipped. Set the expiration date to at least 12 months in the future and update it with each pin rotation.
Development Mode
In development (Expo Go / __DEV__ === true):
- The JS-layer
pinnedFetchpasses through to nativefetchwithout validation - Native pinning configs are not available in Expo Go
- Certificate pinning is only active in standalone/EAS builds
Testing
Unit tests
cd mobile/ppp
yarn test lib/utils/__tests__/certificatePinning.test.tsCI verification
The test suite includes a test that verifies connections are rejected when certificates do not match pinned hashes (simulated via mocked fetch errors).
Manual verification on device
- Build a development client locally:
npx expo run:ios(ornpx expo run:ios --configuration Releasefor a release-mode build that exercises the production pinning config) - Install on a device
- Use a MITM proxy (e.g. Charles Proxy, mitmproxy) to intercept HTTPS traffic
- Verify the app rejects the proxy's certificate and shows a connection error
- Without the proxy, verify normal API calls succeed
Monitoring
Pin violations are currently logged to console.warn in development builds. For production monitoring:
- Implement a reporting endpoint (e.g. CloudWatch, Sentry)
- Update
reportPinningViolation()incertificatePinning.tsto POST violation details - Set up alerts for unexpected pin violations (may indicate an active MITM attack)
- TrustKit (iOS) supports
TSKReportUrisfor automatic violation reporting — configure inwithCertificatePinning.js
Troubleshooting
App cannot connect after certificate change
- Check if the new certificate uses the same public key (
openssl x509 -pubkey -noout -in cert.pem) - If the key changed, a pin update is required (see "Planned rotation" above)
- If pins have expired, the app should fall back to normal TLS validation
Pin hash mismatch
Verify the hash with:
# From a PEM certificate file
openssl x509 -in cert.pem -pubkey -noout \
| openssl pkey -pubin -outform DER \
| openssl dgst -sha256 -binary \
| base64Compare the output with the pins in certificatePinning.ts.
Users stuck on old app version
The expirationDate safety net ensures pinning is disabled after the configured date, preventing permanent lockout. Users on old versions will gracefully fall back to standard TLS validation.