feat(keygen): enroll and download FIDO security keys

Cargo.toml

@@ -80,9 +80,12 @@ libc = "0.2"
 # see src/ssh/security_key for why no ssh-sk-helper style subprocess exists.
 libloading = "0.8"
 # The built-in `SecurityKeyProvider internal` (src/ssh/security_key/internal)
-# implements CTAPHID, CTAP2 getAssertion/clientPIN and the U2F fallback in
-# tree; these three only supply the PIN-protocol crypto and are already in the
-# dependency graph through russh/ssh-key, so they add no crate.
+# implements CTAPHID, CTAP2 enrollment/signing/credential management and U2F.
+# Crypto primitives are shared with the existing russh/ssh-key dependency graph.
+# Validate authenticator-provided Ed25519 keys; already in the ssh-key graph.
+ed25519-dalek = "3.0"
+# Parse authenticator attestation certificates without handwritten ASN.1.
+x509-cert = { version = "0.3", default-features = false, features = ["std"] }
 p256 = { version = "0.14", features = ["ecdh", "ecdsa"] }
 aes = "0.9"
 cbc = { version = "0.2", features = ["alloc"] }
@@ -126,9 +129,6 @@ hidapi = { version = "2.6.7", default-features = false, features = ["macos-share
 windows-sys = { version = "0.61", features = ["Win32_Foundation", "Win32_Storage_FileSystem"] }
 
 [dev-dependencies]
-# The mock FIDO authenticator signs Ed25519 assertions; already in the graph
-# through ssh-key.
-ed25519-dalek = "3.0"
 tempfile = "3.27.0"
 mockito = "1.7.2"
 tokio-test = "0.4"

README.md

@@ -602,7 +602,8 @@ See [examples/mpi_exit_code.sh](examples/mpi_exit_code.sh) and [examples/health_
 bssh supports multiple authentication methods:
 
 ### SSH Key Authentication
-- **Default keys**: Automatically tries `~/.ssh/id_ed25519`, `~/.ssh/id_ed25519_sk`, `~/.ssh/id_rsa`, `~/.ssh/id_ecdsa`, `~/.ssh/id_ecdsa_sk`, `~/.ssh/id_dsa` (the `*_sk` FIDO keys sign with an attached authenticator through the built-in `SecurityKeyProvider internal`, or an sk-api library if configured; on Linux the user needs access to the `/dev/hidraw*` device, usually through the FIDO udev rules of the `libfido2` packages; enrollment, resident keys and biometric-only UV tokens are not supported, and Windows needs an sk-api library)
+- **Default keys**: Automatically tries `~/.ssh/id_ed25519`, `~/.ssh/id_ed25519_sk`, `~/.ssh/id_rsa`, `~/.ssh/id_ecdsa`, `~/.ssh/id_ecdsa_sk`, `~/.ssh/id_dsa` (the `*_sk` FIDO keys sign with an attached authenticator through the built-in `SecurityKeyProvider internal`, or an sk-api library if configured; on Linux the user needs access to the `/dev/hidraw*` device, usually through the FIDO udev rules of the `libfido2` packages; CTAP 2.1 biometric UV tokens are supported, and Windows needs an sk-api library)
+- **Security-key enrollment**: `bssh-keygen -t ed25519-sk` or `-t ecdsa-sk` creates OpenSSH keys using the built-in USB HID provider. Add `-O resident -O application=ssh:work -O user=alice` for a resident credential, `-O verify-required` for PIN verification on use, or `-O no-touch-required` where supported. Download resident keys with `bssh-keygen -K` into the current directory; this prompts for the authenticator PIN. Select an external OpenSSH sk-api library with `-w /path/to/provider.so`, or an environment-configured provider with `-w '$SSH_SK_PROVIDER'`. The key file contains an opaque credential handle; the authenticator is still required for signing. Enrollment supports `-O device=PATH` and `-O challenge=FILE` (1 byte–1 MiB). Resident filenames use portable escaping and numeric suffixes to keep duplicate application/user credentials distinct. Attestation-file output is not supported. Built-in resident enrollment requires a PIN and CTAP2 credential management (`credMgmt` or `credentialMgmtPreview`) to check for an existing application/user credential. Resident and `verify-required` enrollment also require `credProtect`; unsupported authenticators fail explicitly.
 - **Custom key**: Use `-i` flag to specify a key file
 - **Encrypted keys**: Automatically detects and prompts for passphrase
 

docs/man/bssh-keygen.1

@@ -13,10 +13,15 @@ bssh-keygen \- SSH key pair generation tool
 [\fB\-C\fR \fIcomment\fR]
 [\fB\-y\fR]
 [\fB\-q\fR]
+[\fB\-w\fR \fIprovider\fR]
+[\fB\-O\fR \fIoption\fR]
+.br
+.B bssh-keygen
+\fB\-K\fR [\fB\-w\fR \fIprovider\fR] [\fB\-O\fR device=\fIpath\fR]
 
 .SH DESCRIPTION
 .B bssh-keygen
-generates SSH key pairs in OpenSSH format. It supports Ed25519 (recommended) and RSA algorithms.
+generates SSH key pairs in OpenSSH format. It supports Ed25519 (recommended), RSA, and authenticator-backed ed25519-sk and ecdsa-sk algorithms.
 Generated keys are compatible with OpenSSH and can be used for SSH authentication.
 
 By default, bssh-keygen generates an Ed25519 key pair and saves it to
@@ -30,6 +35,10 @@ Specifies the type of key to generate. Supported types:
 .IP \fBed25519\fR 10
 (default, recommended) Ed25519 elliptic curve key. Provides strong security with compact key size
 and fast operations.
+.IP \fBed25519-sk\fR 10
+Ed25519 FIDO security key. Requires a compatible attached authenticator.
+.IP \fBecdsa-sk\fR 10
+ECDSA P-256 FIDO security key.
 .IP \fBrsa\fR 10
 RSA key. Use \fB-b\fR to specify key size. Supported for compatibility with legacy systems.
 .RE
@@ -60,6 +69,47 @@ Default: "bssh-keygen"
 
 Example: \fB-C "user@hostname"\fR
 
+.TP
+.BR \-w ", " \-\-provider " " \fIPROVIDER\fR
+Security-key provider. Defaults to \fBinternal\fR, the built-in USB HID provider.
+May be a trusted shared library implementing OpenSSH sk-api, or a quoted
+\fI$VARIABLE\fR naming an environment variable containing the provider setting.
+External providers execute inside the process. Only load trusted libraries.
+
+.TP
+.B \-O OPTION
+Security-key option; may be repeated with different option names:
+.RS
+.IP \fBapplication=ssh:NAME\fR 10
+Application identifier. Must begin with ssh:. Default: ssh:.
+.IP \fBresident\fR 10
+Create a discoverable credential that can later be downloaded using \fB-K\fR.
+.IP \fBverify-required\fR 10
+Require user verification (normally a PIN) when signing.
+.IP \fBno-touch-required\fR 10
+Do not request user presence for signatures. The authenticator or server may
+still require a touch. Use the corresponding server authorized_keys option.
+.IP \fBuser=NAME\fR 10
+User name for resident credential enrollment.
+.IP \fBchallenge=FILE\fR 10
+Read enrollment challenge bytes from a regular file (1 byte to 1 MiB).
+The default is a random 32-byte challenge.
+.IP \fBdevice=PATH\fR 10
+Select a specific authenticator device. Also accepted with \fB-K\fR.
+.RE
+.PP
+\fB-O write-attestation=FILE\fR is explicitly unsupported. Unknown, duplicate,
+or malformed options fail before authenticator access.
+
+.TP
+.BR \-K ", " \-\-download-resident
+Prompt for the authenticator PIN and download resident SSH credentials into
+the current directory. Filenames follow OpenSSH's id_ed25519_sk_rk or
+id_ecdsa_sk_rk naming with application/user suffixes. Unsafe path characters
+are escaped. Numeric suffixes distinguish credentials with duplicate or
+case-equivalent application/user filenames, including public-key path aliases. Existing key files require
+confirmation unless \fB-y\fR is specified. Cannot be combined with \fB-f\fR.
+
 .TP
 .BR \-y ", " \-\-yes
 Overwrite existing key files without prompting for confirmation.
@@ -108,6 +158,23 @@ Better resistance to implementation errors
 .PP
 RSA support is provided for compatibility with legacy systems.
 
+.SS FIDO Security Keys
+The private file stores an opaque handle rather than the authenticator's private
+signing key. Keep the file private; the attached authenticator is still required
+to authenticate. Defaults are ~/.ssh/id_ed25519_sk and ~/.ssh/id_ecdsa_sk.
+Enrollment may prompt for a PIN and require a touch. Resident download always
+prompts for a PIN. Device and provider support determines available algorithms
+and resident-key operations. Built-in resident enrollment requires a PIN and
+CTAP2 credential management (credMgmt or credentialMgmtPreview), used to check
+for an existing application/user credential before enrollment. Both resident
+and verify-required enrollment require the credProtect extension. Unsupported
+authenticators fail explicitly instead of creating a credential with weaker
+protection. The current ssh-key encoder supports credential
+handles of up to 255 bytes; larger handles fail with an explicit diagnostic.
+On Linux, the user needs access to the authenticator's /dev/hidraw device,
+normally configured by the FIDO udev rules. The built-in provider supports
+Linux and macOS; other platforms require an external provider library.
+
 .SH OUTPUT
 .B bssh-keygen
 creates two files:
@@ -161,6 +228,13 @@ $ bssh-keygen -C "john@workstation"
 $ bssh-keygen -t rsa -b 4096
 .fi
 
+.SS Enroll a Resident Security Key
+.nf
+$ bssh-keygen -t ed25519-sk -O resident -O application=ssh:work -O user=alice
+$ bssh-keygen -t ecdsa-sk -O verify-required -w internal
+$ bssh-keygen -K
+.fi
+
 .SS Generate Key Non-Interactively
 .nf
 $ bssh-keygen -f /tmp/deploy_key -C "deploy@server" -y -q
@@ -255,3 +329,10 @@ There is NO WARRANTY, to the extent permitted by law.
 .BR ssh (1)
 
 Project homepage: https://github.com/lablup/bssh
+
+.SH ATTESTATION
+The internal provider verifies signatures on packed and FIDO U2F registration
+responses using the supplied public key or attestation certificate.
+It also accepts the unsigned "none" attestation format, as OpenSSH does.
+Certificate chains, certificate lifetime and vendor trust are not checked.
+Attestation export with write-attestation is unsupported.