sshalgo

Overview ¶

Package sshalgo provides the SSH algorithm sets a server should offer, filtered for FIPS 140-3 compliance when the binary is built with the fips build tag.

Without the fips build tag the functions return golang.org/x/crypto/ssh's own algorithm sets unchanged, so callers can wire them in unconditionally and let the build tag decide the policy:

config := &ssh.ServerConfig{}

algorithms := sshalgo.DefaultAlgorithms()
config.Ciphers = algorithms.Ciphers
config.MACs = algorithms.MACs
config.KeyExchanges = algorithms.KeyExchanges
config.PublicKeyAuthAlgorithms = algorithms.PublicKeyAuths

signer, err := sshalgo.HostKeySigner(hostKey)
if err != nil {
    return err
}
config.AddHostKey(signer)

Assigning PublicKeyAuthAlgorithms and wrapping each host key are both required, not optional. ssh.ServerConfig has no field that can express either policy on its own: SetDefaults never populates PublicKeyAuthAlgorithms, and a server ignores Config.HostKeyAlgorithms entirely, deriving what it advertises from the keys it was given. Skip them and a FIPS server offers ssh-rsa.

Policy ¶

The algorithms fall into three tiers, because there are three different reasons to withhold one. COMPLIANCE.md gives the per-algorithm mapping to the governing NIST document.

Tier 1 is never offered: ChaCha20-Poly1305, which has no entry in SP 800-140C Rev. 2, and standalone X25519 key agreement, which the FIPS 140-3 Implementation Guidance excludes as a curve in SP 800-186 but not SP 800-56Arev3.

Tier 2 is offered only where the native Go Cryptographic Module is active: the ML-KEM768/X25519 hybrid. ML-KEM-768 supplies an approved shared secret, so the X25519 contribution is permissible additional keying material under SP 800-227 Section 4.6.2, and x/crypto/ssh registers the hybrid ahead of its own FIPS branch so that it survives. It is withheld on BoringCrypto for an operational reason rather than a compliance one: the golang-fips toolchain patches crypto/ecdh to refuse X25519 whenever OpenSSL is active, so the handshake cannot complete.

Tier 3 is offered by default and removed by WithoutDeprecated: the SHA-1 constructions that SP 800-131A deprecates only until 2030-12-31, and finite-field Diffie-Hellman, whose groups are approved safe primes but whose implementation in x/crypto is pure-Go math/big, outside every validated boundary. Withholding these is a hardening choice, not a compliance requirement, so the default keeps older clients working.

Backends ¶

Under the native Go Cryptographic Module (built with GOFIPS140, so crypto/fips140.Enabled reports true) the result is narrowed further to what x/crypto/ssh can actually negotiate: the non-approved algorithms are never registered in its internal maps, and ssh.Config.SetDefaults - which ssh.NewServerConn and ssh.NewClientConn both call unconditionally - drops anything absent from them. Deriving that narrowing rather than hand-maintaining a second list keeps this package in step with the linked module, whose contents depend on GOFIPS140 and may change across Go versions.

Under BoringCrypto (the golang-fips toolchain) crypto/fips140.Enabled reports false, because the OpenSSL backend is invisible to crypto/fips140. x/crypto applies no policy of its own there, so nothing narrows the result.

This package is separate from gitlab.com/gitlab-org/labkit/v2/fips so that services which only need to report their FIPS posture do not take on a golang.org/x/crypto dependency.