StormByte-Crypto 3.1.0
C++26 cryptography module of the StormByte suite
Loading...
Searching...
No Matches
StormByte::Crypto::X509 Namespace Reference

X.509 certificate parsing and chain verification. More...

Classes

class  SubjectAltName
 One supported subjectAltName entry (a DNS name or an IP address). More...
class  Certificate
 Immutable, strictly DER-parsed X.509 certificate. More...
struct  RevocationEvidence
 Borrowed DER evidence for one certificate in a chain. More...
class  RevocationVerifier
 Verifies supplied CRL/OCSP evidence offline using Crypto primitives. More...
class  TLSPeerFailure
 DLL-safe typed failure, with a leaf-to-anchor certificate index. More...
class  TLSPeerVerifier
 Stateless composition for a deliberately constrained TLS 1.3 signing role. More...

Typedefs

using TimePoint = std::chrono::sys_seconds
 Point in time with second precision, as stored in certificates.
using ExpectedPurpose = StormByte::Expected<void, PurposeError>
 Success when certificate usage permits a purpose, or a typed error.
using ExpectedSubjectAltNames = StormByte::Expected<Safe::Vector<SubjectAltName>, IdentityError>
 Supported subjectAltName entries, or a typed extraction error.
using ExpectedIdentity = StormByte::Expected<void, IdentityError>
 Success when the expected identity is present, or a typed error.
using ExpectedRevocation = StormByte::Expected<RevocationStatus, RevocationError>
 Authenticated certificate status or a typed evidence-validation failure.
using ExpectedTLSPeer = StormByte::Expected<void, TLSPeerFailure>
 Offline peer-certificate success or a detailed, indexed failure.
using ExpectedBundledTLSRoots = StormByte::Expected<Safe::Vector<Certificate>, TrustPathError>
 Library-owned certificates or an integrity/parse failure.
using ExpectedTrustPath = StormByte::Expected<void, TrustPathError>
 Path-only success or an explicit failure, with no revocation assertion.
using ExpectedPaymentPeer = StormByte::Expected<void, PaymentPeerError>
 Payment peer trust and revocation result.

Enumerations

enum class  KeyUsage : std::uint16_t {
  DigitalSignature = 1u << 0 , NonRepudiation = 1u << 1 , KeyEncipherment = 1u << 2 , DataEncipherment = 1u << 3 ,
  KeyAgreement = 1u << 4 , KeyCertSign = 1u << 5 , CRLSign = 1u << 6 , EncipherOnly = 1u << 7 ,
  DecipherOnly = 1u << 8
}
 Bits of the keyUsage extension (RFC 5280 §4.2.1.3). More...
enum class  SubjectAltNameType { DNS , IP }
 Supported subjectAltName general name kinds (RFC 5280 §4.2.1.6). More...
enum class  IdentityError {
  InvalidExpectedName , InvalidExpectedAddress , MissingSubjectAltName , MalformedSubjectAltName ,
  NoMatch
}
 Errors of subjectAltName extraction and expected-identity verification. More...
enum class  TLSRole { Server , Client }
 Certificate signing role in TLS 1.3 (RFC 8446 §4.4.2.2). More...
enum class  DetachedSignatureAlgorithm { ECDSA_SHA384 }
 Supported algorithms and encodings for detached signatures. More...
enum class  PurposeError {
  UnsupportedRole , InvalidCertificate , MalformedExtendedKeyUsage , ExtendedKeyUsageNotAllowed ,
  MalformedKeyUsage , KeyUsageNotAllowed
}
 Errors of narrowly scoped certificate-purpose checks. More...
enum class  RevocationFormat { CRL , OCSP }
 Encoding of offline revocation evidence supplied by the caller. More...
enum class  RevocationStatus { Good , Revoked , Unknown }
 Authenticated status reported by a verified evidence object. More...
enum class  RevocationError {
  InvalidRequest , MalformedEvidence , UnsupportedFeature , IssuerMismatch ,
  CertificateMismatch , InvalidSignature , ResponderUnauthorized , NotYetValid ,
  Stale , MissingNextUpdate
}
 Failures that prevent trusting revocation evidence. More...
enum class  TLSPeerError {
  UnsupportedRole , MissingServerIdentity , UnsupportedIdentity , InvalidCertificate ,
  InvalidTime , LeafIsCA , NotCA , IssuerKeyUsageNotAllowed ,
  PathLengthExceeded , SignatureOrIssuerMismatch , UnsupportedAlgorithm , UnsupportedCriticalExtension ,
  UnsupportedConstraint , MalformedExtension , Purpose , Identity
}
 Failures of the constrained, offline TLS signing-certificate verifier. More...
