Browse the docs

silk.tls.certificate_path.

Validate the certificate chain of a TLS server, from its leaf certificate to a trust anchor.

When to use#

Call CertificatePath.validate with the certificates that a server sent and your TrustAnchor list, before you trust the server. After it succeeds, check the host name with silk.tls.https_identity, and check the TLS CertificateVerify and Finished messages. silk.tls.client does all of these steps for you.

Details#

The validator tries to build a path from the leaf, through the intermediates, to an anchor. At each step it tries the anchors first and then the intermediates, in the order that you gave them, and it backtracks when a candidate fails. It checks signatures, validity dates at the Instant that you give, basic constraints, key usage, path length, and DNS and IP name constraints. ValidationLimits bound all work, so a hostile chain cannot make it run for long.

Errors#

  • ValidationError if no valid path exists, an input is not valid, or a limit is exceeded. reason, location, and offset tell you what failed and where.

  • OutOfMemoryError if the Allocator fails.

Gotchas#

A ValidatedPath does not authenticate a TLS connection by itself. Revocation (CRL and OCSP), certificate transparency, fetching missing intermediates, and browser root policies are not checked.

Import as CertificatePath with import silk.tls.certificate_path { CertificatePath }.

Public declarations: 9.

ValidationLimits#

silk
pub struct ValidationLimits

The limits for one validation call. Each limit is inclusive, and 0 allows nothing. ValidationLimits.defaults gives safe values.

Field peerCertificates#

silk
pub peerCertificates: usize

Maximum peer certificates, including the leaf.

Field certificateBytes#

silk
pub certificateBytes: usize

Maximum DER bytes in each peer certificate.

Field peerBytes#

silk
pub peerBytes: usize

Maximum aggregate peer certificate DER bytes.

Field anchors#

silk
pub anchors: usize

Maximum explicit trust-anchor candidates.

Field anchorBytes#

silk
pub anchorBytes: usize

Maximum aggregate encoded trust-anchor bytes.

Field pathCertificates#

silk
pub pathCertificates: usize

Maximum selected path certificates, excluding the anchor and including the leaf.

Field issuerCandidates#

silk
pub issuerCandidates: usize

Maximum issuer-candidate visits.

Field signatureVerifications#

silk
pub signatureVerifications: usize

Maximum primitive signature verifications.

Field completePaths#

silk
pub completePaths: usize

Maximum reached anchored candidate paths.

Field nameComparisons#

silk
pub nameComparisons: usize

Maximum DNS or IP name/subtree comparisons.

Field profile#

silk
pub profile: ProfileLimits

Bounds for each semantic certificate-profile inspection.

Implementation Copy for ValidationLimits#

silk
impl Copy for ValidationLimits

Implementation ValidationLimits#

silk
impl ValidationLimits

Associated function defaults#

silk
pub fn defaults() -> ValidationLimits

Returns the default limits: 64 peer certificates of up to 64 KiB each and 1 MiB in total, 1024 anchors and 16 MiB of anchor data, paths of up to 8 certificates, 4096 issuer candidates, 100 signature checks, 100 complete paths, 250000 name comparisons, and the profile defaults.

ValidationClass#

silk
pub enum ValidationClass

The broad category of a path-validation failure.

InvalidInput#

silk
InvalidInput

Caller input is invalid independently of trust-path selection.

Rejected#

silk
Rejected

The fixed certificate policy rejects all deterministic candidate paths.

ResourceLimit#

silk
ResourceLimit

An inclusive caller-supplied resource or work bound is exceeded.

Implementation Debug for ValidationClass#

silk
impl Debug for ValidationClass

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as InvalidInput.

ValidationReason#

silk
pub enum ValidationReason

Stable path-validation rejection reasons.

UnsupportedVersion#

silk
UnsupportedVersion

The certificate version is outside the fixed role profile.

UnsupportedAlgorithm#

silk
UnsupportedAlgorithm

A required signature or key algorithm is unsupported.

UnsupportedParameters#

silk
UnsupportedParameters

Algorithm parameters are unsupported or inconsistent.

UnsupportedExtension#

silk
UnsupportedExtension

An extension needs unsupported processing.

UnsupportedConstraint#

silk
UnsupportedConstraint

A NameConstraints form is outside the DNS/IP subset.

UnsupportedPolicy#

silk
UnsupportedPolicy

Certificate policy processing is required but not implemented.

InvalidKey#

