forked from openssh/openssh-portable
-
Notifications
You must be signed in to change notification settings - Fork 62
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
2 changed files
with
120 additions
and
95 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,27 +1,35 @@ | ||
| open-quantum-safe/openssh-portable | ||
| ================================== | ||
|
|
||
| **This code is experimental -- do NOT use in production or to protect secrets! See the Limitations section below.** | ||
| **OpenSSH** is an open-source implementation of the Secure Shell protocol https://openssh.org/. ([View the original README file for OpenSSH](https://github.com/open-quantum-safe/openssh-portable/blob/OQS-master/README).) | ||
|
|
||
| OpenSSH is an open-source implementation of the Secure Shell protocol https://openssh.org/. | ||
|
|
||
| This repository contains a fork of OpenSSH that adds quantum-safe key exchange algorithms using liboqs for prototyping purposes. | ||
|
|
||
| This README.md contains information about the modifications to OpenSSH by the Open Quantum Safe project. For information about OpenSSH, | ||
| [see the original README file for OpenSSH](https://github.com/open-quantum-safe/openssh-portable/blob/master/README). | ||
| This repository contains a fork of OpenSSH that adds quantum-resistant key exchange algorithms using liboqs for prototyping purposes. | ||
|
|
||
| Overview | ||
| -------- | ||
|
|
||
| The **Open Quantum Safe (OQS) project** has the goal of developing and prototyping quantum-resistant cryptography. | ||
|
|
||
| **liboqs** is an open source C library for quantum-safe cryptographic algorithms. See more about liboqs at [https://github.com/open-quantum-safe/liboqs/](https://github.com/open-quantum-safe/liboqs/), including a list of supported algorithms. | ||
| **liboqs** is an open source C library for quantum-resistant cryptographic algorithms. See more about liboqs at [https://github.com/open-quantum-safe/liboqs/](https://github.com/open-quantum-safe/liboqs/), including a list of supported algorithms. OpenSSL can use either the [master](https://github.com/open-quantum-safe/liboqs/tree/master) or the [nist](https://github.com/open-quantum-safe/liboqs/tree/nist-branch) branch of liboqs; the former is recommended for normal uses of OpenSSH as included mechanisms follow a stricter set of requirements, the latter contains more algorithms and is better suited for experimentation. | ||
|
|
||
| **open-quantum-safe/openssh-portable** contains a fork of OpenSSH that adds quantum-safe key exchange algorithms using liboqs for prototyping purposes, specifically adding key exchange methods that use hybrid (post-quantum + traditional elliptic curve) or post-quantum-only algorithms. The integration should not be considered "production quality". | ||
| **open-quantum-safe/openssh-portable** contains a fork of OpenSSH that adds quantum-safe key exchange algorithms using liboqs for prototyping purposes, specifically adding key exchange methods that use hybrid (post-quantum + traditional elliptic curve) or post-quantum-only algorithms. The integration should not be considered "production quality". The OQS-master branch of open-quantum-safe/openssh-portable is currently based on **OpenSSH version 7.7** (Git tag V_7_7_P1). | ||
|
|
||
| open-quantum-safe/openssh-portable periodically updated to track the original OpenSSH code (openssh/openssh-portable). The OQS-master branch of open-quantum-safe/openssh-portable is currently based on **OpenSSH version 7.7** (Git tag V_7_7_P1). | ||
| More information on OQS can be found on our website: [https://openquantumsafe.org/](https://openquantumsafe.org/). | ||
|
|
||
| More information on OQS can be found on our website: https://openquantumsafe.org/. | ||
| Contents | ||
| -------- | ||
|
|
||
| This branch ([OQS-master](https://github.com/open-quantum-safe/openssh-portable/tree/OQS-master)) integrates post-quantum key exchange from liboqs in SSH 2 in OpenSSH v7.7 portable 1. | ||
|
|
||
| ### Key exchange mechanisms | ||
|
|
||
| The following key exchange / key encapsulation methods from liboqs are supported (assuming they have been enabled in liboqs): | ||
|
|
||
| - `bike1-L1`, `bike1-L3, `bike1-L5` | ||
| - `frodo-640-aes`, `frodo-976-aes` | ||
| - `newhope-512`, `newhope-1024` | ||
| - `sike-503`, `sike-751` | ||
| - `oqsdefault` | ||
|
|
||
| Limitations and security | ||
| ------------------------ | ||
|
|
@@ -44,74 +52,83 @@ At the time of writing, there are no vulnerabilities or weaknesses known in any | |
|
|
||
| This fork does not yet contain support for post-quantum authentication. | ||
|
|
||
| The message format used in this fork is not standardized, and is subject to unilateral change at any time without regards to backwards compatibility with previous versions of this fork. | ||
|
|
||
| Contents | ||
| -------- | ||
| Lifecycle for open-quantum-safe/openssh-portable OQS-master branch | ||
| ------------------------------------------------------------------ | ||
|
|
||
| ### Key exchange mechanisms | ||
| **Release cycle:** We aim to make releases of our fork of OpenSSH stable on a bi-monthly basis, either when there has been a new release of OpenSSH or when we have made changes to our fork. | ||
|
|
||
| open-quantum-safe/openssh currently implements hybrid key exchange methods and PQ-only key exchange methods using the the following post-quantum key encapsulation mechanisms from liboqs: | ||
| See the README.md files of [liboqs master branch](https://github.com/open-quantum-safe/liboqs/blob/master/README.md) and [liboqs nist-branch](https://github.com/open-quantum-safe/liboqs/blob/nist-branch/README.md) for information about the algorithm lifecycle within the corresponding libraries. | ||
|
|
||
| - BIKE (only available if liboqs is built with BIKE enabled) | ||
| - FrodoKEM | ||
| - SIKE | ||
| - NewHope | ||
| - oqsdefault (see the "oqsdefault KEM" section below) | ||
|
|
||
| See https://github.com/open-quantum-safe/liboqs/blob/master/README.md for more information about each of the above PQ key encapsulation mechanisms. | ||
| **SSH compatibility:** The message format used in this fork is not standardized, and is subject to unilateral change at any time without regards to backwards compatibility with previous versions of this fork. | ||
|
|
||
| Building on Linux and macOS | ||
| --------------------------- | ||
|
|
||
| Builds have been tested on macOS Sierra 10.12.6, macOS High Sierra 10.13.4, and Amazon Linux AMI 2018.03 (AWS EC2). | ||
| Builds have been tested manually on macOS 10.14 (clang 10.0.0), Ubuntu 14.04 (gcc-5), Ubuntu 16.04 (gcc-5), and Ubuntu 18.04.1 (gcc-7). | ||
|
|
||
| ### Step 0: Install dependencies | ||
|
|
||
| **On macOS**: You need to install several tools using `brew`: | ||
| For **Ubuntu**, you need to install the following packages: | ||
|
|
||
| sudo apt install autoconf automake gcc libtool libssl-dev make unzip xsltproc | ||
|
|
||
| For **Ubuntu 18.04**, you need to downgrade the version of OpenSSL. (Ubuntu 18.04 bundles OpenSSL 1.1.0 by default, but OpenSSH only supports building against OpenSSL 1.0.2 at present.) | ||
|
|
||
| brew install autoconf automake libtool openssl | ||
| sudo apt install openssl1.0 libssl1.0-dev | ||
|
|
||
| Warning: this removes the existing libssl 1.1 development package. | ||
|
|
||
| You might have to install xcode for zlib dependency: | ||
| On **Linux**, you also may need to do the following: | ||
|
|
||
| xcode-select --install | ||
| - You may need to create the privilege separation directory: | ||
|
|
||
| sudo mkdir -p -m 0755 /var/empty | ||
|
|
||
| **On Ubuntu**: You need to install several tools using `apt`: | ||
| - You may need to create the privilege separation user: | ||
|
|
||
| sudo apt install make autoconf automake git libtool openssl zlib1g-dev libssl-dev | ||
| sudo groupadd sshd | ||
| sudo useradd -g sshd -c 'sshd privsep' -d /var/empty -s /bin/false sshd | ||
|
|
||
| For **macOS**, you need to install the following packages using brew (or a package manager of your choice): | ||
|
|
||
| brew install autoconf automake libtool openssl wget | ||
|
|
||
| ### Step 1: Build and install liboqs | ||
|
|
||
| First, you must download and build liboqs. You will need to specify a path to install liboqs in during configure time; we recommend that you install in a special-purpose directory, rather than the global `/usr` or `/usr/local` directories. As a summary: | ||
| You can use the either the [master](https://github.com/open-quantum-safe/liboqs/tree/master) or the [nist](https://github.com/open-quantum-safe/liboqs/tree/nist-branch) branch of liboqs with the OQS-master branch of OpenSSH. Each branch support a different set of KEX/KEM mechanisms (see above). | ||
|
|
||
| You will need to specify a path to install liboqs in during configure time; we recommend that you install in a special-purpose directory, rather than the global `/usr` or `/usr/local` directories. | ||
|
|
||
| For the **master branch** of liboqs: | ||
|
|
||
| git clone -b master --single-branch https://github.com/open-quantum-safe/liboqs.git | ||
| cd liboqs | ||
| autoreconf -i | ||
| ./configure --prefix=<path-to-install-liboqs> --with-pic=yes --enable-shared=no | ||
| ./configure --prefix=<path-to-openssl-dir>/oqs --with-pic=yes --enable-shared=no --enable-openssl --with-openssl-dir=<path-to-system-openssl-dir> | ||
| make -j | ||
| make install | ||
| rm -f <path-to-install-liboqs>/lib/liboqs.so* | ||
|
|
||
| Alternatively, you can compile OpenSSH against liboqs nist-branch using the following instructions: | ||
| On **Ubuntu**, `<path-to-system-openssl-dir>` is probably `/usr`. On **macOS** with brew, `<path-to-system-openssl-dir>` is probably `/usr/local/opt/openssl`. | ||
|
|
||
| For the **nist branch** of liboqs: | ||
|
|
||
| git clone -b nist-branch --single-branch https://github.com/open-quantum-safe/liboqs.git | ||
| cd liboqs | ||
| make | ||
| make install PREFIX=<path-to-install-liboqs> | ||
| rm -f <path-to-install-liboqs>/lib/liboqs.so* | ||
| make -j | ||
| make install-noshared PREFIX=<path-to-install-liboqs> | ||
|
|
||
| ### Step 2: Build fork of OpenSSH | ||
|
|
||
| Next, you can build and install our fork of OpenSSH: | ||
|
|
||
| export LIBOQS_INSTALL= TODO: your-install-location | ||
| export OPENSSH_INSTALL= TODO: another-install-location | ||
| export LIBOQS_INSTALL=<path-to-liboqs> | ||
| export OPENSSH_INSTALL=<path-to-install-openssh> | ||
| git clone https://github.com/open-quantum-safe/openssh-portable.git | ||
| cd openssh-portable | ||
| autoreconf | ||
|
|
||
| For Ubuntu 16.04 and MacOS, try the following: | ||
| For Ubuntu 16.04 and macOS, try the following: | ||
|
|
||
| ./configure --enable-pq-kex --enable-hybrid-kex \ | ||
| --with-ssl-dir=<path-to-openssl>/include \ | ||
|
|
@@ -124,7 +141,6 @@ For Ubuntu 16.04 and MacOS, try the following: | |
|
|
||
| On Ubuntu 18.04, some modifications are required due to the default openssl version: | ||
|
|
||
| apt install openssl1.0 libssl1.0-dev # WARNING: removes existing libssl dev pkg! | ||
| ./configure --enable-pq-kex --enable-hybrid-kex \ | ||
| --with-ldflags=-L/usr/lib/ssl1.0 \ | ||
| --prefix=$OPENSSH_INSTALL \ | ||
|
|
@@ -133,27 +149,10 @@ On Ubuntu 18.04, some modifications are required due to the default openssl vers | |
| make -j | ||
| make install | ||
|
|
||
| On Linux: | ||
|
|
||
| - 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 | ||
|
|
||
| Notes about building OpenSSH: | ||
|
|
||
| - `--enable-pq-kex` enables PQ-only key exchange methods. | ||
| - `--enable-hybrid-kex` enables hybrid key exchange methods. | ||
| - On some platforms such as Ubuntu, you may not need to specify the `--with-ssl-dir` and `--with-ldflags` options as OpenSSH-configure automatically detect your OpenSSL installation. | ||
| - If you do not use `--enable-shared=no` when building liboqs master, you may encounter problems with shared libraries when building/installing/running OpenSSH. These can be resolved by judiciously setting `LD_LIBRARY_PATH`, but it is easier to simply build liboqs master with *only* static libraries for OpenSSH to link against. | ||
| - We recommend that you install this fork of OpenSSH in a non-system directory (i.e., not `/usr` or `/usr/local`) | ||
| - With OpenSSL installed via brew on macOS, your command might be: | ||
|
|
||
| ./configure --enable-pq-kex --enable-hybrid-kex --with-ssl-dir=/usr/local/opt/openssl/include --with-ldflags=-L/usr/local/opt/openssl/lib --prefix=<path-to-install-openssh> --sysconfdir=<path-to-install-openssh> --with-liboqs-dir=<path-to-liboqs> | ||
|
|
||
| Running | ||
| ------- | ||
|
|
@@ -170,33 +169,12 @@ In another terminal, run a client: | |
|
|
||
| <path-to-openssh>/bin/ssh -l <username> -o 'KexAlgorithms=LIBOQSALGORITHM' -p 2222 localhost | ||
|
|
||
| where `LIBOQSALGORITHM` is one of the following: | ||
|
|
||
| _Hybrid key exchange methods:_ | ||
|
|
||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
|
|
||
| _PQ-only key exchange methods:_ | ||
|
|
||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| [email protected] | ||
| where `LIBOQSALGORITHM` is either: | ||
|
|
||
| - `[email protected]` (for post-quantum-only key exchange) | ||
| - `[email protected]` (for hybrid post-quantum and elliptic curve key exchange) | ||
|
|
||
| where `X` is one of the algorithms listed in the Contents section above. | ||
|
|
||
| ### Automated tests | ||
|
|
||
|
|
@@ -216,21 +194,19 @@ The purpose of this option is as follows. liboqs master branch and liboqs nist- | |
| - `cd liboqs` | ||
| - Edit `src/kem/kem.h` and change `#define OQS_KEM_DEFAULT` to map to your preferred algorithm | ||
| - `make clean` | ||
| - `make -j8` | ||
| - `make -j` | ||
| - `make install` | ||
| - For liboqs nist-branch: | ||
| - `cd liboqs` | ||
| - `make clean` | ||
| - `make -j8 KEM_DEFAULT=newhope_1024_cca_kem` (or whichever algorithm you prefer) | ||
| - `make install PREFIX=<path-to-install-liboqs>` | ||
| - `rm <path-to-install-liboqs>/lib/liboqs.so` | ||
| - `make -j KEM_DEFAULT=newhope_1024_cca_kem` (or whichever algorithm you prefer) | ||
| - `make install-noshared PREFIX=<path-to-install-liboqs>` | ||
| 2. Recompile OpenSSH against the newly build liboqs: | ||
| - `cd openssh-portable` | ||
| - `make clean` | ||
| - `make -j8` | ||
| - `make -j` | ||
| - `make install` | ||
| 3. Run `ssh` with `[email protected] ` or `[email protected]` for the `KexAlgorithms` option | ||
|
|
||
| 3. Run `ssh` with `[email protected] ` or `[email protected]` for the `KexAlgorithms` option. | ||
|
|
||
| License | ||
| ------- | ||
|
|
@@ -245,19 +221,27 @@ This repository contains an experimental (pre-draft) IETF draft for hybrid key e | |
| Team | ||
| ---- | ||
|
|
||
| The Open Quantum Safe project is led by [Michele Mosca](http://faculty.iqc.uwaterloo.ca/mmosca/) (University of Waterloo) and [Douglas Stebila](https://www.douglas.stebila.ca/research/) (University of Waterloo). | ||
| The Open Quantum Safe project is led by [Douglas Stebila](https://www.douglas.stebila.ca/research/) and [Michele Mosca](http://faculty.iqc.uwaterloo.ca/mmosca/) at the University of Waterloo. | ||
|
|
||
| ### Contributors | ||
|
|
||
| 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) | ||
| - Ben Davies (University of Waterloo) | ||
|
|
||
| Contributors to an earlier OQS fork of OpenSSH included: | ||
|
|
||
| - Mira Belenkiy (Microsoft Research) | ||
| - Karl Knopf (McMaster University) | ||
| - Christian Paquin (Microsoft Research) | ||
|
|
||
| ### Support | ||
|
|
||
| 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, and Microsoft 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 the source papers for funding acknowledgments. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| open-quantum-safe/openssh-portable OQS-master snapshot 2018-11 | ||
| ============================================================== | ||
|
|
||
| About | ||
| ----- | ||
|
|
||
| The **Open Quantum Safe (OQS) project** has the goal of developing and prototyping quantum-resistant cryptography. More information on OQS can be found on our website: https://openquantumsafe.org/ and on Github at https://github.com/open-quantum-safe/. | ||
|
|
||
| **liboqs** is an open source C library for quantum-resistant cryptographic algorithms. | ||
|
|
||
| **open-quantum-safe/openssh-portable** is an integration of liboqs into (a fork of) OpenSSH. The goal of this integration is to provide easy prototyping of quantum-resistant cryptography. The integration should not be considered "production quality". | ||
|
|
||
| This branch of our fork of OpenSSH can be used with the following versions of liboqs: | ||
|
|
||
| - **liboqs master branch** 0.1.0 | ||
| - **liboqs nist-branch** 2018-11 snapshot | ||
|
|
||
| Release notes | ||
| ============= | ||
|
|
||
| **This is a release candidate for the OQS fork of OpenSSH, not a final release.**. | ||
| This snapshot of the OQS fork of OpenSSH was released on TODO. Its release page on Github is TODO. | ||
|
|
||
| What's New | ||
| ---------- | ||
|
|
||
| This is the first snapshot release of the OQS fork of OpenSSH. | ||
|
|
||
| It is based on the upstream OpenSSH 7.7 portable 1 release. | ||
|
|
||
| It provides: | ||
|
|
||
| - post-quantum key exchange in SSH 2 | ||
| - hybrid (post-quantum + elliptic curve) key exchange in SSH 2 | ||
|
|
||
| It can build against either liboqs master branch or liboqs nist-branch. | ||
|
|
||
| Future work | ||
| ----------- | ||
|
|
||
| Snapshot releases of the OQS fork of OpenSSH will be made approximately bi-monthly. These will include syncing the branch with upstream releases of OpenSSH, and changes required to sync with new releases of liboqs. |