Merge pull request #267 from fjarri/interfacing-2

Interfacing with Rust, part 2

.circleci/config.yml

@@ -121,9 +121,12 @@ commands:
       - run:
           name: Install Python dependencies with Pipenv
           command: pipenv install --python << parameters.python_version >> --dev --skip-lock --pre
+      # Workaround for pipenv check erroneously requiring pip>=21.1,
+      # even if it is in fact installed and that version is fixed in Pipfile.
+      # See https://github.com/pypa/pipenv/issues/4147
       - run:
           name: Check PEP 508 Requirements
-          command: pipenv check
+          command: pipenv check --ignore 40291
       - persist_to_workspace:
           root: ~/.local/share/virtualenvs/
           paths:

README.rst

@@ -62,13 +62,14 @@ Additionally, users that delegate access to their data (like Alice, in this exam
 
 .. code-block:: python
 
-    from umbral import SecretKey, PublicKey
+    from umbral import SecretKey, PublicKey, Signer
 
     # Generate Umbral keys for Alice.
     alices_secret_key = SecretKey.random()
     alices_public_key = PublicKey.from_secret_key(alices_secret_key)
 
     alices_signing_key = SecretKey.random()
+    alices_signer = Signer(alices_signing_key)
     alices_verifying_key = PublicKey.from_secret_key(alices_signing_key)
 
     # Generate Umbral keys for Bob.
@@ -112,7 +113,7 @@ which are next sent to N proxies or *Ursulas*.
     # In this example, 10 out of 20.
     kfrags = generate_kfrags(delegating_sk=alices_secret_key,
                              receiving_pk=bobs_public_key,
-                             signing_sk=alices_signing_key,
+                             signer=alices_signer,
                              threshold=10,
                              num_kfrags=20)
 

docs/examples/umbral_simple_api.py

@@ -1,6 +1,6 @@
 import random
 from umbral import (
-    SecretKey, PublicKey, GenericError,
+    SecretKey, PublicKey, Signer, GenericError, CapsuleFrag,
     encrypt, generate_kfrags, reencrypt, decrypt_original, decrypt_reencrypted)
 
 # Generate an Umbral key pair
@@ -13,6 +13,7 @@
 
 alices_signing_key = SecretKey.random()
 alices_verifying_key = PublicKey.from_secret_key(alices_signing_key)
+alices_signer = Signer(alices_signing_key)
 
 # Encrypt some data for Alice
 # ---------------------------
@@ -58,7 +59,7 @@
 
 kfrags = generate_kfrags(delegating_sk=alices_secret_key,
                          receiving_pk=bobs_public_key,
-                         signing_sk=alices_signing_key,
+                         signer=alices_signer,
                          threshold=10,
                          num_kfrags=20)
 
@@ -85,14 +86,18 @@
 
 # Bob checks the capsule fragments
 # --------------------------------
-# Bob can verify that the capsule fragments are valid and really originate from Alice,
+# If Bob received the capsule fragments in serialized form,
+# he can verify that they are valid and really originate from Alice,
 # using Alice's public keys.
 
-assert all(cfrag.verify(capsule,
-                        delegating_pk=alices_public_key,
-                        receiving_pk=bobs_public_key,
-                        signing_pk=alices_verifying_key)
-           for cfrag in cfrags)
+suspicious_cfrags = [CapsuleFrag.from_bytes(bytes(cfrag)) for cfrag in cfrags]
+
+cfrags = [cfrag.verify(capsule,
+                       verifying_pk=alices_verifying_key,
+                       delegating_pk=alices_public_key,
+                       receiving_pk=bobs_public_key,
+                       )
+          for cfrag in suspicious_cfrags]
 
 # Bob opens the capsule
 # ------------------------------------
@@ -101,7 +106,7 @@
 bob_cleartext = decrypt_reencrypted(decrypting_sk=bobs_secret_key,
                                     delegating_pk=alices_public_key,
                                     capsule=bob_capsule,
-                                    cfrags=cfrags,
+                                    verified_cfrags=cfrags,
                                     ciphertext=ciphertext)
 print(bob_cleartext)
 assert bob_cleartext == plaintext

docs/notebooks/pyUmbral Simple API.ipynb

@@ -22,15 +22,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from umbral import SecretKey, PublicKey\n",
+    "from umbral import SecretKey, PublicKey, Signer\n",
     "\n",
     "\n",
     "# Alice's Keys\n",
     "alices_private_key = SecretKey.random()\n",
     "alices_public_key = PublicKey.from_secret_key(alices_private_key)\n",
     "\n",
     "alices_signing_key = SecretKey.random()\n",
-    "alices_verifying_key = PublicKey.from_secret_key(alices_signing_key)"
+    "alices_verifying_key = PublicKey.from_secret_key(alices_signing_key)\n",
+    "alices_signer = Signer(alices_signing_key)"
    ]
   },
   {
@@ -55,7 +56,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "b'\\x1c\\xa0\\xa83\\x0cv\\x97\\x02d\\xe9\\xe9\\xc5_\\x9d5NRGRx\\xd4\\xc9\\x17%\\x9b\\xb4\\x05\\xd1\\xc2\\x1e\\x9d\\x0b\\xbf\\xb4g\\xf0n\\xfe\\x9eM\\x93\\xe0\\xbf#l\\xf9\\x033\\xb00\\xf5\\r\\xff\\xc9\\x133C\\xf0\\xa3\\xc0\\xd1e\\xdb~.E$%'\n"
+      "b'\\xfb\\xc3T\\xb2\\x89=\\x08X\\xb1<\\xd0G/\\xab\\x8c\\xac\\x7f\\xd4)\\xcbB\\xcb^\\x99;P\\x9c\\xbf\\xaaf\\x03\\xdd\\n\\x1f$\\x1b\\xfb\\x88\\xfa\\xcd\\xe2\\x11\\x8d\\xcf\\xe5\\x88\\xaf\\x00\\xfe\\xcb\\x9d\\xf83\\x17\\x9b\\xdd\\xba\\xab\\x8b\\x08\\xbe\\xb1M\\x80\\xf1<S#'\n"
      ]
     }
    ],
