silk/https_identity

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

Bounded HTTPS DNS-ID and IP-ID matching over caller-supplied identities.

When to use

Use HttpsIdentity.reference with the original HTTPS host before DNS resolution. Use HttpsIdentity.verify with the complete SAN list from the same leaf used for trust validation.

DNS inputs borrow ASCII LDH bytes or prepared A-labels. IP references own network-order octets. DNS comparison ignores ASCII case. A whole leftmost wildcard matches exactly one label. The matcher validates all SANs before success and uses constant temporary storage without allocation.

Gotchas

Success proves only name matching, not signatures, path trust, name constraints, or TLS authentication. There is no CN, URI-ID, SRV-ID, alias, or reverse-DNS fallback. Trailing dots and Unicode inputs are rejected. The caller must validate HTTPS origins and convert IP literals; brackets, ports, escapes and zones are not DNS inputs.

Import as HttpsIdentity with import silk.https_identity { HttpsIdentity }.

Public declarations: 13.

`UnsupportedForm`

pub enum UnsupportedForm

A reference form that HTTPS identity verification does not support.

`IpvFuture`

IpvFuture = 0

An IPvFuture reference is unsupported.

`ZoneIdentifier`

ZoneIdentifier = 1

A scoped address reference is unsupported.

`UriId`

UriId = 2

A URI-ID reference is unsupported for HTTPS.

`SrvId`

SrvId = 3

An SRV-ID reference is unsupported for HTTPS.

`OriginHost`

pub union OriginHost<'name>

The original HTTPS host, classified by the caller before DNS resolution.

`Dns`

OriginHost<'name>.Dns { bytes: &'name [u8] }: OriginHost<'name>

Borrowed ASCII DNS bytes without a trailing dot.

Field `bytes`

pub bytes: &'name [u8]

The exact bytes; no normalization or text conversion is implicit.

`Ipv4`

OriginHost<'name>.Ipv4 { bytes: Array<u8, 4> }: OriginHost<'name>

Four owned network-order address octets.

Field `bytes`

pub bytes: Array<u8, 4>

The exact bytes; no normalization or text conversion is implicit.

`Ipv6`

OriginHost<'name>.Ipv6 { bytes: Array<u8, 16> }: OriginHost<'name>

Sixteen owned network-order address octets.

Field `bytes`

pub bytes: Array<u8, 16>

The exact bytes; no normalization or text conversion is implicit.

`Unsupported`

OriginHost<'name>.Unsupported { form: UnsupportedForm }: OriginHost<'name>

An explicitly unsupported reference form.

Field `form`

pub form: UnsupportedForm

The unsupported reference form.

`ReferenceIdentity`

pub union ReferenceIdentity<'name>

A DNS borrow or owned binary IP reference; public construction does not validate it.

`Dns`

ReferenceIdentity<'name>.Dns { bytes: &'name [u8] }: ReferenceIdentity<'name>

Borrowed ASCII DNS bytes without a trailing dot.

Field `bytes`

pub bytes: &'name [u8]

The exact bytes; no normalization or text conversion is implicit.

`Ipv4`

ReferenceIdentity<'name>.Ipv4 { bytes: Array<u8, 4> }: ReferenceIdentity<'name>

Four owned network-order address octets.

Field `bytes`

pub bytes: Array<u8, 4>

The exact bytes; no normalization or text conversion is implicit.

`Ipv6`

ReferenceIdentity<'name>.Ipv6 { bytes: Array<u8, 16> }: ReferenceIdentity<'name>

Sixteen owned network-order address octets.

Field `bytes`

pub bytes: Array<u8, 16>

The exact bytes; no normalization or text conversion is implicit.

`PresentedIdentity`

pub union PresentedIdentity<'cert>

One untrusted SAN descriptor in original certificate order.

`Dns`

PresentedIdentity<'cert>.Dns { bytes: &'cert [u8] }: PresentedIdentity<'cert>

Borrowed ASCII DNS bytes without a trailing dot.

Field `bytes`

pub bytes: &'cert [u8]

The exact bytes; no normalization or text conversion is implicit.

`Ip`

PresentedIdentity<'cert>.Ip { bytes: &'cert [u8] }: PresentedIdentity<'cert>

Borrowed network-order address octets; only lengths four and sixteen are valid.

Field `bytes`

pub bytes: &'cert [u8]

The exact bytes; no normalization or text conversion is implicit.

`Other`

PresentedIdentity<'cert>.Other { tag: u8, bytes: &'cert [u8] }: PresentedIdentity<'cert>

An uninterpreted GeneralName with an alternative number other than two or seven.

Field `tag`

pub tag: u8

The decoded GeneralName alternative number, from zero through eight except two and seven.

Field `bytes`

pub bytes: &'cert [u8]

The complete alternative content octets, counted even when this form is ignored.

`CertificateStructureError`

