domain/base/
cmp.rs

Help
1//! Additional traits for comparisions.
2//!
3//! These traits exist because there are several ways of compare domain
4//! names included in composite structures. Normally, names are compared
5//! ignoring ASCII case. This is what `PartialEq` and `PartialOrd` do for
6//! domain names. Consequently, when comparing resource records and record
7//! data that contain domain names, ASCII case should also be ignored.
8//!
9//! However, the canonical form of most resource type’s record data (apart
10//! from a small set of well-known types) requires names to be considered
11//! as they are for comparisons. In order to make it clear when this mode
12//! of comparision is used, this module defines a new trait [`CanonicalOrd`]
13//! that allows types to define how they should be compared in the context of
14//! DNSSEC. The trait is accompanied by `compose_canonical` methods on all
15//! types that have or may have a canonical form.
16
17use core::cmp::Ordering;
18
19/// A trait for the canonical sort order of values.
20///
21/// The canonical sort order is used in DNSSEC when multiple values are
22/// part of constructing or validating a signature. This sort order differs
23/// in some cases from the normal sort order. To avoid confusion, only this
24/// trait should be used when DNSSEC signatures are involved.
25///
26/// Canonical order is defined in [RFC 4034] and clarified in [RFC 6840]. It
27/// is defined for domain names and resource records within an RR set (i.e.,
28/// a set of records with the same owner name, class, and type).
29///
30/// For domain names, canonical order is the same as the ‘normal’ order as
31/// implemented through the `PartialOrd` and `Ord` traits: Labels are compared
32/// from right to left (i.e, starting from the root label) with each pair of
33/// labels compared as octet sequences with ASCII letters lowercased
34/// before comparison.  The `name_cmp` methods of the
35/// [`ToDname`][crate::base::name::ToDname::name_cmp] and
36/// [`ToRelativeDname`][crate::base::name::ToRelativeDname::name_cmp]
37/// traits can be used to implement this canonical order for name types.
38///
39/// Resource records within an RR set are ordered by comparing the canonical
40/// wire-format representation of their record data as octet sequences. The
41/// canonical form differs from the regular form by lower-casing domain names
42/// included in the record data for the record types NS, MD, MF, CNAME, SOA,
43/// MB, MG, MR, PTR, MINFO, MX, RP, AFSDB, RT, SIG, PX, NXT, NAPTR, KX, SRV,
44/// DNAME, A6, and RRSIG. (NSEC is listed in [RFC 4034] but has been withdrawn
45/// by [RFC 6840]). This canonical representation is provided via the
46/// `Compose::compose_canonical` method.
47///
48/// In order to help implementing this trait for record data types, there are
49/// implementations of it for some types that can appear in record data that
50/// sort differently in their composed representation than normally.
51///
52/// Apart from these explicit use cases, the `CanonicalOrd` trait is also
53/// implemented for the `Record` type to allow ordering records of a zone into
54/// RRsets. It does so by ordering by class first, then canonical owner,
55/// record type, and finally canonical record data. The reason for this
56/// somewhat odd ordering is that in this way not only are all records
57/// for the same owner name and class kept together, but also all the records
58/// subordinate to a owner name and class pair (i.e., the records for a zone)
59/// will sort together.
60///
61/// [RFC 4034]: https://tools.ietf.org/html/rfc4034
62/// [RFC 6840]: https://tools.ietf.org/html/rfc6840
63pub trait CanonicalOrd<Rhs: ?Sized = Self> {
64    /// Returns the canonical ordering between `self` and `other`.
65    #[must_use]
66    fn canonical_cmp(&self, other: &Rhs) -> Ordering;
67
68    /// Returns whether `self` is canonically less than `other`.
69    #[inline]
70    #[must_use]
71    fn canonical_lt(&self, other: &Rhs) -> bool {
72        matches!(self.canonical_cmp(other), Ordering::Less)
73    }
74
75    /// Returns whether `self` is canonically less than or equal to `other`.
76    #[inline]
77    #[must_use]
78    fn canonical_le(&self, other: &Rhs) -> bool {
79        matches!(self.canonical_cmp(other), Ordering::Less | Ordering::Equal)
80    }
81
82    /// Returns whether `self` is canonically greater than `other`.
83    #[inline]
84    #[must_use]
85    fn canonical_gt(&self, other: &Rhs) -> bool {
86        matches!(self.canonical_cmp(other), Ordering::Greater)
87    }
88
89    /// Returns whether `self` is canonically greater than or equal to `other`.
90    #[inline]
91    #[must_use]
92    fn canonical_ge(&self, other: &Rhs) -> bool {
93        matches!(
94            self.canonical_cmp(other),
95            Ordering::Greater | Ordering::Equal
96        )
97    }
98}
domain/base/cmp.rs

domain/base/
cmp.rs