@@ -169,7 +170,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 8,
+   "execution_count": 7,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -179,7 +180,7 @@
     "M, N = 10, 20 # the threshold and the total number of fragments\n",
     "kfrags = generate_kfrags(delegating_sk=alices_private_key,\n",
     "                         receiving_pk=bobs_public_key,\n",
-    "                         signing_sk=alices_signing_key,\n",
+    "                         signer=alices_signer,\n",
     "                         threshold=M,\n",
     "                         num_kfrags=N)"
    ]
@@ -195,7 +196,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 8,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -218,22 +219,27 @@
    "metadata": {},
    "source": [
     "## Bob checks the capsule fragments\n",
-    "Bob can verify that the capsule fragments are valid and really originate from Alice, using Alice's public keys."
+    "If Bob received the capsule fragments in serialized form, he can verify that they are valid and really originate from Alice, using Alice's public keys."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 11,
+   "execution_count": 10,
    "metadata": {
     "scrolled": true
    },
    "outputs": [],
    "source": [
-    "assert all(cfrag.verify(capsule,\n",
-    "                        delegating_pk=alices_public_key,\n",
-    "                        receiving_pk=bobs_public_key,\n",
-    "                        signing_pk=alices_verifying_key)\n",
-    "           for cfrag in cfrags)"
+    "from umbral import CapsuleFrag\n",
+    "\n",
+    "suspicious_cfrags = [CapsuleFrag.from_bytes(bytes(cfrag)) for cfrag in cfrags]\n",
+    "\n",
+    "cfrags = [cfrag.verify(capsule,\n",
+    "                       verifying_pk=alices_verifying_key,\n",
+    "                       delegating_pk=alices_public_key,\n",
+    "                       receiving_pk=bobs_public_key,\n",
+    "                       )\n",
+    "          for cfrag in suspicious_cfrags]"
    ]
   },
   {
@@ -263,7 +269,7 @@
     "bob_cleartext = decrypt_reencrypted(decrypting_sk=bobs_private_key,\n",
     "                                    delegating_pk=alices_public_key,\n",
     "                                    capsule=capsule,\n",
-    "                                    cfrags=cfrags,\n",
+    "                                    verified_cfrags=cfrags,\n",
     "                                    ciphertext=ciphertext)\n",
     "\n",
     "print(bob_cleartext)\n",

docs/source/api.rst

@@ -19,6 +19,14 @@ Keys
     :members:
     :show-inheritance:
 
+.. autoclass:: Signer
+    :members:
+
+.. autoclass:: Signature()
+    :members:
+    :special-members: __eq__, __hash__
+    :show-inheritance:
+
 Intermediate objects
 --------------------
 
@@ -31,11 +39,17 @@ Intermediate objects
     :special-members: __eq__, __hash__
     :show-inheritance:
 
+.. autoclass:: VerifiedKeyFrag()
+    :special-members: __eq__, __hash__
+
 .. autoclass:: CapsuleFrag()
-    :members: verify
+    :members:
     :special-members: __eq__, __hash__
     :show-inheritance:
 
+.. autoclass:: VerifiedCapsuleFrag()
+    :special-members: __eq__, __hash__
+
 Encryption, re-encryption and decryption
 ----------------------------------------
 
@@ -55,6 +69,9 @@ Utilities
 .. autoclass:: umbral.GenericError
     :show-inheritance:
 
+.. autoclass:: umbral.VerificationError
+    :show-inheritance:
+
 .. autoclass:: umbral.serializable.Serializable
     :members: from_bytes
     :special-members: __bytes__

docs/source/conf.py

@@ -20,8 +20,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'pyUmbral'
-copyright = u'2019, Michael Egorov, Justin Myles Holmes, David Nuñez, John Pacific, Kieran Prasch'
-author = u'Michael Egorov, Justin Myles Holmes, David Nuñez, John Pacific, Kieran Prasch'
+copyright = u'2019, Michael Egorov, Justin Myles Holmes, David Nuñez, John Pacific, Kieran Prasch, Bogdan Opanchuk'
+author = u'Michael Egorov, Justin Myles Holmes, David Nuñez, John Pacific, Kieran Prasch, Bogdan Opanchuk'
 
 # The short X.Y version
 version = '0.1'
@@ -133,7 +133,7 @@
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
     (master_doc, 'pyUmbral.tex', 'pyUmbral Documentation',
-     u'Michael Egorov, Justin Myles Holmes, David Nuñez, John Pacific, Kieran Prasch', 'manual'),
+     u'Michael Egorov, Justin Myles Holmes, David Nuñez, John Pacific, Kieran Prasch, Bogdan Opanchuk', 'manual'),
 ]
 
 

