TSIG downstream support

crates/api/src/lib.rs

@@ -1,4 +1,4 @@
-use std::collections::HashMap;
+use std::collections::{HashMap, HashSet};
 use std::fmt::{self, Display};
 use std::net::SocketAddr;
 use std::time::{Duration, SystemTime};
@@ -262,14 +262,17 @@ impl fmt::Display for TsigRemoveError {
 #[derive(Deserialize, Serialize, Debug, Clone)]
 pub struct TsigListResult {
     /// The set of TSIG keys known to Cascade plus information about each key.
-    pub tsig_keys: HashMap<TsigKeyName, TsigKeyInfo>,
+    pub tsig_key_info: HashMap<TsigKeyName, TsigKeyInfo>,
 }
 
 /// Information about a single listed TSIG key.
 #[derive(Deserialize, Serialize, Debug, Clone)]
 pub struct TsigKeyInfo {
     /// The set of zones with which this TSIG key is used.
-    pub zones: Vec<ZoneName>,
+    pub zone_names: HashSet<ZoneName>,
+
+    /// The set of policies with which this TSIG key is used.
+    pub policy_names: HashSet<String>,
 }
 
 //----------- ZoneAdd --------------------------------------------------------
@@ -855,7 +858,7 @@ pub struct ServerPolicyInfo {
 
 #[derive(Deserialize, Serialize, Debug, Clone)]
 pub struct OutboundPolicyInfo {
-    pub accept_xfr_requests_from: Vec<NameserverCommsPolicyInfo>,
+    pub accept_xfr_from: Vec<NameserverCommsPolicyInfo>,
     pub send_notify_to: Vec<NameserverCommsPolicyInfo>,
 }
 

crates/cli/src/commands/policy.rs

@@ -158,8 +158,8 @@ fn print_policy(p: &PolicyInfo) {
     print_review(&p.signer.review);
     println!("  server:");
     println!("    outbound:");
-    println!("      accept XFR requests from:");
-    print_nameserver_comms_policy(&p.server.outbound.accept_xfr_requests_from);
+    println!("      accept XFR from:");
+    print_nameserver_comms_policy(&p.server.outbound.accept_xfr_from);
     println!("      send NOTIFY to:");
     print_nameserver_comms_policy(&p.server.outbound.send_notify_to);
 }

crates/cli/src/commands/tsig.rs

@@ -170,20 +170,33 @@ impl Tsig {
             TsigCommand::List => {
                 let response: TsigListResult = client.get_json("tsig/").await?;
 
-                for (tsig_key_name, key_info) in response.tsig_keys {
-                    // For each TSIG key also list the zones that it is used
-                    // with.
-                    let zones = key_info
-                        .zones
+                for (tsig_key_name, key_info) in response.tsig_key_info {
+                    // For each TSIG key also list the zones and policies that
+                    // it is used with.
+                    let zone_names = key_info
+                        .zone_names
+                        .iter()
+                        .map(ToString::to_string)
+                        .collect::<Vec<String>>()
+                        .join(", ");
+
+                    let policy_names = key_info
+                        .policy_names
                         .iter()
                         .map(ToString::to_string)
                         .collect::<Vec<String>>()
                         .join(", ");
 
                     println!("{tsig_key_name}");
                     print!("  zones: ");
-                    if !zones.is_empty() {
-                        println!("{zones}");
+                    if !zone_names.is_empty() {
+                        println!("{zone_names}");
+                    } else {
+                        println!("none");
+                    }
+                    print!("  policies: ");
+                    if !policy_names.is_empty() {
+                        println!("{policy_names}");
                     } else {
                         println!("none");
                     }

doc/manual/build/man/cascade-debug.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-DEBUG" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-DEBUG" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-debug \- Debug / troubleshoot Cascade
 .SH SYNOPSIS

doc/manual/build/man/cascade-health.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-HEALTH" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-HEALTH" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-health \- Check the health of Cascade
 .sp

doc/manual/build/man/cascade-hsm.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-HSM" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-HSM" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-hsm \- Manage HSMs
 .SH SYNOPSIS

doc/manual/build/man/cascade-keyset.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-KEYSET" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-KEYSET" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-keyset \- Execute manual key roll or key removal commands
 .SH SYNOPSIS

doc/manual/build/man/cascade-policy.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-POLICY" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-POLICY" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-policy \- Manage policies
 .SH SYNOPSIS

doc/manual/build/man/cascade-status.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-STATUS" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-STATUS" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-status \- Show the status of Cascade
 .sp

doc/manual/build/man/cascade-template.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-TEMPLATE" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-TEMPLATE" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-template \- Print example config or policy files
 .SH SYNOPSIS

doc/manual/build/man/cascade-tsig.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-TSIG" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-TSIG" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-tsig \- Manage TSIG keys
 .sp

doc/manual/build/man/cascade-zone.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE-ZONE" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE-ZONE" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade-zone \- Manage zones
 .SH SYNOPSIS

doc/manual/build/man/cascade.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADE" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADE" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascade \- Cascade CLI
 .SH SYNOPSIS

doc/manual/build/man/cascaded-config.toml.5

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADED-CONFIG.TOML" "5" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADED-CONFIG.TOML" "5" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascaded-config.toml \- Cascade configuration file
 .sp

doc/manual/build/man/cascaded-policy.toml.5

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADED-POLICY.TOML" "5" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADED-POLICY.TOML" "5" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascaded-policy.toml \- Cascade policy file format
 .sp
@@ -348,7 +348,7 @@ key roll.
 Each nameserver must be specified as a string in the form:
 .INDENT 7.0
 .INDENT 3.5
-\fB\(dq<IP>:[<PORT>][^<TSIG_KEY_NAME>]\(dq\fP
+\fB\(dq<IP>[:<PORT>][^<TSIG_KEY_NAME>]\(dq\fP
 .UNINDENT
 .UNINDENT
 .sp
@@ -641,17 +641,29 @@ The \fB[server.outbound]\fP section.
 .INDENT 0.0
 .TP
 .B send\-notify\-to = []
-The set of nameservers to which NOTIFY messages should be sent
+The set of nameservers to which NOTIFY messages should be sent.
+.sp
+If no nameservers are specified, no NOTIFY messages will be sent.
 .sp
 Each nameserver must be specified as a string in the form:
 .sp
-\fI\(dq<IP>:[<PORT>][^<TSIG_KEY_NAME>]\(dq\fP
+\fI\(dq<IP>[:<PORT>][^<TSIG_KEY_NAME>]\(dq\fP
 .sp
 If a TSIG key name is specified, a key by that name must exist in the
 Cascade TSIG key store and will be used to authenticate communication with
 the nameserver.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B accept\-xfr\-from = []
+The set of nameservers to accept zone transfer requests from.
+.sp
+If no nameservers are specified, zone transfer requests will be accepted
+from any nameserver.
+.sp
+Each nameserver must be specified as a string in the form:
 .sp
-If not specified, no NOTIFY messages will be sent.
+\fI\(dq<IP>[^<TSIG_KEY_NAME>]\(dq\fP
 .UNINDENT
 .SH FILES
 .INDENT 0.0

doc/manual/build/man/cascaded.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "CASCADED" "1" "Apr 24, 2026" "0.1.0-alpha5" "Cascade"
+.TH "CASCADED" "1" "Apr 30, 2026" "0.1.0-alpha5" "Cascade"
 .SH NAME
 cascaded \- DNSSEC signer
 .SH SYNOPSIS

doc/manual/source/man/cascaded-policy.toml.rst

@@ -520,17 +520,28 @@ The ``[server.outbound]`` section.
 
 .. option:: send-notify-to = []
 
-   The set of nameservers to which NOTIFY messages should be sent
+   The set of nameservers to which NOTIFY messages should be sent.
+
+   If no nameservers are specified, no NOTIFY messages will be sent.
 
    Each nameserver must be specified as a string in the form:
 
-     `"<IP>[:<PORT>][^<TSIG_KEY_NAME>]"`
+   `"<IP>[:<PORT>][^<TSIG_KEY_NAME>]"`
 
    If a TSIG key name is specified, a key by that name must exist in the
    Cascade TSIG key store and will be used to authenticate communication with
    the nameserver.
 
-   If not specified, no NOTIFY messages will be sent.
+.. option:: accept-xfr-from = []
+
+   The set of nameservers to accept zone transfer requests from.
+
+   If no nameservers are specified, zone transfer requests will be accepted
+   from any nameserver.
+
+   Each nameserver must be specified as a string in the form:
+
+   `"<IP>[^<TSIG_KEY_NAME>]"`
 
 Files
 -----

doc/manual/source/nsd.rst

@@ -94,4 +94,31 @@ authenticate with NSD:
 Using NSD as a secondary to Cascade
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-TODO
+The NSD settings relevant here are:
+  - `allow-notify <https://nsd.docs.nlnetlabs.nl/en/latest/manpages/nsd.conf.html#allow~2>`_
+  - `request-xfr <https://nsd.docs.nlnetlabs.nl/en/latest/manpages/nsd.conf.html#request>`_
+
+To allow NSD to receive and respond to NOTIFY messages from Cascade, and
+to instruct NSD to fetch zone updates via zone transfer from Cascade, these
+settings need to be added to the zone configuration.
+
+For example the following configures NSD for an upstream Cascade server
+running at 192.168.0.2 listening on the default port 4542:
+
+.. code-block::
+
+   zone:
+     name: example.com
+	 allow-notify: 192.168.0.2
+	 request-xfr: 192.168.0.2@4542
+
+To authenticate zone transfer related messages using TSIG you must first have
+added the key to both Cascade and NSD using the same :program:`cascade` :subcmd:`tsig add`
+command and ``key:`` block as shown above.
+
+To instruct Cascade to use TSIG when communicating with a downstream
+nameserver such as NSD you must set the required policy settings and reload
+the policy. The relevant policy settings in Cascade are:
+
+- ``server.outbound.send-notify-to``
+- ``server.outbound.accept-xfr-from```

etc/policy.template.toml

@@ -391,3 +391,17 @@ required = false
 #
 # If not specified, no NOTIFY messages will be sent.
 send-notify-to = []
+
+# The set of nameservers to accept zone transfer requests from.
+# 
+# Each nameserver must be specified as a string in the form:
+#
+# `"<IP>[^<TSIG_KEY_NAME>]"`
+#
+# If a TSIG key name is specified, a key by that name must exist in the
+# Cascade TSIG key store and will be used to authenticate communication with
+# the nameserver.
+#
+# If not specified, zone transfer requests will be accepted from any
+# nameserver.
+accept-xfr-from = []

integration-tests/scripts/manage-test-environment.sh

@@ -289,6 +289,11 @@ remote-control:
   control-enable: yes
   control-interface: "${base_dir}/nsd/nsd.sock"
 
+key:
+  name: "tsig-key"
+  algorithm: hmac-sha256
+  secret: "COzoVsYQmXeXiyq1Quhp0bbVnMyxjPxsaGSoIWR98i0="
+
 pattern:
   name: secondary
   zonefile: "%s.secondary-zone"
@@ -300,6 +305,27 @@ pattern:
 zone:
   name: example.test
   include-pattern: secondary
+
+zone:
+  name: notify-tsig.test
+  zonefile: "notify-tsig.test.secondary-zone"
+  allow-notify: 127.0.0.1 tsig-key
+  request-xfr: AXFR 127.0.0.1@${_cascade_port} NOKEY
+  provide-xfr: 127.0.0.1 NOKEY
+
+zone:
+  name: xfr-tsig.test
+  zonefile: "xfr-tsig.test.secondary-zone"
+  allow-notify: 127.0.0.1 NOKEY
+  request-xfr: AXFR 127.0.0.1@${_cascade_port} tsig-key
+  provide-xfr: 127.0.0.1 NOKEY
+
+zone:
+  name: notify-and-xfr-tsig.test
+  zonefile: "notify-and-xfr-tsig.test.secondary-zone"
+  allow-notify: 127.0.0.1 tsig-key
+  request-xfr: AXFR 127.0.0.1@${_cascade_port} tsig-key
+  provide-xfr: 127.0.0.1 NOKEY
 EOF
 
 tee "${base_dir}/nsd-primary.conf" <<EOF >&2

integration-tests/system-tests.yml

@@ -277,3 +277,27 @@ jobs:
         with:
           log-level: ${{ inputs.log-level }}
           key-source: ${{ matrix.key-source }}
+
+  downstream-tsig:
+    name: Using TSIG with downstream nameservers.
+    runs-on: ubuntu-latest
+    strategy:
+      # max-parallel: 1
+      fail-fast: true
+      matrix:
+        send-notify-to: [ '',  '127.0.0.1:1054', '127.0.0.1:1054^tsig-key' ]
+        accept-xfr-from: [ '', '127.0.0.1', '127.0.0.1^tsig-key' ]
+        downstream-expects-tsig: [ 0, 1 ]
+        downstream-uses-tsig: [ 0, 1 ]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/set-build-profile
+        with:
+          build-profile: ${{ inputs.build-profile }}
+      - uses: ./integration-tests/tests/downstream-tsig
+        with:
+          log-level: ${{ inputs.log-level }}
+          send-notify-to: ${{ matrix.send-notify-to }}
+          accept-xfr-from: ${{ matrix.accept-xfr-from }}
+          downstream-expects-tsig: ${{ matrix.downstream-expects-tsig }}
+          downstream-uses-tsig: ${{ matrix.downstream-uses-tsig }}