enum class  TrustPathError {
  BundleInvalid , InvalidRequest , RootNotAdmitted , PeerPathRejected ,
  NativePolicyRejected
}
 Failures of path validation, never a full authentication verdict. More...
enum class  PaymentPeerError {
  TrustPathRejected , RevocationUnavailable , RevocationEvidenceRejected , CertificateRevoked ,
  RevocationUnknown
}
 Fail-closed payment peer failures. More...

Functions

Safe::Optional< Certificate > Load (std::span< const std::byte > data) noexcept
 Loads one certificate from DER or PEM.
Safe::Vector< Certificate > LoadAll (std::span< const std::byte > data) noexcept
 Loads every CERTIFICATE block of a PEM bundle, in order.
const char * BundledTLSRootsRevision () noexcept
 Returns the immutable snapshot revision.
const char * BundledTLSRootsSHA256 () noexcept
 Returns the embedded PEM integrity fingerprint.
ExpectedBundledTLSRoots LoadBundledTLSRoots ()
 Loads a verified copy of the versioned, curated Mozilla server roots.
ExpectedTrustPath ValidateBundledTLSPath (const Certificate &leaf, std::span< const Certificate > intermediates, TimePoint at, const SubjectAltName &identity)
 Validates only a server trust path and SAN identity against bundled admission.
ExpectedTrustPath ValidateCustomCATLSPath (const Certificate &leaf, std::span< const Certificate > intermediates, const Certificate &anchor, TimePoint at, const SubjectAltName &identity)
 Validates a separate, explicitly opted-in custom-CA server path.
ExpectedPaymentPeer VerifyPaymentPeer (const Certificate &leaf, std::span< const Certificate > intermediates, const Certificate &anchor, TimePoint at, const SubjectAltName &identity, std::span< const RevocationEvidence > evidence)
 Validates the bundled path and all non-anchor certificates' revocation status.

Detailed Description

X.509 certificate parsing and chain verification.

X.509 certificate parsing and verification.

Typedef Documentation

◆ ExpectedBundledTLSRoots

Library-owned certificates or an integrity/parse failure.

◆ ExpectedIdentity

Success when the expected identity is present, or a typed error.

◆ ExpectedPaymentPeer

Payment peer trust and revocation result.

◆ ExpectedPurpose

Success when certificate usage permits a purpose, or a typed error.

◆ ExpectedRevocation

Authenticated certificate status or a typed evidence-validation failure.

◆ ExpectedSubjectAltNames

Supported subjectAltName entries, or a typed extraction error.

◆ ExpectedTLSPeer

Offline peer-certificate success or a detailed, indexed failure.

◆ ExpectedTrustPath

Path-only success or an explicit failure, with no revocation assertion.

◆ TimePoint

using StormByte::Crypto::X509::TimePoint = std::chrono::sys_seconds

Point in time with second precision, as stored in certificates.

Enumeration Type Documentation

◆ DetachedSignatureAlgorithm

Supported algorithms and encodings for detached signatures.

Enumerator
ECDSA_SHA384 

ECDSA with SHA-384, encoded as a DER SEQUENCE of INTEGERs.

◆ IdentityError

Errors of subjectAltName extraction and expected-identity verification.

Enumerator
InvalidExpectedName 

The expected DNS name is not an acceptable ASCII host name.

InvalidExpectedAddress 

The expected IP address is not exactly 4 or 16 bytes.

MissingSubjectAltName 

The certificate has no subjectAltName extension.

MalformedSubjectAltName 

The subjectAltName extension or one of its entries is malformed.

NoMatch 

The extension is well formed but no entry matches the expected identity.

◆ KeyUsage

enum class StormByte::Crypto::X509::KeyUsage : std::uint16_t
strong

Bits of the keyUsage extension (RFC 5280 §4.2.1.3).

Enumerator
DigitalSignature 

digitalSignature

NonRepudiation 

nonRepudiation (contentCommitment)

KeyEncipherment 

keyEncipherment

DataEncipherment 

dataEncipherment

KeyAgreement 

keyAgreement

KeyCertSign 

keyCertSign

CRLSign 

cRLSign

EncipherOnly 

encipherOnly

DecipherOnly 

decipherOnly

◆ PaymentPeerError

Fail-closed payment peer failures.

Enumerator
TrustPathRejected 

Path or selected bundled anchor validation failed.

RevocationUnavailable 

