Introduction
The Validation Authority (VA) API provides certificate validation services for the Lamassu IoT Platform. It implements industry-standard protocols including OCSP (Online Certificate Status Protocol) and CRL (Certificate Revocation List) distribution, enabling real-time certificate status verification.Base URL
Authentication
- OCSP and CRL endpoints are publicly accessible (no authentication required)
- VA role management endpoints require Bearer token authentication with JWT tokens
API Groups
The VA API is organized into three main groups:OCSP Operations
Online Certificate Status Protocol for real-time certificate validation:- HTTP GET method for OCSP requests
- HTTP POST method for OCSP requests
- Returns certificate status (good, revoked, unknown)
CRL Distribution
Certificate Revocation List distribution:- Retrieve CRLs by Certificate Authority Subject Key Identifier (SKI)
- Returns DER-encoded CRL data
VA Role Management
Manage Validation Authority configurations per Certificate Authority:- Get VA role configuration
- Update CRL generation settings
- Configure automatic CRL refresh
Key Features
OCSP Support
Real-time certificate status checking via OCSP protocol (RFC 6960)
CRL Distribution
Distribute Certificate Revocation Lists for offline validation
Automatic CRL Generation
Configurable automatic CRL regeneration based on time intervals or revocation events
Per-CA Configuration
Independent VA configuration for each Certificate Authority
Certificate Validation Methods
OCSP (Online Certificate Status Protocol)
Use when:- Real-time validation is required
- Network connectivity is available
- Minimal latency is needed
- Certificate status must be current
- Real-time status checks
- Small response size
- Requires network connectivity
- Lower bandwidth than CRL for single checks
CRL (Certificate Revocation List)
Use when:- Offline validation is needed
- Validating many certificates
- Network connectivity is intermittent
- Caching is beneficial
- Can be cached and used offline
- Contains all revoked certificates
- Larger download size
- Periodic updates (based on refresh interval)
Common Use Cases
Real-Time Device Authentication
Use OCSP to verify device certificates during connection establishment:- Device presents certificate
- Server extracts certificate serial number and issuer
- Server queries OCSP endpoint
- Server accepts or rejects connection based on response
Offline Certificate Validation
Download and cache CRLs for offline validation:- Periodically download CRLs for all trusted CAs
- Cache CRLs locally
- Validate certificates against cached CRLs
- Refresh CRLs based on nextUpdate field
Certificate Revocation Workflow
- Certificate is revoked via CA API
- VA automatically regenerates CRL (if configured)
- OCSP responder immediately returns “revoked” status
- CRL is updated for offline validators
OCSP vs CRL Decision Guide
| Requirement | Recommended Method |
|---|---|
| Real-time status | OCSP |
| Offline validation | CRL |
| Low bandwidth per check | OCSP |
| Validating many certificates | CRL |
| Privacy concerns | CRL (no per-cert query) |
| Minimal infrastructure | CRL |
| Always-connected devices | OCSP |
| Intermittent connectivity | CRL |
Next Steps
Validation Endpoints
Learn about OCSP and CRL endpoints
VA Role Management
Configure VA roles for Certificate Authorities