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 7.9 (Git tag V_7_9_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.
This fork also contains an experimental (pre-draft) IETF draft for hybrid key exchange algorithms ECDH-SIKE and ECDH-BIKE. This document has not been submitted to IETF.
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,bike-l3 - CLASSIC-MCELIECE:
classic-mceliece-348864,classic-mceliece-348864f,classic-mceliece-460896,classic-mceliece-460896f,classic-mceliece-6688128,classic-mceliece-6688128f,classic-mceliece-6960119,classic-mceliece-6960119f,classic-mceliece-8192128,classic-mceliece-8192128f - FRODO:
frodo-640-aes,frodo-640-shake,frodo-976-aes,frodo-976-shake,frodo-1344-aes,frodo-1344-shake - KYBER:
kyber-512,kyber-768,kyber-1024,kyber-512-90s,kyber-768-90s,kyber-1024-90s - NTRU:
ntru-hps-2048-509,ntru-hps-2048-677,ntru-hrss-701,ntru-hps-4096-821 - SABER:
saber-lightsaber,saber-saber,saber-firesaber - SIDH:
sidh-p434,sidh-p503,sidh-p610,sidh-p751,sidh-p434-compressed,sidh-p503-compressed,sidh-p610-compressed,sidh-p751-compressed - SIKE:
sike-p434,sike-p503,sike-p610,sike-p751,sike-p434-compressed,sike-p503-compressed,sike-p610-compressed,sike-p751-compressed - HQC:
hqc-128,hqc-192,hqc-256† - NTRU-PRIME:
ntrulpr-653,ntrulpr-761,ntrulpr-857,sntrup-653,sntrup-761,sntrup-857
The following hybrid algorithms are supported; they combine a quantum-safe algorithm listed above with ECDH that uses NIST's P384 curve:
ecdh-nistp384-<KEX>, where<KEX>is any one of the algorithms listed above.
Note that algorithms marked with a dagger (†) have large stack usage and may cause failures when run on threads or in constrained environments.
The following digital signature algorithms from liboqs are supported (assuming they have been enabled in liboqs). Note that not all variants of all algorithms are enabled by default; algorithms that are enabled by default are marked with an asterisk; should you wish to enable additional variants, consult the "Code Generation" section of the documentation in the wiki.
- DILITHIUM:
dilithium2*,dilithium3,dilithium4 - FALCON:
falcon512*,falcon1024 - PICNIC:
picnicl1fs,picnicl1ur,picnicl1full,picnicl3fs,picnicl3ur,picnicl3full,picnicl5fs,picnicl5ur,picnicl5full,picnic3l1,picnic3l3,picnic3l5 - RAINBOW:
rainbowiclassic,rainbowicircumzenithal,rainbowicompressed,rainbowiiiclassic,rainbowiiicircumzenithal,rainbowiiicompressed,rainbowvclassic,rainbowvcircumzenithal,rainbowvcompressed - SPHINCS:
sphincsharaka128frobust,sphincsharaka128fsimple,sphincsharaka128srobust,sphincsharaka128ssimple,sphincsharaka192frobust,sphincsharaka192fsimple,sphincsharaka192srobust,sphincsharaka192ssimple,sphincsharaka256frobust,sphincsharaka256fsimple,sphincsharaka256srobust,sphincsharaka256ssimple,sphincssha256128frobust,sphincssha256128fsimple,sphincssha256128srobust,sphincssha256128ssimple,sphincssha256192frobust,sphincssha256192fsimple,sphincssha256192srobust,sphincssha256192ssimple,sphincssha256256frobust,sphincssha256256fsimple,sphincssha256256srobust,sphincssha256256ssimple,sphincsshake256128frobust*,sphincsshake256128fsimple,sphincsshake256128srobust,sphincsshake256128ssimple,sphincsshake256192frobust,sphincsshake256192fsimple,sphincsshake256192srobust,sphincsshake256192ssimple,sphincsshake256256frobust,sphincsshake256256fsimple,sphincsshake256256srobust,sphincsshake256256ssimple
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>andp256-<SIG>, which combine<SIG>with RSA3072 and with ECDSA using NIST's P256 curve respectively. - if
<SIG>has L3 security, the fork provides the methodp384-<SIG>, which combines<SIG>with ECDSA using NIST's P384 curve. - if
<SIG>has L5 security, the fork provides the methodp521-<SIG>, which combines<SIG>with ECDSA using NIST's P521 curve.
The steps below have been confirmed to work on macOS 10.14 (clang 10.0.0) and Ubuntu 18.04.1 Bionic (gcc-7).
On Ubuntu, you need to install the following packages:
sudo apt install autoconf automake cmake gcc libtool libssl-dev make ninja-build zlib1g-dev
If you want to run the OQS-specific tests (see the bottom of Step 2 below), you also need to install the following packages:
sudo apt install python3 python3-nose python3-rednose
On Linux, you also may need to do the following:
-
You may need to create the privilege separation directory:
sudo mkdir -p -m 0755 /var/empty -
You may need to create the privilege separation user:
sudo groupadd sshd sudo useradd -g sshd -c 'sshd privsep' -d /var/empty -s /bin/false sshd
On macOS, you need to install the following packages using brew (or a package manager of your choice):
brew install autoconf automake cmake libtool ninja openssl@1.1 wget
The following instructions install liboqs into a subdirectory inside the OpenSSH source. If <OPENSSH_ROOT> is the root of the OpenSSH source:
git clone --branch main --single-branch --depth 1 https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build && cd build
cmake .. -GNinja -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DCMAKE_INSTALL_PREFIX=<OPENSSH_ROOT>/oqs
ninja
ninja install
Building liboqs requires your system to have OpenSSL 1.1.1 or higher already installed. It will automatically be detected if it in a standard location, such as /usr or /usr/local/opt/openssl@1.1 (for brew on macOS). Otherwise, you may need to specify it with -DOPENSSL_ROOT_DIR=<path-to-system-openssl-dir> added to the cmake command.
In <OPENSSH_ROOT>, first run:
export LIBOQS_INSTALL=<path-to-liboqs>
export OPENSSH_INSTALL=<path-to-install-openssh>
autoreconf
Then, run the following:
./configure --with-ssl-dir=<path-to-openssl>/include \
--with-ldflags=-L<path-to-openssl>/lib \
--with-libs=-lm \
--prefix=$OPENSSH_INSTALL \
--sysconfdir=$OPENSSH_INSTALL \
--with-liboqs-dir=$LIBOQS_INSTALL
make -j
make install
To test the build, run:
make tests
To run OQS-specific tests of all the post-quantum key-exchanges:
python3 -m nose --rednose --verbose
To run OQS-specific tests of all combinations of post-quantum key-exchange and authentication algorithms:
env WITH_PQAUTH=true python3 -m nose --rednose --verbose
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. In what follows, <SIG> is one of the quantum-safe digital signature algorithms listed in Supported Algorithms section above.
The server generates its key files with the right permissions, and then generates its key pair:
mkdir ~/ssh_server/
chmod 700 ~/ssh_server/
touch ~/ssh_server/authorized_keys
chmod 600 ~/ssh_server/authorized_keys
<path-to-openssh>/bin/ssh-keygen -t ssh-<SIG> -f ~/ssh_server/id_<SIG>
To enable client-side public-key authentication, the client generates its key pair:
mkdir ~/ssh_client/
<path-to-openssh>/bin/ssh-keygen -t ssh-<SIG> -f ~/ssh_client/id_<SIG>
The server then adds the client's public key to its authorized keys
cat ~/ssh_client/id_<SIG>.pub >> ~/ssh_server/authorized_keys
In one terminal, run a server (the arguments between [...] can be omitted if only classical authentication is required):
sudo <path-to-openssh>/sbin/sshd -p 2222 -d \
-o KexAlgorithms=<OPENSSH_KEX_ALGORITHM> \
[-o AuthorizedKeysFile=<absolute-path-to>/ssh_server/authorized_keys \
-o HostKeyAlgorithms=<OPENSSH_SIG_ALGORITHM> \
-o PubkeyAcceptedKeyTypes=<OPENSSH_SIG_ALGORITHM> \
-h <absolute-path-to>/ssh_server/id_<SIG>]
where <OPENSSH_SIG_ALGORITHM> is ssh-<SIG> (all in lowercase) and <OPENSSH_KEX_ALGORITM> can be one of:
<KEX>-sha384@openquantumsafe.org(for quantum-safe-only key exchange)ecdh-nistp384-<KEX>-sha384@openquantumsafe.org(for hybrid quantum-safe and elliptic curve key exchange)
<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.
The server automatically supports all available hybrid and PQ-only key exchange algorithms. sudo is required on Linux so that sshd can read the shadow password file.
In another terminal, run a client(the arguments between [...] can be omitted if only classical authentication is required):
<path-to-openssh>/bin/ssh \
-p 2222 localhost \
-o KexAlgorithms=<OPENSSH_KEX_ALGORITHM> \
[-o HostKeyAlgorithms=<OPENSSH_SIG_ALGORITHM> \
-o PubkeyAcceptedKeyTypes=<OPENSSH_SIG_ALGORITHM> \
-o StrictHostKeyChecking=no \
-i ~/ssh_client/id_<SIG>]
The StrictHostKeyChecking option is used to allow trusting the newly generated server key; alternatively, the key could be added manually to the client's trusted keys.
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)
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 Canadian Centre for Cyber Security. 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.