Struct BlocklistZoneHandler 

pub struct BlocklistZoneHandler { /* private fields */ }

Available on crate feature blocklist only.

A conditional zone handler that will resolve queries against one or more block lists and return a forged response. The typical use case will be to use this in a chained configuration before a forwarding or recursive resolver in order to pre-emptively block queries for hosts that are on a block list. Refer to tests/test-data/test_configs/chained_blocklist.toml for an example of this configuration.

The blocklist zone handler also supports the consult interface, which allows a zone handler to review a query/response that has been processed by another zone handler, and, optionally, overwrite that response before returning it to the requestor. There is an example of this configuration in tests/test-data/test_configs/example_consulting_blocklist.toml. The main intended use of this feature is to allow log-only configurations, to allow administrators to see if blocklist domains are being queried. While this can be configured to overwrite responses, it is not recommended to do so - it is both more efficient, and more secure, to allow the blocklist to drop queries pre-emptively, as in the first example.

Implementations

impl BlocklistZoneHandler

pub fn try_from_config( origin: Name, config: BlocklistConfig, base_dir: Option<&Path>, ) -> Result<Self, String>

Read the ZoneHandler for the origin from the specified configuration

pub fn add(&mut self, handle: impl Read) -> Result<(), Error>

Add the contents of a block list to the in-memory cache. This function is normally called from try_from_config, but it can be invoked after the blocklist zone handler is created.

Arguments

• handle - A source implementing std::io::Read that contains the blocklist entries to insert into the in-memory cache.

Return value

Result<(), std::io::Error>

Expected format of blocklist entries

• One entry per line
• Any character after a ‘#’ will be treated as a comment and stripped out.
• Leading wildcard entries are supported when the user has wildcard_match set to true. E.g., ‘*.foo.com’ will match any host in the foo.com domain. Intermediate wildcard matches, such as ‘www.*.com’ are not supported. Note: when wildcard matching is enabled, min_wildcard_depth (default: 2) controls how many static name labels must be present for a wildcard entry to be valid. With the default value of 2, an entry for ‘*.foo.com’ would be accepted, but an entry for ‘*.com’ would not.
• All entries are treated as being fully-qualified. If an entry does not contain a trailing ‘.’, one will be added before insertion into the cache.

Example

use std::{fs::File, net::{Ipv4Addr, Ipv6Addr}, path::Path, str::FromStr, sync::Arc};
use hickory_proto::rr::{LowerName, RecordType, Name};
use hickory_server::{
    store::blocklist::*,
    zone_handler::{LookupControlFlow, LookupOptions, ZoneHandler, ZoneType},
};

#[tokio::main]
async fn main() {
    let config = BlocklistConfig {
        wildcard_match: true,
        min_wildcard_depth: 2,
        lists: vec!["default/blocklist.txt".to_string()],
        sinkhole_ipv4: None,
        sinkhole_ipv6: None,
        block_message: None,
        ttl: 86_400,
        consult_action: BlocklistConsultAction::Disabled,
        log_clients: true,
    };

    let mut blocklist = BlocklistZoneHandler::try_from_config(
        Name::root(),
        config,
        Some(Path::new("../../tests/test-data/test_configs")),
    ).unwrap();

    let handle = File::open("../../tests/test-data/test_configs/default/blocklist2.txt").unwrap();
    if let Err(e) = blocklist.add(handle) {
        panic!("error adding blocklist: {e:?}");
    }

    let origin = blocklist.origin().clone();
    let handler = Arc::new(blocklist) as Arc<dyn ZoneHandler>;

    // In this example, malc0de.com only exists in the blocklist2.txt file we added to the
    // zone handler after instantiating it.  The following simulates a lookup against the
    // blocklist zone handler, and checks for the expected response for a blocklist match.
    use LookupControlFlow::*;
    let Break(Ok(_res)) = handler.lookup(
                            &LowerName::from(Name::from_ascii("malc0de.com.").unwrap()),
                            RecordType::A,
                            None,
                            LookupOptions::default(),
                          ).await else {
        panic!("blocklist zone handler did not return expected match");
    };
}

pub fn entry_count(&self) -> usize

Number of unique blocklist entries currently loaded in memory.

Trait Implementations

impl ZoneHandler for BlocklistZoneHandler

fn lookup<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, name: &'life1 LowerName, rtype: RecordType, request_info: Option<&'life2 RequestInfo<'life3>>, _lookup_options: LookupOptions, ) -> Pin<Box<dyn Future<Output = LookupControlFlow<AuthLookup>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Perform a blocklist lookup. This will return LookupControlFlow::Break(Ok) on a match, or LookupControlFlow::Skip on no match.

fn consult<'life0, 'life1, 'life2, 'life3, 'async_trait>( &'life0 self, name: &'life1 LowerName, rtype: RecordType, request_info: Option<&'life2 RequestInfo<'life3>>, lookup_options: LookupOptions, last_result: LookupControlFlow<AuthLookup>, ) -> Pin<Box<dyn Future<Output = (LookupControlFlow<AuthLookup>, Option<TSigResponseContext>)> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait, 'life2: 'async_trait, 'life3: 'async_trait,

Optionally, perform a blocklist lookup after another zone handler has done a lookup for this query.

fn zone_type(&self) -> ZoneType

What type is this zone

fn axfr_policy(&self) -> AxfrPolicy

Return the policy for determining if AXFR requests are allowed

fn origin(&self) -> &LowerName

Get the origin of this zone, i.e. example.com is the origin for www.example.com

fn search<'life0, 'life1, 'async_trait>( &'life0 self, request: &'life1 Request, lookup_options: LookupOptions, ) -> Pin<Box<dyn Future<Output = (LookupControlFlow<AuthLookup>, Option<TSigResponseContext>)> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Using the specified query, perform a lookup against this zone.

fn zone_transfer<'life0, 'life1, 'async_trait>( &'life0 self, _request: &'life1 Request, _lookup_options: LookupOptions, _now: u64, ) -> Pin<Box<dyn Future<Output = Option<(Result<ZoneTransfer, LookupError>, Option<TSigResponseContext>)>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Returns all records in the zone.

fn nsec_records<'life0, 'life1, 'async_trait>( &'life0 self, _name: &'life1 LowerName, _lookup_options: LookupOptions, ) -> Pin<Box<dyn Future<Output = LookupControlFlow<AuthLookup>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Return the NSEC records based on the given name

fn nsec3_records<'life0, 'life1, 'async_trait>( &'life0 self, _info: Nsec3QueryInfo<'life1>, _lookup_options: LookupOptions, ) -> Pin<Box<dyn Future<Output = LookupControlFlow<AuthLookup>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Available on crate feature __dnssec only.

Return the NSEC3 records based on the information available for a query.

fn nx_proof_kind(&self) -> Option<&NxProofKind>

Available on crate feature __dnssec only.

Returns the kind of non-existence proof used for this zone.

fn metrics_label(&self) -> &'static str

Available on crate feature metrics only.

Returns the zone handler metrics label.

fn can_validate_dnssec(&self) -> bool

Whether the zone handler can perform DNSSEC validation

fn update<'life0, 'life1, 'async_trait>( &'life0 self, _update: &'life1 Request, _now: u64, ) -> Pin<Box<dyn Future<Output = (Result<bool, ResponseCode>, Option<TSigResponseContext>)> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Perform a dynamic update of a zone