From 791282079d1c2ec0af8fa12ed40932ff1e225f2f Mon Sep 17 00:00:00 2001 From: Chris Date: Mon, 11 May 2026 16:18:09 -0400 Subject: [PATCH 01/12] adding documentation for show bgp output I95-61467 --- docs/config_bgp.md | 145 +++++++++++++++++++++++++++++++++++++++++++ docusaurus.config.js | 5 +- 2 files changed, 146 insertions(+), 4 deletions(-) diff --git a/docs/config_bgp.md b/docs/config_bgp.md index 1a5a0f2450..8d1147e59b 100644 --- a/docs/config_bgp.md +++ b/docs/config_bgp.md @@ -1037,3 +1037,148 @@ admin@branchoffice1.seattlesite1 (routing-protocol[type=bgp])# confederation mem admin@branchoffice1.seattlesite1 (routing-protocol[type=bgp])# confederation member-as 2200 admin@branchoffice1.seattlesite1 (routing-protocol[type=bgp])# exit ``` + +## Viewing Filtered BGP Routes + +When an inbound BGP policy rejects prefixes received from a neighbor, those routes do not appear in the BGP table or the FIB. The `filtered-routes` option exposes exactly which prefixes were suppressed by the inbound policy for a given neighbor, making it straightforward to troubleshoot why expected routes are absent from the routing table. + +:::note +This feature is available in SSR version 7.2.0-r1 and above. +::: + +### PCLI + +The `filtered-routes` option is available as a third choice alongside `received-routes` and `advertised-routes` in the `show bgp neighbors` command: + +``` +show bgp neighbors [vrf ] filtered-routes [ipv4 | ipv4-vpn | ipv6 | ipv6-vpn] +``` + +**Examples** + +Display filtered routes for a neighbor in the default VRF using IPv4 unicast (the default address family): + +```text +admin@router1.site1# show bgp neighbors 172.16.3.3 filtered-routes +``` + +Display filtered IPv6 routes for a neighbor in a named VRF: + +```text +admin@router1.site1# show bgp neighbors vrf vrfA fd00:5::3 filtered-routes ipv6 +``` + +When no routes have been filtered, the command returns an empty table. When routes are present, the output format mirrors that of `received-routes` and `advertised-routes`. If the neighbor address is unknown, the VRF does not exist, or the address family is invalid, the PCLI surfaces the underlying vty error string describing the problem. + +### REST API + +A new endpoint mirrors the PCLI functionality: + +``` +GET /api/v1/routing/bgp/neighbors/filtered-routes +``` + +**Query Parameters** + +| Parameter | Required | Default | Description | +|---|---|---|---| +| `neighborAddress` | Yes | — | IP address of the BGP neighbor | +| `vrf` | No | `default` | VRF name | +| `addressFamily` | No | `ipv4` | Address family: `ipv4`, `ipv4-vpn`, `ipv6`, or `ipv6-vpn` | +| `firstIndex` | No | `0` | Zero-based starting index for paginated results | +| `elementCount` | No | all | Maximum number of routes to return (range: 1–5000) | + +:::note +The REST endpoint does not support `vrf all` or `addressFamily all`. Each VRF and address family must be queried individually. +::: + +**Example: IPv4, default VRF** + +```bash +curl --unix-socket /var/run/128technology/speakeasy.sock -i -XGET \ + 'http://localhost/api/v1/routing/bgp/neighbors/filtered-routes?neighborAddress=172.16.3.3&firstIndex=0&elementCount=1' +``` + +Response: + +```json +{ + "bgpTableVersion": 14, + "bgpLocalRouterId": "2.1.1.1", + "defaultLocPrf": 100, + "localAS": 2, + "bgpStatusCodes": { + "suppressed": "s", "damped": "d", "history": "h", + "valid": "*", "best": ">", "multipath": "=", + "internal": "i", "ribFailure": "r", "stale": "S", "removed": "R" + }, + "bgpOriginCodes": { "igp": "i", "egp": "e", "incomplete": "?" }, + "filteredRoutes": [ + { + "prefix": "10.99.1.0/24", + "network": "10.99.1.0/24", + "nextHop": "172.16.3.2", + "metric": 0, + "weight": 0, + "path": "3", + "bgpOriginCode": "?", + "valid": true, + "best": true + } + ], + "totalPrefixCounter": 1, + "filteredPrefixCounter": 0, + "nextEntry": 1 +} +``` + +**Example: IPv6, named VRF** + +```bash +curl --unix-socket /var/run/128technology/speakeasy.sock -i -XGET \ + 'http://localhost/api/v1/routing/bgp/neighbors/filtered-routes?neighborAddress=fd00:5::3&firstIndex=0&elementCount=1&addressFamily=ipv6&vrf=vrfA' +``` + +Response: + +```json +{ + "bgpTableVersion": 1, + "bgpLocalRouterId": "2.1.1.1", + "defaultLocPrf": 100, + "localAS": 2, + "filteredRoutes": [ + { + "prefix": "2001:db8:5::1/128", + "network": "2001:db8:5::1/128", + "nextHopGlobal": "fd00:5::3", + "metric": 0, + "weight": 0, + "path": "3", + "bgpOriginCode": "?", + "valid": true, + "best": true + } + ], + "totalPrefixCounter": 1, + "filteredPrefixCounter": 0, + "nextEntry": 1 +} +``` + +### Troubleshooting + +| Failure | PCLI behavior | REST behavior | +|---|---|---| +| `bgpd` not running | Surfaces vty error string | Returns standard upstream failure with informative status code | +| Unknown neighbor IP, neighbor not in specified VRF/address family | Surfaces vty error string with neighbor details | Returns `200 OK` with a `warning` key in the JSON body | +| Invalid `addressFamily` or `vrf` argument | Surfaces vty error string | Returns `200 OK` with a `warning` key in the JSON body | +| vty call timeout (120 s) | Surfaces timeout error string | Returns `HTTP 400` with timeout exception message | + +PCLI and REST activity is logged in `routingManager.log`. FRR vty-level logs are in `routingEngine.log`. + +### Version History + +| Release | Modification | +|---|---| +| 7.2.0 | Feature introduced. | diff --git a/docusaurus.config.js b/docusaurus.config.js index 1959f84cd3..06ad758ec6 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -7,12 +7,9 @@ module.exports = { organizationName: '128technology', // Usually your GitHub org/user name. projectName: 'docs', // Usually your repo name. onBrokenAnchors: 'throw', + onBrokenMarkdownLinks: 'throw', markdown: { mermaid: true, - hooks: { - onBrokenMarkdownLinks: 'throw', - onBrokenMarkdownImages: 'throw', - }, }, themes: ['@docusaurus/theme-mermaid'], themeConfig: { From fda99575cb04047725685f4dd57448ef194be26e Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 12 May 2026 14:19:34 -0400 Subject: [PATCH 02/12] adding AES-GCM content for 7.2 Swift beta 1. --- docs/config_bgp.md | 2 +- docs/sec_security_policy.md | 51 +++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 1 deletion(-) diff --git a/docs/config_bgp.md b/docs/config_bgp.md index 8d1147e59b..4d96c6df90 100644 --- a/docs/config_bgp.md +++ b/docs/config_bgp.md @@ -1068,7 +1068,7 @@ Display filtered IPv6 routes for a neighbor in a named VRF: admin@router1.site1# show bgp neighbors vrf vrfA fd00:5::3 filtered-routes ipv6 ``` -When no routes have been filtered, the command returns an empty table. When routes are present, the output format mirrors that of `received-routes` and `advertised-routes`. If the neighbor address is unknown, the VRF does not exist, or the address family is invalid, the PCLI surfaces the underlying vty error string describing the problem. +When no routes have been filtered, the command returns an empty table. When routes are present, the output format mirrors that of `received-routes` and `advertised-routes`. If the neighbor address is unknown, the VRF does not exist, or the address family is invalid, the PCLI surfaces the underlying error string describing the problem. ### REST API diff --git a/docs/sec_security_policy.md b/docs/sec_security_policy.md index f667db0a4e..aad92f9b2c 100644 --- a/docs/sec_security_policy.md +++ b/docs/sec_security_policy.md @@ -131,3 +131,54 @@ Retrieving session information... Attributes: Metadata Security Policy: ``` + +## AES-GCM Encryption + +:::note +AES-GCM encryption is available in SSR version 7.2.0 and above. +::: + +### Overview + +The SSR supports **AES-GCM** (Advanced Encryption Standard – Galois/Counter Mode) as an additional encryption option for session traffic. AES-GCM is an Authenticated Encryption with Associated Data (AEAD) cipher, meaning it provides both **confidentiality** and **integrity** protection in a single cryptographic operation, rather than combining a separate cipher and HMAC as with AES-CBC modes. + +AES-GCM is applied per-packet after SSR session encapsulation. Both SSR metadata and session payload are independently protected, and authentication failures cause the packet to be silently discarded. No changes to routing, session establishment, or service policy behavior are introduced by enabling AES-GCM. + +### Behavior And Compatibility + +| Property | Behavior | +|---|---| +| Confidentiality | Per-packet encryption of SSR metadata and payload. | +| Integrity | Authenticated; authentication failure causes immediate packet discard. | +| HMAC settings | Ignored when AES-GCM is selected — authentication is inherent to GCM. | +| Peer compatibility | If the remote peer does not support AES-GCM, the session falls back to the mutually supported cipher according to existing SSR negotiation behavior. | +| Mixed-version fabrics | Supported, provided peers negotiate a mutually supported cipher. | +| Platform requirement | Requires OpenSSL with GCM capability; supported on existing SSR hardware platforms. | + +### Configuring AES-GCM + +AES-GCM is selected by setting the `encryption-cipher` field of a security policy to the appropriate AES-GCM value. The security policy is then applied in the same locations as any other cipher: + +- `service > security-policy` — payload encryption for sessions +- `network-interface > inter-router-security` — metadata decryption on received SVR traffic +- `network-interface > adjacency > inter-router-security` — metadata encryption for SVR traffic sent to a peer +- `router > inter-node-security` — encryption for HA inter-node communication + +``` +configure authority security + encryption-cipher + encrypt true + hmac-mode disabled +``` + +:::note +Because AES-GCM provides built-in authentication, `hmac-mode` should be set to `disabled`. Any HMAC configuration is ignored at runtime when AES-GCM is the selected cipher. +::: + +:::caution +Changing an encryption cipher is a service-impacting event. Existing sessions cannot be re-keyed in-place. Follow the guidance in [Changing A Security Policy](#changing-a-security-policy) and perform the change during a maintenance window. +::: + +### Verifying AES-GCM Is In Use + +After applying the new policy, use `show sessions by-id` to confirm the cipher is active on new sessions. The **Payload Security Policy** and **Metadata Security Policy** fields identify which security policy is applied per flow. Confirm that the policy you configured with AES-GCM is listed for the expected flows. From 76d864cba6ff351462df5338ec3f2d4760efed33 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 13 May 2026 12:03:08 -0400 Subject: [PATCH 03/12] adding pmtu topic for 7.2 --- docs/config_pmtu.mdx | 249 +++++++++++++++++++++++++++++++++++++++++++ sidebars.js | 1 + 2 files changed, 250 insertions(+) create mode 100644 docs/config_pmtu.mdx diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx new file mode 100644 index 0000000000..6ddade8d6d --- /dev/null +++ b/docs/config_pmtu.mdx @@ -0,0 +1,249 @@ +--- +title: Path MTU Discovery Enhancements +sidebar_label: Path MTU Discovery Enhancements +--- + +#### Version History + +| Release | Modification | +| ------- | ------------ | +| 7.2.0 | Feature introduced | + +## Overview + +The SSR performs Path MTU Discovery (PMTUD) along the overlay to determine the correct maximum transmission unit (MTU) for each peer path. By default, this test runs every ten minutes. If a change in the underlay reduces the available path MTU between two SSRs, the new value is not discovered until the next PMTUD cycle. Additionally, existing sessions continue to use the previous MTU value until the next time those sessions are rebuilt. + +Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error—referred to here as a _TooBig_ packet—to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. + +SSR 7.2.0 introduces two complementary enhancements to address these gaps: + +1. **Underlay ICMP reaction** — When the SSR receives a TooBig packet from the underlay, it updates the affected overlay flow and generates a corrected TooBig packet toward the original packet sender, allowing the sender to adjust its segment size. +2. **PMTUD-triggered session refresh** — When a periodic PMTUD cycle discovers a new path MTU, existing sessions that are eligible for flow-move are refreshed to use the new value on the next packet. + +For TCP flows, setting `enforced-mss automatic` on the egress `network-interface` is the recommended complement to these features. It adjusts the TCP MSS advertised at the interface boundary to avoid fragmentation in the first place. See [Configuration](#configuration) for details. + +## How The SSR Reacts to Underlay ICMP TooBig Messages + +The following sequence illustrates what happens when the underlay path MTU changes after a session is already established. + +### Initial State + +```mermaid +sequenceDiagram + participant Client + participant Hub as Hub SSR + participant R1 as Spoke SSR + participant Server + + Client->>Hub: Data (MTU 1500) + Hub->>R1: SVR overlay packet (MTU 1500) + R1->>Server: Data (MTU 1500) + Note over Hub,R1: Underlay MTU = 1500. Session PMTU on both SSRs = 1500. +``` + +The client and server are communicating through two peering SSRs over the overlay. The PMTU is consistent at 1500 across all hops, and both SSRs have applied an MTU of 1500 to the forward flow actions for this session. + +### Underlay MTU Drops — First TooBig Received by Hub + +```mermaid +sequenceDiagram + participant Client + participant Hub as Hub SSR + participant R2 as Underlay Device + participant R1 as Spoke SSR + participant Server + + Note over R2,R1: Underlay MTU between Hub and R2 drops to 1300 + Hub->>R2: SVR packet hub-WAN to spoke-WAN (over 1300 bytes) + R2-->>Hub: ICMP TooBig type 3 code 4, reported MTU = 1300 + Note over Hub: DivertedPacketHandler finds reverse flow. Updates Hub-to-Spoke PMTU to 1300. + Hub-->>Server: New TooBig toward Server + Note over Server: Server adjusts MSS if TCP-capable +``` + +When R2 (an underlay device) cannot forward an oversized packet, it sends a TooBig packet to the Hub's WAN interface. The SSR's `DivertedPacketHandler` processes this message: + +1. It extracts the encapsulated IP header from the TooBig body to identify the affected overlay session. +2. It finds the reverse flow using that header and updates the Hub → Spoke forward flow's PMTU to the value reported by the underlay. +3. It constructs a new TooBig packet directed toward the original packet sender (the Server), so the server's TCP stack can reduce its MSS. + +:::note +The MTU value propagated in the new TooBig packet reflects the underlay-reported value. On paths with encryption, HMAC, FEC, or BFD tunneling overhead, the effective usable MTU will be lower than the raw underlay value. The SSR accounts for these overheads when setting the MSS on forward flow actions. +::: + +## Fabric Fragmentation and Oversize Packet Behavior + +When the PMTU on an overlay (SVR/fabric) path is lower than the MTU of the segment immediately preceding the Hub, packets larger than the PMTU will require fragmentation along the overlay. The SSR always fragments fabric packets when necessary, even when the incoming packet carries the Don't Fragment (DF) bit. This preserves packet delivery but prevents the sender from learning about the smaller path MTU and adjusting its segment size. + +:::note +For TCP traffic, setting `enforced-mss automatic` on the egress `network-interface` is the most reliable way to avoid this scenario. When set, the SSR rewrites the TCP MSS at the interface boundary to match the session MTU (including the path MTU for SVR sessions). This is not the default and must be explicitly configured. +::: + +### Oversize Fabric Packet Behavior + +To allow the sender an opportunity to adjust before fragmenting, you can configure `oversize-fabric-packet-behavior` on either a `network-interface` or a `service-policy`. When enabled, the SSR behavior changes as follows: + +| Setting | Behavior | +| ------- | -------- | +| `false` (default) | Oversized fabric packets are fragmented immediately, matching the current behavior. | +| `true` | The oversized fabric packet is **dropped**, and a TooBig packet is generated toward the sender. This is attempted up to N times per flow. If the sender does not reduce its packet size within those attempts, the SSR falls back to fragmenting. | + +This is a best-effort mechanism. Traffic continues over the overlay (via fragmentation) if the sender does not adjust. + +:::note +Packets that do not carry the DF bit fragment immediately regardless of this setting. Only packets that would otherwise be fragmented on an SVR path are subject to this behavior. +::: + +#### Configuration Location + +`oversize-fabric-packet-behavior` can be configured at two locations, with different trade-offs: + +| Location | Benefit | Consideration | +| -------- | ------- | ------------- | +| `network-interface` | Co-located with `mtu` and `enforced-mss`; applies to all traffic egressing that interface. | Applies to all services on the path, independent of individual service requirements. | +| `service-policy` | Per-service control; different services can have different behaviors. | Applies regardless of which egress interface is selected; a flow-move to a different interface may produce unexpected behavior if the interfaces are not configured consistently. | + +## Configuration + +### Enabling Oversize Fabric Packet Behavior + +#### On a `network-interface` + +``` +config + authority + router + node + device-interface + network-interface + oversize-fabric-packet-behavior true + exit + exit + exit + exit + exit +exit +``` + +#### On a `service-policy` + +``` +config + authority + service-policy + oversize-fabric-packet-behavior true + exit + exit +exit +``` + +### Configuring `enforced-mss` (Recommended for TCP) + +Set `enforced-mss` to `automatic` on egress interfaces to avoid fabric fragmentation for TCP traffic. The SSR calculates the correct MSS from the interface or path MTU for SVR sessions. + +``` +config + authority + router + node + device-interface + network-interface + enforced-mss automatic + exit + exit + exit + exit + exit +exit +``` + +### Configuring PMTUD Interval + +The PMTUD interval (how frequently the SSR probes each overlay path) is configurable at the router level and can be overridden per neighborhood or per adjacency. + +``` +config + authority + router + path-mtu-discovery + enabled true + interval 600 + exit + exit + exit +exit +``` + +| Field | Default | Description | +| ----- | ------- | ----------- | +| `enabled` | `true` | Enables or disables PMTUD for this router. | +| `interval` | `600` | Seconds between PMTUD tests. Valid range: 1–86400. | + +To override the interval for a specific adjacency: + +``` +config + authority + router + node + device-interface + network-interface + adjacency + path-mtu-discovery + enabled true + interval 300 + exit + exit + exit + exit + exit + exit + exit +exit +``` + +### Enabling Session Refresh on PMTU Change + +When a PMTUD cycle discovers a new path MTU, the SSR can automatically refresh existing sessions on that path so they adopt the new MTU value without waiting for a manual rebuild. This requires the affected sessions to be eligible for flow-move, which is controlled by the `session-resiliency` setting in the associated `service-policy`. + +Set `session-resiliency` to either `failover` or `revertible-failover` to enable this behavior: + +``` +config + authority + service-policy + session-resiliency revertible-failover + exit + exit +exit +``` + +When a new PMTU is discovered, the SSR issues a `PathMtuChangeEvent` for the affected path. On the next packet for any eligible session using that path, the SSR diverts the packet to the service area for flow modification, applying the new PMTU. Sessions with `session-resiliency none` are not refreshed and will continue using the previous PMTU value until they are rebuilt by another event. + +--- + +## Verification + +Use `show peers` to confirm the currently discovered path MTU for each peer path: + +```text +admin@node1.router1# show peers +Peer Node Network Interface Destination Status Hostname Path MTU +------------------------ --------- ------------------- --------------- -------- ------------ ---------- +router2 node1 wan0 192.0.2.10 Up router2.lab 1300 +``` + +A `Path MTU` value of `0` indicates PMTUD is disabled or has not yet completed a test cycle. + +## Troubleshooting + +- If the path MTU shown by `show peers` does not reflect the expected value, verify that `path-mtu-discovery > enabled` is `true` on both sides of the adjacency. +- If TCP sessions continue to fragment after configuring `enforced-mss automatic`, confirm the setting is applied to the correct egress interface and that both peers have completed a PMTUD cycle. +- If existing sessions are not picking up a new PMTU after a PMTUD cycle, verify the `service-policy` for those sessions has `session-resiliency` set to `failover` or `revertible-failover`. + +## Related Topics + +- [Concepts: Machine to Machine Communication](concepts_machine_communication.md) — path MTU discovery protocol details and BFD traffic patterns. +- [Configuration Reference Guide](config_reference_guide.md) — full parameter reference for `path-mtu-discovery`, `enforced-mss`, and `session-resiliency`. +- [Configuring Session Recovery Detection](config_session_recovery.md) — session health-check and flow rebuild mechanisms. +- [Configuring Forward Error Correction](config_forward_error_correction.md) — complementary resiliency feature for packet loss. diff --git a/sidebars.js b/sidebars.js index 2448b5b239..44cd4cf22e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -283,6 +283,7 @@ module.exports = { "config_prefix_delegation", "config_session_recovery", "config_forward_error_correction", + "config_pmtu", "config_management_over_forwarding", "config_domain-based_web_filter", "config_EthoSVR", From 94e4ffcf506ec8cd4e1ec3f00e75118c1d93df63 Mon Sep 17 00:00:00 2001 From: Chris Date: Wed, 13 May 2026 16:34:05 -0400 Subject: [PATCH 04/12] most of TJ's comments. Need the graphics to display so I can verify whether changes are needed, and need to get stats example. --- docs/config_pmtu.mdx | 60 ++++++++------------------------------------ 1 file changed, 10 insertions(+), 50 deletions(-) diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx index 6ddade8d6d..6f3b6637b6 100644 --- a/docs/config_pmtu.mdx +++ b/docs/config_pmtu.mdx @@ -13,12 +13,13 @@ sidebar_label: Path MTU Discovery Enhancements The SSR performs Path MTU Discovery (PMTUD) along the overlay to determine the correct maximum transmission unit (MTU) for each peer path. By default, this test runs every ten minutes. If a change in the underlay reduces the available path MTU between two SSRs, the new value is not discovered until the next PMTUD cycle. Additionally, existing sessions continue to use the previous MTU value until the next time those sessions are rebuilt. -Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error—referred to here as a _TooBig_ packet—to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. +Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error, referred to here as a _TooBig_ packet, to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. SSR 7.2.0 introduces two complementary enhancements to address these gaps: 1. **Underlay ICMP reaction** — When the SSR receives a TooBig packet from the underlay, it updates the affected overlay flow and generates a corrected TooBig packet toward the original packet sender, allowing the sender to adjust its segment size. -2. **PMTUD-triggered session refresh** — When a periodic PMTUD cycle discovers a new path MTU, existing sessions that are eligible for flow-move are refreshed to use the new value on the next packet. + +2. **Session Refresh** - The flow which was traversed to trigger the TooBig response from the underlay is now updated to use the MTU reported in the TooBig packet. For TCP flows, setting `enforced-mss automatic` on the egress `network-interface` is the recommended complement to these features. It adjusts the TCP MSS advertised at the interface boundary to avoid fragmentation in the first place. See [Configuration](#configuration) for details. @@ -61,14 +62,14 @@ sequenceDiagram Note over Server: Server adjusts MSS if TCP-capable ``` -When R2 (an underlay device) cannot forward an oversized packet, it sends a TooBig packet to the Hub's WAN interface. The SSR's `DivertedPacketHandler` processes this message: +When R2 (an underlay device) cannot forward an oversized packet, it sends a TooBig packet to the Hub's WAN interface. The SSR processes this message and does the following: 1. It extracts the encapsulated IP header from the TooBig body to identify the affected overlay session. 2. It finds the reverse flow using that header and updates the Hub → Spoke forward flow's PMTU to the value reported by the underlay. 3. It constructs a new TooBig packet directed toward the original packet sender (the Server), so the server's TCP stack can reduce its MSS. :::note -The MTU value propagated in the new TooBig packet reflects the underlay-reported value. On paths with encryption, HMAC, FEC, or BFD tunneling overhead, the effective usable MTU will be lower than the raw underlay value. The SSR accounts for these overheads when setting the MSS on forward flow actions. +The MTU value propagated in the new TooBig packet reflects the underlay-reported value. On paths with encryption, HMAC, FEC, or BFD tunneling overhead, the effective usable MTU will be lower than the raw underlay value. The SSR accounts for these overheads when setting the MTU on forward flow actions. ::: ## Fabric Fragmentation and Oversize Packet Behavior @@ -76,33 +77,9 @@ The MTU value propagated in the new TooBig packet reflects the underlay-reported When the PMTU on an overlay (SVR/fabric) path is lower than the MTU of the segment immediately preceding the Hub, packets larger than the PMTU will require fragmentation along the overlay. The SSR always fragments fabric packets when necessary, even when the incoming packet carries the Don't Fragment (DF) bit. This preserves packet delivery but prevents the sender from learning about the smaller path MTU and adjusting its segment size. :::note -For TCP traffic, setting `enforced-mss automatic` on the egress `network-interface` is the most reliable way to avoid this scenario. When set, the SSR rewrites the TCP MSS at the interface boundary to match the session MTU (including the path MTU for SVR sessions). This is not the default and must be explicitly configured. -::: - -### Oversize Fabric Packet Behavior - -To allow the sender an opportunity to adjust before fragmenting, you can configure `oversize-fabric-packet-behavior` on either a `network-interface` or a `service-policy`. When enabled, the SSR behavior changes as follows: - -| Setting | Behavior | -| ------- | -------- | -| `false` (default) | Oversized fabric packets are fragmented immediately, matching the current behavior. | -| `true` | The oversized fabric packet is **dropped**, and a TooBig packet is generated toward the sender. This is attempted up to N times per flow. If the sender does not reduce its packet size within those attempts, the SSR falls back to fragmenting. | - -This is a best-effort mechanism. Traffic continues over the overlay (via fragmentation) if the sender does not adjust. - -:::note -Packets that do not carry the DF bit fragment immediately regardless of this setting. Only packets that would otherwise be fragmented on an SVR path are subject to this behavior. +For TCP traffic, setting `enforced-mss automatic` on the egress `network-interface` is the most reliable way to avoid this scenario. When set, the SSR rewrites the TCP MSS at the interface boundary to match the session MTU (including the path MTU for SVR sessions). This is commonly known as `MSS Clamping` and is not the default; it must be explicitly configured. ::: -#### Configuration Location - -`oversize-fabric-packet-behavior` can be configured at two locations, with different trade-offs: - -| Location | Benefit | Consideration | -| -------- | ------- | ------------- | -| `network-interface` | Co-located with `mtu` and `enforced-mss`; applies to all traffic egressing that interface. | Applies to all services on the path, independent of individual service requirements. | -| `service-policy` | Per-service control; different services can have different behaviors. | Applies regardless of which egress interface is selected; a flow-move to a different interface may produce unexpected behavior if the interfaces are not configured consistently. | - ## Configuration ### Enabling Oversize Fabric Packet Behavior @@ -202,26 +179,6 @@ config exit ``` -### Enabling Session Refresh on PMTU Change - -When a PMTUD cycle discovers a new path MTU, the SSR can automatically refresh existing sessions on that path so they adopt the new MTU value without waiting for a manual rebuild. This requires the affected sessions to be eligible for flow-move, which is controlled by the `session-resiliency` setting in the associated `service-policy`. - -Set `session-resiliency` to either `failover` or `revertible-failover` to enable this behavior: - -``` -config - authority - service-policy - session-resiliency revertible-failover - exit - exit -exit -``` - -When a new PMTU is discovered, the SSR issues a `PathMtuChangeEvent` for the affected path. On the next packet for any eligible session using that path, the SSR diverts the packet to the service area for flow modification, applying the new PMTU. Sessions with `session-resiliency none` are not refreshed and will continue using the previous PMTU value until they are rebuilt by another event. - ---- - ## Verification Use `show peers` to confirm the currently discovered path MTU for each peer path: @@ -235,11 +192,14 @@ router2 node1 wan0 192.0.2.10 Up A `Path MTU` value of `0` indicates PMTUD is disabled or has not yet completed a test cycle. +A new stat, `stats/icmp/flow-mtu-updates`, provides a count of flows that have had their MTU updated at runtime via a TooBig packet. This counter is reset when the system resets (not persisted). + +**need stat example + ## Troubleshooting - If the path MTU shown by `show peers` does not reflect the expected value, verify that `path-mtu-discovery > enabled` is `true` on both sides of the adjacency. - If TCP sessions continue to fragment after configuring `enforced-mss automatic`, confirm the setting is applied to the correct egress interface and that both peers have completed a PMTUD cycle. -- If existing sessions are not picking up a new PMTU after a PMTUD cycle, verify the `service-policy` for those sessions has `session-resiliency` set to `failover` or `revertible-failover`. ## Related Topics From bf3af36016ab2c215e4d812ff46dcd83f2272b7f Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 14 May 2026 10:35:05 -0400 Subject: [PATCH 05/12] Updates per Dennis' comments --- docs/sec_security_policy.md | 96 +++++++++++++++++++++++++++++++++++-- 1 file changed, 93 insertions(+), 3 deletions(-) diff --git a/docs/sec_security_policy.md b/docs/sec_security_policy.md index aad92f9b2c..a726c8f1b2 100644 --- a/docs/sec_security_policy.md +++ b/docs/sec_security_policy.md @@ -157,7 +157,7 @@ AES-GCM is applied per-packet after SSR session encapsulation. Both SSR metadata ### Configuring AES-GCM -AES-GCM is selected by setting the `encryption-cipher` field of a security policy to the appropriate AES-GCM value. The security policy is then applied in the same locations as any other cipher: +AES-GCM is selected by setting the `encryption-cipher` field of a security policy to the appropriate AES-GCM value, either `aes-gcm-128` or `aes-gcm-256`. The security policy is then applied in the same locations as any other cipher: - `service > security-policy` — payload encryption for sessions - `network-interface > inter-router-security` — metadata decryption on received SVR traffic @@ -166,7 +166,7 @@ AES-GCM is selected by setting the `encryption-cipher` field of a security polic ``` configure authority security - encryption-cipher + encryption-cipher aes-gcm-256 encrypt true hmac-mode disabled ``` @@ -181,4 +181,94 @@ Changing an encryption cipher is a service-impacting event. Existing sessions ca ### Verifying AES-GCM Is In Use -After applying the new policy, use `show sessions by-id` to confirm the cipher is active on new sessions. The **Payload Security Policy** and **Metadata Security Policy** fields identify which security policy is applied per flow. Confirm that the policy you configured with AES-GCM is listed for the expected flows. +After applying the new policy, use `show sessions by-id` to confirm the cipher is active on new sessions. The **Payload Security Policy** and **Metadata Security Policy** fields identify which security policy is applied per flow. The **Action List** fields include the GCM encryption and `decryption actions: `AesGcmEncrypt`, `AesGcmDecrypt`, `AesGcmEncryptSvr2`, and `AesGcmDecryptSvr2. Confirm that the policy you configured with AES-GCM is listed for the expected flows. + +``` +admin@test1.combo1# sho sessions by-id 37ed5241-d5d5-4120-b168-884c619935a4 +Thu 2026-05-14 12:00:14 UTC +Retrieving session information... + +============================================================================================================================================================================ + combo1.test1 Session ID: 37ed5241-d5d5-4120-b168-884c619935a4 +============================================================================================================================================================================ + Service Name: east + Service Route Name: + Session Source: SourceType: INTER_ROUTER + Session Type: HTTPS + Service Class: Standard + Source Tenant: red + Destination Peer Name: N/A + Source Peer Name: combo2 + Inter Node: N/A + Inter Router: N/A + Ingress Source Nat: N/A + Payload Security Policy: aes1 + Payload Encrypted: True + Common Name Info: N/A + Tcp Time To Establish: N/A + Tls Time To Establish: N/A + Domain Name: N/A + Uri: N/A + Category: N/A + Override Service Name: N/A + App Stats Tracking Key: N/A + Session Keys: + Forward Session Key: [discriminator 4294967297, tenant red, peer combo2, src ip 172.16.2.201, dest ip 172.16.1.201, src port 443, dest port 10000, proto 17] + Reverse Session Key: [discriminator 4294967297, tenant red, peer combo2, src ip 172.16.1.201, dest ip 172.16.2.201, src port 10000, dest port 443, proto 17] + State Info: + Session State: ESTABLISHED + Redundancy State: SYNCED + Time Info: + Start Time: 0 days 0:00:12 + Ttl Duration For Database: 1900 + Forward Flows: + Key: [src ip 172.16.3.2, dest ip 172.16.3.1, src port 16384, dest port 16385, proto 17, interface 2.0] + Direction: forward + Tcp State: N/A + Packets Received: 999 + Packets Sent: 999 + Bytes Received: 152563 + Bytes Sent: 123876 + Tcp Retransmission Count: N/A + Decrypt Security Policy: interfabric + Action List: Ingress AesGcmDecryptMetadata ForwardMetadataRemove AesGcmDecrypt TtlValidateIpv4 IpHeaderTransform EthernetHeaderTransform AppForward + Time To Live: 1897 + Path Index: 5 + Attributes: + Path Key: NextHop : 1-1.0=172.16.1.201, destination Ip 172.16.1.0/24 + Arp Status: Valid + Waypoint Key: + Source Nat Key: + Metadata Security Policy: + Reverse Flows: + Key: [src ip 172.16.1.201, dest ip 172.16.2.201, src port 10000, dest port 443, proto 17, interface 1.0] + Direction: reverse + Tcp State: N/A + Packets Received: 995 + Packets Sent: 995 + Bytes Received: 123380 + Bytes Sent: 151464 + Tcp Retransmission Count: N/A + Decrypt Security Policy: + Action List: Ingress TtlValidateIpv4 IpHeaderTransform AesGcmEncrypt AppMetadataAdd AesGcmEncryptMetadata EthernetHeaderTransform AppForward + Time To Live: 1897 + Path Index: 5 + Attributes: + Path Key: NextHop : 1-2.0=172.16.3.2, destination Ip 172.16.3.2/32 + Arp Status: Valid + Waypoint Key: + Source Nat Key: + Metadata Security Policy: interfabric + App Identification: + Application: east + Domain Name: N/A + Uri: N/A + Category: N/A + Subcategory: N/A + Override Service Name: N/A + App Stats Tracking Key: N/A + +Completed in 0.07 seconds +``` + + From c5f3aaf8d05701ed3eaa5b7b407f520b42f20936 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 15 May 2026 09:37:25 -0400 Subject: [PATCH 06/12] interim commit --- docs/concepts_machine_communication.md | 4 +++- docs/config_pmtu.mdx | 12 ++---------- 2 files changed, 5 insertions(+), 11 deletions(-) diff --git a/docs/concepts_machine_communication.md b/docs/concepts_machine_communication.md index c6c027b9b7..9b8196419c 100644 --- a/docs/concepts_machine_communication.md +++ b/docs/concepts_machine_communication.md @@ -87,7 +87,9 @@ Peering SSR routers will perform path MTU discovery on each peer path between ea In order to accommodate these deployments where “ICMP Destination Unreachable - Fragmentation Needed” response messages are not generated (RFC1911 is not followed), three successive non-responses are considered equivalent to ICMP responses for the purposes of driving the algorithm with an inferred MTU. -The discovered MTU is viewable in the output of `show peers`. +The discovered MTU is viewable in the output of `show peers`. + +For additional information, see [Path MTU Discovery](config_pmtu.mdx). ### Secure Vector Routing Traffic diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx index 6f3b6637b6..e05dc112e8 100644 --- a/docs/config_pmtu.mdx +++ b/docs/config_pmtu.mdx @@ -1,16 +1,8 @@ --- -title: Path MTU Discovery Enhancements -sidebar_label: Path MTU Discovery Enhancements +title: Path MTU Discovery +sidebar_label: Path MTU Discovery --- -#### Version History - -| Release | Modification | -| ------- | ------------ | -| 7.2.0 | Feature introduced | - -## Overview - The SSR performs Path MTU Discovery (PMTUD) along the overlay to determine the correct maximum transmission unit (MTU) for each peer path. By default, this test runs every ten minutes. If a change in the underlay reduces the available path MTU between two SSRs, the new value is not discovered until the next PMTUD cycle. Additionally, existing sessions continue to use the previous MTU value until the next time those sessions are rebuilt. Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error, referred to here as a _TooBig_ packet, to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. From da3441a6fc8720320b893500a6558c59a20e8041 Mon Sep 17 00:00:00 2001 From: Mike Adams Date: Fri, 15 May 2026 10:33:42 -0400 Subject: [PATCH 07/12] docs: add SAN URI peering identity support for SSR 7.2.0 - Add subject_alt_names parameter to CSR API documentation - Document urn:ssr:peering SAN URI for SVRv2 peer identity - Highlight HA use case: unique CNs per node with shared SAN URI - Update peer authentication flow: CN check then SAN URI fallback - Replace custom_ssr_peering with my_peering_cert in examples - Add legacy note for custom_ssr_peering disk-based fallback - Add 5 new audit event types (generate/delete private key, update/delete certificate, delete CSR) - Update generate_csr audit event with subject_alt_names field - Remove role parameter references (removed in PR #20519) Refs: ssr#20819, ssr#20767, ssr#20519 --- docs/cert_validation_requirements.md | 2 + docs/config_custom_certs.md | 53 +++++++++++------ docs/sec-cert-based-encrypt.md | 85 +++++++++++++++++++++++++--- docs/sec_enhanced_key_mgmt.md | 71 +++++++++++++++++++---- 4 files changed, 175 insertions(+), 36 deletions(-) diff --git a/docs/cert_validation_requirements.md b/docs/cert_validation_requirements.md index 6011391be0..ee0a337e0e 100644 --- a/docs/cert_validation_requirements.md +++ b/docs/cert_validation_requirements.md @@ -8,6 +8,7 @@ sidebar_label: Certificate Requirements and Validation | Release | Modification | | ------- | --------------------------- | | 7.0.0 | Certificate management and validation support added. | +| 7.2.0 | Subject Alternative Name URI support for peering identity. | This page describes the certificate properties that the SSR enforces, how `validation-mode` affects behavior, and the differences between config-time and runtime validation. @@ -112,6 +113,7 @@ Client certificates used for peering are validated as leaf (end-entity) certific | --- | --- | | Signature Algorithm | Must be an [accepted algorithm](#accepted-cryptographic-algorithms). | | Public Key | Must be an [accepted key type and size](#key-requirements). | +| Subject Alternative Name (optional) | Starting in SSR 7.2.0, a `urn:ssr:peering:` SAN URI can be used to carry SVRv2 peering identity as an alternative to the Common Name. See [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules) for details. | ### Intermediate CA Certificates diff --git a/docs/config_custom_certs.md b/docs/config_custom_certs.md index 3d5ca718b6..f69e2a024f 100644 --- a/docs/config_custom_certs.md +++ b/docs/config_custom_certs.md @@ -7,7 +7,8 @@ sidebar_label: Configure Certificate Management | Release | Modification | | ------- | --------------------------- | -| 7.0.0 | Certificate Management support added. | +| 7.0.0 | Certificate Management support added. | +| 7.2.0 | Subject Alternative Name support added to CSR generation. | Security is a critical component of SD-WAN products. The effectiveness of any security strategy relies on the strength of the security algorithm and how related information is exchanged between participants. @@ -51,8 +52,8 @@ The following are some details of certificate security. ## Provisioning Process -:::important -It is necessary for all of the REST APIs to use the name `custom_ssr_peering` in order for this private key and certificate to be visible and usable by Enhanced Security Key Management in 7.0. This is a reserved name specifically used by the Enhanced Security Key Management feature. +:::note Legacy Name +In SSR 7.0.x, the `name` field in all REST API calls was required to be `custom_ssr_peering` (a reserved name) for ESKM visibility. Starting with SSR 7.1.0, any consistent name may be used. The examples below use `my_peering_cert`. ::: :::tip Swagger API Reference @@ -191,7 +192,7 @@ Create the following file (update algorithm and key size to your preference): ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "algorithm": "RSA", "rsa_key_size": "2048" } @@ -213,7 +214,7 @@ curl -k -X POST https://10.27.35.89/api/v1/router/combo-east/node/node2/private- -d @key_request.json ``` -Upon success, `ssh` to the target SSR and verify that `/etc/128technology/pki/custom_ssr_peering.key` exists on disk. +Upon success, `ssh` to the target SSR and verify that `/etc/128technology/pki/my_peering_cert.key` exists on disk. ### Issue a `certificate-signing-request` @@ -226,11 +227,13 @@ This requirement is lifted starting with SSR 7.1.0. ::: -1. Create a file containing the CSR request body. At a minimum provide `name` and a `common_name` that is unique to this router or node: +1. Create a file containing the CSR request body. At a minimum provide `name` and a `common_name`: :::important Naming Rules -- **`name`** must be **the same value across all routers and nodes** — `custom_ssr_peering` in SSR 7.0.x (reserved). This is the authority-wide identifier required for ESKM visibility. -- **`common_name`** must be **unique per router/node** and must **exactly match** that router's configured `peering-common-name`. Using the wrong `common_name` will cause ESKM peer authentication to fail. +- **`name`** must be **the same value across all routers and nodes**. In SSR 7.1+, any consistent name may be used. +- **`common_name`** must be **unique per router/node**. It must match that router's configured `peering-common-name` — either directly, or via a `urn:ssr:peering` SAN URI in the certificate (SSR 7.2.0+). + +For full details on SAN URI peering identity, see [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules). Example mapping for a two-router deployment: @@ -240,15 +243,27 @@ Example mapping for a two-router deployment: | combo-west | `west-alias` | `west-alias` | ::: -**csr_request.json** +**csr_request.json** (minimum): ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "common_name": "east-alias" } ``` +**csr_request.json** (with Subject Alternative Name URI for HA): + +```json +{ + "name": "my_peering_cert", + "common_name": "combo-east-node1", + "subject_alt_names": [ + {"type": "urn_ssr_peering", "value": "east-alias"} + ] +} +``` + This example represents the minimum requirements. Any of the following additional details may be added to the request: - country_name (string, optional): The country name. @@ -261,6 +276,12 @@ This example represents the minimum requirements. Any of the following additiona - rsa_key_size (integer, optional): The RSA key size. Only valid when algorithm is set to “RSA”. Valid key sizes are any multiple of 256 between 2048 and 4096. - ecc_curve (string, optional): The ECC curve to use. Only valid when algorithm is set to “ECC”.Valid curves are: (SECP256R, SECP384R1, SECP521R1) - validity_period (integer, optional): The validity period in days. +- subject_alt_names (array, optional, SSR 7.2.0+): An array of Subject Alternative Name entries to include in the CSR. Each entry is an object with `type` and `value` fields. Supported types: + - `dns` — a DNS hostname (e.g., `"example.com"`) + - `ip` — an IPv4 or IPv6 address (e.g., `"192.168.1.1"`) + - `email` — an email address (e.g., `"admin@example.com"`) + - `uri` — a URI (e.g., `"https://example.com"`) + - `urn_ssr_peering` — a convenience alias that automatically expands the value to `URI:urn:ssr:peering:`. Use this type to carry the SVRv2 peering identity in the SAN extension. 2. Issue the CSR request to the SSR: @@ -301,7 +322,7 @@ When the signed certificate is returned, instruct the SSR to ingest the certific ``` POST /api/v1/router/{router_name}/node/{node_name}/certificate { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "certificate": "-----BEGIN CERTIFICATE----- MIIF3DCCBESgAwIBAgIKAf9HQjJKSQd1lTANBgkqhkiG9w0BAQsFADBaMQswCQYD VQQGEwJERTERMA8GA1UECgwIT3BlblhQS0kxDDAKBgNVBAsMA1BLSTEqMCgGA1UE @@ -319,8 +340,8 @@ Once the certificate is successfully ingested, verify that the certificate was a 1. `ssh` to the SSR. 2. Log in as the root user: `sudo su`. -3. Verify that `/etc/128technology/pki/custom_ssr_peering.pem` exists on disk. - `ls -l /etc/128technology/pki/custom_ssr_peering.pem` +3. Verify that `/etc/128technology/pki/my_peering_cert.pem` exists on disk. + `ls -l /etc/128technology/pki/my_peering_cert.pem` ### Activate the Certificate in Configuration @@ -330,9 +351,9 @@ On the Conductor, configure `client-certificate` using the same `name` value use ``` config authority - client-certificate custom_ssr_peering - name custom_ssr_peering - file custom_ssr_peering + client-certificate my_peering_cert + name my_peering_cert + file my_peering_cert validation-mode strict exit exit diff --git a/docs/sec-cert-based-encrypt.md b/docs/sec-cert-based-encrypt.md index c99ac496e1..13fc7c21a9 100644 --- a/docs/sec-cert-based-encrypt.md +++ b/docs/sec-cert-based-encrypt.md @@ -6,7 +6,8 @@ sidebar_label: Certificate-based Security Encryption | Release | Modification | | ------- | --------------------------- | -| 7.1.0 | Certificate-based Security Encryption support added. | +| 7.1.0 | Certificate-based Security Encryption support added. | +| 7.2.0 | Subject Alternative Name support added to CSR generation. New audit events for certificate lifecycle. | In addition to Enhanced Security Key Management, the SSR offers certificate based security encryption to encrypt, validate, and exchange certificates between devices within the network. @@ -191,7 +192,7 @@ Create the following file (updated to the customers algorithm/key size preferenc ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "algorithm": "RSA", "rsa_key_size": "2048" } @@ -206,19 +207,19 @@ curl -k -X POST https://10.27.35.89/api/v1/private-key -d @key_request.json ``` -Upon success, you can verify that the key was created by logging on to the SSR, `ssh` into a linux shell, and ensuring that `/etc/128technology/pki/custom_ssr_peering.key` exists on disk. +Upon success, you can verify that the key was created by logging on to the SSR, `ssh` into a linux shell, and ensuring that `/etc/128technology/pki/my_peering_cert.key` exists on disk. ### Issue a `certificate-signing-request` In order to create a signed certificate by the CA for the SSR, the CA needs a `certificate-signing-request`. Instruct the SSR to create the request using the values provided; at a minimum the `name` and `common-name`. The SSR must sign the request with its private-key. -1. Create a file that contains the body of the CSR-request. At a minimum this must include the name `custom_ssr_peering`, and the common name: +1. Create a file that contains the body of the CSR-request. At a minimum this must include the `name` and the `common_name`: **csr_request.json** ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "common_name": "SSR_12345679" } ``` @@ -235,6 +236,7 @@ This example represents the minimum requirements. Any of the following additiona - rsa_key_size (integer, optional): The RSA key size. Only valid when algorithm is set to “RSA”. Valid key sizes are any multiple of 256 between 2048 and 4096. - ecc_curve (string, optional): The ECC curve to use. Only valid when algorithm is set to “ECC”.Valid curves are: (SECP256R, SECP384R1, SECP521R1) - validity_period (integer, optional): The validity period in days. +- subject_alt_names (array, optional, SSR 7.2.0+): An array of Subject Alternative Name entries to include in the CSR. Each entry is an object with `type` and `value` fields. Supported types: `dns`, `ip`, `email`, `uri`, `urn_ssr_peering`. For details, see [Configure Certificate Management](config_custom_certs.md#issue-a-certificate-signing-request). 2. Issue the CSR request to the SSR: @@ -270,7 +272,7 @@ When the signed certificate is returned, instruct the SSR to ingest the certific ``` { - "name": "custom_ssr_peering", + "name": "my_peering_cert", "certificate": "-----BEGIN CERTIFICATE----- MIIF3DCCBESgAwIBAgIKAf9HQjJKSQd1lTANBgkqhkiG9w0BAQsFADBaMQswCQYD VQQGEwJERTERMA8GA1UECgwIT3BlblhQS0kxDDAKBgNVBAsMA1BLSTEqMCgGA1UE @@ -288,8 +290,8 @@ Once the certificate is successfully ingested, verify that the certificate was a 1. `ssh` to the SSR. 2. Log in as the root user: `sudo su`. -3. Verify that `/etc/128technology/pki/custom_ssr_peering.pem` exists on disk. - `ls -l /etc/128technology/pki/custom_ssr_peering.pem` +3. Verify that `/etc/128technology/pki/my_peering_cert.pem` exists on disk. + `ls -l /etc/128technology/pki/my_peering_cert.pem` ### Configure the Certificate @@ -371,7 +373,20 @@ Audit events and logs are generated for the following events: Node: test-1 Description: Generated CSR for: TestCertificate Json Event Detail: {"name":"TestCertificate","common_name":"example.com","country_name":"US","state_province_name":"California","locality_name":"San - Francisco","organization_name":"ExampleOrg","organizational_unit_name":"IT","email_address":"admin@example.com","validity_period_days":365} + Francisco","organization_name":"ExampleOrg","organizational_unit_name":"IT","email_address":"admin@example.com","validity_period_days":365,"subject_alt_names":[]} + Permitted: True +``` + +- Generate Private Key + +``` +======================================================================================================================================================= + 2025-03-19T20:50:35.173Z Generated private key. +======================================================================================================================================================= + Type: system.generate_private_key + Node: test-1 + Description: Generated private key for: TestCertificate + Json Event Detail: {"name":"TestCertificate","algorithm":"RSA","rsa_key_size":2048} Permitted: True ``` @@ -400,3 +415,55 @@ Audit events and logs are generated for the following events: GMT","crl_url":"http://10.27.39.143/testCrl.pem","size":14162,"total_entries":279,"added_entries":0,"removed_entries":0,"success":true,"certificate_authority":"/C=US/O=Google Trust Services/CN=WR2"} Permitted: True ``` + +- Update Certificate + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Updated a certificate. +======================================================================================================================================================= + Type: system.update_certificate + Node: test-1 + Description: Updated certificate: TestCertificate + Json Event Detail: {"purpose":"TLS Web Client Authentication","common_name":"example.com","crl_urls":[],"certificate_authority":"N/A","fingerprint":"6D:C7:8E:48:4F:55:63:D9:AB:70:66:CD:29:4E:1C:37:CF:89:17:B0"} + Permitted: True +``` + +- Delete Certificate + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Deleted a certificate. +======================================================================================================================================================= + Type: system.delete_certificate + Node: test-1 + Description: Deleted certificate: TestCertificate + Json Event Detail: {"name":"TestCertificate"} + Permitted: True +``` + +- Delete Private Key + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Deleted a private key. +======================================================================================================================================================= + Type: system.delete_private_key + Node: test-1 + Description: Deleted private key: TestCertificate + Json Event Detail: {"name":"TestCertificate"} + Permitted: True +``` + +- Delete CSR + +``` +======================================================================================================================================================= + 2025-03-26T21:22:43.108Z Deleted a certificate signing request. +======================================================================================================================================================= + Type: system.delete_csr + Node: test-1 + Description: Deleted CSR: TestCertificate + Json Event Detail: {"name":"TestCertificate"} + Permitted: True +``` diff --git a/docs/sec_enhanced_key_mgmt.md b/docs/sec_enhanced_key_mgmt.md index 8b6fa23a69..5eb1becc04 100644 --- a/docs/sec_enhanced_key_mgmt.md +++ b/docs/sec_enhanced_key_mgmt.md @@ -9,6 +9,7 @@ sidebars-label: Enhanced Security Key Management | ------- | --------------------------- | | 7.0.1 | Enhanced Security Key Management support added. | | 7.1.3 | Support for ML-KEM added. | +| 7.2.0 | Subject Alternative Name (SAN) URI support for peering identity. | Security is a critical component of [SD-WAN (software-defined wide area network)](https://www.juniper.net/us/en/products/routers/session-smart-router.html) products in today’s market. [The SSR (Session Smart Router)](about_128t.md) offers several means of ensuring the integrity of data transmitted through the router, such as encrypting application payload content, encrypting SVR (Secure Vector Routing) metadata, and authentication for metadata. @@ -69,7 +70,7 @@ When using CA-signed certificates, the end-to-end provisioning sequence must be 1. Authenticate to the Conductor REST API (`POST /api/v1/login`) and store the bearer token. 2. Generate a private key on the target router's node (`POST /api/v1/router//node//private-key`) — the key never leaves the SSR. -3. Generate a CSR on the same target (`GET /api/v1/router//node//certificate-request`) using a `common_name` that matches that router's `peering-common-name`. +3. Generate a CSR on the same target (`GET /api/v1/router//node//certificate-request`) using a `common_name` that matches that router's `peering-common-name`, or alternatively, using any unique `common_name` with a `urn:ssr:peering` SAN URI that matches the `peering-common-name`. See [API Naming Rules](#api-naming-rules) for details. 4. Submit the CSR to your Certificate Authority and obtain a signed certificate. 5. Ingest the signed certificate back into the SSR (`POST /api/v1/router//node//certificate`). 6. **Activate the certificate in configuration** — having the file on disk is not sufficient. Configure `authority client-certificate` with a `name` and `file` matching the API artifact name. See [Activating the Certificate in Configuration](#activating-the-certificate-in-configuration). @@ -84,16 +85,54 @@ Consistent naming across all API calls and configuration is critical: | Field | Scope | Rule | |---|---|---| -| `name` (in all API requests) | Authority-wide | **Must be identical across all routers and nodes.** Use `custom_ssr_peering` in SSR 7.0.x (reserved name). In SSR 7.1+, any consistent name may be used. | -| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node**, and must **exactly match** that router's configured `peering-common-name`. | -| `peering-common-name` (in config) | Per-router | Unique alias per router. Must match the `common_name` used in that router's CSR. | +| `name` (in all API requests) | Authority-wide | **Must be identical across all routers and nodes.** In SSR 7.1+, any consistent name may be used. | +| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node.** Must match the router's configured `peering-common-name` — either directly in the `common_name` field, or via a `urn:ssr:peering` SAN URI (see below). | +| `peering-common-name` (in config) | Per-router | Unique alias per router. Must match either the `common_name` or a `urn:ssr:peering` SAN URI in that router's certificate. | -**Example mapping for a two-router deployment:** +:::note Legacy Name +In SSR 7.0.x, the `name` field was required to be `custom_ssr_peering` (a reserved name). This is no longer required in SSR 7.1+. If no certificate is configured, the SSR will fall back to searching for certificates named `custom_ssr_peering` on disk for backward compatibility. +::: + +##### Peering Identity via Subject Alternative Name URI (SSR 7.2.0+) + +Starting in SSR 7.2.0, the peering identity can be carried in a Subject Alternative Name (SAN) URI extension instead of the Common Name (CN). This is especially useful in **HA deployments**, where both nodes in a router share the same `peering-common-name` but enterprise PKI policies require unique CNs per certificate. + +When verifying a peer's identity, the SSR checks the certificate CN first. If the CN does not match the configured `peering-common-name`, the SSR falls back to checking for a SAN URI of the form: + +``` +urn:ssr:peering: +``` + +If a matching SAN URI is found, the certificate is accepted. This allows each HA node to have a unique CN while sharing the same peering identity through the SAN URI. -| Router | `peering-common-name` in config | `common_name` in CSR | `name` in all API requests | -|---|---|---|---| -| combo-east | `east-alias` | `east-alias` | `custom_ssr_peering` | -| combo-west | `west-alias` | `west-alias` | `custom_ssr_peering` | +To include a SAN URI in a CSR, add a `subject_alt_names` array to the CSR request body using the `urn_ssr_peering` convenience type: + +```json +{ + "name": "my_peering_cert", + "common_name": "combo-east-node1", + "subject_alt_names": [ + {"type": "urn_ssr_peering", "value": "east-alias"} + ] +} +``` + +The `urn_ssr_peering` type automatically expands the value to `URI:urn:ssr:peering:`. For the full list of supported SAN types, see [Configure Certificate Management](config_custom_certs.md#issue-a-certificate-signing-request). + +**Example: Traditional CN-based identity (single node per router)** + +| Router | `peering-common-name` | `common_name` in CSR | SAN URI | `name` in API | +|---|---|---|---|---| +| combo-east | `east-alias` | `east-alias` | *(not needed)* | `my_peering_cert` | +| combo-west | `west-alias` | `west-alias` | *(not needed)* | `my_peering_cert` | + +**Example: SAN URI identity (HA — unique CN per node)** + +| Router | Node | `peering-common-name` | `common_name` in CSR | SAN URI | `name` in API | +|---|---|---|---|---|---| +| combo-east | node1 | `east-alias` | `combo-east-node1` | `urn:ssr:peering:east-alias` | `my_peering_cert` | +| combo-east | node2 | `east-alias` | `combo-east-node2` | `urn:ssr:peering:east-alias` | `my_peering_cert` | +| combo-west | node1 | `west-alias` | `combo-west-node1` | `urn:ssr:peering:west-alias` | `my_peering_cert` | #### Activating the Certificate in Configuration @@ -196,6 +235,10 @@ When provisioning certificates for an HA router, you must execute the private-ke The same node-scoped pattern applies to the `/certificate-request` and `/certificate` endpoints. The request body — including the `name` field — is identical for both nodes. Consult the Swagger documentation at `https:///api/v1/swagger` for the full per-node endpoint schema. ::: +:::tip Unique Common Names in HA (SSR 7.2.0+) +Because both HA nodes share the same `peering-common-name`, earlier releases required both nodes to use an identical `common_name` in their certificates. Starting in SSR 7.2.0, you can use a [SAN URI](#peering-identity-via-subject-alternative-name-uri-ssr-720) to carry the peering identity, allowing each node to have a unique CN — for example, `combo-east-node1` and `combo-east-node2` — while both certificates include the same `urn:ssr:peering:east-alias` SAN URI. +::: + When two nodes are configured as a redundant pair, the keys are exchanged between nodes. This avoids rekeying on flow migration due to node failures. Keys can be safely exchanged between nodes as the HA sync interfaces are connected point to point over an SSH connection. ### Certificate Replacement or Revocation @@ -210,7 +253,13 @@ When a certificate is revoked, expired, or invalid, the SSR generates an alarm. Peer validation is done whenever a new certificate is added, or peer configuration has changed. When a certificate is received, a cached validation response is used. If configured, the received certificate is validated against the `trusted-ca-certificate` list. -When receiving a certificate from a peer router and performing validation, the receiving router extracts and saves the peer router's public key. This is used for validating the authenticity of any subsequent Peer Key/Rekey requests. +When receiving a certificate from a peer router and performing validation, the receiving router checks the certificate's identity against the peer's configured `peering-common-name` using the following order: + +1. **Common Name (CN) check** — if the certificate's CN matches the peer's `peering-common-name`, the certificate is accepted. +2. **SAN URI fallback (SSR 7.2.0+)** — if the CN does not match, the SSR checks for a `urn:ssr:peering:` SAN URI in the certificate's Subject Alternative Name extension. If found, the certificate is accepted. +3. **Rejection** — if neither the CN nor any SAN URI matches, the certificate is rejected. The behavior depends on the `invalid-certificate-behavior` setting (`fail-soft` or `fail-hard`). + +After successful validation, the receiving router extracts and saves the peer router's public key. This is used for validating the authenticity of any subsequent Peer Key/Rekey requests. ### Requirements @@ -233,7 +282,7 @@ config 2. Configure a unique `peering-common-name` on each router. In a secure environment, the router name should never be sent between routers as plaintext in BFD messages. The `peering-common-name` is a **unique alias per router** that identifies the router and is configured at the router level. When `enhanced-security-key-management` is configured, it is validated against the `peering-common-name` from the certificate, and integrated into the auto-generated adjacencies list for the peers of the router from the neighborhood configuration. :::note -The `peering-common-name` must exactly match the `common_name` field used in the certificate signing request (CSR) generated for that router. See [API Naming Rules](#api-naming-rules) for the full field mapping. +The `peering-common-name` must match either the `common_name` field or a `urn:ssr:peering` SAN URI in the certificate generated for that router. See [API Naming Rules](#api-naming-rules) for the full field mapping. ::: ``` From 5aea61b61ea0e603f81d564fc4c5b9f92dd411f9 Mon Sep 17 00:00:00 2001 From: Chris Date: Fri, 15 May 2026 14:16:14 -0400 Subject: [PATCH 08/12] interim commit --- docs/config_pmtu.mdx | 44 +++++++++++--------------------------------- 1 file changed, 11 insertions(+), 33 deletions(-) diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.mdx index e05dc112e8..bf166c9d1a 100644 --- a/docs/config_pmtu.mdx +++ b/docs/config_pmtu.mdx @@ -5,9 +5,19 @@ sidebar_label: Path MTU Discovery The SSR performs Path MTU Discovery (PMTUD) along the overlay to determine the correct maximum transmission unit (MTU) for each peer path. By default, this test runs every ten minutes. If a change in the underlay reduces the available path MTU between two SSRs, the new value is not discovered until the next PMTUD cycle. Additionally, existing sessions continue to use the previous MTU value until the next time those sessions are rebuilt. +| Direction | Port/Proto | Client Payload (bytes) | Server Payload (bytes) | Default Interval | Notes | +| --- | --- | --- | --- | --- | --- | +| bidirectional | 1280/UDP | 2945 | 90 | 600s | Interval is configurable within `path-mtu-discovery/interval`, or disabled `path-mtu-discovery/enabled`. | + +Peering SSR routers will perform path MTU discovery on each peer path between each other. This test is run every ten (10) minutes by default, to adjust in the event of path changes between peering devices. During the test, SSR routers send packets of various sizes to discover the MTU of the path. However, in some government deployments the use of MTU discovery is not possible. + +In order to accommodate these deployments where “ICMP Destination Unreachable - Fragmentation Needed” response messages are not generated (RFC1911 is not followed), three successive non-responses are considered equivalent to ICMP responses for the purposes of driving the algorithm with an inferred MTU. + +The discovered MTU is viewable in the output of `show peers`. + Devices in the underlay may report an ICMP Destination Unreachable / Fragmentation Needed (type 3, code 4) error, referred to here as a _TooBig_ packet, to indicate they could not forward a packet due to an undersized MTU. Prior to SSR 7.2.0, these messages were forwarded to the correct endpoint, but the SSR itself did not act on the MTU value contained in the message, leaving existing sessions with an incorrect PMTU. -SSR 7.2.0 introduces two complementary enhancements to address these gaps: +SSR 7.2.0 introduces two complementary enhancements to address the gaps mentioned above: 1. **Underlay ICMP reaction** — When the SSR receives a TooBig packet from the underlay, it updates the affected overlay flow and generates a corrected TooBig packet toward the original packet sender, allowing the sender to adjust its segment size. @@ -74,38 +84,6 @@ For TCP traffic, setting `enforced-mss automatic` on the egress `network-interfa ## Configuration -### Enabling Oversize Fabric Packet Behavior - -#### On a `network-interface` - -``` -config - authority - router - node - device-interface - network-interface - oversize-fabric-packet-behavior true - exit - exit - exit - exit - exit -exit -``` - -#### On a `service-policy` - -``` -config - authority - service-policy - oversize-fabric-packet-behavior true - exit - exit -exit -``` - ### Configuring `enforced-mss` (Recommended for TCP) Set `enforced-mss` to `automatic` on egress interfaces to avoid fabric fragmentation for TCP traffic. The SSR calculates the correct MSS from the interface or path MTU for SVR sessions. From 0f1d27713f6fd235755a8628afce039e7945f227 Mon Sep 17 00:00:00 2001 From: Mike Adams Date: Fri, 15 May 2026 14:22:18 -0400 Subject: [PATCH 09/12] Addressed code review comments --- docs/cert_validation_requirements.md | 2 +- docs/sec_enhanced_key_mgmt.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/cert_validation_requirements.md b/docs/cert_validation_requirements.md index ee0a337e0e..c7d0d88b25 100644 --- a/docs/cert_validation_requirements.md +++ b/docs/cert_validation_requirements.md @@ -113,7 +113,7 @@ Client certificates used for peering are validated as leaf (end-entity) certific | --- | --- | | Signature Algorithm | Must be an [accepted algorithm](#accepted-cryptographic-algorithms). | | Public Key | Must be an [accepted key type and size](#key-requirements). | -| Subject Alternative Name (optional) | Starting in SSR 7.2.0, a `urn:ssr:peering:` SAN URI can be used to carry SVRv2 peering identity as an alternative to the Common Name. See [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules) for details. | +| Subject Alternative Name (optional) | Starting in SSR 7.2.0, a `urn:ssr:peering:` SAN URI can be used to carry SVR peering identity as an alternative to the Common Name. See [Enhanced Security Key Management — API Naming Rules](sec_enhanced_key_mgmt.md#api-naming-rules) for details. | ### Intermediate CA Certificates diff --git a/docs/sec_enhanced_key_mgmt.md b/docs/sec_enhanced_key_mgmt.md index 5eb1becc04..6dd2fef3fa 100644 --- a/docs/sec_enhanced_key_mgmt.md +++ b/docs/sec_enhanced_key_mgmt.md @@ -86,7 +86,7 @@ Consistent naming across all API calls and configuration is critical: | Field | Scope | Rule | |---|---|---| | `name` (in all API requests) | Authority-wide | **Must be identical across all routers and nodes.** In SSR 7.1+, any consistent name may be used. | -| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node.** Must match the router's configured `peering-common-name` — either directly in the `common_name` field, or via a `urn:ssr:peering` SAN URI (see below). | +| `common_name` (in CSR request) | Per-router / per-node | **Must be unique per router or HA node.** Must match the router's configured `peering-common-name` — unless a `urn:ssr:peering` SAN URI is used to carry the peering identity instead (see below). | | `peering-common-name` (in config) | Per-router | Unique alias per router. Must match either the `common_name` or a `urn:ssr:peering` SAN URI in that router's certificate. | :::note Legacy Name @@ -257,7 +257,7 @@ When receiving a certificate from a peer router and performing validation, the r 1. **Common Name (CN) check** — if the certificate's CN matches the peer's `peering-common-name`, the certificate is accepted. 2. **SAN URI fallback (SSR 7.2.0+)** — if the CN does not match, the SSR checks for a `urn:ssr:peering:` SAN URI in the certificate's Subject Alternative Name extension. If found, the certificate is accepted. -3. **Rejection** — if neither the CN nor any SAN URI matches, the certificate is rejected. The behavior depends on the `invalid-certificate-behavior` setting (`fail-soft` or `fail-hard`). +3. **Rejection** — if neither the CN nor any SAN URI matches, the certificate is rejected. How the SSR handles the certificate rejection is defined using the `invalid-certificate-behavior` setting (`fail-soft` or `fail-hard`). After successful validation, the receiving router extracts and saves the peer router's public key. This is used for validating the authenticity of any subsequent Peer Key/Rekey requests. From 2d18615da32cd9209e08571f358bce2abca4b093 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 10:32:55 -0400 Subject: [PATCH 10/12] restoring updated docusaurus file to 7.2 docs. --- docusaurus.config.js | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docusaurus.config.js b/docusaurus.config.js index 06ad758ec6..1959f84cd3 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -7,9 +7,12 @@ module.exports = { organizationName: '128technology', // Usually your GitHub org/user name. projectName: 'docs', // Usually your repo name. onBrokenAnchors: 'throw', - onBrokenMarkdownLinks: 'throw', markdown: { mermaid: true, + hooks: { + onBrokenMarkdownLinks: 'throw', + onBrokenMarkdownImages: 'throw', + }, }, themes: ['@docusaurus/theme-mermaid'], themeConfig: { From 918f72c64437d184c0bb8d45213a9bc13cb327af Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 10:52:02 -0400 Subject: [PATCH 11/12] renaming file to see whether the mermaid graphic works --- docs/{config_pmtu.mdx => config_pmtu.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/{config_pmtu.mdx => config_pmtu.md} (100%) diff --git a/docs/config_pmtu.mdx b/docs/config_pmtu.md similarity index 100% rename from docs/config_pmtu.mdx rename to docs/config_pmtu.md From 9ad0d3305e9d4e6f18250dccd8c3ac2d287e6eeb Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 19 May 2026 11:00:17 -0400 Subject: [PATCH 12/12] link fix --- docs/concepts_machine_communication.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/concepts_machine_communication.md b/docs/concepts_machine_communication.md index 9b8196419c..9d34daa9c5 100644 --- a/docs/concepts_machine_communication.md +++ b/docs/concepts_machine_communication.md @@ -89,7 +89,7 @@ In order to accommodate these deployments where “ICMP Destination Unreachable The discovered MTU is viewable in the output of `show peers`. -For additional information, see [Path MTU Discovery](config_pmtu.mdx). +For additional information, see [Path MTU Discovery](config_pmtu.md). ### Secure Vector Routing Traffic