Page MenuHomeFreeBSD

ssh: enable FIDO/U2F keys

Authored by emaste on Oct 15 2021, 7:01 PM.



Add ssh-sk-helper, and set ENABLE_SK_INTERNAL.
Regenerate ssh_namespace.h

Diff Detail

rG FreeBSD src repository
Automatic diff as part of commit; lint not applicable.
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

emaste created this revision.
emaste added a parent revision: D32448: Add libfido2 to the build.
emaste added inline comments.
140 ↗(On Diff #96921)

I accidentally uploaded this diff in D32529 and @des commented (

Isn't this the opposite of what you want?

This is what we want; ENABLE_SK_INTERNAL means ssh builds with its own sk support in ssh-sk-helper using libfido2/libcbor/libusb.

In /readconf.c/:

        if (options->sk_provider == NULL)
                options->sk_provider = xstrdup("internal");
        if (options->sk_provider == NULL)
                options->sk_provider = xstrdup("$SSH_SK_PROVIDER");

i.e., if ENABLE_SK_INTERNAL is not defined the user has to provide a path to the .so

    Specifies a path to a library that will be used when loading any
    FIDO authenticator-hosted keys, overriding the default of using
    the built-in USB HID support.

Note that all code in sk-usbhid.c is inside #ifdef ENABLE_SK_INTERNAL.


This is redundant, unless one of these files fails to #include "config.h".

Remove redundant ENABLE_SK_INTERNAL set via CFLAGS as noted by @des


Oops, thanks. It was leftover from some early WIP.

emaste added a subscriber: peterj.

Set ENABLE_SK_INTERNAL only if we have USB, as reported by @peterj


No need to include this in newly added files, presumably. I will remove it.


Do we -include ssh_namespace.h in each individual Makefile? Perhaps we should move it to

13–15 ↗(On Diff #97830)

This defined ENABLE_SK_INTERNAL for everything in secure/, which is too broad but unlikely to be a problem in practice.

As an alternative I could create secure/ and explicitly include it in each ssh library and binary Makefile. If that's the way we want to go I'd do a first pass to move SSHDIR there.

OpenSSH 8.2 release notes entry, for reference (from

FIDO/U2F Support

This release adds support for FIDO/U2F hardware authenticators to
OpenSSH. U2F/FIDO are open standards for inexpensive two-factor
authentication hardware that are widely used for website
authentication.  In OpenSSH FIDO devices are supported by new public
key types "ecdsa-sk" and "ed25519-sk", along with corresponding
certificate types.

ssh-keygen(1) may be used to generate a FIDO token-backed key, after
which they may be used much like any other key type supported by
OpenSSH, so long as the hardware token is attached when the keys are
used. FIDO tokens also generally require the user explicitly authorise
operations by touching or tapping them.

Generating a FIDO key requires the token be attached, and will usually
require the user tap the token to confirm the operation:

  $ ssh-keygen -t ecdsa-sk -f ~/.ssh/id_ecdsa_sk
  Generating public/private ecdsa-sk key pair.
  You may need to touch your security key to authorize key generation.
  Enter file in which to save the key (/home/djm/.ssh/id_ecdsa_sk): 
  Enter passphrase (empty for no passphrase): 
  Enter same passphrase again: 
  Your identification has been saved in /home/djm/.ssh/id_ecdsa_sk
  Your public key has been saved in /home/djm/.ssh/

This will yield a public and private key-pair. The private key file
should be useless to an attacker who does not have access to the
physical token. After generation, this key may be used like any other
supported key in OpenSSH and may be listed in authorized_keys, added
to ssh-agent(1), etc. The only additional stipulation is that the FIDO
token that the key belongs to must be attached when the key is used.

FIDO tokens are most commonly connected via USB but may be attached
via other means such as Bluetooth or NFC. In OpenSSH, communication
with the token is managed via a middleware library, specified by the
SecurityKeyProvider directive in ssh/sshd_config(5) or the
$SSH_SK_PROVIDER environment variable for ssh-keygen(1) and
ssh-add(1). The API for this middleware is documented in the sk-api.h
and PROTOCOL.u2f files in the source distribution.

OpenSSH includes a middleware ("SecurityKeyProvider=internal") with
support for USB tokens. It is automatically enabled in OpenBSD and may
be enabled in portable OpenSSH via the configure flag
--with-security-key-builtin. If the internal middleware is enabled
then it is automatically used by default. This internal middleware
requires that libfido2 ( its
dependencies be installed. We recommend that packagers of portable
OpenSSH enable the built-in middleware, as it provides the
lowest-friction experience for users.

Note: FIDO/U2F tokens are required to implement the ECDSA-P256
"ecdsa-sk" key type, but hardware support for Ed25519 "ed25519-sk" is
less common. Similarly, not all hardware tokens support some of the
optional features such as resident keys.

The protocol-level changes to support FIDO/U2F keys in SSH are
documented in the PROTOCOL.u2f file in the OpenSSH source

There are a number of supporting changes to this feature:

 * ssh-keygen(1): add a "no-touch-required" option when generating
   FIDO-hosted keys, that disables their default behaviour of
   requiring a physical touch/tap on the token during authentication.
   Note: not all tokens support disabling the touch requirement.

 * sshd(8): add a sshd_config PubkeyAuthOptions directive that
   collects miscellaneous public key authentication-related options
   for sshd(8). At present it supports only a single option
   "no-touch-required". This causes sshd to skip its default check for
   FIDO/U2F keys that the signature was authorised by a touch or press
   event on the token hardware.

 * ssh(1), sshd(8), ssh-keygen(1): add a "no-touch-required" option
   for authorized_keys and a similar extension for certificates. This
   option disables the default requirement that FIDO key signatures
   attest that the user touched their key to authorize them, mirroring
   the similar PubkeyAuthOptions sshd_config option.

 * ssh-keygen(1): add support for the writing the FIDO attestation
   information that is returned when new keys are generated via the
   "-O write-attestation=/path" option. FIDO attestation certificates
   may be used to verify that a FIDO key is hosted in trusted
   hardware. OpenSSH does not currently make use of this information,
   beyond optionally writing it to disk.

FIDO2 resident keys

FIDO/U2F OpenSSH keys consist of two parts: a "key handle" part stored
in the private key file on disk, and a per-device private key that is
unique to each FIDO/U2F token and that cannot be exported from the
token hardware. These are combined by the hardware at authentication
time to derive the real key that is used to sign authentication

For tokens that are required to move between computers, it can be
cumbersome to have to move the private key file first. To avoid this
requirement, tokens implementing the newer FIDO2 standard support
"resident keys", where it is possible to effectively retrieve the key
handle part of the key from the hardware.

OpenSSH supports this feature, allowing resident keys to be generated
using the ssh-keygen(1) "-O resident" flag. This will produce a
public/private key pair as usual, but it will be possible to retrieve
the private key part from the token later. This may be done using
"ssh-keygen -K", which will download all available resident keys from
the tokens attached to the host and write public/private key files
for them. It is also possible to download and add resident keys
directly to ssh-agent(1) without writing files to the file-system
using "ssh-add -K".

Resident keys are indexed on the token by the application string and
user ID. By default, OpenSSH uses an application string of "ssh:" and
an empty user ID. If multiple resident keys on a single token are
desired then it may be necessary to override one or both of these
defaults using the ssh-keygen(1) "-O application=" or "-O user="
options. Note: OpenSSH will only download and use resident keys whose
application string begins with "ssh:"

Storing both parts of a key on a FIDO token increases the likelihood
of an attacker being able to use a stolen token device. For this
reason, tokens should enforce PIN authentication before allowing
download of keys, and users should set a PIN on their tokens before
creating any resident keys.

LGTM overall except ${.CURDIR}, in which case I'd use ${SRCTOP} so if we move this to somewhere else, the Makefile will not need to be amended.

Personally I'd use a separate .mk or .inc file for -DENABLE_SK_INTERNAL=1, but it does seem like a good candidate for a follow up change.



FTR, the MK_USB checks allow this to build successfully on my test system that has WITHOUT_USB="YES"

Use ${SRCTOP} as suggested by @delphij

Personally I'd use a separate .mk or .inc file for -DENABLE_SK_INTERNAL=1, but it does seem like a good candidate for a follow up change.

I created D32808 to add, assuming that looks good I'll rebase this change on it.

add .include "${SRCTOP}/secure/" to ssh-sk-helper/Makefile.

One more update from D32808 for ssh-sk-helper/Makefile.

This looks reasonable to me.

This revision is now accepted and ready to land.Nov 3 2021, 11:47 PM
This revision was automatically updated to reflect the committed changes.