hickory_proto/dnssec/
tbs.rs

1// Copyright 2015-2023 Benjamin Fry <benjaminfry@me.com>
2//
3// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
4// https://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
5// https://opensource.org/licenses/MIT>, at your option. This file may not be
6// copied, modified, or distributed except according to those terms.
7
8//! hash functions for DNSSEC operations
9
10use alloc::{borrow::ToOwned, vec::Vec};
11use time::OffsetDateTime;
12
13use super::Algorithm;
14use crate::{
15    error::{ProtoError, ProtoResult},
16    rr::{DNSClass, Name, Record, RecordSet, RecordType, SerialNumber},
17    serialize::binary::{BinEncodable, BinEncoder, EncodeMode},
18};
19
20use super::{
21    SigSigner,
22    rdata::{RRSIG, SIG, sig},
23};
24
25/// Data To Be Signed.
26pub struct TBS(Vec<u8>);
27
28impl TBS {
29    /// Returns the to-be-signed serialization of the given record set using the information
30    /// provided from the RRSIG record.
31    ///
32    /// # Arguments
33    ///
34    /// * `rrsig` - SIG or RRSIG record, which was produced from the RRSet
35    /// * `records` - RRSet records to sign with the information in the `rrsig`
36    ///
37    /// # Return
38    ///
39    /// binary hash of the RRSet with the information from the RRSIG record
40    pub fn from_rrsig<'a>(
41        rrsig: &Record<RRSIG>,
42        records: impl Iterator<Item = &'a Record>,
43    ) -> ProtoResult<Self> {
44        Self::from_sig(rrsig.name(), rrsig.dns_class(), rrsig.data(), records)
45    }
46
47    /// Returns the to-be-signed serialization of the given record set using the information
48    /// provided from the SIG record.
49    ///
50    /// # Arguments
51    ///
52    /// * `name` - labels of the record to sign
53    /// * `dns_class` - DNSClass of the RRSet, i.e. IN
54    /// * `sig` - SIG or RRSIG record, which was produced from the RRSet
55    /// * `records` - RRSet records to sign with the information in the `rrsig`
56    ///
57    /// # Return
58    ///
59    /// binary hash of the RRSet with the information from the RRSIG record
60    pub fn from_sig<'a>(
61        name: &Name,
62        dns_class: DNSClass,
63        sig: &SIG,
64        records: impl Iterator<Item = &'a Record>,
65    ) -> ProtoResult<Self> {
66        Self::new(
67            name,
68            dns_class,
69            sig.num_labels(),
70            sig.type_covered(),
71            sig.algorithm(),
72            sig.original_ttl(),
73            sig.sig_expiration(),
74            sig.sig_inception(),
75            sig.key_tag(),
76            sig.signer_name(),
77            records,
78        )
79    }
80
81    /// Returns the to-be-signed serialization of the given record set.
82    ///
83    /// # Arguments
84    ///
85    /// * `rr_set` - RRSet to sign
86    /// * `zone_class` - DNSClass, i.e. IN, of the records
87    /// * `inception` - the date/time when this hashed signature will become valid
88    /// * `expiration` - the date/time when this hashed signature will expire
89    /// * `signer` - the signer to use for signing the RRSet
90    ///
91    /// # Returns
92    ///
93    /// the binary hash of the specified RRSet and associated information
94    pub fn from_rrset(
95        rr_set: &RecordSet,
96        zone_class: DNSClass,
97        inception: OffsetDateTime,
98        expiration: OffsetDateTime,
99        signer: &SigSigner,
100    ) -> ProtoResult<Self> {
101        Self::new(
102            rr_set.name(),
103            zone_class,
104            rr_set.name().num_labels(),
105            rr_set.record_type(),
106            signer.key().algorithm(),
107            rr_set.ttl(),
108            SerialNumber(expiration.unix_timestamp() as u32),
109            SerialNumber(inception.unix_timestamp() as u32),
110            signer.calculate_key_tag()?,
111            signer.signer_name(),
112            rr_set.records_without_rrsigs(),
113        )
114    }
115
116    /// Returns the to-be-signed serialization of the given record set.
117    ///
118    /// # Arguments
119    ///
120    /// * `name` - RRset record name
121    /// * `dns_class` - DNSClass, i.e. IN, of the records
122    /// * `num_labels` - number of labels in the name, needed to deal with `*.example.com`
123    /// * `type_covered` - RecordType of the RRSet being hashed
124    /// * `algorithm` - The Algorithm type used for the hashing
125    /// * `original_ttl` - Original TTL is the TTL as specified in the SOA zones RRSet associated record
126    /// * `sig_expiration` - the epoch seconds of when this hashed signature will expire
127    /// * `key_inception` - the epoch seconds of when this hashed signature will be valid
128    /// * `signer_name` - label of the entity responsible for signing this hash
129    /// * `records` - RRSet to hash
130    ///
131    /// # Returns
132    ///
133    /// the binary hash of the specified RRSet and associated information
134    #[allow(clippy::too_many_arguments)]
135    fn new<'a>(
136        name: &Name,
137        dns_class: DNSClass,
138        num_labels: u8,
139        type_covered: RecordType,
140        algorithm: Algorithm,
141        original_ttl: u32,
142        sig_expiration: SerialNumber,
143        sig_inception: SerialNumber,
144        key_tag: u16,
145        signer_name: &Name,
146        records: impl Iterator<Item = &'a Record>,
147    ) -> ProtoResult<Self> {
148        // TODO: change this to a BTreeSet so that it's preordered, no sort necessary
149        let mut rrset: Vec<&Record> = Vec::new();
150
151        // collect only the records for this rrset
152        for record in records {
153            if dns_class == record.dns_class()
154                && type_covered == record.record_type()
155                && name == record.name()
156            {
157                rrset.push(record);
158            }
159        }
160
161        // put records in canonical order
162        rrset.sort();
163
164        let name = determine_name(name, num_labels)?;
165
166        // TODO: rather than buffering here, use the Signer/Verifier? might mean fewer allocations...
167        let mut buf: Vec<u8> = Vec::new();
168
169        {
170            let mut encoder: BinEncoder<'_> = BinEncoder::new(&mut buf);
171            encoder.set_canonical_names(true);
172
173            //          signed_data = RRSIG_RDATA | RR(1) | RR(2)...  where
174            //
175            //             "|" denotes concatenation
176            //
177            //             RRSIG_RDATA is the wire format of the RRSIG RDATA fields
178            //                with the Signature field excluded and the Signer's Name
179            //                in canonical form.
180            sig::emit_pre_sig(
181                &mut encoder,
182                type_covered,
183                algorithm,
184                name.num_labels(),
185                original_ttl,
186                sig_expiration,
187                sig_inception,
188                key_tag,
189                signer_name,
190            )?;
191
192            // construct the rrset signing data
193            for record in rrset {
194                //             RR(i) = name | type | class | OrigTTL | RDATA length | RDATA
195                //
196                //                name is calculated according to the function in the RFC 4035
197                name.to_lowercase().emit_as_canonical(&mut encoder, true)?;
198                //
199                //                type is the RRset type and all RRs in the class
200                type_covered.emit(&mut encoder)?;
201                //
202                //                class is the RRset's class
203                dns_class.emit(&mut encoder)?;
204                //
205                //                OrigTTL is the value from the RRSIG Original TTL field
206                encoder.emit_u32(original_ttl)?;
207                //
208                //                RDATA length
209                let rdata_length_place = encoder.place::<u16>()?;
210                //
211                //                All names in the RDATA field are in canonical form (set above)
212                record.data().emit(&mut encoder)?;
213
214                let length = u16::try_from(encoder.len_since_place(&rdata_length_place))
215                    .map_err(|_| ProtoError::from("RDATA length exceeds u16::MAX"))?;
216                rdata_length_place.replace(&mut encoder, length)?;
217            }
218        }
219
220        Ok(Self(buf))
221    }
222}
223
224impl<'a> From<&'a [u8]> for TBS {
225    fn from(slice: &'a [u8]) -> Self {
226        Self(slice.to_owned())
227    }
228}
229
230impl AsRef<[u8]> for TBS {
231    fn as_ref(&self) -> &[u8] {
232        self.0.as_ref()
233    }
234}
235
236/// Returns the to-be-signed serialization of the given message.
237pub fn message_tbs<M: BinEncodable>(message: &M, pre_sig0: &SIG) -> ProtoResult<TBS> {
238    // TODO: should perform the serialization and sign block by block to reduce the max memory
239    //  usage, though at 4k max, this is probably unnecessary... For AXFR and large zones, it's
240    //  more important
241    let mut buf: Vec<u8> = Vec::with_capacity(512);
242    let mut buf2: Vec<u8> = Vec::with_capacity(512);
243
244    {
245        let mut encoder: BinEncoder<'_> = BinEncoder::with_mode(&mut buf, EncodeMode::Normal);
246        sig::emit_pre_sig(
247            &mut encoder,
248            pre_sig0.type_covered(),
249            pre_sig0.algorithm(),
250            pre_sig0.num_labels(),
251            pre_sig0.original_ttl(),
252            pre_sig0.sig_expiration(),
253            pre_sig0.sig_inception(),
254            pre_sig0.key_tag(),
255            pre_sig0.signer_name(),
256        )?;
257        // need a separate encoder here, as the encoding references absolute positions
258        // inside the buffer. If the buffer already contains the sig0 RDATA, offsets
259        // are wrong and the signature won't match.
260        let mut encoder2: BinEncoder<'_> = BinEncoder::with_mode(&mut buf2, EncodeMode::Signing);
261        message.emit(&mut encoder2).unwrap(); // coding error if this panics (i think?)
262    }
263
264    buf.append(&mut buf2);
265
266    Ok(TBS(buf))
267}
268
269/// [RFC 4035](https://tools.ietf.org/html/rfc4035), DNSSEC Protocol Modifications, March 2005
270///
271/// ```text
272///
273/// 5.3.2.  Reconstructing the Signed Data
274///             ...
275///             To calculate the name:
276///                let rrsig_labels = the value of the RRSIG Labels field
277///
278///                let fqdn = RRset's fully qualified domain name in
279///                                canonical form
280///
281///                let fqdn_labels = Label count of the fqdn above.
282///
283///                if rrsig_labels = fqdn_labels,
284///                    name = fqdn
285///
286///                if rrsig_labels < fqdn_labels,
287///                   name = "*." | the rightmost rrsig_label labels of the
288///                                 fqdn
289///
290///                if rrsig_labels > fqdn_labels
291///                   the RRSIG RR did not pass the necessary validation
292///                   checks and MUST NOT be used to authenticate this
293///                   RRset.
294///
295///    The canonical forms for names and RRsets are defined in [RFC4034].
296/// ```
297pub fn determine_name(name: &Name, num_labels: u8) -> Result<Name, ProtoError> {
298    //             To calculate the name:
299    //                let rrsig_labels = the value of the RRSIG Labels field
300    //
301    //                let fqdn = RRset's fully qualified domain name in
302    //                                canonical form
303    //
304    //                let fqdn_labels = Label count of the fqdn above.
305    let fqdn_labels = name.num_labels();
306    //                if rrsig_labels = fqdn_labels,
307    //                    name = fqdn
308
309    if fqdn_labels == num_labels {
310        return Ok(name.clone());
311    }
312    //                if rrsig_labels < fqdn_labels,
313    //                   name = "*." | the rightmost rrsig_label labels of the
314    //                                 fqdn
315    if num_labels < fqdn_labels {
316        let mut star_name: Name = Name::from_labels(vec![b"*" as &[u8]]).unwrap();
317        let rightmost = name.trim_to(num_labels as usize);
318        if !rightmost.is_root() {
319            star_name = star_name.append_name(&rightmost)?;
320            return Ok(star_name);
321        }
322        return Ok(star_name);
323    }
324    //
325    //                if rrsig_labels > fqdn_labels
326    //                   the RRSIG RR did not pass the necessary validation
327    //                   checks and MUST NOT be used to authenticate this
328    //                   RRset.
329
330    Err(format!("could not determine name from {name}").into())
331}
hickory_proto/dnssec/tbs.rs

hickory_proto/dnssec/
tbs.rs
