Skip to main content
Redhat Developers  Logo
  • Products

    Featured

    • Red Hat Enterprise Linux
      Red Hat Enterprise Linux Icon
    • Red Hat OpenShift AI
      Red Hat OpenShift AI
    • Red Hat Enterprise Linux AI
      Linux icon inside of a brain
    • Image mode for Red Hat Enterprise Linux
      RHEL image mode
    • Red Hat OpenShift
      Openshift icon
    • Red Hat Ansible Automation Platform
      Ansible icon
    • Red Hat Developer Hub
      Developer Hub
    • View All Red Hat Products
    • Linux

      • Red Hat Enterprise Linux
      • Image mode for Red Hat Enterprise Linux
      • Red Hat Universal Base Images (UBI)
    • Java runtimes & frameworks

      • JBoss Enterprise Application Platform
      • Red Hat build of OpenJDK
    • Kubernetes

      • Red Hat OpenShift
      • Microsoft Azure Red Hat OpenShift
      • Red Hat OpenShift Virtualization
      • Red Hat OpenShift Lightspeed
    • Integration & App Connectivity

      • Red Hat Build of Apache Camel
      • Red Hat Service Interconnect
      • Red Hat Connectivity Link
    • AI/ML

      • Red Hat OpenShift AI
      • Red Hat Enterprise Linux AI
    • Automation

      • Red Hat Ansible Automation Platform
      • Red Hat Ansible Lightspeed
    • Developer tools

      • Red Hat Trusted Software Supply Chain
      • Podman Desktop
      • Red Hat OpenShift Dev Spaces
    • Developer Sandbox

      Developer Sandbox
      Try Red Hat products and technologies without setup or configuration fees for 30 days with this shared Openshift and Kubernetes cluster.
    • Try at no cost
  • Technologies

    Featured

    • AI/ML
      AI/ML Icon
    • Linux
      Linux Icon
    • Kubernetes
      Cloud icon
    • Automation
      Automation Icon showing arrows moving in a circle around a gear
    • View All Technologies
    • Programming Languages & Frameworks

      • Java
      • Python
      • JavaScript
    • System Design & Architecture

      • Red Hat architecture and design patterns
      • Microservices
      • Event-Driven Architecture
      • Databases
    • Developer Productivity

      • Developer productivity
      • Developer Tools
      • GitOps
    • Secure Development & Architectures

      • Security
      • Secure coding
    • Platform Engineering

      • DevOps
      • DevSecOps
      • Ansible automation for applications and services
    • Automated Data Processing

      • AI/ML
      • Data Science
      • Apache Kafka on Kubernetes
      • View All Technologies
    • Start exploring in the Developer Sandbox for free

      sandbox graphic
      Try Red Hat's products and technologies without setup or configuration.
    • Try at no cost
  • Learn

    Featured

    • Kubernetes & Cloud Native
      Openshift icon
    • Linux
      Rhel icon
    • Automation
      Ansible cloud icon
    • Java
      Java icon
    • AI/ML
      AI/ML Icon
    • View All Learning Resources

    E-Books

    • GitOps Cookbook
    • Podman in Action
    • Kubernetes Operators
    • The Path to GitOps
    • View All E-books

    Cheat Sheets

    • Linux Commands
    • Bash Commands
    • Git
    • systemd Commands
    • View All Cheat Sheets

    Documentation

    • API Catalog
    • Product Documentation
    • Legacy Documentation
    • Red Hat Learning

      Learning image
      Boost your technical skills to expert-level with the help of interactive lessons offered by various Red Hat Learning programs.
    • Explore Red Hat Learning
  • Developer Sandbox

    Developer Sandbox

    • Access Red Hat’s products and technologies without setup or configuration, and start developing quicker than ever before with our new, no-cost sandbox environments.
    • Explore Developer Sandbox

    Featured Developer Sandbox activities

    • Get started with your Developer Sandbox
    • OpenShift virtualization and application modernization using the Developer Sandbox
    • Explore all Developer Sandbox activities

    Ready to start developing apps?

    • Try at no cost
  • Blog
  • Events
  • Videos

Smart cards support in libssh

October 28, 2020
Sahana Prasad
Related topics:
SecurityKubernetesLinux

Share:

    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

    Recent Posts

    • Unleashing multimodal magic with RamaLama

    • Integrate Red Hat AI Inference Server & LangChain in agentic workflows

    • Streamline multi-cloud operations with Ansible and ServiceNow

    • Automate dynamic application security testing with RapiDAST

    • Assessing AI for OpenShift operations: Advanced configurations

    Red Hat Developers logo LinkedIn YouTube Twitter Facebook

    Products

    • Red Hat Enterprise Linux
    • Red Hat OpenShift
    • Red Hat Ansible Automation Platform

    Build

    • Developer Sandbox
    • Developer Tools
    • Interactive Tutorials
    • API Catalog

    Quicklinks

    • Learning Resources
    • E-books
    • Cheat Sheets
    • Blog
    • Events
    • Newsletter

    Communicate

    • About us
    • Contact sales
    • Find a partner
    • Report a website issue
    • Site Status Dashboard
    • Report a security problem

    RED HAT DEVELOPER

    Build here. Go anywhere.

    We serve the builders. The problem solvers who create careers with code.

    Join us if you’re a developer, software engineer, web designer, front-end designer, UX designer, computer scientist, architect, tester, product manager, project manager or team lead.

    Sign me up

    Red Hat legal and privacy links

    • About Red Hat
    • Jobs
    • Events
    • Locations
    • Contact Red Hat
    • Red Hat Blog
    • Inclusion at Red Hat
    • Cool Stuff Store
    • Red Hat Summit

    Red Hat legal and privacy links

    • Privacy statement
    • Terms of use
    • All policies and guidelines
    • Digital accessibility

    Report a website issue