Evidence is missing for at least one non-anchor certificate.

RevocationEvidenceRejected 

Any evidence is malformed, invalid, stale or unauthorized.

CertificateRevoked 

A validated CRL or OCSP response reports revocation.

RevocationUnknown 

A validated OCSP response reports unknown status.

◆ PurposeError

Errors of narrowly scoped certificate-purpose checks.

Enumerator
UnsupportedRole 

Role is not Server or Client.

InvalidCertificate 

Certificate is empty or moved from.

MalformedExtendedKeyUsage 

EKU is not a non-empty strict DER sequence of valid OIDs.

ExtendedKeyUsageNotAllowed 

EKU does not permit the requested purpose.

MalformedKeyUsage 

Present KU violates DER named-bit-string encoding or its 1..9-bit range.

KeyUsageNotAllowed 

Present KU lacks digitalSignature.

◆ RevocationError

Failures that prevent trusting revocation evidence.

Enumerator
InvalidRequest 

Empty certificates, invalid issuer relationship or oversized evidence.

MalformedEvidence 

Invalid DER, duplicate fields, or malformed status data.

UnsupportedFeature 

Unsupported algorithm, CRL scope, extension or response type.

IssuerMismatch 

Evidence issuer or OCSP CertID does not match the supplied issuer.

CertificateMismatch 

Evidence does not contain a status for the target certificate.

InvalidSignature 

Evidence signature cannot be verified with an authorized key.

ResponderUnauthorized 

OCSP signer is not the issuer or an authorized delegated responder.

NotYetValid 

Evidence was produced after the requested validation time.

Stale 

Evidence validity interval does not cover the requested time.

MissingNextUpdate 

Evidence has no bounded freshness interval.

◆ RevocationFormat

Encoding of offline revocation evidence supplied by the caller.

Enumerator
CRL 

DER-encoded complete X.509 CertificateList.

OCSP 

DER-encoded successful OCSPResponse containing BasicOCSPResponse.

◆ RevocationStatus

Authenticated status reported by a verified evidence object.

Enumerator
Good 

Evidence covers the certificate and does not report it revoked.

Revoked 

A verified CRL or OCSP response reports revocation.

Unknown 

A verified OCSP response explicitly reports unknown status.

◆ SubjectAltNameType

Supported subjectAltName general name kinds (RFC 5280 §4.2.1.6).

Enumerator
DNS 

dNSName, an ASCII host name or a leftmost-label wildcard pattern.

IP 

iPAddress, 4 (IPv4) or 16 (IPv6) network-order bytes.

◆ TLSPeerError

Failures of the constrained, offline TLS signing-certificate verifier.

Enumerator
UnsupportedRole 

Role is neither Server nor Client.

MissingServerIdentity 

A server requires an expected DNS or IP identity.

UnsupportedIdentity 

Identity kind is neither DNS nor IP.

InvalidCertificate 

A leaf, intermediate or anchor is empty.

InvalidTime 

Caller time is outside a certificate's inclusive validity interval.

LeafIsCA 

Peer leaf must not be a CA.

NotCA 

Issuer is not a version 3 CA.

IssuerKeyUsageNotAllowed 

Present issuer KU lacks keyCertSign.

PathLengthExceeded 

Supplied CA count exceeds an issuer's pathLenConstraint.

SignatureOrIssuerMismatch 

Ordered issuer name or certificate signature does not verify.

UnsupportedAlgorithm 

Signature or public key is outside the documented subset.

UnsupportedCriticalExtension 

Critical extension is not fully processed by this verifier.

UnsupportedConstraint 

Present path restriction requires unsupported processing.

MalformedExtension 

Relevant extension has invalid DER or inconsistent semantics.

Purpose 

PurposeDetail supplies the exact EKU/KU failure.

Identity 

IdentityDetail supplies the exact SAN failure.

◆ TLSRole

Certificate signing role in TLS 1.3 (RFC 8446 §4.4.2.2).

Enumerator
Server 

Certificate used by the TLS server.

Client 

Certificate used by the TLS client.

◆ TrustPathError

Failures of path validation, never a full authentication verdict.

Enumerator
BundleInvalid 

Snapshot digest, count or certificate parsing failed.

InvalidRequest 

Empty certificate, invalid identity or excessive chain length.

RootNotAdmitted 

No matching root belongs to the bundled server snapshot.

PeerPathRejected 

Linux's documented constrained verifier rejected the path.

NativePolicyRejected 

Native TLS policy rejected the explicitly anchored path.

Function Documentation

◆ BundledTLSRootsRevision()

