Security & Certificate Management
Who should read these docs?
Firmware engineers implementing certificate storage and rotation on the device, security reviewers, and anyone responding to a suspected device compromise.
This page covers how to store private keys correctly, how to manage the operational certificate over its lifetime, what the platform monitors, and what to do if something goes wrong.
Private Key Storage
Private keys are the most sensitive material on the device. A compromised private key allows an attacker to impersonate the device indefinitely.
Private keys must never leave the device after generation. Only the CSR (which contains the public key) should be transmitted. Never log, transmit, or store private key material in plain text.
Use the most secure storage available on your hardware:
| Storage Type | Security Level | Notes |
|---|---|---|
| Hardware Security Module (HSM) | Highest | Dedicated tamper-resistant hardware; keys never exposed to the CPU |
| Secure Element (SE) | High | Dedicated secure chip (e.g., ATECC608, SE050) |
| Trusted Execution Environment (TEE) | High | Isolated execution environment (e.g., ARM TrustZone) |
| Encrypted File System | Medium | Keys encrypted at rest using a device-specific key |
Each certificate and key has specific storage and access requirements:
| Item | Storage | Access Control |
|---|---|---|
| Bootstrap private key | Secure element or encrypted storage | Read-only after initial write |
| Bootstrap certificate | Non-volatile storage | Read-only |
| Operational private key | Secure element or encrypted storage | Read-only after initial write |
| Operational certificate | Non-volatile storage | Replaceable during rotation |
Memory hygiene: Zero out private key material in RAM immediately after use. Use memory allocation that prevents swapping to disk. Never pass raw key bytes to logging functions.
Physical interfaces: The private key must not be transmitted over UART, SPI, I2C, USB, or any other physical interface, even during manufacturing. In the Phase 1 flow, only the CSR travels from the device to the programming utility, never the private key. If your end-of-line test setup logs all UART traffic, ensure the private key is never serialized to that interface.
Certificate Retention
Devices must retain both certificates permanently. The bootstrap certificate is the only way to rotate the operational certificate without physical access to the device. If it is deleted and the operational certificate expires or is revoked, the device cannot recover remotely.
| Scenario | Certificate Needed |
|---|---|
| Normal operation | Operational |
| Operational cert expiring or revoked | Bootstrap |
For the full rotation procedure, see Certificate Rotation.
Security Monitoring and Quarantine
AWS IoT Defender monitors all provisioned devices for anomalous behavior. The following thresholds apply per device per 5-minute window:
| Metric | Threshold |
|---|---|
| Authentication failures | 5 |
| Connection attempts | 10 |
| Messages published | 5,000 |
| Disconnections | 10 |
If a device exceeds these thresholds or is manually flagged, it is quarantined: moved to the quarantine Thing group, its certificate deactivated, and a restrictive policy applied that allows MQTT connection but denies all publish, subscribe, and shadow operations.
A quarantined device will complete the TLS handshake and receive a CONNACK but all subsequent operations will fail with reason code 135 (Not Authorized). If your device experiences sudden blanket authorization failures after working correctly, contact the Digital IoT team to check whether it has been quarantined.
Pre-Deployment Checklist
Before shipping a device, verify the following:
| Check | Severity |
|---|---|
| ☐ Private keys generated on-device only | Critical |
| ☐ Private keys stored in secure storage (HSM/SE/encrypted) | Critical |
| ☐ No private key material in logs or error messages | Critical |
| ☐ No private key material transmitted over physical interfaces (UART, SPI, USB, etc.) | Critical |
| ☐ All network calls use TLS | Critical |
| ☐ Certificate validation enabled for all TLS connections | High |
| ☐ Memory containing keys is zeroed after use | High |
| ☐ Bootstrap certificate retained in permanent secure storage | High |
| ☐ Certificate expiration check implemented (see Certificate Rotation) | Medium |
| ☐ Rotation procedure tested (see Certificate Rotation) | Medium |
Debugging
Useful commands for inspecting certificates on a development machine:
# Inspect a certificate
openssl x509 -in cert.pem -text -noout
# Inspect a CSR
openssl req -in csr.pem -text -noout
# Check certificate expiry
openssl x509 -in cert.pem -noout -enddate
Check AWS IoT Core CloudWatch logs for detailed error information when MQTT operations fail unexpectedly.
References
Get Help
- Teams: #digital-cpp-support
- Service Now: Open a ticket