From 1681a698a9fb75715bd51b6b1a877b6c8e045214 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 11 Feb 2014 23:43:51 -0600 Subject: add test vector information to the development section --- docs/development/index.rst | 1 + docs/development/submitting-patches.rst | 3 +- docs/development/test-vectors.rst | 147 ++++++++++++++++++++++++++++++++ 3 files changed, 150 insertions(+), 1 deletion(-) create mode 100644 docs/development/test-vectors.rst (limited to 'docs') diff --git a/docs/development/index.rst b/docs/development/index.rst index c0272299..50b60900 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -13,6 +13,7 @@ bug check out `what to put in your bug report`_. getting-started submitting-patches reviewing-patches + test-vectors .. _`GitHub`: https://github.com/pyca/cryptography .. _`what to put in your bug report`: http://www.contribution-guide.org/#what-to-put-in-your-bug-report diff --git a/docs/development/submitting-patches.rst b/docs/development/submitting-patches.rst index 5978a1d6..5dca3f79 100644 --- a/docs/development/submitting-patches.rst +++ b/docs/development/submitting-patches.rst @@ -144,7 +144,8 @@ All code changes must be accompanied by unit tests with 100% code coverage (as measured by the combined metrics across our build matrix). When implementing a new primitive or recipe ``cryptography`` requires that you -provide a set of test vectors. +provide a set of test vectors. See :doc:`/development/test-vectors` for more +details. Documentation ------------- diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst new file mode 100644 index 00000000..03e31f34 --- /dev/null +++ b/docs/development/test-vectors.rst @@ -0,0 +1,147 @@ +Test Vectors +============ + +Testing the correctness of the primitives implemented in each ``cryptography`` +backend requires trusted test vectors. Where possible these vectors are obtained +from official sources such as `NIST`_ or `IETF`_ RFCs. When this is not possible +``cryptography`` has chosen to create a set of custom vectors using an official +vector file as input to verify consistency between implemented backends. + +Sources +------- + +Asymmetric Ciphers +~~~~~~~~~~~~~~~~~~ + +* RSA PKCS1 from the RSA FTP site (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/ + and ftp://ftp.rsa.com/pub/rsalabs/tmp/). + +Hashes +~~~~~~ + +* MD5 from :rfc:`1321`. +* RIPEMD160 from the `RIPEMD website`_. +* SHA1 from `NIST CAVP`_. +* SHA2 (224, 256, 384, 512) from `NIST CAVP`_. +* Whirlpool from the `Whirlpool website`_. + +HMAC +~~~~ + +* HMAC-MD5 from :rfc:`2202`. +* HMAC-SHA1 from :rfc:`2202`. +* HMAC-RIPEMD160 from :rfc:`2286`. +* HMAC-SHA2 (224, 256, 384, 512) from :rfc:`4231`. + +Key Derivation Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +* HKDF (SHA1, SHA256) from :rfc:`5869`. +* PBKDF2 (HMAC-SHA1) from :rfc:`6070`. + +Recipes +~~~~~~~ + +* Fernet from its `specification repository`_. + +Symmetric Ciphers +~~~~~~~~~~~~~~~~~ + +* AES (CBC, CFB, CTR, ECB, GCM, OFB) from `NIST CAVP`_. +* 3DES (CBC, CFB, ECB, OFB) from `NIST CAVP`_. +* ARC4 from :rfc:`6229`. +* Blowfish (CBC, CFB, ECB, OFB) from `Bruce Schneier's vectors`_. +* Camellia (ECB) from NTT's `Camellia page`_ as linked by `CRYPTREC`_. +* Camellia (CBC, CFB, OFB) from `OpenSSL's test vectors`_. +* CAST5 (ECB) from :rfc:`2144`. + + +Creating Test Vectors +--------------------- + +To create test vectors for a block cipher the following code may be used as a +template: + +.. code-block:: python + + import binascii + + from cryptography.hazmat.backends.openssl.backend import backend + from cryptography.hazmat.primitives.ciphers import base, algorithms, modes + + + def encrypt(key, iv, plaintext): + cipher = base.Cipher( + algorithms.CAST5(binascii.unhexlify(key)), + modes.OFB(binascii.unhexlify(iv)), + backend + ) + encryptor = cipher.encryptor() + ct = encryptor.update(binascii.unhexlify(plaintext)) + ct += encryptor.finalize() + return binascii.hexlify(ct) + + + vector_file = open( + "tests/hazmat/primitives/vectors/ciphers/AES/OFB/OFBMMT128.rsp", + "r" + ) + + count = 0 + output = [] + key = None + iv = None + plaintext = None + ct = None + for line in vector_file: + line = line.strip() + if line.startswith("KEY"): + if count != 0: + output.append("CIPHERTEXT = {}".format(encrypt(key, iv, plaintext))) + output.append("\nCOUNT = {}".format(count)) + count += 1 + name, key = line.split(" = ") + output.append("KEY = {}".format(key)) + elif line.startswith("IV"): + name, iv = line.split(" = ") + iv = iv[0:16] + output.append("IV = {}".format(iv)) + elif line.startswith("PLAINTEXT"): + name, plaintext = line.split(" = ") + output.append("PLAINTEXT = {}".format(plaintext)) + + output.append("CIPHERTEXT = {}".format(encrypt(key, iv, plaintext))) + print("\n".join(output)) + +The algorithm, mode, and vector_file loaded must be modified to fit on a case +by case basis. Additionally, the IV must be truncated (if necessary) to the +length of the block size. + +The output generated by this script **must** be verified against at least one +other implementation. In the example above, the vectors were generated against +OpenSSL's implementation, so they must be verified against an implementation +such as ``CommonCrypto`` or ``Go``. + +Any vectors generated by this method must also be prefixed with the following +header format (substituting the correct information): + +.. code-block:: python + + # CAST5 CBC vectors built for https://github.com/pyca/cryptography + # Derived from the AESVS MMT test data for CBC + # Verified against the CommonCrypto and Go crypto packages + # Key Length : 128 + +If official test vectors appear in the future the custom generated vectors +should be discarded. + +.. _`NIST`: http://www.nist.gov/ +.. _`IETF`: https://www.ietf.org/ +.. _`NIST CAVP`: http://csrc.nist.gov/groups/STM/cavp/ +.. _`Bruce Schneier's vectors`: https://www.schneier.com/code/vectors.txt +.. _`Camellia page`: http://info.isl.ntt.co.jp/crypt/eng/camellia/ +.. _`CRYPTREC`: http://www.cryptrec.go.jp +.. _`OpenSSL's test vectors`: https://github.com/openssl/openssl/blob/97cf1f6c2854a3a955fd7dd3a1f113deba00c9ef/crypto/evp/evptests.txt#L232 +.. _`RIPEMD website`: http://homes.esat.kuleuven.be/~bosselae/ripemd160.html +.. _`Whirlpool website`: http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html +.. _`Specification repository`: https://github.com/fernet/spec -- cgit v1.2.3