Security Domain certificate management
The Security Domain manages X.509 certificates primarily for SCP11 protocol operations. These certificates are used for authentication and establishing secure channels. For detailed information about certificate usage in secure channels, see the Secure Channel Protocol (SCP) documentation.
Certificate operations
Storing certificates
Certificates are stored in chains associated with specific key references. A typical certificate chain includes:
- Root CA certificate
- Intermediate certificates (optional)
- Leaf (end-entity) certificate
// Store certificate chain
var certificates = new List<X509Certificate2>
{
rootCert,
intermediateCert,
leafCert
};
session.StoreCertificates(keyReference, certificates);
CA configuration
For SCP11a and SCP11c, you need to configure the Certificate Authority (CA) information:
// Store CA issuer information using Subject Key Identifier (SKI)
byte[] subjectKeyIdentifier = GetSkiFromCertificate(caCert);
session.StoreCaIssuer(keyReference, subjectKeyIdentifier);
Retrieving certificates
// Get all certificates for a key reference
var certificates = session.GetCertificates(keyReference);
// Get leaf certificate (last in chain)
var leafCert = certificates.Last();
// Get supported CA identifiers
var caIds = session.GetSupportedCaIdentifiers(
kloc: true, // Key Loading OCE Certificate
klcc: true // Key Loading Card Certificate
);
Access control
Certificate allowlists
Use of the allowlist will create strong binding to one or multiple OCE(s)
Control which certificates can be used for authentication by maintaining an allowlist of serial numbers:
// Store allowlist of certificate serial numbers
var allowedSerials = new List<string>
{
"7F4971B0AD51F84C9DA9928B2D5FEF5E16B2920A",
"6B90028800909F9FFCD641346933242748FBE9AD"
};
session.StoreAllowlist(keyReference, allowedSerials);
// Clear allowlist (allows any valid certificate)
session.ClearAllowList(keyReference);
Certificate management by SCP11 variant
Different SCP11 variants have different certificate requirements:
SCP11a
- Full certificate chain required
- OCE (Off-Card Entity) certificates needed
- Supports authorization rules in certificates
- Used for mutual authentication
Example setup:
// Setup with full chain for SCP11a
using var session = new SecurityDomainSession(yubiKeyDevice, scp03Params);
var keyRef = KeyReference.Create(ScpKeyIds.Scp11A, kvn);
// Store certificates
session.StoreCertificates(keyRef, certificates);
// Configure OCE
var oceRef = KeyReference.Create(OceKid, kvn);
session.StoreCaIssuer(oceRef, skiBytes);
SCP11b
- No mutual authentication
- Suitable when host authentication isn't required
Example setup:
// Basic SCP11b setup
using var session = new SecurityDomainSession(yubiKeyDevice, scp03Params);
var keyRef = KeyReference.Create(ScpKeyIds.Scp11B, kvn);
// Only store device certificate
session.StoreCertificates(keyRef, new[] { deviceCert });
SCP11c
- Mutual authentication
- Similar to SCP11a but with additional features such as offline scripting usage
(See GlobalPlatform SCP11 Specification Annex B)
Security considerations
Certificate Validation
- Verify certificate chains completely
Access Control
- Consider using allowlists in production environments
- Regularly review and update allowlists
Important
Most certificate operations require an authenticated session. Operations are typically only available when using SCP11a or SCP11c variants.
Common tasks
Initial certificate setup
- Generate or obtain required certificates
- Store certificate chain on YubiKey
- Configure CA information if needed
- Optionally, set up an allowlist
// Example of complete setup
using var session = new SecurityDomainSession(yubiKeyDevice, Scp03KeyParameters.DefaultKey);
var keyRef = KeyReference.Create(ScpKeyIds.Scp11A, kvn);
// Store full chain
session.StoreCertificates(keyRef, certificateChain);
// Configure CA
var oceRef = KeyReference.Create(OceKid, kvn);
session.StoreCaIssuer(oceRef, GetSkiFromCertificate(caCert));
// Set up allowlist
session.StoreAllowlist(keyRef, allowedSerials);
Certificate rotation
using var session = new SecurityDomainSession(yubiKeyDevice, scpParams);
// Store new certificates
session.StoreCertificates(keyRef, newCertificateChain);
// Update allowlist if needed
session.StoreAllowlist(keyRef, newAllowedSerials);
Troubleshooting
Certificate Loading Issues
- Verify certificate format (X.509 v3)
- Check certificate chain order
- Validate key references
Authentication Problems
- Verify certificates
- Check allowlist configuration
Note
For additional details on secure channel establishment and certificate usage, refer to the Secure Channel Protocol (SCP) documentation.