From ecc481d4556e9085cb6ee2f45aea6922aea9e622 Mon Sep 17 00:00:00 2001 From: vladdd Date: Thu, 26 Sep 2013 14:16:17 -0400 Subject: [PATCH] Add doctest examples --- tuf/ed25519_key.py | 65 +++++++++++++++++++++++++++++++++++++++------- 1 file changed, 56 insertions(+), 9 deletions(-) diff --git a/tuf/ed25519_key.py b/tuf/ed25519_key.py index 6a579153..103c8b6f 100755 --- a/tuf/ed25519_key.py +++ b/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(): """ - 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 + None. 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. - 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 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 + 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 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 + 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()