From 3dc86c3b03fba1d0db47e5e561ba9b4fda3be565 Mon Sep 17 00:00:00 2001 From: tiftof Date: Wed, 1 Oct 2008 12:57:29 +0000 Subject: [PATCH] doc en doctest updates git-svn-id: svn+ssh://devel.yobi.be/home/svn/CryptoPlus/trunk@33 49921240-e1b6-4d8d-af3b-5ae6c3d9e7c1 --- README | 4 ++++ src/Cipher/AES.py | 26 ++++++++++++++++++-------- src/Cipher/ARC2.py | 4 ++-- src/Cipher/Blowfish.py | 31 +++++++++++++++++++++++++------ src/Cipher/CAST.py | 14 ++++++++++++-- src/Cipher/python_AES.py | 33 +++++++++++++++++++++------------ src/Cipher/python_Blowfish.py | 16 ++++++++++++++-- src/Cipher/python_Serpent.py | 6 ++++-- src/Cipher/python_Twofish.py | 2 ++ 9 files changed, 102 insertions(+), 34 deletions(-) diff --git a/README b/README index 57adf5d..13c2ada 100644 --- a/README +++ b/README @@ -29,6 +29,10 @@ Note: for all the cipher algorithms, code has been reused from others. Appropria 2. INSTALLING ============== +necessary packages before installing: + - python-setuptools + - python-pkg-resources + python setup.py install 3. GETTING STARTED diff --git a/src/Cipher/AES.py b/src/Cipher/AES.py index f957b9c..f1947f4 100644 --- a/src/Cipher/AES.py +++ b/src/Cipher/AES.py @@ -15,23 +15,29 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): key = raw string containing the key, AES-128..256 will be selected according to the key length -> when using XTS mode: the key should be a concatenation of the 2 keys needed - mode = python_AES.MODE_ECB/CBC/CFB/OFB/CTR/XTS/CMAC + mode = AES.MODE_ECB/CBC/CFB/OFB/CTR/XTS/CMAC IV = IV as a raw string -> only needed for CBC mode counter = counter object (Cipher/util.py:Counter) -> only needed for CTR mode - EXAMPLE: - ---------- + ECB EXAMPLE: + ------------- + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F + >>> from CryptoPlus.Cipher import AES - >>> cipher = AES.new('0123456789012345') - >>> cipher.encrypt('0123456789012345') - '_}\\xf0\\xbf\\x10:\\x8cJ\\xe6\\xfa\\xad\\x99\\x06\\xac;*' - >>> cipher.decrypt(_) - '0123456789012345' + >>> cipher = AES.new('2b7e151628aed2a6abf7158809cf4f3c'.decode('hex')) + >>> crypted = cipher.encrypt('6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e51'.decode('hex')) + >>> crypted.encode('hex') + '3ad77bb40d7a3660a89ecaf32466ef97f5d3d58503b9699de785895a96fdbaaf' + >>> decipher = AES.new('2b7e151628aed2a6abf7158809cf4f3c'.decode('hex')) + >>> decipher.decrypt(crypted).encode('hex') + '6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e51' CBC EXAMPLE (plaintext = 3 blocksizes): ----------------------------------------- + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F + >>> from binascii import hexlify,unhexlify >>> from CryptoPlus.Cipher import AES >>> key = unhexlify('2b7e151628aed2a6abf7158809cf4f3c') @@ -63,6 +69,8 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): CTR EXAMPLE: ------------ + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F + >>> from CryptoPlus.Util.util import Counter >>> key = '2b7e151628aed2a6abf7158809cf4f3c'.decode('hex') >>> counter = Counter('f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff'.decode('hex')) @@ -107,6 +115,8 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): CMAC EXAMPLE: ------------- + NIST publication 800-38B: http://csrc.nist.gov/publications/nistpubs/800-38B/Updated_CMAC_Examples.pdf + >>> key = '2b7e151628aed2a6abf7158809cf4f3c'.decode('hex') >>> plaintext = '6bc1bee22e409f96e93d7e117393172a'.decode('hex') >>> cipher = AES.new(key,AES.MODE_CMAC) diff --git a/src/Cipher/ARC2.py b/src/Cipher/ARC2.py index 79f5ad5..4b6e5f3 100644 --- a/src/Cipher/ARC2.py +++ b/src/Cipher/ARC2.py @@ -35,7 +35,7 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None,effective_keylen=None >>> plaintext = "0000000000000000".decode('hex') >>> ek = 63 >>> cipher = ARC2.new(key,ARC2.MODE_ECB,effective_keylen=ek) - >>> cipher.encrypt(plaintext) + >>> cipher.encrypt(plaintext).encode('hex') 'ebb773f993278eff' """ return ARC2(key,mode,IV,counter,effective_keylen) @@ -46,7 +46,7 @@ class ARC2(blockcipher.BlockCipher): if parse_version(Crypto.__version__) <= parse_version("2.0.1"): self.cipher = Crypto.Cipher.ARC2.new(key) else: - self.cipher = Crypto.Cipher.ARC2.new(key,effective_keylen) + self.cipher = Crypto.Cipher.ARC2.new(key,effective_keylen=effective_keylen) self.blocksize = Crypto.Cipher.ARC2.block_size blockcipher.BlockCipher.__init__(self,key,mode,IV,counter) diff --git a/src/Cipher/Blowfish.py b/src/Cipher/Blowfish.py index e9d736b..c66a6eb 100644 --- a/src/Cipher/Blowfish.py +++ b/src/Cipher/Blowfish.py @@ -17,14 +17,14 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): key = raw string containing the key - mode = python_Blowfish.MODE_ECB/CBC/CFB/OFB/CTR/XTS/CMAC + mode = Blowfish.MODE_ECB/CBC/CFB/OFB/CTR/XTS/CMAC IV = IV as a raw string -> only needed for CBC mode counter = counter object (Cipher/util.py:Counter) -> only needed for CTR mode - EXAMPLE: - ---------- + ECB EXAMPLE: http://www.schneier.com/code/vectors.txt + ------------- >>> import Blowfish >>> from binascii import hexlify, unhexlify >>> cipher = Blowfish.new(unhexlify('0131D9619DC1376E')) @@ -33,10 +33,9 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): >>> hexlify( cipher.decrypt(unhexlify(_)) ) '5cd54ca83def57da' - CBC EXAMPLE: - ----------------------------------------- + CBC, CFB, OFB EXAMPLE: http://www.schneier.com/code/vectors.txt + ---------------------- >>> from binascii import hexlify,unhexlify - >>> import python_AES >>> key = unhexlify('0123456789ABCDEFF0E1D2C3B4A59687') >>> IV = unhexlify('FEDCBA9876543210') >>> plaintext = unhexlify('37363534333231204E6F77206973207468652074696D6520') @@ -44,6 +43,26 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): >>> ciphertext = cipher.encrypt(plaintext) >>> hexlify(ciphertext).upper() '6B77B4D63006DEE605B156E27403979358DEB9E7154616D9' + + + >>> key = '0123456789ABCDEFF0E1D2C3B4A59687'.decode('hex') + >>> iv = 'FEDCBA9876543210'.decode('hex') + >>> plaintext = '37363534333231204E6F77206973207468652074696D6520666F722000'.decode('hex') + + >>> cipher = Blowfish.new(key,Blowfish.MODE_CBC,iv) + >>> ciphertext = cipher.encrypt(plaintext) + >>> hexlify(ciphertext).upper() + '6B77B4D63006DEE605B156E27403979358DEB9E7154616D9' + + >>> cipher = Blowfish.new(key,Blowfish.MODE_CFB,iv) + >>> ciphertext = cipher.encrypt(plaintext) + >>> hexlify(ciphertext).upper() + 'E73214A2822139CAF26ECF6D2EB9E76E3DA3DE04D1517200519D57A6C3' + + >>> cipher = Blowfish.new(key,Blowfish.MODE_OFB,iv) + >>> ciphertext = cipher.encrypt(plaintext) + >>> hexlify(ciphertext).upper() + 'E73214A2822139CA62B343CC5B65587310DD908D0C241B2263C2CF80DA' """ return Blowfish(key,mode,IV,counter) diff --git a/src/Cipher/CAST.py b/src/Cipher/CAST.py index 56d0e4d..2bf9c3f 100644 --- a/src/Cipher/CAST.py +++ b/src/Cipher/CAST.py @@ -25,14 +25,24 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): counter = counter object (Cipher/util.py:Counter) -> only needed for CTR mode - http://www.rfc-editor.org/rfc/rfc2144.txt - ----------------------------------------- + ECB example: http://www.rfc-editor.org/rfc/rfc2144.txt + ------------- + 128 bit key + >>> from CryptoPlus.Cipher import CAST >>> key = "0123456712345678234567893456789A".decode('hex') >>> plaintext = "0123456789ABCDEF".decode('hex') >>> cipher = CAST.new(key,CAST.MODE_ECB,) >>> cipher.encrypt(plaintext).encode('hex') '238b4fe5847e44b2' + + 40 bit key + >>> from CryptoPlus.Cipher import CAST + >>> key = "0123456712".decode('hex') + >>> plaintext = "0123456789ABCDEF".decode('hex') + >>> cipher = CAST.new(key,CAST.MODE_ECB,) + >>> cipher.encrypt(plaintext).encode('hex').upper() + '7AC816D16E9B302E' """ return CAST(key,mode,IV,counter) diff --git a/src/Cipher/python_AES.py b/src/Cipher/python_AES.py index 1d72ef5..b508cad 100644 --- a/src/Cipher/python_AES.py +++ b/src/Cipher/python_AES.py @@ -36,15 +36,18 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): - Always construct a seperate cipher object for encryption and decryption. Once a cipher object has been used for encryption, it can't be used for decryption because it keeps a state (if necessary) for the IV. - EXAMPLE: - ---------- + ECB EXAMPLE: + ------------- + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F + >>> from CryptoPlus.Cipher import python_AES - >>> cipher = python_AES.new('0123456789012345') - >>> cipher.encrypt('0123456789012345') - '_}\\xf0\\xbf\\x10:\\x8cJ\\xe6\\xfa\\xad\\x99\\x06\\xac;*' - >>> decipher = python_AES.new('0123456789012345') - >>> decipher.decrypt(_) - '0123456789012345' + >>> cipher = python_AES.new('2b7e151628aed2a6abf7158809cf4f3c'.decode('hex')) + >>> crypted = cipher.encrypt('6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e51'.decode('hex')) + >>> crypted.encode('hex') + '3ad77bb40d7a3660a89ecaf32466ef97f5d3d58503b9699de785895a96fdbaaf' + >>> decipher = python_AES.new('2b7e151628aed2a6abf7158809cf4f3c'.decode('hex')) + >>> decipher.decrypt(crypted).encode('hex') + '6bc1bee22e409f96e93d7e117393172aae2d8a571e03ac9c9eb76fac45af8e51' PADDING EXAMPLE: ---------------- @@ -58,6 +61,8 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): CBC EXAMPLE (plaintext = 3 blocksizes): ----------------------------------------- + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F + >>> from binascii import hexlify,unhexlify >>> from CryptoPlus.Cipher import python_AES >>> key = unhexlify('2b7e151628aed2a6abf7158809cf4f3c') @@ -87,8 +92,9 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): >>> hexlify(decipher.decrypt(ciphertext[22:])) 'ae2d8a571e03ac9c9eb76fac45af8e5130c81c46a35ce411e5fbc1191a0a52ef' - CFB EXAMPLE: (testvectors from: SP 800-38A) (CFB128-AES192) + CFB EXAMPLE: (CFB128-AES192) ------------ + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F >>> key = '8e73b0f7da0e6452c810f32b809079e562f8ead2522c6b7b'.decode('hex') >>> IV = '000102030405060708090a0b0c0d0e0f'.decode('hex') @@ -116,8 +122,9 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): >>> output.encode('hex') 'cdc80d6fddf18cab34c25909c99a417467ce7f7f81173621961a2b70171d3d7a' - OFB EXAMPLE: (testvectors from: SP 800-38A) (OFB128-AES192) + OFB EXAMPLE: (OFB128-AES192) ------------ + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F >>> key = '8e73b0f7da0e6452c810f32b809079e562f8ead2522c6b7b'.decode('hex') >>> IV = '000102030405060708090a0b0c0d0e0f'.decode('hex') @@ -148,6 +155,8 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): CTR EXAMPLE: ------------ + NIST Special Publication 800-38A http://cryptome.org/bcm/sp800-38a.htm#F + >>> from CryptoPlus.Util.util import Counter >>> key = '2b7e151628aed2a6abf7158809cf4f3c'.decode('hex') >>> counter = Counter('f0f1f2f3f4f5f6f7f8f9fafbfcfdfeff'.decode('hex')) @@ -166,7 +175,7 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): XTS EXAMPLE: ------------ XTS-AES-128 applied for a data unit of 512 bytes - testvector: http://grouper.ieee.org/groups/1619/email/pdf00086.pdf + IEEE P1619/D16: http://grouper.ieee.org/groups/1619/email/pdf00086.pdf >>> key = ('27182818284590452353602874713526'.decode('hex'),'31415926535897932384626433832795'.decode('hex')) >>> plaintext = '000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f303132333435363738393a3b3c3d3e3f404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5d5e5f606162636465666768696a6b6c6d6e6f707172737475767778797a7b7c7d7e7f808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9fa0a1a2a3a4a5a6a7a8a9aaabacadaeafb0b1b2b3b4b5b6b7b8b9babbbcbdbebfc0c1c2c3c4c5c6c7c8c9cacbcccdcecfd0d1d2d3d4d5d6d7d8d9dadbdcdddedfe0e1e2e3e4e5e6e7e8e9eaebecedeeeff0f1f2f3f4f5f6f7f8f9fafbfcfdfeff'.decode('hex') @@ -246,7 +255,7 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): CMAC EXAMPLE: ------------- - testvector: http://csrc.nist.gov/publications/nistpubs/800-38B/Updated_CMAC_Examples.pdf + NIST publication 800-38B: http://csrc.nist.gov/publications/nistpubs/800-38B/Updated_CMAC_Examples.pdf >>> key = '2b7e151628aed2a6abf7158809cf4f3c'.decode('hex') >>> plaintext = '6bc1bee22e409f96e93d7e117393172a'.decode('hex') diff --git a/src/Cipher/python_Blowfish.py b/src/Cipher/python_Blowfish.py index 741f511..fd9448a 100644 --- a/src/Cipher/python_Blowfish.py +++ b/src/Cipher/python_Blowfish.py @@ -13,6 +13,8 @@ MODE_CBC = 2 MODE_CFB = 3 MODE_OFB = 5 MODE_CTR = 6 +#XTS only works with blocksizes of 16 bytes; Blowfish -> 8 bytes +#MODE_XTS = 7 MODE_CMAC = 8 def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): @@ -30,8 +32,18 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): >>> hexlify( cipher.decrypt(unhexlify(_)) ) '5cd54ca83def57da' - Examples from: http://www.schneier.com/code/vectors.txt - ------------------------------------------------------- + CBC, CFB, OFB EXAMPLE: http://www.schneier.com/code/vectors.txt + ---------------------- + >>> from binascii import hexlify,unhexlify + >>> key = unhexlify('0123456789ABCDEFF0E1D2C3B4A59687') + >>> IV = unhexlify('FEDCBA9876543210') + >>> plaintext = unhexlify('37363534333231204E6F77206973207468652074696D6520') + >>> cipher = python_Blowfish.new(key,python_Blowfish.MODE_CBC,IV) + >>> ciphertext = cipher.encrypt(plaintext) + >>> hexlify(ciphertext).upper() + '6B77B4D63006DEE605B156E27403979358DEB9E7154616D9' + + >>> key = '0123456789ABCDEFF0E1D2C3B4A59687'.decode('hex') >>> iv = 'FEDCBA9876543210'.decode('hex') >>> plaintext = '37363534333231204E6F77206973207468652074696D6520666F722000'.decode('hex') diff --git a/src/Cipher/python_Serpent.py b/src/Cipher/python_Serpent.py index 6f6cdfa..94afc5f 100644 --- a/src/Cipher/python_Serpent.py +++ b/src/Cipher/python_Serpent.py @@ -27,7 +27,9 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): see CTR example further on in the docstring EXAMPLE: - ---------- + --------- + NESSIE Test Vectors: http://www.cs.technion.ac.il/~biham/Reports/Serpent/Serpent-128-128.verified.test-vectors + >>> import python_Serpent >>> from binascii import hexlify, unhexlify >>> cipher = python_Serpent.new(unhexlify('000102030405060708090A0B0C0D0E0F')) @@ -45,7 +47,7 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): 'FDFDFDFDFDFDFDFDFDFDFDFDFDFDFDFD' CBC EXAMPLE: - ----------------------------------------- + ------------- >>> from binascii import hexlify,unhexlify >>> import python_Serpent >>> key = unhexlify('000102030405060708090A0B0C0D0E0F') diff --git a/src/Cipher/python_Twofish.py b/src/Cipher/python_Twofish.py index 9db3f18..979f770 100644 --- a/src/Cipher/python_Twofish.py +++ b/src/Cipher/python_Twofish.py @@ -31,6 +31,8 @@ def new(key,mode=blockcipher.MODE_ECB,IV=None,counter=None): EXAMPLE: ---------- + http://www.schneier.com/code/ecb_ival.txt -> test vector I=5 + >>> import python_Twofish >>> from binascii import hexlify, unhexlify >>> cipher = python_Twofish.new(unhexlify('019F9809DE1711858FAAC3A3BA20FBC3')) -- 2.11.4.GIT