Merge pull request #273 from fjarri/shares

Rename `num_kfrags` to `shares`

README.rst

@@ -115,7 +115,7 @@ which are next sent to N proxies or *Ursulas*.
                              receiving_pk=bobs_public_key,
                              signer=alices_signer,
                              threshold=10,
-                             num_kfrags=20)
+                             shares=20)
 
 
 **Re-Encryption**

docs/examples/umbral_simple_api.py

@@ -61,7 +61,7 @@
                          receiving_pk=bobs_public_key,
                          signer=alices_signer,
                          threshold=10,
-                         num_kfrags=20)
+                         shares=20)
 
 # Ursulas perform re-encryption
 # ------------------------------

docs/notebooks/pyUmbral Simple API.ipynb

@@ -180,7 +180,7 @@
     "                         receiving_pk=bobs_public_key,\n",
     "                         signer=alices_signer,\n",
     "                         threshold=M,\n",
-    "                         num_kfrags=N)"
+    "                         shares=N)"
    ]
   },
   {

docs/source/using_pyumbral.rst

@@ -96,7 +96,7 @@ When Alice wants to grant Bob access to view her encrypted data,
 she creates *re-encryption key fragments*, or *"kfrags"*,
 which are next sent to N proxies or *Ursulas*.
 
-Alice must specify ``num_kfrags`` (the total number of kfrags),
+Alice must specify ``shares`` (the total number of kfrags),
 and a ``threshold`` (the minimum number of kfrags needed to activate a capsule).
 In the following example, Alice creates 20 kfrags,
 but Bob needs to get only 10 re-encryptions to activate the capsule.
@@ -108,7 +108,7 @@ but Bob needs to get only 10 re-encryptions to activate the capsule.
     ...                          receiving_pk=bobs_public_key,
     ...                          signer=alices_signer,
     ...                          threshold=10,
-    ...                          num_kfrags=20)
+    ...                          shares=20)
 
 
 Bob receives a capsule

tests/conftest.py

@@ -35,7 +35,7 @@ def kfrags(alices_keys, bobs_keys):
     yield generate_kfrags(delegating_sk=delegating_sk,
                           signer=Signer(signing_sk),
                           receiving_pk=receiving_pk,
-                          threshold=6, num_kfrags=10)
+                          threshold=6, shares=10)
 
 
 @pytest.fixture(scope='session')

tests/test_capsule.py

@@ -60,7 +60,7 @@ def test_open_original(alices_keys):
 def test_open_reencrypted(alices_keys, bobs_keys):
 
     threshold = 6
-    num_kfrags = 10
+    shares = 10
 
     delegating_sk, signing_sk = alices_keys
     receiving_sk, receiving_pk = bobs_keys
@@ -73,7 +73,7 @@ def test_open_reencrypted(alices_keys, bobs_keys):
                              signer=signer,
                              receiving_pk=receiving_pk,
                              threshold=threshold,
-                             num_kfrags=num_kfrags)
+                             shares=shares)
 
     cfrags = [reencrypt(capsule, kfrag).cfrag for kfrag in kfrags]
     key_back = capsule.open_reencrypted(receiving_sk, delegating_pk, cfrags[:threshold])
@@ -96,7 +96,7 @@ def test_open_reencrypted(alices_keys, bobs_keys):
                               signer=signer,
                               receiving_pk=receiving_pk,
                               threshold=threshold,
-                              num_kfrags=num_kfrags)
+                              shares=shares)
     cfrags2 = [reencrypt(capsule, kfrag).cfrag for kfrag in kfrags2]
     with pytest.raises(ValueError, match="CapsuleFrags are not pairwise consistent"):
         capsule.open_reencrypted(receiving_sk, delegating_pk, [cfrags2[0]] + cfrags[:threshold-1])

tests/test_compatibility.py

@@ -100,7 +100,7 @@ def test_encrypt_decrypt(implementations):
 
 
 def _generate_kfrags(umbral, delegating_sk_bytes, receiving_pk_bytes,
-                     signing_sk_bytes, threshold, num_kfrags):
+                     signing_sk_bytes, threshold, shares):
 
     delegating_sk = umbral.SecretKey.from_bytes(delegating_sk_bytes)
     receiving_pk = umbral.PublicKey.from_bytes(receiving_pk_bytes)
@@ -110,7 +110,7 @@ def _generate_kfrags(umbral, delegating_sk_bytes, receiving_pk_bytes,
                                     receiving_pk=receiving_pk,
                                     signer=umbral.Signer(signing_sk),
                                     threshold=threshold,
-                                    num_kfrags=num_kfrags,
+                                    shares=shares,
                                     sign_delegating_key=True,
                                     sign_receiving_key=True,
                                     )
@@ -133,7 +133,7 @@ def test_kfrags(implementations):
     umbral1, umbral2 = implementations
 
     threshold = 2
-    num_kfrags = 3
+    shares = 3
     plaintext = b'peace at dawn'
 
     # On client 1
