Kordant/tasks/android-production/05-cert-pinning.md

05. Certificate Pinning & Network Security Config

meta: id: android-production-05 feature: android-production priority: P1 depends_on: [] tags: [security, networking, production]

objective:

• Implement certificate pinning and network security configuration to prevent man-in-the-middle attacks

deliverables:

• network_security_config.xml with certificate pinning
• OkHttp certificate pinner configuration
• TLS 1.3 enforcement
• Certificate rotation support

steps:

1. Create network security config:
   • Add res/xml/network_security_config.xml
   • Configure domain config with certificate pinning
   • Include production certificate hashes
   • Add debug overrides for development
2. Implement OkHttp certificate pinner:
   • Modify NetworkModule.kt or OkHttp client builder
   • Add CertificatePinner with pinned certificates
   • Support multiple pins for rotation
   • Log pinning failures for monitoring
3. Configure TLS settings:
   • Enforce TLS 1.3 in OkHttp connection specs
   • Disable weak cipher suites
   • Enable certificate transparency
4. Add to manifest:
   • Add android:networkSecurityConfig to AndroidManifest.xml
   • Reference network_security_config.xml
5. Implement certificate rotation:
   • Support old and new certificate hashes
   • Grace period during rotation (30 days)
   • Alert when certificate nearing expiry
6. Add tests:
   • Test with correct certificate → connection succeeds
   • Test with wrong certificate → connection fails
   • Test certificate rotation → seamless transition

tests:

• Unit: Test certificate pinning with mock certificates
• Integration: Test against staging with pinned cert
• Security: Attempt MITM with proxy → blocked

acceptance_criteria:

• network_security_config.xml present in resources
• Certificate pinning active on all API requests
• TLS 1.3 enforced
• MITM attacks blocked (tested with proxy tools)
• Certificate rotation supported with grace period
• Pinning failures logged
• Debug config separate from production
• Unit tests covering pinning success and failure
• No hardcoded certificates in source (use hashes)

validation:

• Run app with correct cert → API calls succeed
• Run app with Charles Proxy MITM → API calls fail
• Check logs → pinning verification logged
• Inspect manifest → networkSecurityConfig referenced

notes:

• Use public key pinning (SHA-256 hash) rather than full certificate
• Include backup pin for certificate rotation
• OkHttp's CertificatePinner is easy to configure
• Test on physical device — emulator may behave differently