silk
InvalidKey

A public key is malformed or outside the admitted profile.

InvalidSignature#

silk
InvalidSignature

A retained certificate signature does not verify.

InvalidSerial#

silk
InvalidSerial

A path-certificate serial is invalid.

InvalidUsage#

silk
InvalidUsage

KeyUsage or ExtendedKeyUsage rejects the selected role.

InvalidBasicConstraints#

silk
InvalidBasicConstraints

BasicConstraints or CA-role policy rejects the certificate.

InvalidName#

silk
InvalidName

A subject name or subjectAltName is invalid.

InvalidTime#

silk
InvalidTime

A caller instant or certificate validity interval is invalid.

DuplicateExtension#

silk
DuplicateExtension

Two extensions contain the same OID.

IssuerMismatch#

silk
IssuerMismatch

Exact issuer and subject Name DER do not match.

NameConstraintViolation#

silk
NameConstraintViolation

A subordinate SAN violates cumulative NameConstraints.

PathLengthExceeded#

silk
PathLengthExceeded

An embedded or configured path-length restriction is exceeded.

Cycle#

silk
Cycle

A linked candidate repeats certificate DER already on the current path.

NoIssuer#

silk
NoIssuer

No supplied candidate has an exact linking subject Name.

NoValidPath#

silk
NoValidPath

Every deterministically visited linked path is rejected.

SizeOverflow#

silk
SizeOverflow

A checked length or counter sum is not representable.

Implementation Debug for ValidationReason#

silk
impl Debug for ValidationReason

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as UnsupportedVersion.

ValidationLocation#

silk
pub union ValidationLocation

The input position associated with one validation failure.

Leaf#

silk
Leaf

The peer end-entity certificate.

Intermediate#

silk
Intermediate

One peer intermediate at its original caller index.

Field index#

silk
pub index: usize

The original caller index.

Anchor#

silk
Anchor

One explicit trust anchor at its original caller index.

Field index#

silk
pub index: usize

The original caller index.

Call#

silk
Call

The validation call rather than one certificate.

Implementation Copy for ValidationLocation#

silk
impl Copy for ValidationLocation

Implementation Debug for ValidationLocation#

silk
impl Debug for ValidationLocation

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant and its fields, such as Leaf.

ValidationLimit#

silk
pub enum ValidationLimit

A named inclusive validation bound.

PeerCertificates#

silk
PeerCertificates

Total peer certificate count, including the leaf.

CertificateBytes#

silk
CertificateBytes

DER bytes in one peer certificate.

PeerBytes#

silk
PeerBytes

Aggregate peer certificate DER bytes.

Anchors#

silk
Anchors

Explicit trust-anchor count.

AnchorBytes#

silk
AnchorBytes

Aggregate encoded trust-anchor bytes.

PathCertificates#

silk
PathCertificates

Selected path certificate count, excluding the anchor.

IssuerCandidates#

silk
IssuerCandidates

Issuer-candidate visits.

SignatureVerifications#

silk
SignatureVerifications

Primitive signature verifications.

CompletePaths#

silk
CompletePaths

Complete anchored candidate paths.

NameComparisons#

silk
NameComparisons

DNS or IP name/subtree comparisons.

ProfileExtensions#

silk
ProfileExtensions

Certificate-profile extension count.

ProfileExtensionBytes#

silk
ProfileExtensionBytes

One certificate-profile extension value size.

ProfileSanNames#

silk
ProfileSanNames

Certificate-profile subjectAltName count.

ProfileConstraintSubtrees#

silk
ProfileConstraintSubtrees

Certificate-profile NameConstraints subtree count.

ProfileNodes#

silk
ProfileNodes

Certificate-profile DER-node count.

ProfileDepth#

silk
ProfileDepth

Certificate-profile DER nesting depth.

Arithmetic#

silk
Arithmetic

Checked arithmetic representation.

Implementation Debug for ValidationLimit#

silk
impl Debug for ValidationLimit

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the name of the variant, such as PeerCertificates.

ValidationError#

silk
pub struct ValidationError

The error of one failed CertificatePath.validate call.

Details#

reason, location, and offset tell what failed and where. When no path is valid, reason is NoValidPath and detailReason gives the first rejection. It owns its values and does not borrow the input.

Field kind#

silk
pub kind: ValidationClass

Broad failure category.

Field reason#

silk
pub reason: ValidationReason

Stable primary reason.

Field detailReason#

