silk.tls.trust_source_native.

When to use#

Provide NativeFileTrustSource for TrustSource when your program uses one PEM bundle of CA certificates, for example /etc/ssl/certs/ca-certificates.crt on Debian or /etc/ssl/cert.pem on macOS.

Details#

NativeFileTrustSource.make copies the root directory and the path. It does no I/O. Each load opens the file again, reads at most the input limit, closes it, and decodes it with TrustSnapshot.fromAnnotatedPem. Text outside the certificate blocks is allowed. A bad block fails the load. Each snapshot owns its anchors.

The path is opened below the root without following symbolic links, as in silk.platform.native.filesystem. Trust the root and its parent directories. To change the file, write a new file and rename it. A change in place can be read half way.

Errors#

TrustSourceError for bad configuration, a file error, a file over the input limit, or bad PEM. OutOfMemoryError if the allocation fails.

Gotchas#

• It does not look for a default file, read environment variables, or use the trust store of the system (such as the macOS keychain). It does not check revocation.

• The provider exists only on Darwin on aarch64, and Linux with GNU libc on x86_64 or aarch64.

Examples#

Configure a bundle and see a load fail#

import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.core.result { Result }
import silk.system.filesystem { FileError, Path }
import silk.tls.trust_source_native { NativeFileTrustSource }
import silk.tls.trust_snapshot { TrustLoadLimits, TrustSourceError }
import silk.tls.trust_source { TrustSource }

effect fn program() -> i32
  ! FileError | TrustSourceError | OutOfMemoryError
  ? &mut Allocator {
  // On Debian, the bundle is /etc/ssl/certs/ca-certificates.crt. On macOS, /etc/ssl/cert.pem.
  let bundle = run Path.fromBytes(b"/ca-certificates.crt")
  let debian = run NativeFileTrustSource.make(b"/etc/ssl/certs", &bundle)
  drop debian

  // `make` does no I/O. A missing file fails at `load`.
  let missing = run Path.fromBytes(b"/silk-doc-missing.pem")
  let mut source = run NativeFileTrustSource.make(b"/tmp", &missing)
  let loaded = run Effect.result(TrustSource.load(TrustLoadLimits.defaults()))
    |> Effect.provideMut<TrustSource>(&mut source)
  return match move loaded {
    Result.Success { value: _ } => 1
    Result.Failure { error: failure } => match move failure {
      TrustSourceError.File { operation: _, error: cause } => {
        drop cause
        return 0
      }
      _ => 1
    }
  }
}

effect fn failed<E>(error: E) -> i32 {
  drop error
  return 1
}

pub fn main() -> i32 {
  let mut allocator = Allocator.systemAllocatorProvider()
  return run Effect.catchAll(program(), failed) |> Effect.provideMut<Allocator>(&mut allocator)
}

Import as NativeFileTrustSource with import silk.tls.trust_source_native { NativeFileTrustSource }.

Public declarations: 1.

NativeFileTrustSource#

pub struct NativeFileTrustSource

A TrustSource provider that owns a root directory and a path to a PEM file below it. It does not cache snapshots.

When to use#

Provide it for TrustSource when your program uses one PEM bundle of CA certificates, for example /etc/ssl/certs/ca-certificates.crt on Debian or /etc/ssl/cert.pem on macOS.

Details#

Each load opens the file again, reads at most the input limit, closes it, and decodes it with TrustSnapshot.fromAnnotatedPem. Text outside the certificate blocks is allowed. A bad block fails the load. Each snapshot owns its anchors. The path is opened below the root without following symbolic links. Trust the root and its parent directories. To change the file, write a new file and rename it. A change in place can be read half way.

Gotchas#

• It does not look for a default file, read environment variables, or use the trust store of the system (such as the macOS keychain). It does not check revocation.

• The provider exists only on Darwin on aarch64, and Linux with GNU libc on x86_64 or aarch64.

Implementation NativeFileTrustSource#

impl NativeFileTrustSource

Associated function make#

pub effect fn make(
      root: &[u8],
      path: &Path,
    ) -> NativeFileTrustSource
    ! TrustSourceError | OutOfMemoryError
    ? &mut Allocator

Returns a provider for the PEM file at path below root. It does no I/O.

Errors#

• TrustSourceError with InvalidConfiguration if root is empty, is not absolute, or has NUL, or if root and path together have more than 4096 bytes.

• OutOfMemoryError if the copies cannot be allocated.

Implementation TrustSource for NativeFileTrustSource#

impl TrustSource for NativeFileTrustSource

Operation load#

load: NativeFileTrustSource.loadCurrent

Category: TLS and certificates.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, x86_64-unknown-linux-gnu.