Browse the docs

silk.tls.trust_snapshot.

A fixed list of trust anchors: the root CAs that certificate path validation starts from.

When to use#

Make a TrustSnapshot from your CA certificates with TrustSnapshot.fromPem, or from anchors with limits with TrustSnapshot.fromAnchors. Pass it to path validation or to a TLS client. Use TrustSnapshot.combine to add your own CAs to another snapshot.

Details#

A snapshot keeps its anchors in input order, with duplicates, and does not change after you make it. SnapshotLimits and TrustLoadLimits bound its size. An empty snapshot is valid: it trusts no certificate.

Errors#

  • TrustSourceError if a certificate is not valid, or a limit is exceeded.

  • OutOfMemoryError if the Allocator fails.

Gotchas#

A snapshot is only a list of authorities. It does not check chains, names, dates, or revocation, and it is not the trust store of the operating system.

Examples#

Make an empty snapshot#

silk
import silk.collections.list { List }
import silk.core.result { Result }
import silk.tls.trust_anchor { TrustAnchor }
import silk.tls.trust_snapshot { SnapshotLimits, TrustSnapshot, TrustSourceError }

pub fn main() -> i32 {
  return match TrustSnapshot.fromAnchors(List<TrustAnchor>.make(), SnapshotLimits.defaults()) {
    Result<TrustSnapshot, TrustSourceError>.Success { value } => {
      // An empty snapshot is valid, but no certificate chains to it.
      if TrustSnapshot.anchors(&value).length != 0 {
        return 1
      }
      return 0
    }
    Result<TrustSnapshot, TrustSourceError>.Failure { error: _ } => 1
  }
}

Import as TrustSnapshot with import silk.tls.trust_snapshot { TrustSnapshot }.

Public declarations: 7.

SnapshotLimits#

silk
pub struct SnapshotLimits

The limits for one snapshot. Each limit is inclusive, and 0 allows nothing.

Field anchors#

silk
pub anchors: usize

The maximum number of anchors, with duplicates.

Field encodedBytes#

silk
pub encodedBytes: usize

The maximum size of all anchors, as TrustAnchor.encodedBytes counts it.

Implementation Copy for SnapshotLimits#

silk
impl Copy for SnapshotLimits

Implementation SnapshotLimits#

silk
impl SnapshotLimits

Associated function defaults#

silk
pub fn defaults() -> SnapshotLimits

Returns the default limits: 1024 anchors and 8 MiB.

TrustLoadLimits#

silk
pub struct TrustLoadLimits

The limits for loading trust: the certificate decoder limits and the snapshot limits.

Field decode#

silk
pub decode: DecodeLimits

The limits for decoding PEM and certificates.

Field snapshot#

silk
pub snapshot: SnapshotLimits

The limits for the snapshot.

Implementation Copy for TrustLoadLimits#

silk
impl Copy for TrustLoadLimits

Implementation TrustLoadLimits#

silk
impl TrustLoadLimits

Associated function defaults#

silk
pub fn defaults() -> TrustLoadLimits

Returns DecodeLimits.defaults() and SnapshotLimits.defaults.

TrustLimitKind#

silk
pub enum TrustLimitKind

The limit that a trust load exceeded.

AnchorCount#

silk
AnchorCount

The number of anchors.

EncodedBytes#

silk
EncodedBytes

The size of all anchors.

InputBytes#

silk
InputBytes

The size of a file that a native trust source reads.

Implementation Debug for TrustLimitKind#

silk
impl Debug for TrustLimitKind

Operation debug#

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

Writes the name of the variant, such as AnchorCount.

TrustConfigurationReason#

silk
pub enum TrustConfigurationReason

The reason that the configuration of a native trust source is not valid.

EmptyRoot#

silk
EmptyRoot

A root file path is empty.

NonAbsoluteRoot#

silk
NonAbsoluteRoot

A root file path is not absolute.

NulRoot#

silk
NulRoot

A root file path contains a zero byte.

PathBytes#

silk
PathBytes

A root file path is too long.

Implementation Debug for TrustConfigurationReason#

silk
impl Debug for TrustConfigurationReason

Operation debug#

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

Writes the name of the variant, such as EmptyRoot.

TrustFileOperation#

silk
pub enum TrustFileOperation

The file step that failed in a native trust source.

Open#

silk
Open

Opening the trust file.

Read#

silk
Read

Reading the trust file.

Close#

silk
Close

Closing the trust file.

Implementation Debug for TrustFileOperation#

