add test vector information to the development section
diff --git a/docs/development/index.rst b/docs/development/index.rst
index c027229..50b6090 100644
--- a/docs/development/index.rst
+++ b/docs/development/index.rst
@@ -13,6 +13,7 @@
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 5978a1d..5dca3f7 100644
--- a/docs/development/submitting-patches.rst
+++ b/docs/development/submitting-patches.rst
@@ -144,7 +144,8 @@
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 0000000..03e31f3
--- /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