adjust to python2.6 syntax, add docstrings

Author: gstarovo

src/ecdsa/der.py

@@ -152,9 +152,18 @@ def encode_number(n):
     return b"".join([int2byte(d) for d in b128_digits])
 
 
-def encode_boolean(n):
-    # True is a non-zero value, False is encoded as zero
-    return b"\x01" + encode_length(1) + encode_number(1 if n else 0)
+def encode_boolean(b):
+    """
+    Encodes BOOLEAN acording to ASN.1 DER format.
+    The ASN.1 BOOLEAN type has two possible values: TRUE and FALSE.
+    True is encoded as a non-zero value, False is encoded as a zero.
+
+    :param boolean b: the boolean value to be encoded
+    :return: a byte string
+    :rtype: bytes
+    """
+
+    return b"\x01" + encode_length(1) + encode_number(1 if b else 0)
 
 
 def is_sequence(string):
@@ -239,6 +248,15 @@ def remove_octet_string(string):
 
 
 def remove_boolean(string):
+    """
+    Removes the ASN.1 BOOLEAN type.
+    In DER, The BOOLEAN in ASN.1 DER encoding has the tag 01.
+    True is encoded as a non-zero value, False is encoded as a zero.
+
+    :param bytes string: the boolean value to be encoded
+    :return: a boolean value and the rest of the string
+    :rtype: tuple(boolean, bytes)
+    """
     if not string:
         raise UnexpectedDER("Empty string is an invalid encoding of a boolean")
     if string[:1] != b"\x01":

src/ecdsa/ecdsa.py

@@ -181,7 +181,7 @@ def __ne__(self, other):
         """Return False if the keys are identical, True otherwise."""
         return not self == other
 
-    def verifies(self, hash, signature, accelerate=False):
+    def verifies(self, hash, signature):
         """Verify that signature is a valid signature of hash.
         Return True if the signature is valid.
         """
@@ -194,7 +194,7 @@ def verifies(self, hash, signature, accelerate=False):
         s = signature.s
         if s < 1 or s > n - 1:
             return False
-        if type(r) in {bytearray, bytes, memoryview}:
+        if type(r) in set((bytearray, bytes, memoryview)):
             point = ellipticcurve.AbstractPoint.from_bytes(
                 self.generator.curve(), r)
             r = point[0] % n

src/ecdsa/keys.py

@@ -632,8 +632,7 @@ def verify(
         data,
         hashfunc=None,
         sigdecode=sigdecode_string,
-        allow_truncate=True,
-        accelerate=False
+        allow_truncate=True
     ):
         """
         Verify a signature made over provided data.
@@ -684,15 +683,14 @@ def verify(
         hashfunc = hashfunc or self.default_hashfunc
         digest = hashfunc(data).digest()
         return self.verify_digest(
-            signature, digest, sigdecode, allow_truncate, accelerate)
+            signature, digest, sigdecode, allow_truncate)
 
     def verify_digest(
         self,
         signature,
         digest,
         sigdecode=sigdecode_string,
-        allow_truncate=False,
-        accelerate=False
+        allow_truncate=False
     ):
         """
         Verify a signature made over provided hash value.
@@ -739,7 +737,7 @@ def verify_digest(
         except (der.UnexpectedDER, MalformedSignature) as e:
             raise BadSignatureError("Malformed formatting of signature", e)
         sig = ecdsa.Signature(r, s)
-        if self.pubkey.verifies(number, sig, accelerate):
+        if self.pubkey.verifies(number, sig):
             return True
         raise BadSignatureError("Signature verification failed")
 

src/ecdsa/test_pyecdsa.py

@@ -468,7 +468,7 @@ def test_sigencode_der_full_r(self):
         sig = priv1.sign(data, sigencode=sigencode_der_full_r, accelerate=True)
 
         self.assertEqual(type(sig), binary_type)
-        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_full_r, accelerate=True))
+        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_full_r))
 
     def test_sigencode_der_full_r_uncompressed(self):
         priv1 = SigningKey.generate()
@@ -480,7 +480,7 @@ def test_sigencode_der_full_r_uncompressed(self):
         sig = sigencode_der_full_r(point, s, None, encoding="uncompressed")
 
         self.assertEqual(type(sig), binary_type)
-        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_full_r, accelerate=True))
+        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_full_r))
 
     def test_sigencode_der_full_r_compressed(self):
         priv1 = SigningKey.generate()
