GSoC 2025

Tue, 08 Jul 2025 15:10:40 +0530

Introduction

This summer, I had the incredible opportunity of contributing to libssh, an open-source C library for the SSHv2 protocol, as part of Google Summer of Code 2025. My project focuses on adding client-side support for FIDO2/U2F keys, under the mentorship of Eshan Kelkar, Jakub Jelen, and Sahana Prasad.

In this blog post, I’ll try to explain my project in detail, and what I’ve worked on until now. But first, we need to discuss some background information required to better understand the project.

Background

How Traditional SSH Keys Work

To understand why FIDO2/U2F keys are special, we need to first understand how SSH public key authentication works.

The following is the authentication flow with a regular public key:

You generate a key pair on your computer (like ssh-keygen -t ecdsa)
The private key stays on your computer (usually in ~/.ssh/id_ecdsa)
You copy the public key to servers you want to access (stored in ~/.ssh/authorized_keys)
When you connect to the server, it requires the client to send a valid signature
Your computer uses the private key file (i.e., ~/.ssh/id_ecdsa) to generate a valid signature and sends it to the server
The server verifies the signature using the stored public key

The problem with this is that the private key is just a file on your computer. If someone gains access to your computer or steals this file, they can impersonate you on any server that trusts your public key. Even if the private key is password-protected, a determined attacker with enough time and resources might crack it.

Enter FIDO2/U2F Keys: Hardware-Backed Security

FIDO2 (Fast Identity Online) and U2F (Universal 2nd Factor) security keys/authenticators are small devices, like USBs, that revolutionize this security model. Instead of storing your private key as a file on your computer, the FIDO2/U2F either uses a master key to deterministically derive private keys or stores the private key on the device itself (See Resident Keys).

The following are a few reasons why security keys are fundamentally more secure:

Hardware Protection: All private data is stored inside a tamper-resistant hardware security module within the chip. The private key derivation process also happens entirely within the security chip, making it impossible for malware or hackers to obtain any key material remotely.
Physical Presence Required: Most security keys require you to physically touch or interact with the device to authorize each authentication (see this section). This means even if someone compromises your computer, they can’t authenticate without physically accessing your security key.
No Shared Secrets: Security keys use a challenge-response protocol where no secret information like a password is ever transmitted over the network. Each authentication is unique and cannot be replayed by an attacker.

So, security keys are much safer than passwords, or even traditional SSH keys, as they require an attacker to have both remote access to your computer and physical access to your FIDO2/U2F device - a significantly higher bar for compromise.

I highly recommend you check out this cool demonstration of the authentication flow using a security key.

Now that the basics of security keys have been covered, let’s discuss some of the their key concepts that are relevant to my project.

Resident Keys

FIDO2 devices can store credentials in two fundamentally different ways: non-resident keys and resident keys (also called discoverable credentials). In the context of SSH authentication:

Non-Resident Keys: With regular FIDO2 credentials, a credential ID (also known as a key handle) and associated metadata are stored in a file on the client side. When authentication is needed, the client provides the credential ID to the FIDO2 device, which then derives the corresponding private key from its master key to authenticate.

Resident Keys (Discoverable Credentials): With resident keys, the private key and associated metadata are stored directly in persistent memory on the FIDO2 device itself and nothing is stored on the client side. During authentication, the device can present all available credentials without needing to know any credential ID.

Advantages of resident keys include portability (using the same FIDO2 device across hosts) and resilience (no loss if the local machine is destroyed). Although, they may be limited by the storage of the authenticator.

You can read more about resident keys here.

User Presence and User Verification

FIDO2/U2F authentication incorporates two important security concepts that provide different levels of assurance and user experience. A relying party (like an SSH server) can require either or both of these features during authentication to ensure additional security:

User Presence (UP): Confirms that a human is physically interacting with the security key, typically by touching a button or sensor. This doesn’t identify who the user is, but ensures someone is physically controlling the device, preventing remote attacks and automated abuse.

User Verification (UV): Actually verifies the user’s identity through biometric authentication (fingerprint, face recognition) or a PIN entered on the device. This provides stronger security by ensuring that even if someone steals your FIDO2/U2F device, they can’t use it without your biometric or PIN. This enables passwordless authentication where the FIDO2 key serves as the sole authentication factor.

You can read more about UP and UV here.

Now that we have a good understanding of what FIDO2/U2F keys are, and their key security features, let’s understand how my GSoC project brings this technology to libssh.

About the Project

While libssh already supports server-side authentication using security keys, it currently does not have support for interacting with FIDO2/U2F devices on the client side. This means that users can’t use their security keys to authenticate to SSH servers when using libssh-based clients, which forces them to compromise on security.

My GSoC project is about solving this problem by implementing client-side FIDO2/U2F key support in libssh. This involves:

