pyUmbral/README.rst

.. role:: bash(code)
   :language: bash

=========
pyUmbral
=========

.. start-badges

|version|  |circleci| |commits-since| |docs| |discord|

.. |docs| image:: https://readthedocs.org/projects/pyumbral/badge/?style=flat
    :target: https://readthedocs.org/projects/pyumbral
    :alt: Documentation Status

.. |discord| image:: https://img.shields.io/discord/411401661714792449.svg?logo=discord
    :target: https://discord.gg/xYqyEby
    :alt: Discord

.. |circleci| image:: https://img.shields.io/circleci/project/github/nucypher/pyUmbral.svg?logo=circleci
    :target: https://circleci.com/gh/nucypher/pyUmbral/tree/master
    :alt: CircleCI build status

.. |version| image:: https://img.shields.io/pypi/v/umbral.svg
    :alt: PyPI Package latest release
    :target: https://pypi.org/project/umbral

.. |commits-since| image:: https://img.shields.io/github/commits-since/nucypher/pyumbral/v0.1.3-alpha.0.svg
    :alt: Commits since latest release
    :target: https://github.com/nucypher/pyUmbral/compare/v0.1.3-alpha.0...master

.. end-badges

pyUmbral is a Python implementation of David Nuñez's threshold proxy re-encryption scheme: Umbral_.
Implemented with OpenSSL_ and Cryptography.io_, pyUmbral is a referential and open-source cryptography library
extending the traditional cryptological narrative of "Alice and Bob" by introducing a new actor,
*Ursula*, who has the ability to take secrets encrypted for Alice and *re-encrypt* them for Bob,
without being able to learn any information about the original secret.

pyUmbral is the cryptographic engine behind nucypher_,
a proxy re-encryption network to empower privacy in decentralized systems.

.. _Umbral: https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdf
.. _Cryptography.io: https://cryptography.io/en/latest/
.. _OpenSSL: https://www.openssl.org/
.. _nucypher: https://github.com/nucypher/nucypher

Usage
=====

**Key Generation**

As in any public-key cryptosystem, users need a pair of public and private keys.
Additionally, users that delegate access to their data (like Alice, in this example) need a signing keypair.

.. code-block:: python

    from umbral import pre, keys, signing

    # Generate Umbral keys for Alice.
    alices_private_key = keys.UmbralPrivateKey.gen_key()
    alices_public_key = alices_private_key.get_pubkey()

    alices_signing_key = keys.UmbralPrivateKey.gen_key()
    alices_verifying_key = alices_signing_key.get_pubkey()
    alices_signer = signing.Signer(private_key=alices_signing_key)

    # Generate Umbral keys for Bob.
    bobs_private_key = keys.UmbralPrivateKey.gen_key()
    bobs_public_key = bobs_private_key.get_pubkey()


**Encryption**

Now let's encrypt data with Alice's public key.
Invocation of ``pre.encrypt`` returns both the ``ciphertext`` and a ``capsule``.
Note that anyone with Alice's public key can perform this operation.

Since data was encrypted with Alice's public key,
Alice can open the capsule and decrypt the ciphertext with her private key.


.. code-block:: python

    # Encrypt data with Alice's public key.
    plaintext = b'Proxy Re-Encryption is cool!'
    ciphertext, capsule = pre.encrypt(alices_public_key, plaintext)

    # Decrypt data with Alice's private key.
    cleartext = pre.decrypt(ciphertext=ciphertext, 
                            capsule=capsule, 
                            decrypting_key=alices_private_key)


**Re-Encryption Key Fragments**

When Alice wants to grant Bob access to open her encrypted messages,
she creates *re-encryption key fragments*, or *"kfrags"*,
which are next sent to N proxies or *Ursulas*.

.. code-block:: python

    # Alice generates "M of N" re-encryption key fragments (or "KFrags") for Bob.
    # In this example, 10 out of 20.
    kfrags = pre.generate_kfrags(delegating_privkey=alices_private_key,
                                 signer=alices_signer,
                                 receiving_pubkey=bobs_public_key,
                                 threshold=10,
                                 N=20)


**Re-Encryption**

Bob asks several Ursulas to re-encrypt the capsule so he can open it.
Each Ursula performs re-encryption on the capsule using the ``kfrag``
provided by Alice, obtaining this way a "capsule fragment", or ``cfrag``.

Bob collects the resulting cfrags from several Ursulas.
Bob must gather at least ``threshold`` cfrags in order to activate the capsule.

.. code-block:: python

  # Several Ursulas perform re-encryption, and Bob collects the resulting `cfrags`.
  # He must gather at least `threshold` `cfrags` in order to activate the capsule.

  capsule.set_correctness_keys(delegating=alices_public_key,
                               receiving=bobs_public_key,
                               verifying=alices_verifying_key)

  cfrags = list()           # Bob's cfrag collection
  for kfrag in kfrags[:10]:
    cfrag = pre.reencrypt(kfrag=kfrag, capsule=capsule)
    cfrags.append(cfrag)    # Bob collects a cfrag


**Decryption by Bob**

Finally, Bob activates the capsule by attaching at least ``threshold`` cfrags,
and then decrypts the re-encrypted ciphertext.

.. code-block:: python

  # Bob activates and opens the capsule
  for cfrag in cfrags:
    capsule.attach_cfrag(cfrag)

  bob_cleartext = pre.decrypt(ciphertext=ciphertext, 
                              capsule=capsule, 
                              decrypting_key=bobs_private_key)
  assert bob_cleartext == plaintext

See more detailed usage examples in the docs_ directory.

.. _docs : https://github.com/nucypher/pyUmbral/tree/master/docs


Quick Installation
==================

To install pyUmbral, simply use ``pip``:

.. code-block:: bash

  $ pip3 install umbral


Alternatively, you can checkout the repo and install it from there. 
The NuCypher team uses ``pipenv`` for managing pyUmbral's dependencies.
The recommended installation procedure is as follows:

.. code-block:: bash

    $ sudo pip3 install pipenv
    $ pipenv install

Post-installation, you can activate the project virtual environment
in your current terminal session by running ``pipenv shell``.

For more information on ``pipenv``, find the official documentation here: https://docs.pipenv.org/.


Academic Whitepaper
====================

The Umbral scheme academic whitepaper and cryptographic specifications
are available on GitHub_.

  "Umbral: A Threshold Proxy Re-Encryption Scheme"
  *by David Nuñez*
  https://github.com/nucypher/umbral-doc/blob/master/umbral-doc.pdf

.. _GitHub: https://github.com/nucypher/umbral-doc/


Support & Contribute
=====================

- Issue Tracker: https://github.com/nucypher/pyUmbral/issues
- Source Code: https://github.com/nucypher/pyUmbral

OFAC Sanctions Disclaimer
=========================

By using this software, you hereby affirm you are not an individual or entity subject to economic sanctions administered by the U.S. Government or any other applicable authority, including but not limited to, sanctioned party lists administered by the U.S. Treasury Department’s Office of Foreign Assets Control (OFAC), the U.S. State Department, and the U.S. Commerce Department.  You further affirm you are not located in, or ordinarily resident in, any country, territory or region subject to comprehensive economic sanctions administered by OFAC, which are subject to change but currently include Cuba, Iran, North Korea, Syria and the Crimea region.