@@ -492,7 +492,7 @@ def test_sigencode_der_full_r_compressed(self):
         sig = sigencode_der_full_r(point, s, None, encoding="compressed")
 
         self.assertEqual(type(sig), binary_type)
-        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_full_r, accelerate=True))
+        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_full_r))
 
     def test_sigencode_der_sig_value_with_y_boolean(self):
         priv1 = SigningKey.generate()
@@ -501,7 +501,7 @@ def test_sigencode_der_sig_value_with_y_boolean(self):
         sig = priv1.sign(data, sigencode=sigencode_der_sig_value_y_boolean,
                          accelerate=True)
         self.assertEqual(type(sig), binary_type)
-        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_ecdsa_sig_value, accelerate=True))
+        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_ecdsa_sig_value))
 
     def test_sigencode_der_sig_value_with_y_field_elem(self):
         priv1 = SigningKey.generate()
@@ -510,7 +510,7 @@ def test_sigencode_der_sig_value_with_y_field_elem(self):
         sig = priv1.sign(data, sigencode=sigencode_der_sig_value_y_field_elem,
                          accelerate=True)
         self.assertEqual(type(sig), binary_type)
-        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_ecdsa_sig_value, accelerate=True))
+        self.assertTrue(pub1.verify(sig, data, sigdecode=sigdecode_der_ecdsa_sig_value))
 
     def test_sigencode_string_canonize_no_change(self):
         r = 12

src/ecdsa/util.py

@@ -303,6 +303,31 @@ def sigencode_der(r, s, order):
 
 
 def sigencode_der_sig_value_y_field_elem(r, s, order):
+    """
+    Encode the signature into the ECDSA-Sig-Value structure using :term:`DER`.
+
+    Encodes the signature to the following :term:`ASN.1` structure::
+
+        ECDSA-Sig-Value ::= SEQUENCE {
+            r INTEGER,
+            s INTEGER,
+            a INTEGER OPTIONAL,
+            y CHOICE { b BOOLEAN, f FieldElement } OPTIONAL
+        }
+
+        with 'y' being a field element.
+
+    It's expected that this function will be used as a ``sigencode=`` parameter
+    in :func:`ecdsa.keys.SigningKey.sign` method.
+
+    :param int r: first parameter of the signature
+    :param int s: second parameter of the signature
+    :param int order: the order of the curve over which the signature was
+        computed
+
+    :return: DER encoding of ECDSA signature
+    :rtype: bytes
+    """
     y = r.y()
     r = r.x() % order
     f = number_to_string(y, order)
@@ -313,6 +338,31 @@ def sigencode_der_sig_value_y_field_elem(r, s, order):
 
 
 def sigencode_der_sig_value_y_boolean(r, s, order):
+    """
+    Encode the signature into the ECDSA-Sig-Value structure using :term:`DER`.
+
+    Encodes the signature to the following :term:`ASN.1` structure::
+
+        ECDSA-Sig-Value ::= SEQUENCE {
+            r INTEGER,
+            s INTEGER,
+            a INTEGER OPTIONAL,
+            y CHOICE { b BOOLEAN, f FieldElement } OPTIONAL
+        }
+
+        with 'y' being a boolean.
+
+    It's expected that this function will be used as a ``sigencode=`` parameter
+    in :func:`ecdsa.keys.SigningKey.sign` method.
+
+    :param int r: first parameter of the signature
+    :param int s: second parameter of the signature
+    :param int order: the order of the curve over which the signature was
+        computed
+
+    :return: DER encoding of ECDSA signature
+    :rtype: bytes
+    """
     y = r.y()
     r = r.x() % order
     b = False
@@ -330,16 +380,17 @@ def sigencode_der_full_r(r, s, order, encoding='raw'):
     Encodes the signature to the following :term:`ASN.1` structure::
 
         ECDSA-Full-R ::= SEQUENCE {
-            r       ECPoint,
-            s       INTEGER
+            r ECPoint,
+            s INTEGER
         }
 
-    Encodes the ECPoint with 'uncompressed' encoding.
+    Encodes the ECPoint with chosen encoding.
+    If no encoding was provided, the 'raw' encoding will be used.
 
     It's expected that this function will be used as a ``sigencode=`` parameter
     in :func:`ecdsa.keys.SigningKey.sign` method.
 
-    :param ECPoint r: first parameter of the signature
+    :param ECPoint r: the point used to create the signature
     :param int s: second parameter of the signature
     :param int order: the order of the curve over which the signature was
         computed