pub enum CertificateStructureError

A structural failure reported by a complete SAN decoder.

`InvalidDer`

InvalidDer = 0

The SAN input violates DER framing.

`InvalidGeneralName`

InvalidGeneralName = 1

A GeneralName violates its structural encoding.

`DuplicateSanExtension`

DuplicateSanExtension = 2

The certificate contains more than one SAN extension.

`EmptySanExtension`

EmptySanExtension = 3

A present SAN extension has no GeneralNames.

`CertificateIdentities`

pub union CertificateIdentities<'cert>

The complete SAN state; an absent extension is distinct from an empty extension.

`Absent`

CertificateIdentities<'cert>.Absent: CertificateIdentities<'cert>

The certificate has no SAN extension; common names are never consulted.

`Decoded`

CertificateIdentities<'cert>.Decoded { entries: &'cert [silk/https_identity.PresentedIdentity<'cert>] }: CertificateIdentities<'cert>

All SAN descriptors in source order, with no filtered entries.

Field `entries`

pub entries: &'cert [silk/https_identity.PresentedIdentity<'cert>]

The complete shared descriptor slice and payloads, bounded by the same lifetime.

`Malformed`

CertificateIdentities<'cert>.Malformed { reason: CertificateStructureError }: CertificateIdentities<'cert>

A structural failure that must prevent a match.

Field `reason`

pub reason: CertificateStructureError

The failed rule.

`NameError`

pub enum NameError

The first failed DNS admission rule under the documented precedence.

`EmptyName`

EmptyName = 0

The name has no octets.

`NameTooLong`

NameTooLong = 1

The name exceeds 253 octets.

`EmptyLabel`

EmptyLabel = 2

A label has no octets.

`LabelTooLong`

LabelTooLong = 3

A label exceeds 63 octets.

`Nul`

Nul = 4

The name contains an embedded zero octet.

`NonAscii`

NonAscii = 5

The name contains an octet above 127.

`InvalidCharacter`

InvalidCharacter = 6

A label contains an octet outside ASCII letters, digits and hyphens.

`EdgeHyphen`

EdgeHyphen = 7

A label starts or ends with a hyphen.

`TrailingDot`

TrailingDot = 8

The name ends with a dot.

`WildcardReference`

WildcardReference = 9

A reference contains an asterisk.

`NumericFinalLabel`

NumericFinalLabel = 10

The final label contains decimal digits only.

`MissingWildcardSuffix`

MissingWildcardSuffix = 11

A wildcard name has no suffix.

`CertificateIdentityError`

pub enum CertificateIdentityError

An invalid SAN descriptor form or binary address size.

`InvalidIpLength`

InvalidIpLength = 0

An IP SAN has neither four nor sixteen octets.

`WrongGeneralNameTag`

WrongGeneralNameTag = 1

An Other descriptor uses tag two, seven, or a number above eight.

`LimitKind`

pub enum LimitKind

The exhausted matcher budget.

`SanCount`

SanCount = 0

The total descriptor count exceeds the configured budget.

`SanBytes`

SanBytes = 1

The sum of payload lengths exceeds the configured budget.

`IdentityError`

pub union IdentityError

An identity failure that is independent of certificate path trust.

`MalformedReference`

IdentityError.MalformedReference { reason: NameError }: IdentityError

The reference violates DNS admission rules.

Field `reason`

pub reason: NameError

The failed rule.

`MalformedCertificateStructure`

IdentityError.MalformedCertificateStructure { reason: CertificateStructureError }: IdentityError

The complete SAN structure is malformed.

Field `reason`

pub reason: CertificateStructureError

The failed rule.

`MalformedCertificateName`

IdentityError.MalformedCertificateName { index: usize, reason: NameError }: IdentityError

A DNS SAN violates name admission rules.

Field `index`

pub index: usize

The original zero-based SAN index.

Field `reason`

pub reason: NameError

The failed rule.

`MalformedCertificateIdentity`

IdentityError.MalformedCertificateIdentity { index: usize, reason: CertificateIdentityError }: IdentityError

A SAN descriptor has an invalid form.

Field `index`

pub index: usize

The original zero-based SAN index.

Field `reason`

pub reason: CertificateIdentityError

The failed rule.

`Unsupported`

IdentityError.Unsupported { form: UnsupportedForm }: IdentityError

An explicitly unsupported reference form.

Field `form`

pub form: UnsupportedForm

The unsupported reference form.

`LimitExceeded`

IdentityError.LimitExceeded { kind: LimitKind }: IdentityError

A count or byte budget was exceeded.

Field `kind`

pub kind: LimitKind

The exhausted resource budget.

`NoMatch`

IdentityError.NoMatch: IdentityError

No eligible SAN matches the reference.

`IdentityLimits`

pub struct IdentityLimits

Inclusive SAN budgets; zero allows none of the corresponding resource.

