Article

Smart cards support in libssh

October 28, 2020
Security Kubernetes Linux
Sahana Prasad
Software Engineer
libssh SSH library smart card featured image

In computer security, software implementations of cryptographic algorithms are vulnerable to side-channel attacks. This type of attack seeks to glean information from the computer system rather than from the program that it is running. As examples, Spectre and Meltdown are both side-channel attacks that target the microarchitecture of modern processors. Microarchitectural attacks are only a subset of all side-channel attacks. There are many others that leak sensitive secret information.

An attacker who is able to access unauthorized regions in memory can discover private or sensitive information, including authentication secrets. A question that naturally follows is, "Where can I safely store my secrets?"

One way to protect your secrets is to store them in a hardware token. A hardware token physically separates your secret key from the host machine and the applications that it is running. You can use secret keys stored on smart cards or cryptographic tokens to authenticate to server-side applications.

This article introduces Public Key Cryptography Standard #11 (PKCS #11), which you can use to uniquely identify objects stored in tokens. I will show you how to build and use libssh with support for PKCS #11 and how to use curl to store and retrieve tokens through the secure shell (SSH) protocol.

The PKCS #11 interface

PKCS #11 provides an application programming interface (API) for interacting with devices like smart cards, which store private cryptographic information. Such cryptographic devices are known as tokens. PKCS #11 uses a uniform resource identifier (URI) to uniquely identify objects stored in tokens. The PKCS #11 URI is defined by the RFC 7512: PKCS #11 URI Scheme: 

pkcs11:token=my-token;object=my-object;type=private?pin-value=1234

The URI format is defined as follows:

  • Every PKCS #11 URI begins with the scheme name, "pkcs11:".
  • The scheme name is followed by attribute-value pairs, which are separated by a semicolon.
  • The parameter token represents the name of the device or smart card.
  • The stored-object name in the token is identified by the parameter object.
  • The object itself can be of type private, public, certificate, data, or a secret key.
  • The parameter pin-value stores the personal identification number that is required to access the private key.

Note: The token description provides authenticating applications with a logical view of the hardware device storing the cryptographic token.

Smart card support in libssh

The SSH library, or libssh, is a library-based implementation of the Secure Shell (SSH) protocol. It supports using PKCS #11 URIs to authenticate users to a remote server. Currently, PKCS #11 URI support is only available in the libssh main branch and not in Fedora. The next libssh release (0.9.x) will include PKCS #11 URI support, which will then be available in Fedora.

Build and use libssh with PKCS #11

The SSH library uses OpenSSL (Secure Socket Layer) as its cryptographic back end. OpenSSL defines an abstract layer called the engine, which implements cryptographic primitives. It provides cryptographic functionality, called key-loading, which we use to load private and public keys from smart cards. The engine_pkcs11 module acts as an interface between the PKCS #11 modules and OpenSSL.

To build and use libssh with support for PKCS #11, do the following:

  1. Enable the cmake option: $ cmake -DWITH_PKCS11_URI=ON.
  2. Build with OpenSSL.
  3. Install and configure engine_pkcs11.
  4. Plug-in a working smart card or configure SoftHSM, a cryptographic store that is accessible through PKCS #11.

The legacy functions in libssh are extended to automatically detect if a provided filename is a file path or a PKCS #11 URI. You can replace the paths to files containing keys and certificates with PKCS #11 URIs. If a PKCS #11 URI is detected, the engine is loaded and initialized. The engine loads the private or public key corresponding to the PKCS #11 URI from the PKCS #11 device.

Note: If you wish to authenticate using public keys on your own, follow the steps described in the "Authentication with public keys" section of the libssh documentation (see Chapter 2: A deeper insight on authentication).

Public-key authentication with PKCS #11 and libssh

Here is a minimalistic example of public-key authentication using PKCS #11 URIs: 

int authenticate_pkcs11_URI(ssh_session session)
{
  int rc;
  char priv_uri[1042] = “pkcs11:token=my-token;object=my-object;type=private?pin-value=1234”;

  rc = ssh_options_set(session, SSH_OPTIONS_IDENTITY, priv_uri);
  assert_int_equal(rc, SSH_OK)

  rc = ssh_userauth_publickey_auto(session, NULL, NULL);

  if (rc == SSH_AUTH_ERROR)
  {
    fprintf(stderr, “Authentication with PKCS #11 URIs failed: %s\n”,
      ssh_get_error(session));
    return SSH_AUTH_ERROR;
  }

  return rc;
}

Instead of specifying the path where the private-key file was stored, all you need to do is to set the PKCS #11 URI using SSH_OPTIONS_IDENTITY.

Using PKCS #11 smart cards with curl

Applications such as curl use libssh as the underlying library to communicate through the SSH protocol. In this example, we use curl to connect to a Secure File Transfer Protocol (SFTP) server: 

curl -kvu root: sftp://localhost –key ‘pkcs11:token=my-token;object=my-object;type=private?pin-value=1234’ — testuser

We could change the above command to use a PKCS #11 URI to test a SSH testuser's access to localhost. Instead of specifying the path to the private key in the --key attribute,  we would specify the corresponding PKCS #11 URI.

Conclusion

This article has been a brief introduction to using the PKCS #11 standard and libssh to store and access cryptographic private information in hardware tokens such as smart cards. I will leave you with two additional recommendations.

First, provide a specific PKCS #11 URI that matches only a single slot in the engine. If the engine discovers multiple slots that could potentially contain the private keys referenced by the provided PKCS #11 URI, the engine will not attempt to authenticate. Second, if you are using Elliptic Curve Digital Signature Algorithm (ECDSA) for your PKCS #11 URIs, ensure that you import the public keys along with the private keys to the token. Unlike the more commonly used RSA algorithm, ECDSA public keys cannot be derived from private keys.

Last updated: November 4, 2020

Comments