[Server] add XrdSecssh plugin with tests and packaging

Add the new TLS-only XrdSecssh security plugin (sec.protocol ssh) for
SSH-key-based authentication, together with its documentation, unit
tests and packaging integration.

Plugin (src/XrdSecssh/XrdSecProtocolssh.cc):
- Raw-key authentication (ssh-ed25519, ssh-rsa) with a server-side
  keys-file mapping keys to local users (explicit and authorized_keys
  comment-style mappings).
- OpenSSH user certificate authentication validated against a
  configurable ca-keys-file: signature is verified against a trusted CA,
  the certificate must be a user certificate (type=1), the validity
  window is enforced, and any critical option causes a fail-closed
  rejection.
- Principal-to-local-user mapping via -principal-as-user and/or a
  hot-reloaded -principal-map[-file].
- Two-step challenge/response handshake using a single-use, TTL-bounded
  random nonce; the signed payload binds the nonce to the presented
  key/certificate fingerprint.
- Client support for private-key files (PEM/PKCS8 ed25519/rsa) and
  ssh-agent (including certificate identities), with fingerprint-based
  identity selection.
- Hardening: TLS is mandatory; key/CA/principal-map files are loaded via
  an O_NOFOLLOW, fstat-based safe reader (regular file, owner == euid,
  not group/other writable, size-capped); RSA uses rsa-sha2-256;
  pending-challenge state is capped and garbage-collected; and SSH blob
  length parsing uses 64-bit arithmetic so attacker-supplied 32-bit
  lengths cannot wrap.
- Use RAII wrappers for OpenSSL handles and owning unique_ptr storage
  for trusted keys and client private keys; allocate protocol/credential
  objects with make_unique().release() for the XRootD C APIs.
- Further hardening: cap per-field SSH wire blobs and keys-file lines;
  reject duplicate pending challenges per tident; synchronize principal
  map reload/lookup; require client private keys and ssh-agent sockets to
  be user-owned and not group/other accessible; validate mapped usernames;
  and redact fingerprints in debug logs.

Documentation (src/XrdSecssh/README.md):
- Document the server/client configuration, file formats, option ranges
  (-maxsz 1..524288, -nonce-ttl 1..600), the file-ownership requirement,
  startup-only vs. hot-reloaded files, the rsa-sha2-256 requirement, the
  ssh-agent requirement for client certificate auth, and a security
  considerations section (TLS-reliance / no channel binding, trusted-CA
  implications, parser limits, and debug-log redaction).

Tests (tests/XrdSec/XrdSecSSH.cc):
- GoogleTest unit tests that exercise the plugin internals directly,
  covering blob/length parsing, the safe file reader, key/CA loading,
  sign/verify for ed25519 and rsa, the full raw-key and certificate
  handshakes, principal mapping and hot-reload, and negative cases
  including untrusted keys/CAs, bad/replayed signatures, expired and
  not-yet-valid certificates, wrong certificate type, critical options,
  signature-algorithm mismatch, malformed/truncated inputs, oversized
  credentials and invalid configuration options.
- Add tests for wire-field size limits, duplicate pending challenges,
  invalid keys-file usernames, client key permission checks, and
  username validation.

Build/packaging:
- Register libXrdSecssh.so in XrdVersionPlugin.hh, build it from
  src/CMakeLists.txt, wire up the tests/XrdSec unit-test target, and add
  the plugin to the RPM (xrootd.spec), Debian (xrootd-plugins.install)
  and Python install documentation.

Assisted-by: Cursor:Opus-4.8 CursorAI

Author: apeters1971

debian/xrootd-plugins.install

@@ -10,3 +10,4 @@
 /usr/lib/*/libXrdSecsss-6.so
 /usr/lib/*/libXrdSecunix-6.so
 /usr/lib/*/libXrdSecztn-6.so
+/usr/lib/*/libXrdSecssh-6.so

python/docs/source/install.rst

@@ -166,6 +166,7 @@ In this case, the structure is a bit different than before::
   |   |-- libXrdSecgsiAUTHZVO-5.so
   |   |-- libXrdSecgsiGMAPDN-5.so
   |   |-- libXrdSeckrb5-5.so
+  |   |-- libXrdSecssh-5.so
   |   |-- libXrdSecpwd-5.so
   |   |-- libXrdSecsss-5.so
   |   |-- libXrdSecunix-5.so

src/CMakeLists.txt

@@ -62,6 +62,7 @@ add_subdirectory( XrdPosix )
 add_subdirectory( XrdSec )
 add_subdirectory( XrdSecgsi )
 add_subdirectory( XrdSeckrb5 )
