add test vector information to the development section

3 files changed, 150 insertions, 1 deletions

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