docs/development/test-vectors.rst

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 PKCS #1 from the RSA FTP site (ftp://ftp.rsasecurity.com/pub/pkcs/pkcs-1/
  and ftp://ftp.rsa.com/pub/rsalabs/tmp/).
* DSA test vectors from `FIPS 186-2`_ and `FIPS 186-3`_.
* OpenSSL PEM RSA serialization vectors from the `OpenSSL example key`_ and
  `GnuTLS key parsing tests`_.
* OpenSSL PEM DSA serialization vectors from the `GnuTLS example keys`_.
* PKCS #8 PEM serialization vectors from

  * GnuTLS: `encpkcs8.pem`_, `enc2pkcs8.pem`_, `unencpkcs8.pem`_,
    `pkcs12_s2k_pem.c`_.
  * `Botan's ECC private keys`_.

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`.
* scrypt from the `draft RFC`_.

Recipes
~~~~~~~

* Fernet from its `specification repository`_.

Symmetric Ciphers
~~~~~~~~~~~~~~~~~

* AES (CBC, CFB, ECB, GCM, OFB) from `NIST CAVP`_.
* AES CTR from :rfc:`3686`.
* 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`.
* CAST5 (CBC, CFB, OFB) generated by this project.
  See: :doc:`/development/custom-vectors/cast5`

Two Factor Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~

* HOTP from :rfc:`4226`
* TOTP from :rfc:`6238` (Note that an `errata`_ for the test vectors in RFC
  6238 exists)


Creating Test Vectors
---------------------

When official vectors are unavailable ``cryptography`` may choose to build
its own using existing vectors as source material. Current custom vectors:

.. toctree::
    :maxdepth: 1

    custom-vectors/cast5

If official test vectors appear in the future the custom generated vectors
should be discarded.

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

.. _`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
.. _`draft RFC`: https://tools.ietf.org/html/draft-josefsson-scrypt-kdf-01
.. _`Specification repository`: https://github.com/fernet/spec
.. _`errata`: http://www.rfc-editor.org/errata_search.php?rfc=6238
.. _`OpenSSL example key`: http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=test/testrsa.pem;h=aad21067a8f7cb93a52a511eb9162fd83be39135;hb=66e8211c0b1347970096e04b18aa52567c325200
.. _`GnuTLS key parsing tests`: https://gitorious.org/gnutls/gnutls/commit/f16ef39ef0303b02d7fa590a37820440c466ce8d
.. _`encpkcs8.pem`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs8-decode/encpkcs8.pem
.. _`enc2pkcs8.pem`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs8-decode/enc2pkcs8.pem
.. _`unencpkcs8.pem`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs8-decode/unencpkcs8.pem
.. _`pkcs12_s2k_pem.c`: https://gitorious.org/gnutls/gnutls/source/f8d943b38bf74eaaa11d396112daf43cb8aa82ae:tests/pkcs12_s2k_pem.c
.. _`Botan's ECC private keys`: https://github.com/randombit/botan/tree/4917f26a2b154e841cd27c1bcecdd41d2bdeb6ce/src/tests/data/ecc
.. _`FIPS 186-2`: http://csrc.nist.gov/groups/STM/cavp/documents/dss/186-2dsatestvectors.zip
.. _`FIPS 186-3`: http://csrc.nist.gov/groups/STM/cavp/documents/dss/186-3dsatestvectors.zip
.. _`GnuTLS example keys`: https://gitorious.org/gnutls/gnutls/commit/ad2061deafdd7db78fd405f9d143b0a7c579da7b