docs/source/using_pyumbral.rst

@@ -43,13 +43,14 @@ A delegating key pair and a signing key pair.
 
 .. doctest:: capsule_story
 
-    >>> from umbral import SecretKey, PublicKey
+    >>> from umbral import SecretKey, PublicKey, Signer
 
     >>> alices_secret_key = SecretKey.random()
     >>> alices_public_key = PublicKey.from_secret_key(alices_secret_key)
 
     >>> alices_signing_key = SecretKey.random()
     >>> alices_verifying_key = PublicKey.from_secret_key(alices_signing_key)
+    >>> alices_signer = Signer(alices_signing_key)
 
 
 Encrypt with a public key
@@ -105,7 +106,7 @@ but Bob needs to get only 10 re-encryptions to activate the capsule.
     >>> from umbral import generate_kfrags
     >>> kfrags = generate_kfrags(delegating_sk=alices_secret_key,
     ...                          receiving_pk=bobs_public_key,
-    ...                          signing_sk=alices_signing_key,
+    ...                          signer=alices_signer,
     ...                          threshold=10,
     ...                          num_kfrags=20)
 
@@ -172,17 +173,20 @@ Decryption
 
 Bob checks the capsule fragments
 --------------------------------
-Bob can verify that the capsule fragments are valid and really originate from Alice,
+If Bob received the capsule fragments in serialized form,
+he can verify that they are valid and really originate from Alice,
 using Alice's public keys.
 
 .. doctest:: capsule_story
 
-    >>> all(cfrag.verify(capsule,
-    ...                  delegating_pk=alices_public_key,
-    ...                  receiving_pk=bobs_public_key,
-    ...                  signing_pk=alices_verifying_key)
-    ...     for cfrag in cfrags)
-    True
+    >>> from umbral import CapsuleFrag
+    >>> suspicious_cfrags = [CapsuleFrag.from_bytes(bytes(cfrag)) for cfrag in cfrags]
+    >>> cfrags = [cfrag.verify(capsule,
+    ...                        verifying_pk=alices_verifying_key,
+    ...                        delegating_pk=alices_public_key,
+    ...                        receiving_pk=bobs_public_key,
+    ...                        )
+    ...           for cfrag in suspicious_cfrags]
 
 
 Bob opens the capsule
@@ -195,7 +199,7 @@ Finally, Bob decrypts the re-encrypted ciphertext using his key.
     >>> cleartext = decrypt_reencrypted(decrypting_sk=bobs_secret_key,
     ...                                 delegating_pk=alices_public_key,
     ...                                 capsule=capsule,
-    ...                                 cfrags=cfrags,
+    ...                                 verified_cfrags=cfrags,
     ...                                 ciphertext=ciphertext)