Use Alamofire’s built-in SSL pinning features in Swift to defend your app’s network traffic from man-in-the-middle threats. We’ll guide you through loading certificates, configuring trust, and handling failures, all while sharing our hard-won lessons from the trenches.
This is practical, not theoretical, steps you can follow, mistakes we’ve made, and why you never want a pinning misfire on launch day. Secure your APIs, keep users safe, and sleep better at night.
Key Takeaways
- Pinning certificates in iOS with Alamofire stops many MITM attacks cold, protecting user data.
- Automation, error logging, and testing are as crucial as the pinning setup itself.
- Planning for certificate rotation and failures prevents app-breaking surprises later.
Implementing Certificate Pinning with Swift and Alamofire
It’s true, most of us don’t notice SSL until something breaks. Those of us running secure development bootcamps hear the same stories, the app worked fine, until suddenly it didn’t. MITM attacks aren’t theoretical. They’re real, and certificate pinning is our first line of defense. Here’s how we (and you) can do it right in Swift using Alamofire. [1]
Preparing Your Project for Pinning
We always start with the basics: ensure Alamofire is installed and up to date in your Xcode project. You’ll need your server’s certificate, preferably in .cer format. It’s easy to overlook, but make sure the certificate is valid, not expired, and matches the domain you’ll pin against.
- Alamofire 5.x or newer is required.
- The .cer file should use X.509 DER encoding.
We’ve seen devs try to pin against incorrect or test certs, double-check before moving on.
Obtaining and Adding the Server Certificate to Xcode
You can grab the server certificate using Safari (show certificate, drag to desktop) or with openssl s_client. We usually do this:
openssl s_client -connect your.server.com:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform DER > your_server.cer
Drag the resulting .cer file into your Xcode project. Make sure it’s included in your main app target, not just a test target. We’ve seen this slip by and cause mysterious pinning failures.
Loading the Certificate Programmatically in Swift
This is the point where many folks mess up: the certificate’s got to be loaded as a SecCertificate. Here’s a snippet we use (and teach):
struct Certificates {
static let certificate: SecCertificate = Certificates.certificate(filename: “your_server”)
private static func certificate(filename: String) -> SecCertificate {
let filePath = Bundle.main.path(forResource: filename, ofType: “cer”)!
let data = try! Data(contentsOf: URL(fileURLWithPath: filePath))
let certificate = SecCertificateCreateWithData(nil, data as CFData)!
return certificate
}
}
Use this pattern, but swap in your certificate’s filename. This pulls the cert from the bundle and gets it ready for Alamofire’s trust manager.
Configuring Alamofire for Certificate Pinning
Alamofire’s approach to iOS certificate pinning is both powerful and straightforward if you know where to look. We see a lot of copy-paste code, but it’s better to understand what’s happening.
- Use ServerTrustManager for all your SSL trust policies.
- Map domains to trust evaluators.
- Only trust what you explicitly pin.
Setting Up ServerTrustManager and Evaluators
Here’s the structure we teach in our bootcamp:
import Alamofire
let evaluators: [String: ServerTrustEvaluating] = [
“api.example.com”: PinnedCertificatesTrustEvaluator(
certificates: [Certificates.certificate],
acceptSelfSignedCertificates: false,
performDefaultValidation: true,
validateHost: true
)
]
let serverTrustManager = ServerTrustManager(
allHostsMustBeEvaluated: true,
evaluators: evaluators
)
We prefer setting allHostsMustBeEvaluated to true. Otherwise, unlisted hosts bypass pinning, and that’s a risk. Use the real domain. No wildcards.
Using PinnedCertificatesTrustEvaluator
PinnedCertificatesTrustEvaluator matches the presented server cert with the one loaded into your app. It checks:
- The exact certificate bytes (strict match).
- Hostname matches (if validateHost is true).
- Default validation (chain-of-trust and expiration).
For public key pinning, swap to PublicKeysTrustEvaluator, but that’s less common in our experience. [2]
Configuring Trust Policies
A few key parameters in the evaluator trip people up:
- acceptSelfSignedCertificates: Use true only in dev. Never in production.
- performDefaultValidation: Set true unless you have a very good reason.
- validateHost: Always true unless you control all endpoints and know why you’re skipping hostname checks.
These parameters are your last line of defense. We’ve had students accidentally accept self-signed certs in production. Not good.
Creating a Custom Alamofire Session with ServerTrustManager
Tie it all together by creating an Alamofire Session with your custom trust manager:
let session = Session(serverTrustManager: serverTrustManager)
Keep this session alive as long as you need network requests. Reusing it is safer and more efficient.
Using the Pinned Session to Make Secure Requests
Here’s how you make requests with the pinned session:
session.request(“https://api.example.com/data”)
.validate()
.response { response in
// Handle response or errors
}
Don’t use Alamofire’s default session for sensitive traffic. Stick to your pinned session.
Implementing Network Requests with the Custom Session
For all sensitive API calls, route them through this session. We recommend isolating network logic in a single class or service. This keeps pinning consistent and prevents mistakes from newcomers or future maintainers.
Managing Session Lifecycle for Consistent Pinning Enforcement
What we’ve learned: create the session once, hold onto it. Creating new sessions repeatedly can cause unexpected behavior and break pinning. We usually attach the session to a singleton or a dependency-injected networking manager.
Handling Pinning Failures and Errors
Pinning failures usually pop up as SSL errors or Alamofire request failures. Users often see generic errors, which confuses them and us. Instead, we log these events and show a friendly alert about network security. Never expose technical details.
Detecting Pinning Validation Failures
Watch for URLError.serverCertificateUntrusted or similar. In Alamofire’s response, check the AFError type and log pinning-related failures. We’ve written custom error handlers for this.
User Alerts and Logging Strategies for Failure Cases
On pinning failure, we:
- Show a generic “secure connection failed” alert.
- Log the error locally for debugging.
- (Optionally) Send anonymized failure logs to our backend for audit.
Do not ask users to “try again” if the cert is wrong, they can’t fix it.
Advanced Considerations and Best Practices
There’s more to pinning than setting it up once. We’ve seen apps break at scale due to expired or rotated certs. We’ve also seen pinning collide with inter-process communication flows when background services or extensions try to talk without proper trust setup.
Managing Multiple Certificates for Key Rotation
To support cert rotation, pin all valid certs:
let evaluators: [String: ServerTrustEvaluating] = [
“api.example.com”: PinnedCertificatesTrustEvaluator(
certificates: [cert1, cert2], // Old and new certs
acceptSelfSignedCertificates: false,
performDefaultValidation: true,
validateHost: true
)
]
This prevents downtime during CA updates.
Strategies to Pin Multiple Certificates in Alamofire
Keep an array of certificates. When updating, add the new cert before the old one expires. After the switch, remove the old cert from the bundle in your next app update.
Planning Certificate Updates to Avoid App Disruptions
Set calendar reminders for certificate expiration. Monitor pinning failures in your logs. Push app updates early if you need to change pins.
Testing and Validating Your Pinning Implementation
You can’t trust code until you’ve tested it under attack.
Using Tools Like Charles Proxy for MITM Simulation
We simulate MITM attacks in our training using Charles Proxy with “SSL Proxying” enabled. If pinning is working, requests should fail when Charles tries to intercept.
Automated Testing Approaches to Ensure Pinning Integrity
Write integration tests that hit a test server with valid and invalid certs. Your tests should:
- Succeed with the correct cert.
- Fail with a mismatched cert.
We’ve caught mistakes this way that manual tests missed.
Security Best Practices for Certificate Pinning
Following the crowd isn’t always enough. We’ve built a list of rules from real-world pain.
Avoiding Custom Pinning Logic and Leveraging Trusted Libraries
Stick to Alamofire’s built-in pinning. Rolling your own pinning logic is a minefield. We’ve seen it go wrong. Some rollouts have even opened doors to iOS injection vulnerabilities when security logic isn’t handled carefully.
Monitoring and Logging Pinning Failures for Security Audits
Track failed pinning attempts. It’s a sign of either misconfiguration or attack. We log failures locally and, where appropriate, send them to our SIEM.
Handling Self-Signed Certificates and Their Risks
Self-signed certs are only for development. If you must use them, set acceptSelfSignedCertificates: true, but never ship this to production. The risk is too high.
When and How to Accept Self-Signed Certificates
Only for dev or test servers. Always swap to CA-signed certs before release.
Security Implications and Recommendations
Shipping with self-signed certs is like leaving your front door unlocked. We warn all our trainees against it.
Enhancing Your App’s Security and Networking Architecture
Credits: IBM Technology
Pinning isn’t a silver bullet, but it’s a strong first line.
Integrating Certificate Pinning with Other Security Measures
We combine pinning with:
- HTTPS enforced everywhere.
- OAuth tokens for sensitive endpoints.
- ATS (App Transport Security) settings in Info.plist.
We also follow general secure mobile coding patterns to build defensively from the start.
Using Network Security Configurations Alongside Pinning
ATS and pinning together block most MITM vectors. We never rely on one layer alone.
Performance Impact and Optimization Tips
Pinning can add overhead, but it’s manageable.
Minimizing Latency and Resource Use When Pinning Certificates
- Load certs once, not per request.
- Use in-memory caching for loaded certs.
- Keep trust evaluators lightweight.
Efficient Certificate Loading and Caching Techniques
We load certs at app startup. If you load per request, you’ll see a performance hit.
Supporting Multiple Environments and Hosts
Our bootcamp apps need to connect to dev, staging, and prod. Pinning must not get in the way.
Configuring Pinning for Development, Staging, and Production
Configure evaluators for each environment. Keep certs organized and environment-specific.
Handling Different Hostnames and Subdomains Securely
Map each API domain or subdomain to its own evaluator. Don’t wildcard unless you control all subdomains.
Future-Proofing Your Pinning Strategy
SSL and pinning standards change. We teach students to keep an eye on the future.
Adapting to Changes in Certificate Authorities and Protocols
Stay informed about CA changes, deprecations, and protocol updates. Rotate pins before you’re forced to.
Monitoring Industry Trends and Updating Pinning Approaches
Follow Apple’s security updates. Update your pinning strategies as new threats emerge.
FAQ
How do I configure domain-specific iOS certificate pinning using NSPinnedDomains and Info.plist?
To configure domain-specific iOS certificate pinning, you can define NSPinnedDomains in your Info.plist. This allows you to apply certificate pinning at the system level using Apple Transport Security.
Include the SPKI-SHA256-BASE64 hash for each certificate’s public key. This Info.plist pinning works alongside Alamofire ServerTrustManager and helps reinforce HTTPS security through stricter network security iOS policies, even for subdomain pinning cases.
What’s the difference between PublicKeysTrustEvaluator and PinnedCertificatesTrustEvaluator in Alamofire?
Alamofire supports two major types of evaluators for SSL pinning: PublicKeysTrustEvaluator and PinnedCertificatesTrustEvaluator. The first focuses on public key pinning, checking the server’s key against the app’s stored key using SPKI-SHA256-BASE64.
The second validates the full X.509 certificate. Both methods support SSL handshake inspection and man-in-the-middle protection, but public key pinning offers more flexibility during certificate renewal or rotation without app updates.
How can I handle certificate expiration or renewal without breaking SSL pinning in my Swift app?
Certificate expiration and renewal are serious issues in Swift certificate pinning. You must plan for key rotation support and configure fallback mechanisms using Alamofire custom session.
When using Alamofire ServerTrustManager, maintain multiple certificates in your bundle or trust both old and new public keys. This avoids pinning failure handling problems. Secure certificate storage should also be updated with renewed certificates to ensure uninterrupted secure API communication.
How do I implement secure self-signed certificate pinning with Alamofire on iOS?
For self-signed certificate pinning, store the .cer file of your certificate in DER-encoded format inside your app bundle. Use PinnedCertificatesTrustEvaluator within Alamofire’s trust manager.
Set validateHost and performDefaultValidation to true for added protection. This approach strengthens network security iOS apps need and helps avoid relying on certificate chain validation. Make sure to update certificates before expiration to prevent app-side SSL security iOS failures.
Why does Info.plist pinning sometimes fail even with correct settings?
Info.plist pinning can fail due to certificate chain issues, ASN.1 structure problems in the cert, or incorrect base64 certificate hash. Apple’s system validates the entire certificate trust policy including CA public key pinning and leaf certificate pinning.
You also need to ensure your NSAppTransportSecurity allows secure connection enforcement and doesn’t include unnecessary ATS exceptions. Double-check your domain-specific pinning, especially when dealing with subdomains or wildcard certs.
Conclusion
We’ve seen what happens when certificate pinning is skipped or botched, broken trust, exposed users, and preventable breaches. If you’re building iOS apps with Swift and Alamofire, pinning isn’t optional. Log failures. Plan rotation. Test like it’s production. Because it is. Mobile security needs attention, not assumptions.
Want real-world secure coding skills? Join our Secure Coding Practices Bootcamp for hands-on training that helps you ship safer code, no fluff, just what works.
References
- https://oleksandr-stepanov.medium.com/ssl-pinning-with-alamofire-5-538ad7b8ee0f
- https://alamofire.github.io/Alamofire/Classes/PinnedCertificatesTrustEvaluator.html
Related Articles