silk
pub detailReason: Option<ValidationReason>

First rejected-candidate detail when reason is NoValidPath.

Field location#

silk
pub location: ValidationLocation

Input position associated with the primary or retained detail.

Field extensionIndex#

silk
pub extensionIndex: Option<usize>

Extension index when a profile failure belongs to an extension.

Field limit#

silk
pub limit: Option<ValidationLimit>

Named bound for a resource-limit failure.

Field offset#

silk
pub offset: usize

Byte offset in the relevant certificate or configured constraint input.

Implementation Debug for ValidationError#

silk
impl Debug for ValidationError

Operation debug#

silk
effect fn debug(self: &Self, formatter: &mut Formatter) -> () ! WriterError ? &mut Writer

Writes the fields, as ValidationError { kind: ..., reason: ..., ... }.

RevocationStatus#

silk
pub enum RevocationStatus

Revocation evidence attached to a validated path.

NotChecked#

silk
NotChecked

No CRL, OCSP, must-staple, or other revocation check was performed.

ValidatedPath#

silk
pub struct ValidatedPath<'a>

A path that passed validation. It borrows the certificates and anchors that you gave.

The intermediates are given as indexes into your list, from the leaf toward the anchor.

Gotchas#

A validated path does not authenticate a TLS connection by itself. Check the host name with silk.tls.https_identity, and check the TLS CertificateVerify and Finished messages. Revocation (CRL and OCSP), certificate transparency, fetching missing intermediates, and browser root policies are not checked.

Implementation ValidatedPath<'a>#

silk
impl<'a> ValidatedPath<'a>

Method leaf#

silk
pub fn leaf(self: &Self) -> &'a Certificate

Returns the leaf certificate.

Method anchorIndex#

silk
pub fn anchorIndex(self: &Self) -> usize

Returns the index of the trust anchor that the path ends at, in your anchor list.

Method intermediateCount#

silk
pub fn intermediateCount(self: &Self) -> usize

Returns the number of intermediate certificates in the path.

Method intermediateIndex#

silk
pub fn intermediateIndex(self: &Self, index: usize) -> Option<usize>

Returns the index in your intermediate list of the path certificate at index, counted from the leaf, or None if index is out of range.

Method validationTime#

silk
pub fn validationTime(self: &Self) -> Instant

Returns the time that the dates were checked at.

Method revocationStatus#

silk
pub fn revocationStatus(self: &Self) -> RevocationStatus

Returns NotChecked, because path validation does not check revocation.

CertificatePath#

silk
pub struct CertificatePath

Functions that validate the certificate chain of a TLS server, from its leaf certificate to a trust anchor.

When to use#

Call CertificatePath.validate with the certificates that a server sent and your TrustAnchor list, before you trust the server. silk.tls.client does this and the other TLS checks for you.

Gotchas#

A ValidatedPath does not authenticate a TLS connection by itself. Revocation (CRL and OCSP), certificate transparency, fetching missing intermediates, and browser root policies are not checked.

Implementation CertificatePath#

silk
impl CertificatePath

Associated function validate#

silk
pub effect fn validate<'a>(
    leaf: &'a Certificate,
    intermediates: &'a [Certificate],
    anchors: &'a [TrustAnchor],
    at: &Instant,
    limits: ValidationLimits,
  ) -> Result<ValidatedPath<'a>, ValidationError>
  ! OutOfMemoryError
  ? &mut Allocator

Finds and checks a path from leaf through intermediates to one of anchors, at time at.

At each step it tries the anchors first and then the intermediates, in the order that you gave them, and it backtracks when a candidate fails. It checks signatures, validity dates at at, basic constraints, key usage, path length, and DNS and IP name constraints. limits bound all work, so a hostile chain cannot make it run for long.

It returns the first valid path that it finds. A candidate that fails does not stop the search, but each limit counts across the whole call. The result borrows leaf, intermediates, and anchors.

Errors#

  • Failure with a ValidationError. If no path is valid, reason is NoValidPath and detailReason gives the first rejection.

  • OutOfMemoryError if the Allocator fails.

Gotchas#

A valid path does not authenticate a TLS connection by itself. After it succeeds, check the host name with silk.tls.https_identity, and check the TLS CertificateVerify and Finished messages. Revocation (CRL and OCSP), certificate transparency, fetching missing intermediates, and browser root policies are not checked.

Category: TLS and certificates.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.

View the source of this page