From da3441a6fc8720320b893500a6558c59a20e8041 Mon Sep 17 00:00:00 2001 From: Mike Adams Date: Fri, 15 May 2026 10:33:42 -0400 Subject: [PATCH 1/2] 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 0f1d27713f6fd235755a8628afce039e7945f227 Mon Sep 17 00:00:00 2001 From: Mike Adams Date: Fri, 15 May 2026 14:22:18 -0400 Subject: [PATCH 2/2] 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.