Skip to content

Update SSH installer documentation for post-quantum KEX hardening #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Stensel8 merged 2 commits into from
Mar 30, 2026
+26 −21
Merged

Update SSH installer documentation for post-quantum KEX hardening #58

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fcc964a
Initial plan
Claude Mar 30, 2026
9eeb58c
Update SSH installer: add post-quantum KEX comments
Claude Mar 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 26 additions & 21 deletions openssh/openssh_installer.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,22 @@
#########################################################################
# OpenSSH Hardened Configuration Installer
#
# Installs OpenSSH and applies a maximally hardened configuration.
# Designed for modern systems where password authentication over SSH
# is considered obsolete and insecure.
# Ed25519-only · No password auth · Post-quantum hardened
#
# Philosophy:
# SSH keys are the only acceptable authentication method for remote
# access. Passwords belong exclusively in sudo as a second layer,
# never as SSH authentication.
#
# Recommendation: store your SSH private keys in Bitwarden (SSH Agent
# feature) or another password manager. This gives you:
# - Encrypted key storage
# - Cross-device key sync
# - Audit log of key usage
# - Easy revocation
# feature) or another password manager.
#
# External access: PKI auth only, FUTURE crypto policy (Fedora/RHEL)
# Internal access: PKI auth only, sudo for privilege escalation
#
# OpenSSH official website: https://www.openssh.com/
# Crypto policy:
# This script does not require or enforce Fedora/RHEL FUTURE crypto
# policy. It independently applies strong, post-quantum-aware settings
# that align with FUTURE in spirit — Ed25519, curve25519, AES-256,
# SHA-2 — while adding ML-KEM (Kyber) key exchange to mitigate
# store-now-decrypt-later attacks. No FUTURE policy activation needed.
#########################################################################

