Add OQS rand API support (#19)

Add OQS rand API support

Author: dstebila

.gitignore

@@ -2,4 +2,119 @@
 __pycache__
 liboqs.so
 *.pyc
-test-results
+test-results
+
+.swp
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# PyCharm & virtualenv
+.idea
+bin/
+include/
+lib/
+spell/
+pip-selfcheck.json
+pyvenv.cfg
+
+# vim
+*.swp

CHANGES.txt

@@ -0,0 +1,11 @@
+Version 0.2.1 - January 22, 2020
+    - Added a signature example
+    - Added partial support for RNGs from <oqs/rand.h>
+    - Added an RNG example
+
+Version 0.2.0 - October 8, 2019
+    - This release updates for compatibility with liboqs 0.2.0, which contains
+      new/updated algorithms based on NIST Round 2 submissions.
+
+Version 0.1.0 - April 23, 2019
+    - Initial release

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Open Quantum Safe
+Copyright (c) 2018-2020 Open Quantum Safe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -33,25 +33,29 @@ Contents
 
 The project contains the following files:
 
- - **`oqs/wrapper.py`: a Python 3 module wrapper for the liboqs C library.**
- - `examples/example.py`: illustrates the usage of the liboqs-python wrapper.
- - `tests/test_*.py`: unit tests for the liboqs-python wrapper.
+ - **`oqs/oqs.py`: a Python 3 module wrapper for the liboqs C library.**
+ - `oqs/rand.py`: a Python 3 module supporting RNGs from `<oqs/rand.h>`
+ - `examples/kem.py`: key encapsulation example
+ - `examples/rand.py`: RNG example
+ - `examples/sig.py`: signature example
+ - `tests`: unit tests
 
 Usage
 -----
 
-liboqs-python defines two main classes: `KeyEncapsulation` and `Signature`, providing post-quantum key encapsulation and signture mechanisms, respectively. Each must be instantiated with a string identifying one of mechanisms supported by liboqs; these can be enumerated using the `get_enabled_KEM_mechanisms` and `get_enabled_sig_mechanisms` functions. The `example.py` file demonstrates the wrapper's API.
+liboqs-python defines two main classes: `KeyEncapsulation` and `Signature`, providing post-quantum key encapsulation and signture mechanisms, respectively. Each must be instantiated with a string identifying one of mechanisms supported by liboqs; these can be enumerated using the `get_enabled_KEM_mechanisms` and `get_enabled_sig_mechanisms` functions. The files in `examples/` demonstrate the wrapper's API.
+Support for alternative RNGs is provided via the `randombytes[*]` functions.
 
 liboqs installation
 -------------------
 
 liboqs-python depends on the liboqs C library; it must be compiled as a Linux/macOS library or Windows DLL, and installed in one of:
 
-- any file path specified by the `LIBOQS_INSTALL_PATH` environment variable (e.g. `LIBOQS_INSTALL_PATH="/path/to/liboqs.so"`)
+- any file path specified by the `LIBOQS_INSTALL_PATH` environment variable (e.g. `LIBOQS_INSTALL_PATH="/usr/local/bin/liboqs.so"`; **do not forget to specify `liboqs.so` at the end**)
 - system-wide folder
 - the liboqs Python module's current folder
 
-`wrapper.py` checks the above locations in that order. At present, only liboqs master branch can be installed; see the [liboqs project](https://github.com/open-quantum-safe/liboqs/) for installation instructions.
+`oqs/oqs.py` checks the above locations in that order. At present, only liboqs master branch can be installed; see the [liboqs project](https://github.com/open-quantum-safe/liboqs/) for installation instructions.
 
 liboqs-python does not depend on any other Python packages. The package isn't hosted on PyPI yet, but can be installed into a virtualenv using:
 
@@ -71,9 +75,9 @@ The liboqs-python project should be in the `PYTHONPATH`:
 
 As any python module, liboqs wrapper components can be imported into python programs with `import oqs`.
 
-To run the example program:
+To run an example program:
 
-	python3 examples/example.py
+	python3 examples/kem.py
 
 To run the unit tests with a test runner (e.g. nose or rednose (`apt install python3-nose python3-rednose` or `pip3 install nose rednose`)):
 
@@ -112,12 +116,14 @@ The Open Quantum Safe project is led by [Douglas Stebila](https://www.douglas.st
 Contributors to the liboqs-python wrapper include:
 
 - Ben Davies (University of Waterloo)
+- Vlad Gheorghiu (evolutionQ, University of Waterloo)
 - Christian Paquin (Microsoft Research)
+- Douglas Stebila (University of Waterloo)
 
 ### 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.
+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, Cisco Systems, evolutionQ, IBM Research, 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.

RELEASE.md

@@ -1,23 +1,25 @@
-liboqs-python version 0.2.0
+liboqs-python version 0.2.1
 ===========================
 
 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/.  
+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.  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.
 
-**liboqs-python** is an open source Python 3 wrapper for the liboqs C library for quantum-resistant cryptographic algorithms.  Details about liboqs-python can be found in [README.md](https://github.com/open-quantum-safe/liboqs-python/blob/master/README.md).  See in particular limitations on intended use.
+**liboqs-python** is an open source Python 3 wrapper for the liboqs C library for quantum-resistant cryptographic algorithms. Details about liboqs-python can be found in [README.md](https://github.com/open-quantum-safe/liboqs-python/blob/master/README.md). See in particular limitations on intended use.
 
 Release notes
 =============
 
-This release of liboqs-python was released on October 8, 2019.  Its release page on GitHub is https://github.com/open-quantum-safe/liboqs-python/releases/tag/0.2.0.
+This release of liboqs-python was released on January 22, 2020. Its release page on GitHub is https://github.com/open-quantum-safe/liboqs-python/releases/tag/0.2.1.
 
 What's New
 ----------
 
-This is the second release of liboqs-python.
+This is the third release of liboqs-python. 
 
-This release updates for compatibility with liboqs 0.2.0, which contains new/updated algorithms based on NIST Round 2 submissions.
+This release added partial support for RNGs from `<oqs/rand.h>`, together with a signature example and an RNG example.
+
+For a list of changes see [CHANGES.txt](https://github.com/open-quantum-safe/liboqs-python/blob/master/CHANGES.txt).

examples/example.py

@@ -0,0 +1,36 @@
+# key encapsulation Python example
+
+from pprint import pprint
+import oqs
+
+#######################################################################
+# KEM example
+#######################################################################
+
+kems = oqs.get_enabled_KEM_mechanisms()
+
+print('Enabled KEM mechanisms:')
+pprint(kems)
+
+# create client and server with default KEM mechanisms
+kemalg = "DEFAULT"
+with oqs.KeyEncapsulation(kemalg) as client:
+    with oqs.KeyEncapsulation(kemalg) as server:
+        print("\nKey encapsulation details:")
+        pprint(client.details)
+
+        # client generates its keypair
+        public_key = client.generate_keypair()
+        # optionally, the secret key can be obtained by calling export_secret_key()
+        # and the client can later be re-instantiated with the key pair:
+        # secret_key = client.export_secret_key()
+        # store key pair, wait... (session resumption):
+        # client = oqs.KeyEncapsulation(kemalg, secret_key)
+
+        # the server encapsulates its secret using the client's public key
+        ciphertext, shared_secret_server = server.encap_secret(public_key)
+
+        # the client decapsulates the the server's ciphertext to obtain the shared secret
+        shared_secret_client = client.decap_secret(ciphertext)
+        
+        print("\nShared secretes coincide:", shared_secret_client == shared_secret_server)

examples/kem.py

@@ -0,0 +1,23 @@
+# various RNGs Python example
+
+import oqs.rand as oqsrand  # must be explicitly imported
+
+#######################################################################
+# randomness example
+#######################################################################
+
+# set the entropy seed to some random values
+entropy_seed = [0] * 48
+entropy_seed[0] = 100
+entropy_seed[20] = 200
+entropy_seed[47] = 150
+
+oqsrand.randombytes_nist_kat_init(bytes(entropy_seed))
+oqsrand.randombytes_switch_algorithm('NIST-KAT')
+print('{:17s}'.format("NIST-KAT:"), ' '.join('{:02X}'.format(x) for x in oqsrand.randombytes(32)))
+
+oqsrand.randombytes_switch_algorithm("OpenSSL")
+print('{:17s}'.format("OpenSSL:"), ' '.join('{:02X}'.format(x) for x in oqsrand.randombytes(32)))
+
+oqsrand.randombytes_switch_algorithm("system")
+print('{:17s}'.format("System (default):"), ' '.join('{:02X}'.format(x) for x in oqsrand.randombytes(32)))