@@ -142,7 +142,7 @@ def test_kfrags(implementations):
     delegating_sk_bytes, delegating_pk_bytes = _create_keypair(umbral1)
     signing_sk_bytes, verifying_pk_bytes = _create_keypair(umbral1)
     kfrags_bytes = _generate_kfrags(umbral1, delegating_sk_bytes, receiving_pk_bytes,
-                                    signing_sk_bytes, threshold, num_kfrags)
+                                    signing_sk_bytes, threshold, shares)
 
     # On client 2
 
@@ -192,7 +192,7 @@ def test_reencrypt(implementations):
     umbral1, umbral2 = implementations
 
     threshold = 2
-    num_kfrags = 3
+    shares = 3
     plaintext = b'peace at dawn'
 
     # On client 1
@@ -204,7 +204,7 @@ def test_reencrypt(implementations):
     capsule_bytes, ciphertext = _encrypt(umbral1, plaintext, delegating_pk_bytes)
 
     kfrags_bytes = _generate_kfrags(umbral1, delegating_sk_bytes, receiving_pk_bytes,
-                                    signing_sk_bytes, threshold, num_kfrags)
+                                    signing_sk_bytes, threshold, shares)
 
     # On client 2
 

tests/test_pre.py

@@ -28,16 +28,16 @@ def test_public_key_encryption(alices_keys):
 
 
 SIMPLE_API_PARAMETERS = (
-    # (num_kfrags, threshold)
+    # (shares, threshold)
     (1, 1),
     (6, 1),
     (6, 4),
     (6, 6),
     (50, 30)
 )
 
-@pytest.mark.parametrize("num_kfrags, threshold", SIMPLE_API_PARAMETERS)
-def test_simple_api(num_kfrags, threshold):
+@pytest.mark.parametrize("shares, threshold", SIMPLE_API_PARAMETERS)
+def test_simple_api(shares, threshold):
     """
     This test models the main interactions between actors (i.e., Alice,
     Bob, Data Source, and Ursulas) and artifacts (i.e., public and private keys,
@@ -73,7 +73,7 @@ def test_simple_api(num_kfrags, threshold):
                              receiving_pk=receiving_pk,
                              signer=signer,
                              threshold=threshold,
-                             num_kfrags=num_kfrags)
+                             shares=shares)
 
     # Bob requests re-encryption to some set of M ursulas
     cfrags = [reencrypt(capsule, kfrag) for kfrag in kfrags]
@@ -111,7 +111,7 @@ def test_decrypt_unverified_cfrag(verification_keys, bobs_keys, capsule_and_ciph
                                               )
 
 
-def test_wrong_num_kfrags(alices_keys, bobs_keys):
+def test_wrong_shares(alices_keys, bobs_keys):
     delegating_sk, signing_sk = alices_keys
     _receiving_sk, receiving_pk = bobs_keys
 
@@ -121,4 +121,4 @@ def test_wrong_num_kfrags(alices_keys, bobs_keys):
                         signer=Signer(signing_sk),
                         receiving_pk=receiving_pk,
                         threshold=3,
-                        num_kfrags=2)
+                        shares=2)

umbral/pre.py

@@ -35,12 +35,12 @@ def generate_kfrags(delegating_sk: SecretKey,
                     receiving_pk: PublicKey,
                     signer: Signer,
                     threshold: int,
-                    num_kfrags: int,
+                    shares: int,
                     sign_delegating_key: bool = True,
                     sign_receiving_key: bool = True,
                     ) -> List[VerifiedKeyFrag]:
     """
-    Generates ``num_kfrags`` key fragments to pass to proxies for re-encryption.
+    Generates ``shares`` key fragments to pass to proxies for re-encryption.
     At least ``threshold`` of them will be needed for decryption.
     If ``sign_delegating_key`` or ``sign_receiving_key`` are ``True``,
     the corresponding keys will have to be provided to :py:meth:`KeyFrag.verify`.
@@ -49,12 +49,12 @@ def generate_kfrags(delegating_sk: SecretKey,
     base = KeyFragBase(delegating_sk, receiving_pk, signer, threshold)
 
     # Technically we could allow it, but what would be the use of these kfrags?
-    if num_kfrags < threshold:
-        raise ValueError(f"Creating less kfrags ({num_kfrags}) "
+    if shares < threshold:
+        raise ValueError(f"Creating less kfrags ({shares}) "
                          f"than threshold ({threshold}) makes them useless")
 
     kfrags = [KeyFrag.from_base(base, sign_delegating_key, sign_receiving_key)
-              for _ in range(num_kfrags)]
+              for _ in range(shares)]
 
     # Make them verified - we know they're good.
     return [VerifiedKeyFrag(kfrag) for kfrag in kfrags]

vectors/generate_test_vectors.py

@@ -52,7 +52,7 @@ def create_test_vector_file(vector, filename, generate_again=False):
                          receiving_pk=receiving_pk,
                          signer=Signer(signing_sk),
                          threshold=6,
-                         num_kfrags=10,
+                         shares=10,
                          )
 
 plain_data = b'peace at dawn'