Struct Domain

pub struct Domain {
    is_wildcard: bool,
    labels: Vec<Label>,
}

A domain name split into individual labels (not including the root label).

Labels are stored in most-significant-first order, i.e. "www.example.com." would be stored as ["com", "example", "www"]. Labels are stored in their ASCII-encoded form (A-labels for internationalized domain name labels). If the left-most label is equal to '*', is_wildcard is set to true, and the label itself is not stored in labels.

See the library documentation for details about syntax rules for domain names.

Eq vs matches()

The PartialEq / Eq implementation for Domain is equivalent to a string comparison of the domains (e.g. "example.com" == "example.com", but "*.example.com" != "www.example.com"). Domain::matches, on the other hand checks if a reference identifier domain matches a given presented identifier domain (e.g. "example.com".matches("example.com"), and "*.example.com".matches("www.example.com")). Care should be taken to use the appropriate method in each situation.

Fields

is_wildcard: bool

Indicates whether the domain is a wildcard, i.e. that the left-most label is exactly equal to "*"

labels: Vec<Label>

The labels of the domain, in right-to-left (most-significant-first) order, not including the seperators or wildcard label (if any)

Implementations

impl Domain

pub fn reference(input: &str) -> Result<Self, ParseError>

Create a new Domain from a [reference identifier], without allowing wildcards. Note that this function assumes the input is already ACE-encoded and it does not check the validity of A-labels, allowing so-called “fake A-labels” (labels starting with “xn–”, while not being valid punycode).

Errors

Returns a ParseError if the parsing of the domain name fails. See the documentation for the error type for an explanation of possible error variants.

Examples

let example = Domain::reference(&"www.example.com".to_string())?;
assert!(!example.is_wildcard());
assert_eq!(example.labels().len(), 3);
assert_eq!(example.labels()[0].as_ref(), "com");
assert_eq!(example.labels()[1].as_ref(), "example");
assert_eq!(example.labels()[2].as_ref(), "www");

let wildcard = Domain::reference(&"*.example.com".to_string());
assert!(wildcard.is_err());
assert!(matches!(wildcard, Err(ParseError::InvalidChar('*'))));

if let Some(server_name) = client_hello.server_name() {
	let domain = Domain::reference(&server_name).ok()?;
	let certificate = certificates.get(&domain)?;
	Some(certificate.clone())
} else {
	get_default_cert()
}

pub fn presented(input: &str) -> Result<Self, ParseError>

Create a new Domain from a presented identifier, while also checking for wildcards. This function accepts and encodes ASCII labels, A-labels, or U-labels, or a mix of them. If the leftmost label is “*”, then the domain name is considered a wildcard domain, and is_wildcard is set to true. Additionally, this function also accepts absolute domain names (i.e. domain names ending with a ‘.’), which is not allowed in certificates.

Errors

Returns a ParseError if the parsing of the domain name fails. See the documentation for the error type for an explanation of possible error variants.

Examples

let example = Domain::presented(&"www.example.com".to_string())?;
assert!(!example.is_wildcard());
assert_eq!(example.labels().len(), 3);
assert_eq!(example.labels()[0].as_ref(), "com");
assert_eq!(example.labels()[1].as_ref(), "example");
assert_eq!(example.labels()[2].as_ref(), "www");

let idn = Domain::presented(&"παράδειγμα.例子.example.com".to_string())?;
assert!(!idn.is_wildcard());
assert_eq!(idn.labels().len(), 4);
assert_eq!(idn.labels()[0].as_ref(), "com");
assert_eq!(idn.labels()[1].as_ref(), "example");
assert_eq!(idn.labels()[2].as_ref(), "xn--fsqu00a");
assert_eq!(idn.labels()[3].as_ref(), "xn--hxajbheg2az3al");

let wildcard = Domain::presented(&"*.example.com".to_string())?;
assert!(wildcard.is_wildcard());
assert_eq!(wildcard.labels().len(), 2);
assert_eq!(wildcard.labels()[0].as_ref(), "com");
assert_eq!(wildcard.labels()[1].as_ref(), "example");

let wildcard_idn = Domain::presented(&"*.приклад.com".to_string())?;
assert!(wildcard_idn.is_wildcard());
assert_eq!(wildcard_idn.labels().len(), 2);
assert_eq!(wildcard_idn.labels()[0].as_ref(), "com");
assert_eq!(wildcard_idn.labels()[1].as_ref(), "xn--80aikifvh");

for (domain_name, certificate) in tls_config.get_config() {
	let domain = Domain::presented(&domain_name)?;
	let certificate = certificates.set(domain, certificate);
}

pub const fn is_wildcard(&self) -> bool

Whether this Domain represents a wildcard, i.e. the left-most label is “*”. If this is true, this domain matches another non-wildcard domain, if this domain’s labels are a prefix of the other domain’s, and the other domain has exactly one extra label, e.g. if this domain has the labels ["com", "example"], then it would match another domain with labels ["com", "example", "foo"] or ["com", "example", "bar"], but not ["com", "example"] or ["com", "example", "bar", "foo"].

pub fn labels(&self) -> &[Label]

Get the labels of this Domain. The labels are in right-to-left / most-significant-first order, i.e. "www.example.com" would have the labels ["com", "example", "www"]. If this domain is a wildcard domain, the wildcard label is not included in the returned slice. See Domain’s documentation for details.

pub fn matches(&self, presented: &Self) -> Option<bool>

Check whether this Domain matches the given presented identifier. This domain is treated as a reference identifier, and therefore if its is_wildcard property is set, this function returns None.

Trait Implementations

impl Clone for Domain

fn clone(&self) -> Domain

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Domain

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Domain

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Domain

Format a Domain with the given formatter. Use alternate formatting ("{:#}") to encode labels into Unicode; by default internationalized labels are formatted in their ASCII compatible encoding form.

fn fmt(&self, fmt: &mut Formatter<'_>) -> FmtResult

Formats the value using the given formatter.

impl Hash for Domain

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Domain

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Domain

fn eq(&self, other: &Domain) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Domain

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Domain

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Domain

impl StructuralPartialEq for Domain