silk
impl Debug for TrustFileOperation

Operation debug#

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

Writes the name of the variant, such as Open.

TrustSourceError#

silk
pub union TrustSourceError

The reason that loading trust failed. An allocation failure is an OutOfMemoryError instead.

Decode#

silk
Decode

A certificate or its PEM is not valid.

Field error#

silk
pub error: DecodeError

The decoder error, with its position.

LimitExceeded#

silk
LimitExceeded

A limit was exceeded.

Field kind#

silk
pub kind: TrustLimitKind

The limit.

Field limit#

silk
pub limit: usize

The value of the limit.

InvalidConfiguration#

silk
InvalidConfiguration

The configuration of a native trust source is not valid.

Field reason#

silk
pub reason: TrustConfigurationReason

The problem.

File#

silk
File

A file operation of a native trust source failed.

Field operation#

silk
pub operation: TrustFileOperation

The step that failed.

Field error#

silk
pub error: FileError

The file error.

Implementation Debug for TrustSourceError#

silk
impl Debug for TrustSourceError

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 Decode { ... }.

TrustSnapshot#

silk
pub struct TrustSnapshot

A list of trust anchors that does not change. It owns them and keeps their order and duplicates.

When to use#

Make one from your CA certificates with TrustSnapshot.fromPem, or from anchors with limits with TrustSnapshot.fromAnchors. Pass it to path validation or to a TLS client. Use TrustSnapshot.combine to add your own CAs to another snapshot.

Details#

SnapshotLimits and TrustLoadLimits bound its size. An empty snapshot is valid: it trusts no certificate.

Gotchas#

A snapshot is only a list of authorities. It does not check chains, names, dates, or revocation, and it is not the trust store of the operating system.

Implementation TrustSnapshot#

silk
impl TrustSnapshot

Associated function fromAnchors#

silk
pub fn fromAnchors(
    anchors: List<TrustAnchor>,
    limits: SnapshotLimits,
  ) -> Result<TrustSnapshot, TrustSourceError>

Returns a snapshot with anchors, in their order. It does not copy them.

An empty list is valid.

Errors#

  • LimitExceeded if anchors goes over limits. The anchors are dropped.

Associated function fromPem#

silk
pub effect fn fromPem(
    input: &[u8],
    limits: TrustLoadLimits,
  ) -> Result<TrustSnapshot, TrustSourceError>
  ! OutOfMemoryError
  ? &mut Allocator

Returns a snapshot with one anchor without limits for each CERTIFICATE block of input.

Errors#

  • Failure with Decode if the PEM or a certificate is not valid. The decoder is strict, and an empty file is an error.

  • Failure with LimitExceeded if a limit is exceeded.

  • OutOfMemoryError if the Allocator fails.

Associated function fromAnnotatedPem#

silk
pub effect fn fromAnnotatedPem(input: &[u8], limits: TrustLoadLimits) -> Result<TrustSnapshot, TrustSourceError>
  ! OutOfMemoryError ? &mut Allocator

Returns a snapshot from a CA file that has comment lines between the blocks.

It uses CertificateBundle.decodeAnnotatedPem. A certificate that is not valid fails the whole call. None are skipped.

Errors#

Gotchas#

Use it only for a CA file that you configured and trust, never for data from a peer.

Method anchors#

silk
pub fn anchors(self: &Self) -> &[TrustAnchor]

Returns the anchors in their order, with duplicates.

Method copy#

silk
pub effect fn copy(
    self: &Self,
    limits: SnapshotLimits,
  ) -> Result<TrustSnapshot, TrustSourceError>
  ! OutOfMemoryError
  ? &mut Allocator

Returns a copy of the snapshot that is checked against limits.

Errors#

  • Failure with LimitExceeded if the snapshot goes over limits.

  • OutOfMemoryError if the Allocator fails.

Associated function combine#

silk
pub effect fn combine(
    primary: &TrustSnapshot,
    additional: &TrustSnapshot,
    limits: SnapshotLimits,
  ) -> Result<TrustSnapshot, TrustSourceError>
  ! OutOfMemoryError
  ? &mut Allocator

Returns a new snapshot with the anchors of primary and then those of additional.

Duplicates are kept. Equal certificates are not merged.

Errors#

  • Failure with LimitExceeded if the result goes over limits.

  • OutOfMemoryError if the Allocator fails.

Gotchas#

An anchor in additional with fewer limits than the same certificate in primary makes the trust wider.

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