# 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