Skip to content

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.

SurfaceStateWhyTracking
Android productionDisabled (enforced: false, pins: [])Placeholder AAAA/BBBB hashes would have rejected every connection on a release build#4888 (defusal) → #5110 (restore)
Android UATDisabledSame 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
localhostAlways offLocal dev never needs pinningn/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:

  1. Native layer (primary enforcement, currently disabled):

    • Android: network_security_config.xml generated by the Expo config plugin. With every domain currently commented out of DEFAULT_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.js is a no-op pass-through for iOS (see #5074). When re-enabled, it will patch Info.plist with TrustKit TSKConfiguration entries.
    • When re-enabled, the OS rejects TLS connections where the server certificate's public key hash does not match any pinned hash.
  2. JavaScript layer (defense-in-depth, always active):

    • lib/utils/certificatePinning.ts provides a custom fetch wrapper (pinnedFetch)
    • Validates requests go to known/pinned hosts only (fail-closed on unknown hosts in production)
    • Reports SSL violations for monitoring
    • Used by trpcClient.ts via the httpBatchLink({ fetch: pinnedFetch }) option

Configuration Files ​

FilePurpose
lib/utils/certificatePinning.tsPin hashes, JS-layer fetch wrapper, violation reporting
plugins/withCertificatePinning.jsExpo config plugin — generates native pinning configs at prebuild
app.config.jsReferences the config plugin

Pinned Domains ​

DomainEnvironmentEnforced (current)Enforced (target, #5110)
api.professionalperformanceportfolio.comProductionNo — pins []Yes
api-uat.professionalperformanceportfolio.comUATNo — pins []Yes
localhostDevelopmentNoNo

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 ​

bash
# 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 \
  | base64

Generate a backup pin (offline key pair) ​

bash
# 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 control

For an RSA key ​

bash
openssl genrsa 2048 -out backup-rsa-key.pem
openssl pkey -in backup-rsa-key.pem -pubout -outform DER \
  | openssl dgst -sha256 -binary \
  | base64

Pin 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) ​

  1. 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 (the pins array)
      • plugins/withCertificatePinning.js (the DEFAULT_CONFIG)
    • Ship an app update with both old and new pins
    • Wait for sufficient user adoption of the new app version (check analytics)
  2. Deploy the new certificate on the server

  3. 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) ​

  1. Deploy the server with the backup key (whose hash is already pinned)
  2. Generate a new backup key pair and compute its hash
  3. Ship an urgent app update replacing the compromised pin with the new backup hash
  4. Store the new backup key securely in AWS Secrets Manager

Timeline ​

StepActionDuration
T-30 daysAdd new pin hash to app, ship update1-2 days
T-14 daysVerify >90% user adoption of new app versionMonitor
T-0Deploy new certificate on serverMinutes
T+7 daysRemove old pin hash, ship update1-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() returns false

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 pinnedFetch passes through to native fetch without validation
  • Native pinning configs are not available in Expo Go
  • Certificate pinning is only active in standalone/EAS builds

Testing ​

Unit tests ​

bash
cd mobile/ppp
yarn test lib/utils/__tests__/certificatePinning.test.ts

CI 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 ​

  1. Build a development client locally: npx expo run:ios (or npx expo run:ios --configuration Release for a release-mode build that exercises the production pinning config)
  2. Install on a device
  3. Use a MITM proxy (e.g. Charles Proxy, mitmproxy) to intercept HTTPS traffic
  4. Verify the app rejects the proxy's certificate and shows a connection error
  5. Without the proxy, verify normal API calls succeed

Monitoring ​

Pin violations are currently logged to console.warn in development builds. For production monitoring:

  1. Implement a reporting endpoint (e.g. CloudWatch, Sentry)
  2. Update reportPinningViolation() in certificatePinning.ts to POST violation details
  3. Set up alerts for unexpected pin violations (may indicate an active MITM attack)
  4. TrustKit (iOS) supports TSKReportUris for automatic violation reporting — configure in withCertificatePinning.js

Troubleshooting ​

App cannot connect after certificate change ​

  1. Check if the new certificate uses the same public key (openssl x509 -pubkey -noout -in cert.pem)
  2. If the key changed, a pin update is required (see "Planned rotation" above)
  3. If pins have expired, the app should fall back to normal TLS validation

Pin hash mismatch ​

Verify the hash with:

bash
# From a PEM certificate file
openssl x509 -in cert.pem -pubkey -noout \
  | openssl pkey -pubin -outform DER \
  | openssl dgst -sha256 -binary \
  | base64

Compare 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.

Internal documentation — org members only