OpenSSH is an open-source implementation of the Secure Shell protocol. (View the original README.)
OQS-OpenSSH is a fork of OpenSSH that adds quantum-safe key exchange and signature algorithms using liboqs for prototyping and evaluation purposes. This fork is not endorsed by the OpenSSH project.
liboqs is an open source C library for quantum-resistant cryptographic algorithms. See here for more information.
OQS-OpenSSH is a fork of OpenSSH that adds quantum-safe cryptography to enable its use and evaluation in the SSH protocol.
Both liboqs and this fork are part of the Open Quantum Safe (OQS) project, which aims to develop and prototype quantum-safe cryptography. More information about the project can be found here.
This fork is currently based on OpenSSH version 9.7 (Git tag V_9_7_P1); release notes can be found here. IT IS AT AN EXPERIMENTAL STAGE, and has not received the same level of auditing and analysis that OpenSSH has received. See the Limitations and Security section below for more information.
WE DO NOT RECOMMEND RELYING ON THIS FORK TO PROTECT SENSITIVE DATA.
liboqs is provided "as is", without warranty of any kind. See LICENSE.txt for the full disclaimer. Portable OpenSSH is built using autoconf and make. It requires a working C compiler, standard library and headers.
libcrypto from either LibreSSL or OpenSSL may also be used, but OpenSSH may be built without it supporting a subset of crypto algorithms.
zlib is optional; without it transport compression is not supported.
FIDO security token support needs libfido2 and its dependencies. Also, certain platforms and build-time options may require additional dependencies; see README.platform for details.
This fork implements the draft-kampanakis-curdle-ssh-pq-ke IETF draft for hybrid key exchange algorithms.
As research advances, the supported algorithms may see rapid changes in their security, and may even prove insecure against both classical and quantum computers.
We believe that the NIST Post-Quantum Cryptography standardization project is currently the best avenue to identifying potentially quantum-resistant algorithms, and strongly recommend that applications and protocols rely on the outcomes of the NIST standardization project when deploying quantum-safe cryptography.
While at the time of this writing there are no vulnerabilities known in any of the quantum-safe algorithms used in this fork, 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.
We realize some parties may want to deploy quantum-safe cryptography prior to the conclusion of the standardization project. We strongly recommend such attempts make use of so-called hybrid cryptography, in which quantum-safe public-key algorithms are combined with traditional public key algorithms (like RSA or elliptic curves) such that the solution is at least no less secure than existing traditional cryptography. This fork provides the ability to use hybrid cryptography.
If an algorithm is provided by liboqs but is not listed below, it can still be used in the fork through either one of two ways.
The following quantum-safe algorithms from liboqs are supported (assuming they have been enabled in liboqs):
- BIKE:
bike-l1-sha512,bike-l3-sha512,bike-l5-sha512 - ClassicMcEliece:
classic-mceliece-348864-sha256,classic-mceliece-348864f-sha256,classic-mceliece-460896-sha512,classic-mceliece-460896f-sha512,classic-mceliece-6688128-sha512,classic-mceliece-6688128f-sha512,classic-mceliece-6960119-sha512,classic-mceliece-6960119f-sha512,classic-mceliece-8192128-sha512,classic-mceliece-8192128f-sha512 - FrodoKEM:
frodokem-640-aes-sha256,frodokem-976-aes-sha384,frodokem-1344-aes-sha512,frodokem-640-shake-sha256,frodokem-976-shake-sha384,frodokem-1344-shake-sha512 - HQC:
hqc-128-sha256,hqc-192-sha384,hqc-256-sha512† - Kyber:
kyber-512-sha256,kyber-768-sha384,kyber-1024-sha512 - ML-KEM:
ml-kem-512-sha256,ml-kem-768-sha256,ml-kem-1024-sha384 - NTRU-Prime:
ntruprime-sntrup761-sha512
The following hybrid algorithms are made available:
- BIKE:
[email protected][email protected][email protected][email protected] - ClassicMcEliece:
ecdh-nistp256-classic-mceliece-348864r4-sha256@openquantumsafe.org[email protected]ecdh-nistp256-classic-mceliece-348864fr4-sha256@openquantumsafe.org[email protected]ecdh-nistp384-classic-mceliece-460896r4-sha512@openquantumsafe.orgecdh-nistp384-classic-mceliece-460896fr4-sha512@openquantumsafe.orgecdh-nistp521-classic-mceliece-6688128r4-sha512@openquantumsafe.orgecdh-nistp521-classic-mceliece-6688128fr4-sha512@openquantumsafe.orgecdh-nistp521-classic-mceliece-6960119r4-sha512@openquantumsafe.orgecdh-nistp521-classic-mceliece-6960119fr4-sha512@openquantumsafe.orgecdh-nistp521-classic-mceliece-8192128r4-sha512@openquantumsafe.orgecdh-nistp521-classic-mceliece-8192128fr4-sha512@openquantumsafe.org - FrodoKEM:
[email protected][email protected][email protected][email protected][email protected][email protected][email protected][email protected] - HQC:
[email protected][email protected][email protected][email protected] - Kyber:
[email protected][email protected][email protected][email protected] - ML-KEM:
[email protected][email protected]mlkem768nistp256-sha256mlkem768x25519-sha256mlkem1024nistp384-sha384 - NTRU-Prime:
[email protected]
Note that algorithms marked with a dagger (†) have large stack usage and may cause failures when run on threads or in constrained environments. For example, McEliece require building oqs-openssh with a large(r) stack provision than is default: Adding LDFLAGS="-Wl,--stack,20000000" to the ./configure command below is required to allow cygwin-based testing to pass.
Algorithms which involve ML-KEM are provided using the names as proposed in draft-kampanakis-curdle-ssh-pq-ke. The underlying implementation uses a liboqs API name for the final ML-KEM implementation which is currently (August 13th, 2024) aliased to ML-KEM-IPD. When the final implementation for ML-KEM becomes available, the alias will also be updated to the standardized ML-KEM implementation.
The following digital signature algorithms from liboqs are supported (assuming they have been enabled in liboqs). Note that only select L3 signature variants are enabled by default. In general, algorithms that are enabled by default are marked with an asterisk, and should you wish to enable additional variants, consult the "Code Generation" section of the documentation in the wiki.
- Dilithium:
dilithium2,dilithium3,dilithium5 - Falcon:
falcon512*,falcon1024*,falconpadded512,falconpadded1024 - MAYO:
mayo1,mayo2*,mayo3*,mayo5* - ML-DSA:
mldsa44*,mldsa65*,mldsa87* - SPHINCS:
sphincssha2128fsimple*,sphincssha2128ssimple,sphincsshake128fsimple,sphincsshake128ssimple,sphincssha2192fsimple,sphincssha2192ssimple,sphincsshake192fsimple,sphincsshake192ssimple,sphincssha2256fsimple*,sphincssha2256ssimple,sphincsshake256fsimple,sphincsshake256ssimple
The following hybrid algorithms are supported; they combine a quantum-safe algorithm listed above with a traditional digital signature algorithm (<SIG> is any one of the algorithms listed above):
- if
<SIG>has L1 security, then the fork provides the methodsrsa3072-<SIG>andecdsa-nistp256-<SIG>, which combine<SIG>with RSA3072 and with ECDSA using NIST's P256 curve respectively. - if
<SIG>has L3 security, the fork provides the methodecdsa-nistp384-<SIG>, which combines<SIG>with ECDSA using NIST's P384 curve. - if
<SIG>has L5 security, the fork provides the methodecdsa-nistp521-<SIG>, which combines<SIG>with ECDSA using NIST's P521 curve.
Algorithms which involve ML-DSA use a liboqs API name for the final ML-DSA implementation which is currently (August 13th, 2024) aliased to ML-DSA-IPD. When the final implementation for ML-DSA becomes available, the alias will also be updated to the standardized ML-DSA implementation.
The steps below have been confirmed to work on Ubuntu 20.04.1 Focal
On Ubuntu, you need to install the following packages:
sudo apt install autoconf automake cmake gcc libtool libssl-dev make ninja-build zlib1g-dev
On Linux, you also may need to do the following:
-
Create the privilege separation directory:
sudo mkdir -p -m 0755 /var/empty -
Create the privilege separation user:
sudo groupadd sshd sudo useradd -g sshd -c 'sshd privsep' -d /var/empty -s /bin/false sshd
The following instructions install liboqs into a subdirectory inside the OpenSSH source.
./oqs-scripts/clone_liboqs.sh
./oqs-scripts/build_liboqs.sh
Building liboqs requires your system to have OpenSSL 1.1.1 or higher already installed. It will automatically be detected if it is under /usr or another standard location. Otherwise, you may need to specify it with -DOPENSSL_ROOT_DIR=<path-to-system-openssl-dir> added to the cmake command.
See the Build-time Customisation section below for configure options. If you plan on installing OpenSSH to your system, then you will usually want to specify destination paths.
Run the following:
env OPENSSL_SYS_DIR=<PATH_TO_OPENSSL> ./oqs-scripts/build_openssh.sh
OPENSSL_SYS_DIR does not have to be specified if OpenSSL is present under /usr.
As not all tests in the stock regression suite pass, run oqs-test/run_tests.sh instead of simply executing make tests to ensure the build was successful.
To run the following tests, the /regress folder must have been populated using either oqs-test/run_tests.sh or make tests. To execute a connection test with a randomly chosen key-exchange and signature algorithm, run python3 oqs-test/try_connection.py. If it is desired that each such combination be tested (exactly once), run python3 oqs-test/try_connection.py doall. Be aware that the latter can take a long time due to the number of algorithm combinations available.
The following instructions explain how to establish an SSH connection that uses quantum-safe key exchange and authentication.
To setup quantum-safe authentication, the server (and optionally, the client) need to generate quantum-safe keys. To generate keys for all the OQS algorithms supported by fork, simply run make tests -e LTESTS="".
Keys for a particular <SIG> also be generated using the ssh-keygen command as follows:
<OPENSSH_SRC>/ssh-keygen -t ssh-<SIG> -f ~/ssh_client/id_<SIG>
Let <OPENSSH_SRC> denote the absolute path to the directory in which this source is present.
In one terminal, run the ssh server:
<OPENSSH_SRC>/sshd -D \
-f <OPENSSH_SRC>/regress/sshd_config \
-o KexAlgorithms=<KEX> \
-o HostKeyAlgorithms=ssh-<SIG> \
-o PubkeyAcceptedKeyTypes=ssh-<SIG> \
-h <OPENSSH_SRC>/regress/host.ssh-<SIG>
<KEX> and <SIG> are respectively one of the key exchange and signature (PQ-only or hybrid) algorithms listed in the Supported Algorithms section above.
The -o options can also be added to the server/client configuration file instead of being specified on the command line.
In another terminal, run the ssh client:
<OPENSSH_SRC>/ssh -F <OPENSSH_SRC>/regress/ssh_config \
-o KexAlgorithms=<KEX> \
-o HostKeyAlgorithms=ssh-<SIG>\
-o PubkeyAcceptedKeyTypes=ssh-<SIG> \
-o PasswordAuthentication=no \
-i regress/ssh-<SIG> \
somehost true
The PasswordAuthentication option is used to ensure the test server does not fall back to password authentication if public key authentication fails for some reason.
The -o options can also be added to the regress/{ssh|sshd}_config client/server configuration files instead of being specified on the command line.
Contributions are gratefully welcomed. See our Contributing Guide for more details.
This fork is released under the same license(s) as Portable OpenSSH. More information can be found in the LICENSE file.
The Open Quantum Safe project is led by Douglas Stebila and Michele Mosca at the University of Waterloo.
Contributors to this fork of OpenSSH include:
- Eric Crockett (Amazon Web Services)
- Ben Davies (University of Waterloo)
- Torben Hansen (Amazon Web Services and Royal Holloway, University of London)
- Christian Paquin (Microsoft Research)
- Douglas Stebila (University of Waterloo)
- Goutam Tamvada (University of Waterloo)
- Michael Baentsch
- Gerardo Ravago (Amazon Web Services)
Contributors to an earlier OQS fork of OpenSSH included:
- Mira Belenkiy (Microsoft Research)
- Karl Knopf (McMaster University)
Financial support for the development of Open Quantum Safe has been provided by Amazon Web Services and the Tutte Institute for Mathematics and Computing. We'd like to make a special acknowledgement to the companies who have dedicated programmer time to contribute source code to OQS, including Amazon Web Services, evolutionQ, Microsoft Research, Cisco Systems, and IBM Research.
Research projects which developed specific components of OQS have been supported by various research grants, including funding from the Natural Sciences and Engineering Research Council of Canada (NSERC); see here and here for funding acknowledgments.