1#![forbid(unsafe_code)]
9#![allow(
10 clippy::doc_markdown,
11 clippy::missing_errors_doc,
12 clippy::module_name_repetitions,
13 reason = "HNS and DNS protocol names are intentional"
14)]
15
16use std::io::{Read, Write};
17use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, TcpStream, UdpSocket};
18use std::sync::Arc;
19use std::sync::atomic::{AtomicBool, Ordering};
20use std::time::Duration;
21
22use hns_covenants::hash_name;
23use hns_dns_wire::{Message, ParseLimits, Query};
24use hns_header_consensus::Network;
25use hns_light_chain::{HnsAnchor, HnsResourceRecord, ResourceName, VerifiedHnsResource};
26use hns_primitives::NameHash;
27use thiserror::Error;
28
29pub const DNS_PORT: u16 = 53;
31pub const MAX_AUTHORITY_ENDPOINTS: usize = 64;
33
34#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
36pub enum AuthorityPortPolicy {
37 #[default]
39 StandardDns,
40 RegtestFixture(u16),
42}
43
44#[derive(Clone, Copy, Debug, Eq, PartialEq)]
46pub struct TransportLimits {
47 pub timeout: Duration,
49 pub max_query_bytes: usize,
51 pub max_response_bytes: usize,
53}
54
55impl Default for TransportLimits {
56 fn default() -> Self {
57 Self {
58 timeout: Duration::from_secs(5),
59 max_query_bytes: 1_232,
60 max_response_bytes: usize::from(u16::MAX),
61 }
62 }
63}
64
65impl TransportLimits {
66 fn validate(self) -> Result<Self, TransportError> {
67 if self.timeout.is_zero()
68 || self.timeout > Duration::from_secs(60)
69 || self.max_query_bytes == 0
70 || self.max_query_bytes > usize::from(u16::MAX)
71 || self.max_response_bytes < 12
72 || self.max_response_bytes > usize::from(u16::MAX)
73 {
74 return Err(TransportError::InvalidLimits);
75 }
76 Ok(self)
77 }
78}
79
80#[derive(Clone, Debug, Default)]
82pub struct CancellationToken {
83 cancelled: Arc<AtomicBool>,
84}
85
86impl CancellationToken {
87 pub fn cancel(&self) {
89 self.cancelled.store(true, Ordering::Release);
90 }
91
92 #[must_use]
94 pub fn is_cancelled(&self) -> bool {
95 self.cancelled.load(Ordering::Acquire)
96 }
97
98 fn check(&self) -> Result<(), TransportError> {
99 if self.is_cancelled() {
100 Err(TransportError::Cancelled)
101 } else {
102 Ok(())
103 }
104 }
105}
106
107#[derive(Clone, Copy, Debug, Eq, PartialEq)]
109pub struct AuthoritativeEndpoint {
110 address: SocketAddr,
111 anchor: HnsAnchor,
112 name_hash: NameHash,
113}
114
115impl AuthoritativeEndpoint {
116 #[must_use]
118 pub const fn address(self) -> SocketAddr {
119 self.address
120 }
121
122 #[must_use]
124 pub const fn anchor(self) -> HnsAnchor {
125 self.anchor
126 }
127
128 #[must_use]
130 pub const fn name_hash(self) -> NameHash {
131 self.name_hash
132 }
133}
134
135#[derive(Clone, Debug, Eq, PartialEq)]
137pub struct AuthoritativeSet {
138 endpoints: Vec<AuthoritativeEndpoint>,
139 anchor: HnsAnchor,
140}
141
142impl AuthoritativeSet {
143 pub fn from_verified_resource(
145 resource: &VerifiedHnsResource,
146 port_policy: AuthorityPortPolicy,
147 ) -> Result<Self, TransportError> {
148 let port = match port_policy {
149 AuthorityPortPolicy::StandardDns => DNS_PORT,
150 AuthorityPortPolicy::RegtestFixture(port) => {
151 if resource.anchor().network() != Network::Regtest || port == 0 || port == DNS_PORT
152 {
153 return Err(TransportError::InvalidRegtestFixture);
154 }
155 port
156 }
157 };
158 let mut addresses = Vec::new();
159 for record in resource.resource().records() {
160 let address = match record {
161 HnsResourceRecord::Glue4 { name, address }
162 if in_bailiwick(name, resource.name()) =>
163 {
164 Some(IpAddr::V4(*address))
165 }
166 HnsResourceRecord::Glue6 { name, address }
167 if in_bailiwick(name, resource.name()) =>
168 {
169 Some(IpAddr::V6(*address))
170 }
171 HnsResourceRecord::Synth4(address) => Some(IpAddr::V4(*address)),
172 HnsResourceRecord::Synth6(address) => Some(IpAddr::V6(*address)),
173 _ => None,
174 };
175 let Some(address) = address else {
176 continue;
177 };
178 let permitted = match port_policy {
179 AuthorityPortPolicy::RegtestFixture(_) => address.is_loopback(),
180 AuthorityPortPolicy::StandardDns
181 if matches!(
182 resource.anchor().network(),
183 Network::Mainnet | Network::Testnet
184 ) =>
185 {
186 is_globally_routable(address)
187 }
188 AuthorityPortPolicy::StandardDns => {
189 !address.is_unspecified() && !address.is_multicast()
190 }
191 };
192 if permitted && !addresses.contains(&address) {
193 if addresses.len() >= MAX_AUTHORITY_ENDPOINTS {
194 return Err(TransportError::EndpointLimit);
195 }
196 addresses.push(address);
197 }
198 }
199 if addresses.is_empty() {
200 return Err(TransportError::NoPermittedEndpoint);
201 }
202 let anchor = resource.anchor();
203 Ok(Self {
204 endpoints: addresses
205 .into_iter()
206 .map(|address| AuthoritativeEndpoint {
207 address: SocketAddr::new(address, port),
208 anchor,
209 name_hash: resource.name_hash(),
210 })
211 .collect(),
212 anchor,
213 })
214 }
215
216 #[must_use]
218 pub const fn anchor(&self) -> HnsAnchor {
219 self.anchor
220 }
221
222 #[must_use]
224 pub fn endpoints(&self) -> &[AuthoritativeEndpoint] {
225 &self.endpoints
226 }
227}
228
229#[derive(Clone, Copy, Debug, Eq, PartialEq)]
231pub struct DirectDnsTransport {
232 limits: TransportLimits,
233}
234
235impl DirectDnsTransport {
236 pub fn new(limits: TransportLimits) -> Result<Self, TransportError> {
238 Ok(Self {
239 limits: limits.validate()?,
240 })
241 }
242
243 pub fn exchange_udp(
245 &self,
246 endpoint: AuthoritativeEndpoint,
247 query: &Query,
248 cancellation: &CancellationToken,
249 now: u64,
250 ) -> Result<Message, TransportError> {
251 authorize(endpoint, query, now)?;
252 cancellation.check()?;
253 let query_bytes = query.encode(self.limits.max_query_bytes)?;
254 let bind_address = match endpoint.address.ip() {
255 IpAddr::V4(_) => SocketAddr::new(IpAddr::V4(Ipv4Addr::UNSPECIFIED), 0),
256 IpAddr::V6(_) => SocketAddr::new(IpAddr::V6(Ipv6Addr::UNSPECIFIED), 0),
257 };
258 let socket = UdpSocket::bind(bind_address)?;
259 socket.set_read_timeout(Some(self.limits.timeout))?;
260 socket.set_write_timeout(Some(self.limits.timeout))?;
261 socket.connect(endpoint.address)?;
262 cancellation.check()?;
263 if socket.send(&query_bytes)? != query_bytes.len() {
264 return Err(TransportError::ShortWrite);
265 }
266 let mut response = vec![0_u8; self.limits.max_response_bytes.saturating_add(1)];
267 let received = socket.recv(&mut response)?;
268 cancellation.check()?;
269 if received == 0 || received > self.limits.max_response_bytes {
270 return Err(TransportError::ResponseLimit);
271 }
272 response.truncate(received);
273 parse_correlated(query, &response, self.limits.max_response_bytes)
274 }
275
276 pub fn exchange_tcp(
278 &self,
279 endpoint: AuthoritativeEndpoint,
280 query: &Query,
281 cancellation: &CancellationToken,
282 now: u64,
283 ) -> Result<Message, TransportError> {
284 authorize(endpoint, query, now)?;
285 cancellation.check()?;
286 let query_bytes = query.encode(self.limits.max_query_bytes)?;
287 let query_length =
288 u16::try_from(query_bytes.len()).map_err(|_| TransportError::QueryLimit)?;
289 let mut stream = TcpStream::connect_timeout(&endpoint.address, self.limits.timeout)?;
290 stream.set_read_timeout(Some(self.limits.timeout))?;
291 stream.set_write_timeout(Some(self.limits.timeout))?;
292 cancellation.check()?;
293 stream.write_all(&query_length.to_be_bytes())?;
294 stream.write_all(&query_bytes)?;
295 stream.flush()?;
296 let mut length = [0_u8; 2];
297 stream.read_exact(&mut length)?;
298 let response_length = usize::from(u16::from_be_bytes(length));
299 if response_length == 0 || response_length > self.limits.max_response_bytes {
300 return Err(TransportError::ResponseLimit);
301 }
302 let mut response = vec![0_u8; response_length];
303 stream.read_exact(&mut response)?;
304 cancellation.check()?;
305 parse_correlated(query, &response, self.limits.max_response_bytes)
306 }
307
308 #[must_use]
310 pub const fn limits(self) -> TransportLimits {
311 self.limits
312 }
313}
314
315fn parse_correlated(
316 query: &Query,
317 response: &[u8],
318 maximum: usize,
319) -> Result<Message, TransportError> {
320 let mut limits = ParseLimits::requester();
321 limits.max_message_len = maximum;
322 let message = Message::parse_with_limits(response, limits)?;
323 query.correlate(&message)?;
324 Ok(message)
325}
326
327fn authorize(
328 endpoint: AuthoritativeEndpoint,
329 query: &Query,
330 now: u64,
331) -> Result<(), TransportError> {
332 if now < endpoint.anchor.validated_at().get() || now > endpoint.anchor.valid_until().get() {
333 return Err(TransportError::StaleAnchor);
334 }
335 let tld = query
336 .question
337 .name
338 .labels()
339 .last()
340 .ok_or(TransportError::QueryOutsideAuthority)?;
341 if hash_name(tld)? != endpoint.name_hash {
342 return Err(TransportError::QueryOutsideAuthority);
343 }
344 Ok(())
345}
346
347fn in_bailiwick(name: &ResourceName, tld: &[u8]) -> bool {
348 name.labels().last().is_some_and(|label| label == tld)
349}
350
351fn is_globally_routable(address: IpAddr) -> bool {
352 match address {
353 IpAddr::V4(address) => is_global_v4(address),
354 IpAddr::V6(address) => {
355 if let Some(mapped) = address.to_ipv4_mapped() {
356 return is_global_v4(mapped);
357 }
358 let segments = address.segments();
359 !(address.is_unspecified()
360 || address.is_loopback()
361 || address.is_multicast()
362 || segments[0] & 0xfe00 == 0xfc00
363 || segments[0] & 0xffc0 == 0xfe80
364 || segments[0] == 0x2001 && segments[1] == 0x0db8)
365 }
366 }
367}
368
369fn is_global_v4(address: Ipv4Addr) -> bool {
370 let octets = address.octets();
371 !address.is_unspecified()
372 && !address.is_loopback()
373 && !address.is_private()
374 && !address.is_link_local()
375 && !address.is_multicast()
376 && !address.is_broadcast()
377 && !address.is_documentation()
378 && !(octets[0] == 100 && (64..=127).contains(&octets[1]))
379 && !(octets[0] == 192 && octets[1] == 0 && octets[2] == 0)
380 && !(octets[0] == 198 && matches!(octets[1], 18 | 19))
381 && octets[0] < 240
382}
383
384#[derive(Debug, Error)]
386#[non_exhaustive]
387pub enum TransportError {
388 #[error("DNS wire failure: {0}")]
390 Wire(#[from] hns_dns_wire::Error),
391 #[error("direct DNS I/O failure: {0}")]
393 Io(#[from] std::io::Error),
394 #[error("invalid direct DNS transport limits")]
396 InvalidLimits,
397 #[error("invalid nonstandard regtest DNS fixture")]
399 InvalidRegtestFixture,
400 #[error("authoritative endpoint bound exceeded")]
402 EndpointLimit,
403 #[error("verified HNS resource has no permitted direct endpoint")]
405 NoPermittedEndpoint,
406 #[error("DNS query exceeds its bound")]
408 QueryLimit,
409 #[error("DNS response exceeds its bound")]
411 ResponseLimit,
412 #[error("short DNS datagram write")]
414 ShortWrite,
415 #[error("direct DNS request cancelled")]
417 Cancelled,
418 #[error("authoritative endpoint Handshake anchor is stale")]
420 StaleAnchor,
421 #[error("DNS query is outside the endpoint's verified HNS authority")]
423 QueryOutsideAuthority,
424 #[error("invalid Handshake TLD in DNS query: {0}")]
426 Covenant(#[from] hns_covenants::CovenantError),
427}
428
429#[cfg(test)]
430#[allow(
431 clippy::unwrap_used,
432 reason = "tests fail immediately on invalid local network fixtures"
433)]
434mod tests {
435 use std::net::{TcpListener, UdpSocket};
436 use std::thread;
437
438 use blake2::Blake2bVar;
439 use blake2::digest::{Update, VariableOutput};
440 use hns_dns_wire::{Flags, Header as DnsHeader, Name, Question, RecordType};
441 use hns_header_consensus::Header;
442 use hns_light_chain::{ChainLimits, CurrencyPolicy, LightChain};
443 use hns_primitives::{BlockTime, Chainwork, Height, TreeRoot};
444
445 use super::*;
446
447 fn blake2b_256(parts: &[&[u8]]) -> [u8; 32] {
448 let mut hasher = Blake2bVar::new(32).unwrap();
449 for part in parts {
450 hasher.update(part);
451 }
452 let mut output = [0_u8; 32];
453 hasher.finalize_variable(&mut output).unwrap();
454 output
455 }
456
457 fn verified_resource(port: u16) -> (VerifiedHnsResource, AuthoritativeSet) {
458 let mut resource = vec![0, 2, 2, b'n', b's', 5];
459 resource.extend_from_slice(b"alpha");
460 resource.push(0);
461 resource.extend_from_slice(&Ipv4Addr::LOCALHOST.octets());
462 let mut state = Vec::new();
463 state.push(5);
464 state.extend_from_slice(b"alpha");
465 state.extend_from_slice(&u16::try_from(resource.len()).unwrap().to_le_bytes());
466 state.extend_from_slice(&resource);
467 state.extend_from_slice(&1_u32.to_le_bytes());
468 state.extend_from_slice(&1_u32.to_le_bytes());
469 state.extend_from_slice(&0_u16.to_le_bytes());
470 let key = hns_covenants::hash_name(b"alpha").unwrap();
471 let value_hash = blake2b_256(&[&state]);
472 let tree_root = TreeRoot::new(blake2b_256(&[&[0], key.as_bytes(), &value_hash]));
473 let mut proof = Vec::new();
474 proof.extend_from_slice(&0xc000_u16.to_le_bytes());
475 proof.extend_from_slice(&0_u16.to_le_bytes());
476 proof.extend_from_slice(&u16::try_from(state.len()).unwrap().to_le_bytes());
477 proof.extend_from_slice(&state);
478
479 let genesis_time = Network::Regtest.parameters().genesis_time;
480 let now = BlockTime::new(genesis_time.get() + 100);
481 let mut chain =
482 LightChain::from_genesis(Network::Regtest, now, ChainLimits::default()).unwrap();
483 let mut header = Header {
484 time: BlockTime::new(genesis_time.get() + 1),
485 previous_block: chain.tip().hash(),
486 tree_root,
487 bits: Network::Regtest.parameters().pow.bits,
488 ..Header::default()
489 };
490 while !header.verify_pow() {
491 header.nonce = header.nonce.checked_add(1).unwrap();
492 }
493 chain.append(&header, now).unwrap();
494 let current = chain
495 .require_current(CurrencyPolicy {
496 now,
497 maximum_tip_age_seconds: 3_600,
498 minimum_height: Height::new(1),
499 minimum_chainwork: Chainwork::ZERO,
500 })
501 .unwrap();
502 let verified = current.verify_name_resource(b"alpha", &proof).unwrap();
503 let set = AuthoritativeSet::from_verified_resource(
504 &verified,
505 AuthorityPortPolicy::RegtestFixture(port),
506 )
507 .unwrap();
508 (verified, set)
509 }
510
511 fn query() -> Query {
512 Query::new(
513 0x1234,
514 Name::from_ascii("_443._tcp.alpha.").unwrap(),
515 RecordType::Tlsa,
516 )
517 .unwrap()
518 }
519
520 fn endpoint(set: &AuthoritativeSet) -> AuthoritativeEndpoint {
521 set.endpoints().first().copied().unwrap()
522 }
523
524 fn response(query: &Query) -> Vec<u8> {
525 Message {
526 header: DnsHeader {
527 id: query.id,
528 flags: Flags::from_bits(0x8400),
529 question_count: 1,
530 answer_count: 0,
531 authority_count: 0,
532 additional_count: 0,
533 },
534 questions: vec![Question {
535 name: query.question.name.clone(),
536 record_type: query.question.record_type,
537 class: query.question.class,
538 }],
539 answers: Vec::new(),
540 authorities: Vec::new(),
541 additionals: Vec::new(),
542 }
543 .encode(usize::from(u16::MAX))
544 .unwrap()
545 }
546
547 #[test]
548 fn derives_only_in_bailiwick_loopback_regtest_fixture() {
549 let (resource, set) = verified_resource(5_353);
550 assert_eq!(set.endpoints().len(), 1);
551 assert_eq!(
552 endpoint(&set).address(),
553 SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 5_353)
554 );
555 assert_eq!(set.anchor(), resource.anchor());
556 assert!(matches!(
557 AuthoritativeSet::from_verified_resource(
558 &resource,
559 AuthorityPortPolicy::RegtestFixture(DNS_PORT),
560 ),
561 Err(TransportError::InvalidRegtestFixture)
562 ));
563 assert!(!is_globally_routable(IpAddr::V4(Ipv4Addr::LOCALHOST)));
564 assert!(is_globally_routable(IpAddr::V4(Ipv4Addr::new(8, 8, 8, 8))));
565 }
566
567 #[test]
568 fn exchanges_correlated_udp_and_honors_cancellation() {
569 let server = UdpSocket::bind((Ipv4Addr::LOCALHOST, 0)).unwrap();
570 let port = server.local_addr().unwrap().port();
571 let server_thread = thread::spawn(move || {
572 let mut buffer = [0_u8; 1_232];
573 let (length, peer) = server.recv_from(&mut buffer).unwrap();
574 let query =
575 Query::parse(buffer.get(..length).unwrap(), ParseLimits::requester()).unwrap();
576 server.send_to(&response(&query), peer).unwrap();
577 });
578 let (_, set) = verified_resource(port);
579 let transport = DirectDnsTransport::new(TransportLimits {
580 timeout: Duration::from_secs(2),
581 ..TransportLimits::default()
582 })
583 .unwrap();
584 let cancellation = CancellationToken::default();
585 let query = query();
586 let message = transport
587 .exchange_udp(
588 endpoint(&set),
589 &query,
590 &cancellation,
591 endpoint(&set).anchor().validated_at().get(),
592 )
593 .unwrap();
594 assert_eq!(message.header.id, query.id);
595 server_thread.join().unwrap();
596
597 cancellation.cancel();
598 assert!(matches!(
599 transport.exchange_udp(
600 endpoint(&set),
601 &query,
602 &cancellation,
603 endpoint(&set).anchor().validated_at().get(),
604 ),
605 Err(TransportError::Cancelled)
606 ));
607 }
608
609 #[test]
610 fn exchanges_exact_length_delimited_tcp() {
611 let server = TcpListener::bind((Ipv4Addr::LOCALHOST, 0)).unwrap();
612 let port = server.local_addr().unwrap().port();
613 let server_thread = thread::spawn(move || {
614 let (mut stream, _) = server.accept().unwrap();
615 let mut length = [0_u8; 2];
616 stream.read_exact(&mut length).unwrap();
617 let mut bytes = vec![0_u8; usize::from(u16::from_be_bytes(length))];
618 stream.read_exact(&mut bytes).unwrap();
619 let query = Query::parse(&bytes, ParseLimits::requester()).unwrap();
620 let response = response(&query);
621 stream
622 .write_all(&u16::try_from(response.len()).unwrap().to_be_bytes())
623 .unwrap();
624 stream.write_all(&response).unwrap();
625 });
626 let (_, set) = verified_resource(port);
627 let transport = DirectDnsTransport::new(TransportLimits {
628 timeout: Duration::from_secs(2),
629 ..TransportLimits::default()
630 })
631 .unwrap();
632 let query = query();
633 let message = transport
634 .exchange_tcp(
635 endpoint(&set),
636 &query,
637 &CancellationToken::default(),
638 endpoint(&set).anchor().validated_at().get(),
639 )
640 .unwrap();
641 assert_eq!(message.header.id, query.id);
642 server_thread.join().unwrap();
643 }
644
645 #[test]
646 fn limits_fail_before_network_io() {
647 assert!(matches!(
648 DirectDnsTransport::new(TransportLimits {
649 timeout: Duration::ZERO,
650 ..TransportLimits::default()
651 }),
652 Err(TransportError::InvalidLimits)
653 ));
654 let cancellation = CancellationToken::default();
655 cancellation.cancel();
656 let (_, set) = verified_resource(5_353);
657 assert!(matches!(
658 DirectDnsTransport::new(TransportLimits::default())
659 .unwrap()
660 .exchange_tcp(
661 endpoint(&set),
662 &query(),
663 &cancellation,
664 endpoint(&set).anchor().validated_at().get(),
665 ),
666 Err(TransportError::Cancelled)
667 ));
668
669 let transport = DirectDnsTransport::new(TransportLimits::default()).unwrap();
670 let outside = Query::new(
671 1,
672 Name::from_ascii("_443._tcp.beta.").unwrap(),
673 RecordType::Tlsa,
674 )
675 .unwrap();
676 assert!(matches!(
677 transport.exchange_tcp(
678 endpoint(&set),
679 &outside,
680 &CancellationToken::default(),
681 endpoint(&set).anchor().validated_at().get(),
682 ),
683 Err(TransportError::QueryOutsideAuthority)
684 ));
685 assert!(matches!(
686 transport.exchange_tcp(
687 endpoint(&set),
688 &query(),
689 &CancellationToken::default(),
690 endpoint(&set).anchor().valid_until().get() + 1,
691 ),
692 Err(TransportError::StaleAnchor)
693 ));
694 }
695}