OQS-libssh

<span style="color: red;">DEPRECATION NOTICE</span>

<b><span style="color: red;">The Open Quantum Safe project has discontinued development of our libssh fork. This repository is being archived as read-only. Use of this code is not recommended, as it may rely on obsolete algorithms or implementations or may have security vulnerabilities or other bugs. If you are interested in reviving and maintaining this project, please reach out via the OQS discussion board on Github.</span></b>

About

libssh is an open-source implementation of the Secure Shell protocol. This version of libssh provides support for using "post-quantum" (PQ) cryptographic algorithms. Not to be confused with "quantum cryptography," which is cryptography done on quantum computers, "post-quantum" cryptography (PQC) is algorithms to be used on classical computers which are not vulnerable to the attacks the algorithms in current use (primarily RSA and Elliptic Curve Cryptography) are. See the home page for the Open Quantum Safe (OQS) project at https://openquantumsafe.org/ for further information.

WARNING: These algorithms and implementations are experimental. Standards for post-quantum cryptographic algorithms are still under development. Included at this time are implementations of algorithms from Round 3 of the NIST's Post-Quantum Cryptography standardization process. While at the time of this writing there are no vulnerabilities known in any of the quantum-safe algorithms used in the OQS project, it is advisable to wait on deploying quantum-safe algorithms until further guidance is provided by the standards community, especially from the NIST standardization project. Accordingly, although "pure-PQ" options are provided, we recommend only enabling "hybrid" options, which combine time-tested classical algorithms with new PQ algorithms. This will ensure the solution is at least no less secure than existing traditional cryptography.

• OQS-libssh
  • DEPRECATION NOTICE
  • About
  • Overview
  • Build Instructions
    • Preserving client and server authentication keys for runs of the pkd_hello suite
  • Build instructions for OQS-OpenSSH
  • Key Exchange Algorithms
  • Digital Signature Algorithms
  • Known Issues
  • Contributing
  • License
  • Team
  • Acknowledgments

Overview

This implementation is designed to interoperate with the OQS project's fork of OpenSSH v8, available at https://github.com/open-quantum-safe/openssh. As the protocol is not yet standardized and may change without any allowance for backwards-compatibility, future changes to OQS-OpenSSH may break interoperability until this library can be updated.

The build instructions here always use the latest development versions of liboqs and OQS-OpenSSH, but it is possible changes in those dependencies may cause libssh's build to break, before we have a chance to update it. If that happens, the following commit IDs are known to work with this build, and can manually be snapped to by providing them to git checkout after cloning the repositories in the instructions below.

• liboqs: commit ID 2e42595804242d1e24e04f0f770a348c0c22313b "Add ntruprime (#1328)"
• OQS-OpenSSH: commit ID 54d09519a75c3fedd7d47400f55d7642e05cbae8 "Removed NTRU. (#130)"

This implementation tracks libssh's master branch that contains the current development version. At this time, this library is based on libssh's commit ID 4975487c18090e24ff97208022a605a15351e773 "config: Include files with relative paths", which was committed on 2022-02-10.

This support can only be built if OpenSSL is used as the cryptographic library for libssh, due to liboqs's reliance on OpenSSL for some symmetric cryptographic primitives. libgcrypt and mbedTLS are not supported.

Build Instructions

1. Clone the liboqs repository's main branch, and then snap to the particular commit above, which is the latest version of liboqs known to work with libssh. Newer versions of liboqs may work, but there is no guarantee. Do this outside of the libssh repository clone.

    git clone --branch main --single-branch --depth 1 https://github.com/open-quantum-safe/liboqs.git

2. Install necessary dependencies. In particular, you will need CMake, Ninja, gcc, and libssl-dev to build. On Ubuntu:

    sudo apt install cmake gcc g++ ninja-build libssl-dev python3-pytest python3-pytest-xdist unzip xsltproc doxygen graphviz

If you want to build client as well as server tests for libssh (-DCLIENT_TESTING=ON) below in step 6, install these additional dependencies. On Ubuntu:

    sudo apt install libcmocka-dev libcmocka0 libsocket-wrapper libnss-wrapper libuid-wrapper libpam-wrapper libpam0g-dev

