7.1.0 r2 documentation #890
Conversation
… placeholder/starting point.
docs/config-smart-download.md
Outdated
|
|
||
| ## Download Failover Resiliency | ||
|
|
||
| SSR images can be downloaded from a variety of sources, depending on software access mode (eg. internet-only, prefer-conductor, conductor-only, offline-mode): the HA peer, both conductor nodes, artifactory, and the mist proxy to artifactory (cloud deployments only). |
docs/config-smart-download.md
Outdated
|
|
||
| SSR images can be downloaded from a variety of sources, depending on software access mode (eg. internet-only, prefer-conductor, conductor-only, offline-mode): the HA peer, both conductor nodes, artifactory, and the mist proxy to artifactory (cloud deployments only). | ||
|
|
||
| To improve resiliency to network connectivity issues, the SSR queries available versions from all sources before beginning the download. It compiles a list of sources where the requested version is available and begins the download. If more than 50% of requests to a source fail within a window of 10 requests, the SSR marks that source unavailable and moves on to the next source. The following priority order is used for sources: |
There was a problem hiding this comment.
In my mind the size of the window is more of an implementation detail and may be subject to change based on tuning. We may want to be less specific about that in case we decide to adjust it in the future. But this may be fine too. Not sure how likely we are to need to adjust it
docs/config-smart-download.md
Outdated
|
|
||
| In the event that all sources have reached the threshold of consecutive failures and a download attempt has returned an error, the SSR can be configured to wait for a specified amount of time and then retry the download. If a connection is successfully made, the download will resume where it left off. | ||
|
|
||
| When the timeout is enabled, the SSR waits for a configurable amount of time (default is 10800s) for the download to complete. When the timeout value is reached, the download is marked as **Failed** and the retry delay begins. |
There was a problem hiding this comment.
This is not quite accurate. The retry delay will begin once we have marked all download sources as unavailable, as described in the failover resilience section. If enabled, once this timeout is hit, the download will be entirely stopped and marked as a failure. Or in other words, the retries happen inside of this timeout, not after it.
docs/config-smart-download.md
Outdated
|
|
||
| ### Sequenced HA Download | ||
|
|
||
| The SSR supports sequenced downloading; one node of an HA pair downloads an image from the remote repository, and the other node waits for it to complete. Once that download is complete, the second node downloads it from the first. When targeting an HA router, the download is sequenced by default. To disable this sequencing, use `request system software download simultaneous disable`. |
There was a problem hiding this comment.
Once note about the second node downloads it from the first. The peer is the first place that an HA router will attempt to download from, so in most cases this would be the case, but if for whatever reason the connection to the peer went down, the router would move on and continue downloading from the conductor or remote sources. Not sure if that needs to be clarified or not.
There was a problem hiding this comment.
Does the download happen over the HA sync connection or the HA fabric?
There was a problem hiding this comment.
I believe it's the HA sync connection
docs/sec-conductor-onboard.md
Outdated
|
|
||
| ## Configuration | ||
|
|
||
| Three components: Onboarding conductor, router, Operational conductor. |
There was a problem hiding this comment.
This is a customer specific tpopology. We shoudn;t limit this doc to just this use case. The doc should only talk about the router and conductor.
docs/sec-conductor-onboard.md
Outdated
|
|
||
| The next step in the process is to generate an onboarding token from conductor Web interface, command line, or using APIs. The generated tokens are signed by the conductor’s private key so that they cannot be altered once generated. The SSR supports two modes; Authority Wide and Router Specific tokens. These are mutually exclusive and are defined in the configuration. | ||
|
|
||
| #### Authority-Wide Tokens |
There was a problem hiding this comment.
This concept is removed from the FS and should be deleted from the doc. We will only support per router tokens.
…tation' into 7.1.0-r2-documentation
…o 7.1.0-r2-documentation
Chr1st0ph3rTurn3r
requested review from
BenMatase and
agrawalkaushik
and removed request for
plessard128
BenMatase
left a comment
BenMatase
left a comment
There was a problem hiding this comment.
Feels like there is some duplicate information in sco doc
|
|
||
| Secure Conductor Onboarding (SCO) provides the ability to onboard a router to a conductor ensuring that each device proves possession of a private key, and that the connection is trusted and authenticated. SCO employs asymmetric cryptography (RSA key pairs) to perform digital signatures and verification. The secure conductor onboarding process leverages the physical or virtual TPM module for mutual authentication. | ||
|
|
||
| When a router has SCO enabled, asset-id based onboarding is disabled. Ports 4505 and 4506 are disabled on the conductor, so any devices not using this feature will fail to onboard to the conductor. In addition, if an SCO enabled device attempts to onboard using the legacy method, the onboarding is rejected. |
There was a problem hiding this comment.
This isn't automatically being done yet. Its a manual step. Do we want to call out the caveat?
docs/sec-conductor-onboard.md
Outdated
|
|
||
| ### Prerequisites | ||
|
|
||
| - The `secure-conductor-onboarding mode` must be enabled |
There was a problem hiding this comment.
This makes it sound like there is only at the authority level. We don't have a mode at the authority at this time
docs/sec-conductor-onboard.md
Outdated
|
|
||
| To provide a secure and mutually authenticated onboarding mechanism, the following information must be configured. | ||
|
|
||
| - Pre-shared key: The onboarding pre-shared key is a 48-character alpha-numeric string, configured at the authority or the router level. This key is mandatory for the SCO process. |
There was a problem hiding this comment.
Not at the authority level for now
docs/sec-conductor-onboard.md
Outdated
|
|
||
| - Pre-shared key: The onboarding pre-shared key is a 48-character alpha-numeric string, configured at the authority or the router level. This key is mandatory for the SCO process. | ||
| - Conductor Public certificate: A public-private key certificate. | ||
| - Conductor CA certificate: Optionally, you can configure a public certificate signed by a preferred CA signing authority. |
docs/sec-conductor-onboard.md
Outdated
| After the user generates an onboarding token, enter the token and other onboarding details in the onboarding UI or using CLI commands. There are two methods to onboard a router: | ||
| - Using the Command line: `secure-conductor-onboarding-token` command and `onboarding-config.json`. |
There was a problem hiding this comment.
- Using the Command line: `create secure-conductor-onboarding token` command and `onboarding-config.json`.
docs/sec-conductor-onboard.md
Outdated
| 4. The router connects to the conductor over port 930 using the SSH keys exchanged in previous steps. | ||
| 5. The router is prepped and initialized by the conductor. During this process, the system goes through the reboot cycle. | ||
| Once the secure SSH tunnels are established, the SCO workflow concludes. All future communication between the router and conductor will occur on standard SSR to conductor ports such as 930, 4505, 4506, etc. |
There was a problem hiding this comment.
If SCO happens, won't use 4505/4506 from that point on. Everything is over 930
docs/sec-conductor-onboard.md
Outdated
| `configure authority router secure-conductor-onboarding pre-shared-secret` | ||
| The pre-shared secret is a 48-character alpha-numeric string. When enabled, any empty PSK will auto generate a random 48-byte alphanumeric string using the FIPS-approved, highly secure DRBG function from OpenSSL. Once generated, the key does not automatically change. It can be updated by the user if necessary. |
There was a problem hiding this comment.
This is not complete yet
docs/sec-conductor-onboard.md
Outdated
| ### Token Contents | ||
| The next step in the process is to generate an onboarding token from the conductor Web interface, command line, or using APIs. The generated tokens are signed by the conductor’s private key so that they cannot be altered once generated. The SSR supports two modes; Authority-wide and Router-specific tokens. These are mutually exclusive and are defined in the configuration. |
There was a problem hiding this comment.
I think this doc needs to be scrubbed of "authority wide" tokens for now
docs/sec-conductor-onboard.md
Outdated
| The following parameters are required, and are configured at the Router level. | ||
| `configure authority router secure-conductor-onboarding mode` |
There was a problem hiding this comment.
This might not match the func spec exactly, but the router level path is at configure authority router system secure-conductor-onboarding. This applies to the other paths in the doc
docs/config-smart-download.md
Outdated
| ### Auto-resume Download on WAN Failures | ||
|
|
||
| In the event that all sources have reached the threshold of consecutive failures and a download attempt has failed, the SSR can be configured to wait for a specified amount of time and then retry the download. If a connection is successfully made, the download will resume where it left off. | ||
| In the event that all sources have reached the threshold of consecutive failures and a download attempt has returned an error, the SSR can be configured to wait for a specified amount of time and then retry the download. If a connection is successfully made, the download will resume where it left off. Use the `software-update download enable-timeout` command to enable the retry feature. |
There was a problem hiding this comment.
The enable-timeout field is separate from retries. The only thing it enables is the timeout described in the next paragraph, and retries will happen regardless of whether the timeout is enabled
docs/config-smart-download.md
Outdated
| In the event that all sources have reached the threshold of consecutive failures and a download attempt has returned an error, the SSR can be configured to wait for a specified amount of time and then retry the download. If a connection is successfully made, the download will resume where it left off. Use the `software-update download enable-timeout` command to enable the retry feature. | ||
|
|
||
| When the timeout is enabled, the SSR waits for a configurable amount of time (default is 10800s) for the download to complete. When the timeout value is reached, the download is marked as **Failed** and the retry delay begins. | ||
| When the timeout is enabled (software-update download enable-timeout true) the SSR will wait for a configurable amount of time (default is 10800s) for the download to complete. If the timeout value is reached without successfully downloading the software, the download is marked as "Failed". |
There was a problem hiding this comment.
Is it worth noting that the timeout is enabled by default?
docs/config-smart-download.md
Outdated
| The retry delay time is the longest time to wait between retry attempts. For example, the initial retry delay starts at 30 seconds. With each failure the delay is increased exponentially. However, when that calculated value reaches the maximum retry delay time, successive wait times for additional attempts do not exceed the maximium retry delay time. The default is 3600 seconds. A maximum number of times to retry can also be configured. | ||
|
|
||
| The retry timeout can be disabled. If it is disabled, the download will retry indefinitely. | ||
| If the retry timeout is disabled, the download will retry indefinitely |
There was a problem hiding this comment.
As mentioned above, the timeout is a separate mechanism from the retries, so I wouldn't necessarily describe it as a retry timeout. And the download would only retry indefinitely if both the timeout is disabled and the attempts is configured to 0.
docs/config-smart-download.md
Outdated
|
|
||
| ### Sequenced HA Download | ||
|
|
||
| The SSR supports sequenced downloading; one node of an HA pair downloads an image from the remote repository, and the other node waits for it to complete. Once that download is complete, the second node downloads it from the first. When targeting an HA router, the download is sequenced by default. To disable this sequencing, use `request system software download simultaneous disable`. |
There was a problem hiding this comment.
Update: I ended up making the download unsequenced by default. I may change that in the future, but in the beta we're giving Swift, it will be unsequenced.
In order to do a sequenced download, you would use request system software download router RouterName version SSR-X.Y.Z sequenced
docs/sec-conductor-onboard.md
Outdated
| After the user generates an onboarding token, enter the token and other onboarding details in the onboarding UI or using CLI commands. There are two methods to onboard a router: | ||
| - Using the Command line: `create secure-conductor-onboarding-token` command and `onboarding-config.json`. |
There was a problem hiding this comment.
The command still needs to be fixed
There was a problem hiding this comment.
What is wrong with it? I copied your command from the earlier review. Am I missing something?
docs/sec-conductor-onboard.md
Outdated
| To enable this feature on the conductor, verify the following: | ||
| - The `secure conductor onboarding mode` should not be disabled (see above). |
There was a problem hiding this comment.
This line should be removed. The conductor/whole authority doesn't have a mode
docs/sec-conductor-onboard.md
Outdated
| The CA certificate is read from disk at the location given in `secure-conductor-onboarding ca-certificate`. | ||
| ## Token Management |
There was a problem hiding this comment.
This section is a dup of the Token Creation section and can be removed
docs/config-smart-download.md
Outdated
| In the event that all sources have reached the threshold of consecutive failures and a download attempt has returned an error, the SSR can be configured to wait for a specified amount of time and then retry the download. If a connection is successfully made, the download will resume where it left off. | ||
|
|
||
| When the timeout is enabled (software-update download enable-timeout true) the SSR will wait for a configurable amount of time (default is 10800s) for the download to complete. If the timeout value is reached without successfully downloading the software, the download is marked as "Failed". | ||
| The timeout is enabled by default (`software-update download enable-timeout true`). The SSR waits for a configurable amount of time (default is 10800s) for the download to complete. If the timeout value is reached without successfully downloading the software, the download is marked as "Failed". |
There was a problem hiding this comment.
This is accurate, but something I hadn't thought of when reviewing before is that the retry configuration in the paragraph below is probably more significant than the timeout configuration, so I might swap the two paragraphs.
docs/config-smart-download.md
Outdated
| When the timeout is enabled (software-update download enable-timeout true) the SSR will wait for a configurable amount of time (default is 10800s) for the download to complete. If the timeout value is reached without successfully downloading the software, the download is marked as "Failed". | ||
| The timeout is enabled by default (`software-update download enable-timeout true`). The SSR waits for a configurable amount of time (default is 10800s) for the download to complete. If the timeout value is reached without successfully downloading the software, the download is marked as "Failed". | ||
|
|
||
| The retry delay time is the longest time to wait between retry attempts. For example, the initial retry delay starts at 30 seconds. With each failure the delay is increased exponentially. However, when that calculated value reaches the maximum retry delay time, successive wait times for additional attempts do not exceed the maximium retry delay time. The default is 3600 seconds. A maximum number of times to retry can also be configured. |
docs/config-smart-download.md
Outdated
|
|
||
| If the retry timeout is disabled, the download will retry indefinitely | ||
|
|
||
| Use the command `configure authority router system software-update download enable-timeout [enabled]` to enable auto-resume. The command parameters are listed below: |
There was a problem hiding this comment.
The enable-timeout field doesn't really enable auto-resume. It's just a way you can tune the behavior to meet your needs. Maybe something along the lines of this would be more accurate?
Use the command
configure authority router system software-update downloadto adjust the download retry behavior. The command parameters are listed below:
docs/config-smart-download.md
Outdated
| - `enable-timeout`: True/false, default is true. This enables a time limit for the overall download. | ||
| - `timeout`: Amount of time in seconds that the SSR waits for the software download to complete. When the timeout value is reached the download is marked as **Failed**, and the retry delay begins. The default download wait time is 10800s. Range is 1800s - 604800s. | ||
| - `attempts`: The maximum number of attempts to download before considering the download as failed. If set to 0, the SSR will retry the download until the timeout is hit. Default is 10. | ||
| - `max retry delay`: The maximum amount of time in seconds to wait in between retry attempts. The retry delay will start off low and back off exponentially up to this duration. Range is 0 to 86400s. Default is 3600s. |
docs/enhanced-sec-key-mgmt.md
Outdated
| 4. Decapsulation: The receiver uses their private keys (SK1,SK2, etc.) in reverse order to decrypt each layer: | ||
| - Cn−1 = Decapsulate(Cn, SKn). This is repeated until the original symmetric key `K` is retrieved. | ||
|
|
||
| ### Certificate Considerations |
There was a problem hiding this comment.
ML-DSA, needed for PQC certificates, is not yet supported in the product and is not scheduled for 7.1.3-R2. I'm of the opinion that we should not be discussing PQC certificates here. ML-KEM does not need PCQ certificates to operate.
There was a problem hiding this comment.
Mike I'm not sure what in this section you are referring to. I'm not familiar with PQC (post quantum certificates?) or where ML-DSA is referenced. Can you clarify a bit? Thanks.
There was a problem hiding this comment.
Ah, the entire ### Certificate Considerations section needs to be removed. In conjunction with ML-KEM, an X.509 certificate must be selected to align with the cryptographic requirements of the protocol. is false as there are no certificate considerations taking place here for this release.
docs/concepts-config-integrity.md
Outdated
|
|
||
| Modern compliance requirements and regulatory frameworks mandate encryption-at-rest for sensitive data, particularly in industries handling financial transactions, healthcare records, or government communications. High-security customers in financial services, government, and healthcare sectors require robust protection against data exfiltration to maintain their security posture and meet regulatory obligations. These requirements have evolved beyond simple access controls to demand cryptographic protection of stored credentials, configuration data, and private key material that could be exploited to compromise broader network infrastructure. | ||
|
|
||
| SSR Configuration Integrity prevents unauthorized access to SSR configuration files when the system is powered off and physically compromised, ensuring that sensitive routing configurations, authentication credentials, and network topology information cannot be extracted through direct storage access. The system protects private keys and certificates from extraction via physical storage access, preventing attackers from impersonating network nodes or intercepting encrypted communications. Most importantly, it meets compliance requirements for encryption-at-rest without impacting runtime performance, allowing organizations to satisfy regulatory mandates while maintaining the high-performance networking capabilities that SSR devices are designed to provide. |
There was a problem hiding this comment.
SSR Configuration Integrity prevents unauthorized access to SSR configuration files when the system is powered off and physically compromised, ensuring
This reads to me as muddling two different behaviors into one comment.
- It prevents access when the system is powered off. (e.g. encryption at rest prevents data scrubbing)
- It prevents SSR from running when physically compromised.
Perhaps break this apart along the lines of:
SSR Configuration Integrity prevents unauthorized access to SSR files when the system is powered off and prevents SSR operations when the system is compromised, ensuring...
docs/concepts-config-integrity.md
Outdated
| ### Hardware Bootstrapper | ||
|
|
||
| The hardware bootstrapper is an existing component of the SSR, responsible for the initialization of the SSR during its first boot. It performs the enablement requirements check (detailed below) to verify that the system can support Configuration Integrity, and if so, go through the steps to enable it for the lifetime of the system. This workflow will be explained in more detail in a later section. |
There was a problem hiding this comment.
The integrity handler is responsible for almost everything that you wrote here, not the HWB. I think this entire paragraph can be removed.
There was a problem hiding this comment.
Agreed, lets remove the hardware bootstrapper section
docs/concepts-config-integrity.md
Outdated
| 3. Pass unencrypted FEMK to fscrypt. | ||
| 4. fscrypt uses the FEMK to automatically unlock the necessary encrypted directories. | ||
|
|
||
| If any of these steps fail, it is interpreted as an integrity event, an emergency log is generated (which is also broadcast to all consoles on the system) that the system has had its integrity compromised and it must be reprovisioned. The SSR will repeatedly try to start the integrity service to unlock the encrypted directories and fail, each time writing the emergency log. |
There was a problem hiding this comment.
We should probably mention that it blocks the operation of networking in the event of a failure, because we can not operate normally if the integrity of the system has been violated. Any recovery steps require physical access, e.g. to reimage the system with a fresh ISO.
docs/concepts-config-integrity.md
Outdated
|
|
||
| ### Logging | ||
|
|
||
| Logging is handled through existing system components rather than a dedicated log category. During initial system provisioning, the Hardware Bootstrapper handles all Configuration Integrity initialization logging as part of its standard provisioning process. On subsequent boots, the systemd service that is responsible for unlocking encrypted directories logs all unlock operations and service status information through the systemd journal. This provides comprehensive visibility into the operational state of the encryption system during the boot sequence. |
There was a problem hiding this comment.
Remove HWB from this as well. Also should probably include journalctl -u integrity-handler.
docs/concepts-config-integrity.md
Outdated
| 3. Pass unencrypted FEMK to fscrypt. | ||
| 4. fscrypt uses the FEMK to automatically unlock the necessary encrypted directories. | ||
|
|
||
| If any of these steps fail, it is interpreted as an integrity event, an emergency log is generated (which is also broadcast to all consoles on the system) that the system has had its integrity compromised and it must be reprovisioned. The SSR will repeatedly try to start the integrity service to unlock the encrypted directories and fail, each time writing the emergency log. |
There was a problem hiding this comment.
Please add the output of the broadcast message to this section.
|
|
||
| If any of these steps fail, it is interpreted as an integrity event, an emergency log is generated (which is also broadcast to all consoles on the system) that the system has had its integrity compromised and it must be reprovisioned. The SSR will repeatedly try to start the integrity service to unlock the encrypted directories and fail, each time writing the emergency log. | ||
|
|
||
| ## Troubleshooting |
There was a problem hiding this comment.
Add a subsection to troubleshooting for what to do when a system has been compromised: Zeroize -> Factory Reset, or RMA.
There was a problem hiding this comment.
No factory reset unfortunately, because some of the directories we need for the factory reset will be locked, and we won't be able to unlock them due to the compromise. The only options are clean install or RMA.
Co-authored-by: Mike Adams <75860404+madamsJuniper@users.noreply.github.com>
Co-authored-by: Adam Drescher <adrescher@juniper.net>
Co-authored-by: Adam Drescher <adrescher@juniper.net>
Co-authored-by: Adam Drescher <adrescher@juniper.net>
docs/enhanced-sec-key-mgmt.md
Outdated
| 4. Decapsulation: The receiver uses their private keys (SK1,SK2, etc.) in reverse order to decrypt each layer: | ||
| - Cn−1 = Decapsulate(Cn, SKn). This is repeated until the original symmetric key `K` is retrieved. | ||
|
|
||
| ### Certificate Considerations |
There was a problem hiding this comment.
Ah, the entire ### Certificate Considerations section needs to be removed. In conjunction with ML-KEM, an X.509 certificate must be selected to align with the cryptographic requirements of the protocol. is false as there are no certificate considerations taking place here for this release.
docs/concepts-config-integrity.md
Outdated
| ### Hardware Bootstrapper | ||
|
|
||
| The hardware bootstrapper is an existing component of the SSR, responsible for the initialization of the SSR during its first boot. It performs the enablement requirements check (detailed below) to verify that the system can support Configuration Integrity, and if so, go through the steps to enable it for the lifetime of the system. This workflow will be explained in more detail in a later section. |
There was a problem hiding this comment.
Agreed, lets remove the hardware bootstrapper section
Co-authored-by: Craig Nesbitt <cnesbitt@juniper.net>
Co-authored-by: Adam Drescher <adrescher@juniper.net>
Co-authored-by: Adam Drescher <adrescher@juniper.net>
Co-authored-by: Adam Drescher <adrescher@juniper.net>
Chr1st0ph3rTurn3r
requested review from
MichaelBaj,
adrescher-JNPR,
cnesbitt-JNPR,
madamsJuniper and
robert-patterson
docs/concepts-config-integrity.md
Outdated
| 4. fscrypt uses the FEK to automatically unlock the necessary encrypted directories. | ||
|
|
||
| This systemd service handles the subsequent boots of the SSR after Configuration Integrity has been enabled. It runs a series of integrity checks, and identifies when the system is ready to continue operation after successful unlocking of the encrypted directories. When it is run, it performs the following sequence: | ||
| If any of these steps fail, it is interpreted as an integrity event. Network activities are blocked. An emergency log is generated and broadcast to all consoles on the system that the system integrity is compromised and it must be reprovisioned. The SSR will repeatedly try to start the integrity service to unlock the encrypted directories and fail, each time writing the emergency log. |
There was a problem hiding this comment.
extra space after "system"
No description provided.