const char * StormByte::Crypto::X509::BundledTLSRootsRevision ( )
noexcept

Returns the immutable snapshot revision.

Returns
Library-owned NSS revision identifier.

◆ BundledTLSRootsSHA256()

const char * StormByte::Crypto::X509::BundledTLSRootsSHA256 ( )
noexcept

Returns the embedded PEM integrity fingerprint.

Returns
Library-owned lowercase SHA-256 hexadecimal text.

◆ Load()

Safe::Optional< Certificate > StormByte::Crypto::X509::Load ( std::span< const std::byte > data)
noexcept

Loads one certificate from DER or PEM.

Parameters
dataDER bytes, or PEM text whose first CERTIFICATE block is used.
Returns
Parsed certificate, or empty on malformed input.

◆ LoadAll()

Safe::Vector< Certificate > StormByte::Crypto::X509::LoadAll ( std::span< const std::byte > data)
noexcept

Loads every CERTIFICATE block of a PEM bundle, in order.

Parameters
dataPEM text, or a single DER certificate.
Returns
Parsed certificates; empty when there are none or any block is malformed.

◆ LoadBundledTLSRoots()

ExpectedBundledTLSRoots StormByte::Crypto::X509::LoadBundledTLSRoots ( )

Loads a verified copy of the versioned, curated Mozilla server roots.

Returns
Safe certificate vector, or BundleInvalid; never system or environment roots.
Exceptions
StormByte::Safe::AllocationErrorStorage cannot be allocated.
Note
Updating the returned copy cannot modify production trust. No file or network I/O.

◆ ValidateBundledTLSPath()

ExpectedTrustPath StormByte::Crypto::X509::ValidateBundledTLSPath ( const Certificate & leaf,
std::span< const Certificate > intermediates,
TimePoint at,
const SubjectAltName & identity )

Validates only a server trust path and SAN identity against bundled admission.

Parameters
leafUntrusted server certificate.
intermediatesIssuers, excluding leaf and root; Linux requires exact order.
atExplicit validation time, with second precision.
identityExpected DNS or network-order IP identity; no CN fallback.
Returns
Path-only result. Success is NOT peer authentication or payment authorization.
Exceptions
StormByte::Safe::AllocationErrorStorage cannot be allocated.

Linux uses only the embedded roots and the constrained TLSPeerVerifier subset, including unsupported-constraint failures. It never consults distro, environment or system CA files. Windows/macOS apply native TLS policy with exclusive bundled anchors; admission does not additionally require the OS to trust the root. Network fetching is disabled. No CRL/OCSP validation or proof of key possession. See doc/trust-path-validation.md for exclusions and exact policy limitations.

◆ ValidateCustomCATLSPath()

ExpectedTrustPath StormByte::Crypto::X509::ValidateCustomCATLSPath ( const Certificate & leaf,
std::span< const Certificate > intermediates,
const Certificate & anchor,
TimePoint at,
const SubjectAltName & identity )

Validates a separate, explicitly opted-in custom-CA server path.

Parameters
leafUntrusted server certificate.
intermediatesIssuers, excluding leaf and anchor.
anchorExplicit caller-selected custom trust anchor.
atExplicit validation time.
identityExpected DNS or IP identity.
Returns
Path-only result; custom trust never modifies bundled admission.
Exceptions
StormByte::Safe::AllocationErrorStorage cannot be allocated.
Note
Native platforms apply scoped native TLS policy, without requiring OS root admission of the custom CA. Linux retains TLSPeerVerifier's constraints.

◆ VerifyPaymentPeer()

ExpectedPaymentPeer StormByte::Crypto::X509::VerifyPaymentPeer ( const Certificate & leaf,
std::span< const Certificate > intermediates,
const Certificate & anchor,
TimePoint at,
const SubjectAltName & identity,
std::span< const RevocationEvidence > evidence )

Validates the bundled path and all non-anchor certificates' revocation status.

Parameters
leafUntrusted server certificate.
intermediatesIssuers, excluding leaf and root.
anchorExact bundled trust anchor for this chain.
atExplicit validation time.
identityExpected payment endpoint DNS or IP identity.
evidenceOne CRL or OCSP response per leaf/intermediate in chain order. The trust anchor is excluded. Each response is borrowed for this call.
Returns
Success only when path and every required revocation status are valid and Good.
Exceptions
StormByte::Safe::AllocationErrorStorage cannot be allocated.
Note
Missing, unknown, stale, invalid or revoked evidence fails closed. Crypto performs no network, filesystem, native store or cache access.