Merge pull request #596 from reaperhulk/docs-test-vectors

Add test vector information to the development section

3 files changed, 71 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..2a071d7c
--- /dev/null
+++ b/docs/development/test-vectors.rst
@@ -0,0 +1,68 @@
+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`.
+
+
+.. _`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