X.509 Certification
X.509 certificates provide a robust authentication mechanism for CommonsDB declarations, ensuring that your digital signatures can be verified and trusted by the system.
Overview
When using X.509 certificates for authentication of your declarations, you establish a cryptographic link between your domain and your digital identity. This process enables other parties to verify that declarations truly originate from your organization.
Why X.509 Certificates?
X.509 certificates offer several advantages for API authentication:
- Identity Verification: Certificates are issued by trusted Certificate Authorities (CAs)
- Public Key Infrastructure: Leverages established PKI for key management
- Domain Validation: Links cryptographic identity to domain ownership
- Standardization: Based on widely adopted standards
Prerequisites
Before setting up X.509 certification, ensure you have:
Required Items
- ✓ A valid X.509 certificate (.p12 format)
- ✓ Access to your domain's web server
- ✓ Certificate private key
- ✓ OpenSSL installed on your system
Technical Requirements
- ✓ HTTPS-enabled domain
- ✓ Ability to serve files from /.well-known/
- ✓ Node.js (for key conversion scripts)
- ✓ Understanding of JSON Web Keys (JWK)
The Authentication Process
CommonsDB uses a decentralized approach to X.509 certificate verification:
-
Certificate Preparation
Convert your .p12 certificate to the required formats and extract the public key components.
-
DID Document Creation
Create a DID (Decentralized Identifier) document that associates your domain with your cryptographic keys.
-
Well-Known Deployment
Deploy the DID document to your domain's
.well-known/did.jsonendpoint for public verification. -
Signature Generation
Use your private key to sign metadata, creating verifiable declarations.
DID Web Method: CommonsDB uses the did:web method, which allows verification of decentralized identifiers through web domains. This approach combines the benefits of decentralized identity with the familiarity of domain-based verification.
Certificate Requirements
Your X.509 certificate must meet the following criteria:
Domain Validation
- Certificate must be issued for the domain you intend to use
- Domain must be accessible via HTTPS
- You must have control over the domain's web server
Security Notice: Never share your private key or .p12 file. These should be stored securely and access should be limited to authorized systems only.
Next Steps
Ready to set up X.509 authentication? Follow these guides in order:
- Setup .well-known/did.json - Configure your domain for DID verification
- Certificate Signature Creation - Learn how to sign metadata with your certificate
- TSA Signature Creation - Add timestamp signatures for temporal verification
Troubleshooting
Common issues and solutions:
- Certificate not recognized: Ensure your certificate is issued by a trusted CA
- Domain verification fails: Check that your .well-known/did.json is accessible via HTTPS
- Signature validation errors: Verify that your public key in the DID document matches your certificate
Need help with X.509 setup? Each step is detailed in the subsequent guides with practical examples and code snippets.