Field `maxSanCount`

pub maxSanCount: usize

Maximum number of descriptors, including ignored and unsupported forms.

Field `maxSanBytes`

pub maxSanBytes: usize

Maximum sum of all payload lengths, counting each alias occurrence.

Associated function `IdentityLimits.standard`

pub fn standard() -> IdentityLimits

Returns inclusive limits of 256 SAN descriptors and 65536 payload octets.

`IdentityMatch`

pub struct IdentityMatch

The first matching SAN index after validation of the entire SAN set.

Field `sanIndex`

pub sanIndex: usize

The original zero-based index of the first matching SAN.

`HttpsIdentity`

pub struct HttpsIdentity

Pure HTTPS DNS-ID and IP-ID reference construction and verification.

Associated function `HttpsIdentity.exactDnsNameError`

pub fn exactDnsNameError<'life0>(bytes: &'life0 [u8]) -> silk/option.Option<silk/https_identity.NameError>

Returns the shared HTTPS-profile admission error for one exact DNS name, when invalid.

Details

This applies the canonical 253-octet, LDH-label, edge-hyphen, wildcard-free, and nonnumeric-final-label grammar used by HTTPS reference identities.

Associated function `HttpsIdentity.presentedDnsNameError`

pub fn presentedDnsNameError<'life0>(bytes: &'life0 [u8]) -> silk/option.Option<silk/https_identity.NameError>

Returns the shared HTTPS-profile admission error for one presented DNS name, when invalid.

Details

A wildcard is admitted only as the complete leftmost *. label and remains included in the 253-octet total-name bound. All other label policy is identical to exact DNS names.

Associated function `HttpsIdentity.reference`

pub fn reference<'name>(host: silk/https_identity.OriginHost<'name>) -> silk/result.Result<silk/https_identity.ReferenceIdentity<'name>, silk/https_identity.IdentityError>

Creates a reference from the original HTTPS host without allocation or name substitution.

Details

DNS bytes remain borrowed and unchanged. IP arrays become owned network-order addresses. DNS names require 1..253 ASCII octets and 1..63-octet LDH labels without a numeric final label. Errors follow empty name, total length, NUL, non-ASCII, trailing dot, wildcard, then label grammar order. Label checks proceed left to right: empty, length, characters, then edge hyphens. Numeric final labels fail last.

Gotchas

Supply the original origin host before resolution, never an alias, peer name, or resolved address. The caller checks HTTPS and converts IP literals. DNS input rejects brackets, ports, escapes, underscores and Unicode. A-label grammar does not validate Punycode. Explicit IPvFuture, zones, URI-ID and SRV-ID return Unsupported.

Associated function `HttpsIdentity.verify`

pub fn verify<'name, 'cert, 'life2, 'life3>(reference: &'life2 silk/https_identity.ReferenceIdentity<'name>, certificate: &'life3 silk/https_identity.CertificateIdentities<'cert>, limits: IdentityLimits) -> silk/result.Result<silk/https_identity.IdentityMatch, silk/https_identity.IdentityError>

Validates the complete SAN list and returns the first matching DNS-ID or IP-ID index.

Details

Revalidates public references, then checks structure, count, total bytes, and every SAN in order before comparison. DNS matches ignore ASCII case. A whole leftmost wildcard matches one label; invalid wildcard placement is ignored. Other malformed DNS names fail, including non-ASCII before wildcard handling. NUL is checked after invalid wildcard skipping. IP SANs require four or sixteen equal network-order bytes. IPv4 and mapped IPv6 remain distinct. All descriptors consume limits, including aliases and ignored forms. Zero budgets are valid. Errors retain no input borrow. Work is linear in reference bytes, SAN count and payload bytes, with constant temporary storage and no allocation.

Gotchas

A malformed later SAN defeats an earlier match, even if its identity kind differs from the reference. Empty present SANs fail structurally. Absent, unsupported-only and mismatching sets return NoMatch; there is no CN fallback. Success does not validate trust, name constraints, signatures, time, or the TLS handshake.

Implementation `Copy for silk/https_identity.OriginHost<'a>`

impl Copy for silk/https_identity.OriginHost<'a>

Implementation `Copy for silk/https_identity.ReferenceIdentity<'a>`

impl Copy for silk/https_identity.ReferenceIdentity<'a>

Implementation `Copy for silk/https_identity.PresentedIdentity<'a>`

impl Copy for silk/https_identity.PresentedIdentity<'a>

Implementation `Copy for silk/https_identity.CertificateIdentities<'a>`

impl Copy for silk/https_identity.CertificateIdentities<'a>

Implementation `Copy for IdentityError`

impl Copy for IdentityError

Implementation `Copy for IdentityLimits`

impl Copy for IdentityLimits

Implementation `Copy for IdentityMatch`

impl Copy for IdentityMatch

silk/https_identity

On this page