Add doctest examples

tuf/ed25519_key.py

@@ -41,6 +41,8 @@
 
  """
 
+from __future__ import print_function
+
 # Required for hexadecimal conversions.  Signatures are hexlified.
 import binascii
 
@@ -70,7 +72,7 @@
 def generate():
   """
   <Purpose> 
-    Generate an ed25519 pseed key ('sk') and public key ('pk').
+    Generate an ed25519 seed key ('sk') and public key ('pk').
     In addition, a keyid used as an identifier for ed25519 keys is generated.
     The object returned conforms to 'tuf.formats.ED25519KEY_SCHEMA' and has the
     form:
@@ -82,16 +84,20 @@ def generate():
     The public and private keys are strings.  An ed25519 seed key is a random
     32-byte value.  Public keys are also 32 bytes.
 
+    >>> ed25519_key = generate()
+    >>> tuf.formats.ED25519KEY_SCHEMA.matches(ed25519_key)
+    True
+    >>> len(ed25519_key['keyval']['public'])
+    32
+    >>> len(ed25519_key['keyval']['private'])
+    32
+
   <Arguments>
     None.
 
   <Exceptions>
     NotImplementedError, if a randomness source is not found.
 
-    ValueError, if an exception occurs after calling the RSA key generation
-    routine.  'bits' must be a multiple of 256.  The 'ValueError' exception is
-    raised by the key generation function of the cryptography library called.
-
   <Side Effects>
     The ed25519 keys are generated by first creating a random 32-byte value
     'sk' with os.urandom() and then calling ed25519's ed25519.25519.publickey(sk).
@@ -150,7 +156,7 @@ def create_in_metadata_format(key_value, private=False):
     
     or if 'private' is False:
 
-    {'keytype': 'rsa',
+    {'keytype': 'ed25519',
      'keyval': {'public': '\xb3\x17c\xda\x80\xed`F\xcc\xe4 ...',
                 'private': ''}}
     
@@ -158,6 +164,12 @@ def create_in_metadata_format(key_value, private=False):
     
     ed25519 keys are stored in Metadata files (e.g., root.txt) in the format
     returned by this function.
+
+    >>> ed25519_key = generate()
+    >>> key_val = ed25519_key['keyval']
+    >>> ed25519_metadata = create_in_metadata_format(key_val, private=True)
+    >>> tuf.formats.KEY_SCHEMA.matches(ed25519_metadata)
+    True
   
   <Arguments>
     key_value:
@@ -166,6 +178,7 @@ def create_in_metadata_format(key_value, private=False):
 
       {'public': '\xb3\x17c\xda\x80\xed`F\xcc\xe4 ...',
        'private': '\xd7D\xb9b\xdf\xf6*\xa1\xbb\x19 ...'}
+      
       conformat to 'tuf.formats.KEYVAL_SCHEMA'.
 
     private:
@@ -183,7 +196,6 @@ def create_in_metadata_format(key_value, private=False):
     A 'KEY_SCHEMA' dictionary.
 
   """
-	
 
   # Does 'key_value' have the correct format?
   # This check will ensure 'key_value' has the appropriate number
@@ -223,6 +235,15 @@ def create_from_metadata_format(key_metadata):
     new key and returns it in the format appropriate for 'keydb.py' and
     'keystore.py'.
 
+    >>> ed25519_key = generate()
+    >>> key_val = ed25519_key['keyval']
+    >>> ed25519_metadata = create_in_metadata_format(key_val, private=True)
+    >>> ed25519_key_2 = create_from_metadata_format(ed25519_metadata)
+    >>> tuf.formats.ED25519KEY_SCHEMA.matches(ed25519_key_2)
+    True
+    >>> ed25519_key == ed25519_key_2
+    True
+
   <Arguments>
     key_metadata:
       The ed25519 key dictionary as stored in Metadata files, conforming to
@@ -310,6 +331,14 @@ def create_signature(ed25519_key_dict, data):
     ed25519_key_dict['keyval']['public']
     
     and 'data' to generate the signature.
+    
+    >>> ed25519_key_dict = generate()
+    >>> data = 'The quick brown fox jumped over the lazy dog'
+    >>> signature = create_signature(ed25519_key_dict, data)
+    >>> tuf.formats.SIGNATURE_SCHEMA.matches(signature)
+    True
+    >>> len(signature['sig'])
+    128
 
   <Arguments>
     ed25519_key_dict:
@@ -395,6 +424,16 @@ def verify_signature(ed25519_key_dict, signature, data):
     and 'data' to complete the verification.  Type-checking performed on both
     'ed25519_key_dict' and 'signature'.
 
+    >>> ed25519_key_dict = generate()
+    >>> data = 'The quick brown fox jumped over the lazy dog'
+    >>> signature = create_signature(ed25519_key_dict, data)
+    >>> verify_signature(ed25519_key_dict, signature, data)
+    True
+    >>> bad_data = 'The sly brown fox jumped over the lazy dog'
+    >>> bad_signature = create_signature(ed25519_key_dict, bad_data) 
+    >>> verify_signature(ed25519_key_dict, bad_signature, data)
+    False
+  
   <Arguments>
     ed25519_key_dict:
       A dictionary containing the ed25519 keys and other identifying information.
@@ -461,9 +500,17 @@ def verify_signature(ed25519_key_dict, signature, data):
       ed25519.ed25519.checkvalid(signature, data, public_key)
       valid_signature = True
     except Exception, e:
-      message = 'The ed25519 signature could not be verified.'
-      raise tuf.CryptoError(message)
+      pass 
   else:
     raise tuf.UnknownMethodError(method)
 
   return valid_signature 
+
+
+
+if __name__ == '__main__':
+  # The interactive sessions of the documentation strings can
+  # be tested by running ed25519_key.py as a standalone module.
+  # python -B ed25519_key.py
+  import doctest
+  doctest.testmod()