3. Choose an appropriate installation location for OQS's libraries and include files. Example choices are /usr/local or /usr/local/oqs for a system-wide installation, or ${HOME}/oqs or ${HOME}/build/oqs for a user-local installation. This can be anywhere, but in the instructions below we refer to it as ${OQS_ROOT_DIR}.

4. Build and install liboqs. Change directory into the repository for liboqs cloned above, and execute these steps:

  mkdir build && cd build
  cmake -GNinja -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_INSTALL_PREFIX=${OQS_ROOT_DIR} ..
  ninja
  ninja install

5. OPTIONAL: Build OQS-OpenSSH using the instructions below. This is required to run tests, which use OpenSSH as the remote client or server. To run any tests, including the pkd_hello test suite, you MUST build OQS-OpenSSH, and add the path to the ssh binary it creates to your PATH environment variable before any official version of OpenSSH, so that libssh's CMake detects it and not the official version.

   Failing to do this step BEFORE running CMake in step 6 will cause tests to fail en masse, as it will not call the PQ-enabled OpenSSH client.

6. Configure and build libssh with the post-quantum cryptography turned on. We follow the regular instructions for libssh (see INSTALL), but we add two new configuration directives for cmake: WITH_POST_QUANTUM_CRYPTO and OQS_ROOT_DIR. Set WITH_POST_QUANTUM_CRYPTO to ON to enable the algorithms, and set OQS_ROOT_DIR to be the value of ${OQS_ROOT_DIR} you chose above. Without the WITH_POST_QUANTUM_CRYPTO setting, PQC is not included. Change directory back into the repository for libssh, and execute these steps:

  mkdir build && cd build
  cmake -DUNIT_TESTING=ON -DWITH_SERVER=ON -DSERVER_TESTING=ON -DCMAKE_BUILD_TYPE=Debug -DWITH_POST_QUANTUM_CRYPTO=ON -DOQS_ROOT_DIR=${OQS_ROOT_DIR} ..
  make -j

If you want to build the tests for libssh in client mode as well as server mode, add -DCLIENT_TESTING=ON to the cmake command line above. See Known Issues at the bottom of this document concerning the client tests.

The above steps will create the build directory underneath the libssh repository, but you can place it anywhere. If you place it elsewhere, replace the .. argument at the end of the call to cmake with the full path to the libssh repository.

Preserving client and server authentication keys for runs of the pkd_hello suite

By default, the pkd_hello test suite deletes all the authentication keys used by libssh as a server and OpenSSH as a client after the test run is complete. Because WITH_POST_QUANTUM_CRYPTO=ON adds many more key types, there can be a delay of up to a couple of minutes before test runs while keys are generated. pkd_hello now has a command option -p for "preserve," which will not delete these keys. If the key files are then present when pkd_hello runs, those keys will be reused. While we recommend the default behavior and always generate fresh keys for CI or other automated test runs, developers may find it convenient to preserve keys to speed up testing during development.

Build instructions for OQS-OpenSSH

libssh interoperates with the Open Quantum Safe project's fork of OpenSSH that adds post-quantum cryptography. If you are only building the libssh library itself, building OQS-OpenSSH is not required. However, building any of libssh's test code requires building OQS-OpenSSH in step 5 above, as the test code calls OpenSSH as part of its operation. When running libssh's server tests, OpenSSH is used as the client. Similarly, when running libssh's client tests, OpenSSH is used as the server.

The OQS version of OpenSSH can be used by building it and adding an entry to your PATH that precedes where the system-installed versions of OpenSSH are located. These will also be used by other clients that rely on OpenSSH, such as git. See https://github.com/open-quantum-safe/openssh/ for more information on using OQS-OpenSSH.

These instructions assume you have completed the build above; in particular, that liboqs is built and copied to ${OQS_ROOT_DIR}.

1. Clone the openssh repository OQS-v7.9 branch, and then snap to the particular commit above, which is the version known to interoperate with libssh. Newer versions of OQS-OpenSSH may work, but there is no guarantee. Do this outside of the libssh or liboqs repository clones.

  git clone --branch OQS-v8 --single-branch --depth 1 https://github.com/open-quantum-safe/openssh.git

2. Install necessary dependencies. In particular, beyond what libssh and liboqs require, OpenSSH requires autoconf, automake, libtool, and zlib1g-dev. On Ubuntu: