diff options
Diffstat (limited to 'docs/development')
| -rw-r--r-- | docs/development/custom-vectors/cast5.rst | 2 | ||||
| -rw-r--r-- | docs/development/custom-vectors/cast5/generate_cast5.py | 17 | ||||
| -rw-r--r-- | docs/development/custom-vectors/idea.rst | 30 | ||||
| -rw-r--r-- | docs/development/custom-vectors/idea/generate_idea.py | 60 | ||||
| -rw-r--r-- | docs/development/custom-vectors/idea/verify_idea.py | 39 | ||||
| -rw-r--r-- | docs/development/getting-started.rst | 8 | ||||
| -rw-r--r-- | docs/development/reviewing-patches.rst | 18 | ||||
| -rw-r--r-- | docs/development/submitting-patches.rst | 4 | ||||
| -rw-r--r-- | docs/development/test-vectors.rst | 46 |
9 files changed, 194 insertions, 30 deletions
diff --git a/docs/development/custom-vectors/cast5.rst b/docs/development/custom-vectors/cast5.rst index f5400270..98c5ba75 100644 --- a/docs/development/custom-vectors/cast5.rst +++ b/docs/development/custom-vectors/cast5.rst @@ -1,4 +1,4 @@ -CAST5 Vector Creation +CAST5 vector creation ===================== This page documents the code that was used to generate the CAST5 CBC, CFB, OFB, diff --git a/docs/development/custom-vectors/cast5/generate_cast5.py b/docs/development/custom-vectors/cast5/generate_cast5.py index 32ef3b43..6a4acdad 100644 --- a/docs/development/custom-vectors/cast5/generate_cast5.py +++ b/docs/development/custom-vectors/cast5/generate_cast5.py @@ -1,7 +1,22 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import absolute_import, division, print_function + import binascii from cryptography.hazmat.backends import default_backend -from cryptography.hazmat.primitives.ciphers import base, algorithms, modes +from cryptography.hazmat.primitives.ciphers import algorithms, base, modes def encrypt(mode, key, iv, plaintext): diff --git a/docs/development/custom-vectors/idea.rst b/docs/development/custom-vectors/idea.rst new file mode 100644 index 00000000..e0db58d9 --- /dev/null +++ b/docs/development/custom-vectors/idea.rst @@ -0,0 +1,30 @@ +IDEA vector creation +===================== + +This page documents the code that was used to generate the IDEA CBC, CFB, and +OFB test vectors as well as the code used to verify them against another +implementation. For IDEA the vectors were generated using OpenSSL and verified +with Go. + +Creation +-------- + +``cryptography`` was modified to support IDEA in CBC, CFB, and OFB modes. Then +the following python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/idea/generate_idea.py + +Download link: :download:`generate_idea.py </development/custom-vectors/idea/generate_idea.py>` + + +Verification +------------ + +The following python code was used to verify the vectors using the `Botan`_ +project's Python bindings. + +.. literalinclude:: /development/custom-vectors/idea/verify_idea.py + +Download link: :download:`verify_idea.py </development/custom-vectors/idea/verify_idea.py>` + +.. _`Botan`: http://botan.randombit.net diff --git a/docs/development/custom-vectors/idea/generate_idea.py b/docs/development/custom-vectors/idea/generate_idea.py new file mode 100644 index 00000000..c9f94024 --- /dev/null +++ b/docs/development/custom-vectors/idea/generate_idea.py @@ -0,0 +1,60 @@ +import binascii + +from cryptography.hazmat.backends.openssl.backend import backend +from cryptography.hazmat.primitives.ciphers import algorithms, base, modes + + +def encrypt(mode, key, iv, plaintext): + cipher = base.Cipher( + algorithms.IDEA(binascii.unhexlify(key)), + mode(binascii.unhexlify(iv)), + backend + ) + encryptor = cipher.encryptor() + ct = encryptor.update(binascii.unhexlify(plaintext)) + ct += encryptor.finalize() + return binascii.hexlify(ct) + + +def build_vectors(mode, filename): + with open(filename, "r") as f: + vector_file = f.read().splitlines() + + count = 0 + output = [] + key = None + iv = None + plaintext = None + for line in vector_file: + line = line.strip() + if line.startswith("KEY"): + if count != 0: + output.append("CIPHERTEXT = {0}".format( + encrypt(mode, key, iv, plaintext)) + ) + output.append("\nCOUNT = {0}".format(count)) + count += 1 + name, key = line.split(" = ") + output.append("KEY = {0}".format(key)) + elif line.startswith("IV"): + name, iv = line.split(" = ") + iv = iv[0:16] + output.append("IV = {0}".format(iv)) + elif line.startswith("PLAINTEXT"): + name, plaintext = line.split(" = ") + output.append("PLAINTEXT = {0}".format(plaintext)) + + output.append("CIPHERTEXT = {0}".format(encrypt(mode, key, iv, plaintext))) + return "\n".join(output) + + +def write_file(data, filename): + with open(filename, "w") as f: + f.write(data) + +CBC_PATH = "tests/hazmat/primitives/vectors/ciphers/AES/CBC/CBCMMT128.rsp" +write_file(build_vectors(modes.CBC, CBC_PATH), "idea-cbc.txt") +OFB_PATH = "tests/hazmat/primitives/vectors/ciphers/AES/OFB/OFBMMT128.rsp" +write_file(build_vectors(modes.OFB, OFB_PATH), "idea-ofb.txt") +CFB_PATH = "tests/hazmat/primitives/vectors/ciphers/AES/CFB/CFB128MMT128.rsp" +write_file(build_vectors(modes.CFB, CFB_PATH), "idea-cfb.txt") diff --git a/docs/development/custom-vectors/idea/verify_idea.py b/docs/development/custom-vectors/idea/verify_idea.py new file mode 100644 index 00000000..89713c80 --- /dev/null +++ b/docs/development/custom-vectors/idea/verify_idea.py @@ -0,0 +1,39 @@ +import binascii + +import botan + +from tests.utils import load_nist_vectors + +BLOCK_SIZE = 64 + + +def encrypt(mode, key, iv, plaintext): + encryptor = botan.Cipher("IDEA/{0}/NoPadding".format(mode), "encrypt", + binascii.unhexlify(key)) + + cipher_text = encryptor.cipher(binascii.unhexlify(plaintext), + binascii.unhexlify(iv)) + return binascii.hexlify(cipher_text) + + +def verify_vectors(mode, filename): + with open(filename, "r") as f: + vector_file = f.read().splitlines() + + vectors = load_nist_vectors(vector_file) + for vector in vectors: + ct = encrypt( + mode, + vector["key"], + vector["iv"], + vector["plaintext"] + ) + assert ct == vector["ciphertext"] + + +cbc_path = "tests/hazmat/primitives/vectors/ciphers/IDEA/idea-cbc.txt" +verify_vectors("CBC", cbc_path) +ofb_path = "tests/hazmat/primitives/vectors/ciphers/IDEA/idea-ofb.txt" +verify_vectors("OFB", ofb_path) +cfb_path = "tests/hazmat/primitives/vectors/ciphers/IDEA/idea-cfb.txt" +verify_vectors("CFB", cfb_path) diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst index 412f0545..3d9012eb 100644 --- a/docs/development/getting-started.rst +++ b/docs/development/getting-started.rst @@ -1,4 +1,4 @@ -Getting Started +Getting started =============== Working on ``cryptography`` requires the installation of a small number of @@ -14,7 +14,7 @@ dependencies, install ``cryptography`` in ``editable`` mode. For example: You are now ready to run the tests and build the documentation. -Running Tests +Running tests ~~~~~~~~~~~~~ ``cryptography`` unit tests are found in the ``tests/`` directory and are @@ -49,7 +49,7 @@ You may not have all the required Python versions installed, in which case you will see one or more ``InterpreterNotFound`` errors. -Explicit Backend Selection +Explicit backend selection ~~~~~~~~~~~~~~~~~~~~~~~~~~ While testing you may want to run tests against a subset of the backends that @@ -63,7 +63,7 @@ delimited list of backend names. $ tox -- --backend=openssl $ py.test --backend=openssl,commoncrypto -Building Documentation +Building documentation ~~~~~~~~~~~~~~~~~~~~~~ ``cryptography`` documentation is stored in the ``docs/`` directory. It is diff --git a/docs/development/reviewing-patches.rst b/docs/development/reviewing-patches.rst index 302c998e..bd3ee96a 100644 --- a/docs/development/reviewing-patches.rst +++ b/docs/development/reviewing-patches.rst @@ -1,8 +1,11 @@ -Reviewing/Merging Patches -========================= +Reviewing and merging patches +============================= -Everyone is encouraged to review open pull requests. When reviewing a patch try -to keep each of these concepts in mind: +Everyone is encouraged to review open pull requests. We only ask that you try +and think carefully, ask questions and are `excellent to one another`_. Code +review is our opportunity to share knowledge, design ideas and make friends. + +When reviewing a patch try to keep each of these concepts in mind: Architecture ------------ @@ -24,15 +27,15 @@ Implementation * Has it been documented? * Will this change introduce new bugs? -Grammar/Style -------------- +Grammar and style +----------------- These are small things that are not caught by the automated style checkers. * Does a variable need a better name? * Should this be a keyword argument? -Merge Requirements +Merge requirements ------------------ Because cryptography is so complex, and the implications of getting it wrong so @@ -54,3 +57,4 @@ devastating, ``cryptography`` has a strict merge policy for committers: The purpose of these policies is to minimize the chances we merge a change that jeopardizes our users' security. +.. _`excellent to one another`: https://speakerdeck.com/ohrite/better-code-review diff --git a/docs/development/submitting-patches.rst b/docs/development/submitting-patches.rst index 1797b9c1..f1bf954b 100644 --- a/docs/development/submitting-patches.rst +++ b/docs/development/submitting-patches.rst @@ -1,4 +1,4 @@ -Submitting Patches +Submitting patches ================== * Always make a new branch for your work. @@ -29,7 +29,7 @@ Additionally, every Python code file must contain from __future__ import absolute_import, division, print_function -API Considerations +API considerations ~~~~~~~~~~~~~~~~~~ Most projects' APIs are designed with a philosophy of "make easy things easy, diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index 8b27e9d9..484d06bd 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -1,22 +1,31 @@ -Test Vectors +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. +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. + +Vectors are kept in the `cryptography_vectors` package rather than within our +main test suite. Sources ------- -Asymmetric Ciphers +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/). -* OpenSSL PEM serialization vectors from the `OpenSSL test suite`_ and `GnuTLS - test suite`_. +* RSA FIPS 186-2 and PKCS1 v1.5 vulnerability test vectors from `NIST CAVP`_. +* FIPS 186-2 and FIPS 186-3 DSA test vectors from `NIST CAVP`_. +* FIPS 186-2 and FIPS 186-3 ECDSA test vectors from `NIST CAVP`_. +* Ed25519 test vectors from the `Ed25519 website_`. +* 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`_, @@ -40,7 +49,7 @@ HMAC * HMAC-RIPEMD160 from :rfc:`2286`. * HMAC-SHA2 (224, 256, 384, 512) from :rfc:`4231`. -Key Derivation Functions +Key derivation functions ~~~~~~~~~~~~~~~~~~~~~~~~ * HKDF (SHA1, SHA256) from :rfc:`5869`. @@ -52,7 +61,7 @@ Recipes * Fernet from its `specification repository`_. -Symmetric Ciphers +Symmetric ciphers ~~~~~~~~~~~~~~~~~ * AES (CBC, CFB, ECB, GCM, OFB) from `NIST CAVP`_. @@ -65,16 +74,18 @@ Symmetric Ciphers * CAST5 (ECB) from :rfc:`2144`. * CAST5 (CBC, CFB, OFB) generated by this project. See: :doc:`/development/custom-vectors/cast5` +* IDEA (ECB) from the `NESSIE IDEA vectors`_ created by `NESSIE`_. +* IDEA (CBC, CFB, OFB) generated by this project. + See: :doc:`/development/custom-vectors/idea` -Two Factor Authentication +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 +Creating test vectors --------------------- When official vectors are unavailable ``cryptography`` may choose to build @@ -84,6 +95,7 @@ its own using existing vectors as source material. Current custom vectors: :maxdepth: 1 custom-vectors/cast5 + custom-vectors/idea If official test vectors appear in the future the custom generated vectors should be discarded. @@ -110,10 +122,14 @@ header format (substituting the correct information): .. _`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 test suite`: http://git.openssl.org/gitweb/?p=openssl.git;a=blob;f=test/testrsa.pem;h=aad21067a8f7cb93a52a511eb9162fd83be39135;hb=66e8211c0b1347970096e04b18aa52567c325200 -.. _`GnuTLS test suite`: https://gitorious.org/gnutls/gnutls/commit/f16ef39ef0303b02d7fa590a37820440c466ce8d +.. _`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 +.. _`GnuTLS example keys`: https://gitorious.org/gnutls/gnutls/commit/ad2061deafdd7db78fd405f9d143b0a7c579da7b +.. _`NESSIE IDEA vectors`: https://www.cosic.esat.kuleuven.be/nessie/testvectors/bc/idea/Idea-128-64.verified.test-vectors +.. _`NESSIE`: https://en.wikipedia.org/wiki/NESSIE +.. _`Ed25519 website`: http://ed25519.cr.yp.to/software.html |