+add_subdirectory( XrdSecssh )
 add_subdirectory( XrdSecpwd )
 add_subdirectory( XrdSecsss )
 add_subdirectory( XrdSecunix )

src/XrdSecssh/CMakeLists.txt

@@ -0,0 +1,12 @@
+if( XRDCL_ONLY )
+  return()
+endif()
+
+set(XrdSecssh XrdSecssh-${PLUGIN_VERSION})
+
+find_package(OpenSSL REQUIRED)
+
+add_library(${XrdSecssh} MODULE XrdSecProtocolssh.cc)
+target_link_libraries(${XrdSecssh} PRIVATE XrdUtils OpenSSL::Crypto)
+
+install(TARGETS ${XrdSecssh} LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR})

src/XrdSecssh/README.md

@@ -0,0 +1,226 @@
+# XrdSecssh
+
+`XrdSecssh` is an experimental XRootD security protocol plugin (`sec.protocol ssh`)
+for SSH-key-based authentication over TLS.
+
+## V1 behavior
+
+- Raw key mode and OpenSSH user certificate mode
+- Server trust source:
+  - `keys-file` for raw key -> user mapping
+  - optional `ca-keys-file` for user certificate validation
+- Supported raw key algorithms: `ssh-ed25519`, `ssh-rsa`
+- Supported user certificate algorithms: `ssh-ed25519-cert-v01@openssh.com`,
+  `ssh-rsa-cert-v01@openssh.com`
+- Two-step handshake:
+  1. client sends user + SSH key/certificate blob
+  2. server sends nonce challenge
+  3. client signs challenge with private key
+  4. server verifies signature and maps to local username
+
+## Server configuration
+
+```conf
+sec.protocol ssh \
+  -keys-file /etc/xrootd/ssh_authorized_keys \
+  -ca-keys-file /etc/xrootd/ssh_ca_keys \
+  -principal-as-user \
+  -principal-map \
+  -maxsz 8192 \
+  -nonce-ttl 30 \
+  -debug
+```
+
+`keys-file` security checks:
+
+- opened with `O_NOFOLLOW` (symlinks are rejected)
+- must be a regular file
+- must be owned by the effective xrootd uid
+- must not be group/other writable
+- must not exceed 10 MB
+
+The same security checks apply to `ca-keys-file` when configured.
+The same security checks apply to `principal-map-file` when configured.
+
+> **Note:** the ownership check requires the file to be owned by the *effective*
+> uid the `xrootd` process runs as. A `root`-owned key file will be rejected when
+> `xrootd` runs as an unprivileged service account; make the key files owned by
+> that account.
+
+`-keys-file` and `-ca-keys-file` are read once at plugin initialization, so a
+restart is required to pick up changes. Only the `principal-map-file` is
+hot-reloaded (see below).
+
+Validated option ranges:
+
+- `-maxsz <bytes>`: `1`..`524288` (default `8192`)
+- `-nonce-ttl <seconds>`: `1`..`600` (default `30`)
+
+### keys-file format
+
+Accepted line formats:
+
+1. Explicit user mapping:
+
+```text
+foo ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...
+foo ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...
+```
+
+2. Authorized-keys style fallback mapping (username extracted from comment prefix before `@`):
+
+```text
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... foo@host
+ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ... foo@host
+```
+
+### ca-keys-file format (optional)
+
+Each line should contain a CA public key:
+
+```text
+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...
+ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...
+```
+
+Also accepted:
+
+```text
+cert-authority ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI...
+```
+
+When a user certificate is presented, the server validates:
+
+- certificate signature against a trusted CA key
+- certificate type is user (`type=1`)
+- validity window (`valid_after` / `valid_before`)
+- certificate carries no critical options (any critical option is rejected,
+  i.e. the server fails closed on options such as `force-command` or
+  `source-address` that it does not enforce)
+- principals contain requested user (if principals list is non-empty)
+
+> **Security note:** following OpenSSH semantics, a certificate with an *empty*
+> principals list is treated as valid for any requested user. Because the CA is
+> fully trusted, only issue zero-principal user certificates if every holder is
+> meant to authenticate as an arbitrary account.
+
+### Principal mapping options (cert mode)
+
+Server options:
+
+- `-principal-as-user`:
+  map a certificate principal directly to local account if it is a valid
+  local username or uid.
+- `-principal-map`:
+  enable principal mapping file at default path (no argument)
+  `/etc/xrootd/ssh_principals.map`.
+- `-principal-map-file <path>`:
+  use a custom principal mapping file.
+
+If both direct and file mapping are enabled, direct principal->local-user
+mapping is tried first, then the map file.
+
+Map file format:
+
+```text
+principal-a alice
+principal-b 1001
+```
+
+Each line is `<principal> <username|uid>`.
+
+The principal map file is monitored during authentication and is reloaded
+automatically if its inode or mtime changes.
+
+## Client configuration
+
+> **Certificate clients:** private key *file* mode only supports raw
+> `ssh-ed25519` / `ssh-rsa` keys. To authenticate with an OpenSSH user
+> certificate, the client must use `ssh-agent` mode (the certificate identity is
+> selected from the agent).
+
+Default mode uses a private key file (PEM/PKCS8 format; supported key types: ed25519, rsa):
+
+```sh
+export XRD_SSH_KEY_FILE=/path/to/ed25519-private.pem
+```
+
+`XRD_SSH_PRIVATE_KEY_FILE` is accepted as an alias and is consulted when
+`XRD_SSH_KEY_FILE` is unset.
+
+Client `ssh-agent` mode is also supported:
+
+```sh
+export SSH_AUTH_SOCK=/run/user/1000/ssh-agent.socket
+export XRD_SSH_AGENT=1
+```
+
+When `XRD_SSH_AGENT=1`, the client picks a supported identity from the agent
+and signs the server challenge via agent.
+
+Supported agent identities:
+
+- raw keys: `ssh-ed25519`, `ssh-rsa`
+- user certificates: `ssh-ed25519-cert-v01@openssh.com`,
+  `ssh-rsa-cert-v01@openssh.com`
+
+Optional key selection by fingerprint:
+
+```sh
+export XRD_SSH_AGENT_FINGERPRINT='SHA256:base64fingerprint'
+```
+
+Fallback behavior:
+
+- if `XRD_SSH_AGENT` is not set, key-file mode is tried first
+- if key-file is not configured and `SSH_AUTH_SOCK` exists, agent mode is used
+- if not in agent mode, no key-file env is set, and `XRD_SSH_USER` is not set,
+  the client also tries default key files in order:
+  - `~/.ssh/id_ed25519`
+  - `~/.ssh/id_rsa`
+- if all methods fail, authentication fails with a detailed error
+
+Optional username override:
+
+```sh
+export XRD_SSH_USER=foo
+```
+
+If `XRD_SSH_USER` is not set, `USER` is used.
+
+## Notes
+
+- TLS is mandatory (`needTLS() == true`)
+- handshake nonce is single-use and expires after `-nonce-ttl`
+- debug logging can be enabled via `-debug` or `XrdSecDEBUG=1`; it prints
+  loaded key metadata (alg/user/fingerprint) and authentication key selection
+- RSA signatures (challenge responses and certificate signatures) use
+  `rsa-sha2-256`. Legacy `ssh-rsa` (SHA-1) signatures are not accepted, so RSA
+  certificates must be signed by a CA using `rsa-sha2-256`.
+
+## Security considerations
+
+- This protocol authenticates the *client* to the server. It does not
+  authenticate the server within the handshake and provides no channel binding
+  between the SSH challenge/response and the underlying TLS session. Its safety
+  therefore relies on TLS with server-certificate verification to prevent
+  man-in-the-middle relay of the signed challenge; do not disable TLS peer
+  verification.
+- The challenge is signed over `xrdsec-ssh-v1|<nonce>|<fingerprint>`, binding the
+  response to the presented key/certificate and the single-use server nonce.
+- Only one pending challenge is allowed per transport identity (`tident`); a
+  second init on the same connection is rejected with `EBUSY`.
+- SSH wire string fields are capped at 64 KiB; `keys-file` lines and base64 key
+  material have separate limits to reduce parser DoS risk at init.
+- Client private key files must be owned by the effective uid and must not be
+  group/other accessible; `ssh-agent` sockets must be owned by the effective uid
+  and must not be group/other accessible.
+- Mapped usernames are restricted to a conservative charset and length before
+  being stored in `XrdSecEntity.name`.
+- Debug logging (`-debug` / `XrdSecDEBUG=1`) prints redacted key fingerprints
+  and omits transport usernames and socket paths.
+- The principal map file is reloaded under a mutex so lookups are not racy with
+  hot reload.
+- In certificate mode the CA is fully trusted: any principal it issues is
+  accepted (subject to the validity window, `type=1`, and the no-critical-options
+  rule). Restrict the CA key set in `ca-keys-file` accordingly.