1. Device Communication: Building the infrastructure for libssh to interact with FIDO2/U2F devices through various communication protocols

2. Key Management Operations: Implementing the ability for libssh to:

Generate new keys: Create new cryptographic credentials on a FIDO2/U2F device
Load resident keys: Discover and retrieve keys that are stored on the device itself
Import/Export keys: Support storing and loading key files containing credential IDs and metadata

3. Authentication Operations: Using the FIDO2/U2F keys to create cryptographic signatures that prove your identity

4. Developer-Friendly API: Creating clean, easy-to-use functions that application developers can integrate into their SSH clients without needing to understand the complex underlying FIDO2/U2F specifications.

Now that we’ve outlined what the project aims to achieve, let’s understand the technical approach and architecture that makes this possible.

Implementation details

Callback-based Architecture

FIDO2/U2F keys support a wide range of communication protocols including USB HID, NFC, and potentially other protocols in the future. To effectively handle this diversity and ensure extensibility, after discussing with my mentors, I decided to adopt the following approach, which is inspired by OpenSSH’s approach:

We mainly need to interact with FIDO2/U2F devices to perform the following core operations:

Enrolling new keys
Creating signatures using an existing key
Loading all the resident keys

So, to allow libssh to support different communication methods without tying the library to any specific protocol implementation, I’ve defined a Security Key API (sk_api.h) that contains the various parameters that these operations can take, and the structs that they must return. We then model these operations as function callbacks - essentially pluggable functions that can be swapped out by the user depending on the communication protocol that is needed.

I also had to implement defaults for these callbacks (sk_usbhid.c) which interact with FIDO2/U2F devices over the USB HID protocol, which is by far the most common one, via the libfido2 library. Also, the parameters and return types of the callbacks defined in sk_api.h are consistent with OpenSSH’s, so that any middleware developed for OpenSSH which implements the above core operations can also be used with libssh.

Once we have these callbacks in place, we also need to integrate security key support into libssh’s existing key management infrastructure.

PKI Integration

libssh currently has many functions as part of its internal PKI (Public Key Infrastructure) which support various operations for dealing with traditional RSA, ECDSA, Ed25519, etc., keys. To deal with the new security key types, I extended the the existing PKI functions where possible, or created entirely new functions (pki_sk.c) for operations which require considerably different handling from traditional keys. The PKI functions internally use the SK API callbacks, as discussed above, to perform the actual communication with the FIDO2/U2F devices.

Client API Integration

To complete support for FIDO2/U2F keys on the client side, intuitive public-facing APIs must be provided so that users may configure the key operations and perform them. This was something that I really struggled with initially, but after a lot of discussions with my mentors, we were able to finalize a decent API design, that is both easy to use and flexible enough to cover various use cases.

Overall Architecture

The overall architecture of the project is as follows:

┌─────────────────────────────────────┐
│ libssh Client API │ ← User-facing SSH client functions
├─────────────────────────────────────┤
│ PKI SK Integration │ ← pki_sk.c - adds SK capabilities to libssh's existing PKI
├─────────────────────────────────────┤
│ Security Key API Layer │ ← sk_api.h - abstract callback interface
├─────────────────────────────────────┤
│ Protocol Implementations │ ← sk_usbhid.c - USB HID via libfido2
├─────────────────────────────────────┤
│ Hardware Communication │ ← libfido2, future NFC/BLE libraries
└─────────────────────────────────────┘

This architecture ensures that adding support for new protocols (like NFC or Bluetooth) only requires implementing the SK API callbacks for that specific protocol, without modifying the core libssh codebase.

Comprehensive Testing

To allow for testing the security key functionality in the CI environment, where a physical FIDO2/U2F device is not available, I made use of the openssh-sk-dummy library, to define dummy callbacks that can be used for testing purposes. I then worked on creating unit tests for various components of the implementation, as well as extending existing integration tests to cover the new security key authentication flow.

Documentation

API Documentation: I made sure to properly document most of the new functions using Doxygen comments.
FIDO2 key Tutorial: I also worked on adding a dedicated documentation chapter similar to libssh’s existing authentication guide to help new users adopt FIDO2/U2F support.

The Code

All of the work done over the course of this project has been done as part of GitLab merge requests. The following is a list of the MRs (ordered chronologically):

Conclusion

I’m incredibly grateful to my mentors for their constant guidance in shaping the direction of my project. Their advice has been invaluable. They have been very patient in reviewing my work, catching any mistakes, and providing suggestions to improve it. My journey so far has been an amazing learning experience, and I’m looking forward to finishing my project and seeing it become a part of libssh, and I’d love to continue contributing to libssh in the future.

Thanks for reading my blog :)

FIDO2 on ph03n1x's blog