set -euo pipefail
Expand Down Expand Up @@ -71,7 +67,7 @@ print_header() {
echo
echo -e "${BOLD}OpenSSH Hardened Configuration Installer${NC}"
echo -e "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo -e "Ed25519-only · No password auth · FUTURE crypto policy compatible"
echo -e "Ed25519-only · No password auth · Post-quantum hardened"
echo -e "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo
}
Expand Down Expand Up @@ -139,7 +135,7 @@ configure_ssh() {
cat > "$tmp_config" << 'EOF'
# =============================================================================
# Hardened OpenSSH Server Configuration
# Ed25519-only · No password auth · FUTURE crypto policy compatible
# Ed25519-only · No password auth · Post-quantum hardened
#
# CVE mitigations:
# CVE-2023-51767 — Ed25519 only (no RSA)
Expand All @@ -158,8 +154,12 @@ configure_ssh() {
# Use passwords only for sudo (local privilege escalation), never for
# SSH authentication itself.
#
# External access: PKI auth only, FUTURE crypto policy (Fedora/RHEL)
# Internal access: PKI auth only, sudo as the second layer
# Crypto policy:
# This script does not require or enforce Fedora/RHEL FUTURE crypto
# policy. It independently applies strong, post-quantum-aware settings
# that align with FUTURE in spirit — Ed25519, curve25519, AES-256,
# SHA-2 — while adding ML-KEM (Kyber) key exchange to mitigate
# store-now-decrypt-later attacks. No FUTURE policy activation needed.
# =============================================================================

# -----------------------------------------------------------------------------
Expand Down Expand Up @@ -221,11 +221,16 @@ ClientAliveCountMax 2
TCPKeepAlive no

# -----------------------------------------------------------------------------
# Cryptographic Algorithms — FUTURE policy compatible
# Ed25519 + curve25519 + AES-256 + SHA-256+ only
# Cryptographic Algorithms — Post-quantum hardened
#
# Goal: mitigate store-now-decrypt-later (SNDL) attacks by adding a
# post-quantum key exchange (ML-KEM / FIPS 203) alongside classical
# curve25519. This does not require FUTURE crypto policy to be active.
#
# Ed25519 + ML-KEM + curve25519 + AES-256 + SHA-2 only
# No RSA, no ECDSA, no SHA-1, no AES-128
# -----------------------------------------------------------------------------
KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.org
KexAlgorithms mlkem768x25519-sha256,curve25519-sha256,curve25519-sha256@libssh.org

Copilot AI Mar 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

KexAlgorithms now includes mlkem768x25519-sha256. On systems with an OpenSSH build that doesn’t support this KEX name, sshd -t -f "$tmp_config" will fail with a “Bad KexAlgorithms” style error and the installer will abort (because set -e propagates the non-zero return). Consider gating this by checking sshd -Q kex (or ssh -Q kex) and only prepending ML-KEM when supported, or documenting/enforcing a minimum OpenSSH version.

Suggested change
KexAlgorithms mlkem768x25519-sha256,curve25519-sha256,curve25519-sha256@libssh.org
KexAlgorithms curve25519-sha256,curve25519-sha256@libssh.org
# To enable hybrid post-quantum KEX (ML-KEM / FIPS 203), ensure your OpenSSH
# build supports "mlkem768x25519-sha256" (check with: sshd -Q kex | grep mlkem768x25519-sha256)
# and then replace the line above with the following:
# KexAlgorithms mlkem768x25519-sha256,curve25519-sha256,curve25519-sha256@libssh.org

Copilot uses AI. Check for mistakes.

Copilot AI Mar 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

PR description says the KEX configuration was already present and this PR is documentation-only, but this change modifies the generated sshd_config by changing KexAlgorithms (adds mlkem768x25519-sha256). Please update the PR description to reflect the behavioral change or revert the config line change if it’s out of scope.

Copilot uses AI. Check for mistakes.
Ciphers chacha20-poly1305@openssh.com,aes256-gcm@openssh.com
MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com
Comment on lines +230 to 235

Copilot AI Mar 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comment claims “Ed25519 + ML-KEM + curve25519 + AES-256 + SHA-2 only”, but the actual Ciphers list also enables chacha20-poly1305@openssh.com. Consider updating the comment to reflect the real cipher set (e.g., “ChaCha20-Poly1305 and AES-256-GCM only”) so the documentation matches the enforced config.

Copilot uses AI. Check for mistakes.
HostKeyAlgorithms ssh-ed25519
Expand Down Expand Up @@ -325,7 +330,8 @@ show_summary() {
echo -e "${GREEN}✓${NC} $ssh_version installed"
echo -e "${GREEN}✓${NC} Ed25519-only host key"
echo -e "${GREEN}✓${NC} Password authentication disabled"
echo -e "${GREEN}✓${NC} FUTURE crypto policy compatible"
echo -e "${GREEN}✓${NC} Post-quantum KEX (ML-KEM / mlkem768x25519)"

Copilot AI Mar 30, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary text refers to mlkem768x25519 but the configured KEX name is mlkem768x25519-sha256. To avoid confusion when users cross-check the effective sshd_config, consider printing the full algorithm identifier (or matching whatever is actually configured after any feature-detection/fallback logic).

Suggested change
echo -e "${GREEN}✓${NC} Post-quantum KEX (ML-KEM / mlkem768x25519)"
echo -e "${GREEN}✓${NC} Post-quantum KEX (ML-KEM / mlkem768x25519-sha256)"

Copilot uses AI. Check for mistakes.
echo -e "${GREEN}✓${NC} Aligned with FUTURE crypto policy (not required)"
echo -e "${GREEN}✓${NC} All forwarding disabled"
echo -e "${GREEN}✓${NC} CVE mitigations applied"
systemctl is-active --quiet "$SSH_SERVICE" \
Expand All @@ -345,7 +351,6 @@ show_summary() {
echo -e "1. Add your public key: ${BLUE}ssh-copy-id user@host${NC}"
echo -e "2. Test login: ${BLUE}ssh user@${ip_hint}${NC}"
echo -e "3. Store key in: ${BLUE}Bitwarden SSH Agent${NC}"
echo -e "4. On Fedora/RHEL: ${BLUE}sudo update-crypto-policies --set FUTURE${NC}"
echo
echo -e "${YELLOW}Emergency password access:${NC}"
echo -e "Uncomment ${BLUE}PasswordAuthentication yes${NC} in $CONFIG_FILE"
Expand Down
Loading