diff options
Diffstat (limited to 'docs')
36 files changed, 825 insertions, 247 deletions
diff --git a/docs/api-stability.rst b/docs/api-stability.rst index 6a2e60e2..53669b0f 100644 --- a/docs/api-stability.rst +++ b/docs/api-stability.rst @@ -1,4 +1,4 @@ -API Stability +API stability ============= From its first release, ``cryptography`` will have a strong API stability diff --git a/docs/conf.py b/docs/conf.py index 3486fb38..a924fa43 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,4 +1,18 @@ # -*- coding: utf-8 -*- + +# 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. + # # Cryptography documentation build configuration file, created by # sphinx-quickstart on Tue Aug 6 19:19:14 2013. @@ -11,6 +25,8 @@ # All configuration values have a default; values that are commented out # serve to show the default. +from __future__ import absolute_import, division, print_function + import os import sys @@ -33,7 +49,7 @@ sys.path.insert(0, os.path.abspath('.')) # -- General configuration ---------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -#needs_sphinx = '1.0' +# needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. @@ -55,7 +71,7 @@ templates_path = ['_templates'] source_suffix = '.rst' # The encoding of source files. -#source_encoding = 'utf-8-sig' +# source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' @@ -78,37 +94,37 @@ version = release = about["__version__"] # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -#language = None +# language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: -#today = '' +# today = '' # Else, today_fmt is used as the format for a strftime call. -#today_fmt = '%B %d, %Y' +# today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents -#default_role = None +# default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +# add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). -#add_module_names = True +# add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. -#show_authors = False +# show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. -#modindex_common_prefix = [] +# modindex_common_prefix = [] # -- Options for HTML output -------------------------------------------------- @@ -125,23 +141,23 @@ else: # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +# html_theme_options = {} # The name for this set of Sphinx documents. If None, it defaults to # "<project> v<release> documentation". -#html_title = None +# html_title = None # A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None +# html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. -#html_logo = None +# html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. -#html_favicon = None +# html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -150,44 +166,44 @@ html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' +# html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -#html_use_smartypants = True +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +# html_additional_pages = {} # If false, no module index is generated. -#html_domain_indices = True +# html_domain_indices = True # If false, no index is generated. -#html_use_index = True +# html_use_index = True # If true, the index is split into individual pages for each letter. -#html_split_index = False +# html_split_index = False # If true, links to the reST sources are added to the pages. -#html_show_sourcelink = True +# html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -#html_show_sphinx = True +# html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True +# html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a <link> tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. -#html_use_opensearch = '' +# html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None +# html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'Cryptographydoc' @@ -196,14 +212,6 @@ htmlhelp_basename = 'Cryptographydoc' # -- Options for LaTeX output ------------------------------------------------- latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - #'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - #'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples @@ -215,23 +223,23 @@ latex_documents = [ # The name of an image file (relative to this directory) to place at the top of # the title page. -#latex_logo = None +# latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +# latex_use_parts = False # If true, show page references after internal links. -#latex_show_pagerefs = False +# latex_show_pagerefs = False # If true, show URL addresses after external links. -#latex_show_urls = False +# latex_show_urls = False # Documents to append as an appendix to all manuals. -#latex_appendices = [] +# latex_appendices = [] # If false, no module index is generated. -#latex_domain_indices = True +# latex_domain_indices = True # -- Options for manual page output ------------------------------------------- @@ -244,7 +252,7 @@ man_pages = [ ] # If true, show URL addresses after external links. -#man_show_urls = False +# man_show_urls = False # -- Options for Texinfo output ----------------------------------------------- @@ -260,13 +268,13 @@ texinfo_documents = [ ] # Documents to append as an appendix to all manuals. -#texinfo_appendices = [] +# texinfo_appendices = [] # If false, no module index is generated. -#texinfo_domain_indices = True +# texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. -#texinfo_show_urls = 'footnote' +# texinfo_show_urls = 'footnote' # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/docs/cryptography-docs.py b/docs/cryptography-docs.py index 0252d693..e4e9296c 100644 --- a/docs/cryptography-docs.py +++ b/docs/cryptography-docs.py @@ -1,3 +1,18 @@ +# 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 + from docutils import nodes from sphinx.util.compat import Directive, make_admonition 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 diff --git a/docs/doing-a-release.rst b/docs/doing-a-release.rst index 15583afb..fc88a91c 100644 --- a/docs/doing-a-release.rst +++ b/docs/doing-a-release.rst @@ -1,4 +1,4 @@ -Doing a Release +Doing a release =============== Doing a release of ``cryptography`` is a two part process. @@ -10,6 +10,7 @@ The first step in doing a release is bumping the version number in the software. * Update the version number in ``cryptography/__about__.py``. +* Update the version number in ``vectors/cryptography_vectors/__about__.py``. * Set the release date in the :doc:`/changelog`. * Do a commit indicating this. * Send a pull request with this. @@ -33,5 +34,8 @@ correctly: >>> import cryptography >>> cryptography.__version__ '...' + >>> import cryptography_vectors + >>> cryptography_vectors.__version__ + '...' Verify that this is the version you just released. diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 7f9ae347..28da8ecc 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -3,6 +3,13 @@ Exceptions .. currentmodule:: cryptography.exceptions + +.. class:: UnsupportedAlgorithm + + Raised when the requested algorithm, or combination of algorithms is not + supported. + + .. class:: AlreadyFinalized This is raised when a context is used after being finalized. @@ -26,12 +33,6 @@ Exceptions has already been called. -.. class:: UnsupportedAlgorithm - - This is raised when a backend doesn't support the requested algorithm (or - combination of algorithms). - - .. class:: InvalidKey This is raised when the verify method of a key derivation function's @@ -42,8 +43,3 @@ Exceptions This is raised when the verify method of a one time password function's computed token does not match the expected token. - - -.. class:: UnsupportedPadding - - This is raised when the chosen padding is not supported by the backend. diff --git a/docs/faq.rst b/docs/faq.rst index cbbb74ad..0b7bdce4 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -1,4 +1,4 @@ -Frequently Asked Questions +Frequently asked questions ========================== How does ``cryptography`` compare to NaCl (Networking and Cryptography Library)? diff --git a/docs/fernet.rst b/docs/fernet.rst index 40f1a3c8..f55a2d60 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -1,4 +1,4 @@ -Fernet (Symmetric encryption) +Fernet (symmetric encryption) ============================= .. currentmodule:: cryptography.fernet diff --git a/docs/hazmat/backends/commoncrypto.rst b/docs/hazmat/backends/commoncrypto.rst index 16a61337..77d6612c 100644 --- a/docs/hazmat/backends/commoncrypto.rst +++ b/docs/hazmat/backends/commoncrypto.rst @@ -1,9 +1,10 @@ .. hazmat:: -CommonCrypto Backend +CommonCrypto backend ==================== -The `CommonCrypto`_ C library provided by Apple on OS X and iOS. +The `CommonCrypto`_ C library provided by Apple on OS X and iOS. The CommonCrypto +backend is only supported on OS X versions 10.8 and above. .. currentmodule:: cryptography.hazmat.backends.commoncrypto.backend diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst index 983a44e9..aec7a1e0 100644 --- a/docs/hazmat/backends/index.rst +++ b/docs/hazmat/backends/index.rst @@ -3,7 +3,7 @@ Backends ======== -Getting a Backend +Getting a backend ----------------- .. currentmodule:: cryptography.hazmat.backends @@ -24,7 +24,7 @@ the libraries we use in those backends changes. :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and :class:`~interfaces.HMACBackend`. -Individual Backends +Individual backends ------------------- .. toctree:: diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index af19fbc6..c38f818f 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -1,6 +1,6 @@ .. hazmat:: -Backend Interfaces +Backend interfaces ================== .. currentmodule:: cryptography.hazmat.backends.interfaces @@ -249,6 +249,20 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + .. method:: mgf1_hash_supported(algorithm) + + Check if the specified ``algorithm`` is supported for use with + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + inside :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` + padding. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: ``True`` if the specified ``algorithm`` is supported by this + backend, otherwise ``False``. + .. class:: OpenSSLSerializationBackend @@ -258,7 +272,7 @@ A specific ``backend`` may provide one or more of these interfaces. style key serialization. .. method:: load_openssl_pem_private_key(data, password) - + :param bytes data: PEM data to deserialize. :param bytes password: The password to use if this data is encrypted. diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index d6351c9c..fdfadf0b 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -1,9 +1,11 @@ .. hazmat:: -OpenSSL Backend +OpenSSL backend =============== -The `OpenSSL`_ C library. +The `OpenSSL`_ C library. Cryptography supports version ``0.9.8e`` (present in +Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are +**not tested or supported**. .. data:: cryptography.hazmat.backends.openssl.backend @@ -32,7 +34,7 @@ The `OpenSSL`_ C library. This will activate the default OpenSSL CSPRNG. -OS Random Engine +OS random engine ---------------- OpenSSL uses a user-space CSPRNG that is seeded from system random ( @@ -56,7 +58,7 @@ When importing only the binding it is added to the engine list but **not activated**. -OS Random Sources +OS random sources ----------------- On OS X and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and diff --git a/docs/hazmat/bindings/commoncrypto.rst b/docs/hazmat/bindings/commoncrypto.rst index 50dbe69a..9484cfa1 100644 --- a/docs/hazmat/bindings/commoncrypto.rst +++ b/docs/hazmat/bindings/commoncrypto.rst @@ -1,14 +1,14 @@ .. hazmat:: -CommonCrypto Binding +CommonCrypto binding ==================== .. currentmodule:: cryptography.hazmat.bindings.commoncrypto.binding .. versionadded:: 0.2 -These are `CFFI`_ bindings to the `CommonCrypto`_ C library. It is available on -Mac OS X. +These are `CFFI`_ bindings to the `CommonCrypto`_ C library. It is only +available on Mac OS X versions 10.8 and above. .. class:: cryptography.hazmat.bindings.commoncrypto.binding.Binding() diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst index caab8d6a..ccd36e3e 100644 --- a/docs/hazmat/bindings/index.rst +++ b/docs/hazmat/bindings/index.rst @@ -13,7 +13,7 @@ Using these functions directly is likely to require you to be careful in managing memory allocation, locking and other resources. -Individual Bindings +Individual bindings ------------------- .. toctree:: diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 557f8c4d..a6d1c484 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -1,11 +1,13 @@ .. hazmat:: -OpenSSL Binding +OpenSSL binding =============== .. currentmodule:: cryptography.hazmat.bindings.openssl.binding -These are `CFFI`_ bindings to the `OpenSSL`_ C library. +These are `CFFI`_ bindings to the `OpenSSL`_ C library. Cryptography supports +version ``0.9.8e`` (present in Red Hat Enterprise Linux 5) and greater. Earlier +versions may work but are **not tested or supported**. .. class:: cryptography.hazmat.bindings.openssl.binding.Binding() diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst new file mode 100644 index 00000000..69e8d58e --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -0,0 +1,68 @@ +.. hazmat:: + +DSA +=== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.dsa + +`DSA`_ is a `public-key`_ algorithm for signing messages. + +.. class:: DSAParameters(modulus, subgroup_order, generator) + + .. versionadded:: 0.4 + + DSA Parameters are required for generating a DSA private key. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + +.. class:: DSAPrivateKey(modulus, subgroup_order, generator, x, y) + + .. versionadded:: 0.4 + + A DSA private key is required for signing messages. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + +.. class:: DSAPublicKey(modulus, subgroup_order, generator, y) + + .. versionadded:: 0.4 + + A DSA public key is required for verifying messages. + + Normally you do not need to directly construct public keys because you'll + be loading them from a file, generating them automatically or receiving + them from a 3rd party. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``,``generator``, or ``y`` + do not match the bounds specified in `FIPS 186-4`_. + + +.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm +.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography +.. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf + diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 10319fad..ca048d11 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -1,10 +1,11 @@ .. hazmat:: -Asymmetric Algorithms +Asymmetric algorithms ===================== .. toctree:: :maxdepth: 1 + dsa rsa padding diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 7aec3bd3..2a5de3c7 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,6 +10,17 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. +.. class:: PSS(mgf) + + .. versionadded:: 0.3 + + PSS (Probabilistic Signature Scheme) is a signature scheme defined in + :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_. + This is the `recommended padding algorithm`_ for RSA signatures. + + :param mgf: A mask generation function object. At this time the only + supported MGF is :class:`MGF1`. + .. class:: PKCS1v15() .. versionadded:: 0.3 @@ -17,4 +28,29 @@ Padding PKCS1 v1.5 (also known as simply PKCS1) is a simple padding scheme developed for use with RSA keys. It is defined in :rfc:`3447`. +Mask generation functions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: MGF1(algorithm, salt_length) + + .. versionadded:: 0.3 + + MGF1 (Mask Generation Function 1) is used as the mask generation function + in :class:`PSS` padding. It takes a hash algorithm and a salt length. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param int salt_length: The length of the salt. It is recommended that this + be set to ``MGF1.MAX_LENGTH``. + + .. attribute:: MAX_LENGTH + + Pass this attribute to ``salt_length`` to get the maximum salt length + available. + + .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ +.. _`security proof`: http://eprint.iacr.org/2001/062.pdf +.. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 7943981e..182e35d2 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -50,6 +50,11 @@ RSA provider. :return: A new instance of ``RSAPrivateKey``. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + + .. method:: signer(padding, algorithm, backend) .. versionadded:: 0.3 @@ -67,7 +72,12 @@ RSA ... backend=default_backend() ... ) >>> signer = private_key.signer( - ... padding.PKCS1v15(), + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), ... hashes.SHA256(), ... default_backend() ... ) @@ -90,6 +100,24 @@ RSA :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` or if + the backend does not support the chosen hash or padding algorithm. + If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` + with the + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + mask generation function it may also refer to the ``MGF1`` hash + algorithm. + + :raises TypeError: This is raised when the padding is not an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :raises ValueError: This is raised when the chosen hash algorithm is + too large for the key size. + .. class:: RSAPublicKey(public_exponent, modulus) @@ -128,12 +156,31 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer( + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> data= b"this is some data I'd like to sign" >>> signer.update(data) >>> signature = signer.finalize() >>> public_key = private_key.public_key() - >>> verifier = public_key.verifier(signature, padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> verifier = public_key.verifier( + ... signature, + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> verifier.update(data) >>> verifier.verify() @@ -154,6 +201,25 @@ RSA :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` or if + the backend does not support the chosen hash or padding algorithm. + If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` + with the + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + mask generation function it may also refer to the ``MGF1`` hash + algorithm. + + :raises TypeError: This is raised when the padding is not an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :raises ValueError: This is raised when the chosen hash algorithm is + too large for the key size. + + .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography .. _`use 65537`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 6c56acad..773d97f6 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -1,6 +1,6 @@ .. hazmat:: -Message Digests +Message digests =============== .. currentmodule:: cryptography.hazmat.primitives.hashes @@ -29,7 +29,8 @@ Message Digests 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' If the backend doesn't support the requested ``algorithm`` an - :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be + raised. Keep in mind that attacks against cryptographic hashes only get stronger with time, and that often algorithms that were once thought to be strong, @@ -45,28 +46,32 @@ Message Digests :class:`~cryptography.hazmat.backends.interfaces.HashBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HashBackend` + .. method:: update(data) - :param bytes data: The bytes you wish to hash. - :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :param bytes data: The bytes to be hashed. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`. .. method:: copy() - Copy this :class:`Hash` instance, usually so that we may call - :meth:`finalize` and get an intermediate digest value while we continue - to call :meth:`update` on the original. + Copy this :class:`Hash` instance, usually so that you may call + :meth:`finalize` to get an intermediate digest value while we continue + to call :meth:`update` on the original instance. :return: A new instance of :class:`Hash` that can be updated - and finalized independently of the original instance. - :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`. .. method:: finalize() Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used and - :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. + After ``finalize`` has been called this object can no longer be used + and :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise an + :class:`~cryptography.exceptions.AlreadyFinalized` exception. :return bytes: The message digest as bytes. @@ -83,31 +88,31 @@ SHA-1 .. class:: SHA1() - SHA-1 is a cryptographic hash function standardized by NIST. It has a + SHA-1 is a cryptographic hash function standardized by NIST. It produces an 160-bit message digest. -SHA-2 Family +SHA-2 family ~~~~~~~~~~~~ .. class:: SHA224() - SHA-224 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 224-bit message digest. + SHA-224 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 224-bit message digest. .. class:: SHA256() - SHA-256 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 256-bit message digest. + SHA-256 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 256-bit message digest. .. class:: SHA384() - SHA-384 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 384-bit message digest. + SHA-384 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 384-bit message digest. .. class:: SHA512() - SHA-512 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 512-bit message digest. + SHA-512 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 512-bit message digest. RIPEMD160 ~~~~~~~~~ @@ -115,7 +120,7 @@ RIPEMD160 .. class:: RIPEMD160() RIPEMD160 is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It has a 160-bit message digest. + 10118-3:2004. It produces a 160-bit message digest. Whirlpool ~~~~~~~~~ @@ -123,7 +128,7 @@ Whirlpool .. class:: Whirlpool() Whirlpool is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It has a 512-bit message digest. + 10118-3:2004. It produces a 512-bit message digest. MD5 ~~~ @@ -136,8 +141,8 @@ MD5 .. class:: MD5() - MD5 is a deprecated cryptographic hash function. It has a 128-bit message - digest and has practical known collision attacks. + MD5 is a deprecated cryptographic hash function. It produces a 128-bit + message digest and has practical known collision attacks. .. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 0118be78..11b10735 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -1,6 +1,6 @@ .. hazmat:: -Hash-based Message Authentication Codes +Hash-based message authentication codes ======================================= .. currentmodule:: cryptography.hazmat.primitives.hmac @@ -12,13 +12,13 @@ Hash-based Message Authentication Codes Hash-based message authentication codes (or HMACs) are a tool for calculating message authentication codes using a cryptographic hash function coupled with a -secret key. You can use an HMAC to verify integrity as well as authenticate a -message. +secret key. You can use an HMAC to verify both the integrity and authenticity +of a message. .. class:: HMAC(key, algorithm, backend) - HMAC objects take a ``key`` and a provider of - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`. + HMAC objects take a ``key`` and a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. The ``key`` should be randomly generated bytes and is recommended to be equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. @@ -35,7 +35,8 @@ message. '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' If the backend doesn't support the requested ``algorithm`` an - :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be + raised. To check that a given signature is correct use the :meth:`verify` method. You will receive an exception if the signature is wrong: @@ -47,15 +48,19 @@ message. ... cryptography.exceptions.InvalidSignature: Signature did not match digest. - :param key: Secret key as ``bytes``. - :param algorithm: A + :param bytes key: Secret key as ``bytes``. + :param algorithm: An :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider such as those described in :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`. - :param backend: A + :param backend: An :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + .. method:: update(msg) :param bytes msg: The bytes to hash and authenticate. @@ -64,8 +69,8 @@ message. .. method:: copy() Copy this :class:`HMAC` instance, usually so that we may call - :meth:`finalize` and get an intermediate digest value while we continue - to call :meth:`update` on the original. + :meth:`finalize` to get an intermediate digest value while we continue + to call :meth:`update` on the original instance. :return: A new instance of :class:`HMAC` that can be updated and finalized independently of the original instance. @@ -86,9 +91,10 @@ message. Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used and - :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. + After ``finalize`` has been called this object can no longer be used + and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize` + will raise an :class:`~cryptography.exceptions.AlreadyFinalized` + exception. :return bytes: The message digest as bytes. :raises cryptography.exceptions.AlreadyFinalized: diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 15ad1d1b..9a1f3307 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -12,7 +12,7 @@ to document argument and return types. .. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html -Symmetric Ciphers +Symmetric ciphers ~~~~~~~~~~~~~~~~~ .. currentmodule:: cryptography.hazmat.primitives.interfaces @@ -47,7 +47,7 @@ Symmetric Ciphers The number of bits in a block. -Cipher Modes +Cipher modes ------------ Interfaces used by the symmetric cipher modes described in @@ -103,7 +103,7 @@ Interfaces used by the symmetric cipher modes described in Exact requirements of the nonce are described by the documentation of individual modes. -Asymmetric Interfaces +Asymmetric interfaces ~~~~~~~~~~~~~~~~~~~~~ .. class:: RSAPrivateKey @@ -231,6 +231,119 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +.. class:: DSAParameters + + .. versionadded:: 0.3 + + `DSA`_ parameters. + + .. attribute:: modulus + + :type: int + + The prime modulus that is used in generating the DSA key pair and used + in the DSA signing and verification processes. + + .. attribute:: subgroup_order + + :type: int + + The subgroup order that is used in generating the DSA key pair + by the generator and used in the DSA signing and verification + processes. + + .. attribute:: generator + + :type: int + + The generator that is used in generating the DSA key pair and used + in the DSA signing and verification processes. + + .. attribute:: p + + :type: int + + The prime modulus that is used in generating the DSA key pair and used + in the DSA signing and verification processes. Alias for :attr:`modulus`. + + .. attribute:: q + + :type: int + + The subgroup order that is used in generating the DSA key pair + by the generator and used in the DSA signing and verification + processes. Alias for :attr:`subgroup_order`. + + .. attribute:: g + + :type: int + + The generator that is used in generating the DSA key pair and used + in the DSA signing and verification processes. Alias for :attr:`generator`. + + +.. class:: DSAPrivateKey + + .. versionadded:: 0.3 + + A `DSA`_ private key. + + .. method:: public_key() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` + + An DSA public key object corresponding to the values of the private key. + + .. method:: parameters() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + + The DSAParameters object associated with this private key. + + .. attribute:: key_size + + :type: int + + The bit length of the modulus. + + .. attribute:: x + + :type: int + + The private key. + + .. attribute:: y + + :type: int + + The public key. + + +.. class:: DSAPublicKey + + .. versionadded:: 0.3 + + A `DSA`_ public key. + + .. attribute:: key_size + + :type: int + + The bit length of the modulus. + + .. method:: parameters() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + + The DSAParameters object associated with this public key. + + .. attribute:: y + + :type: int + + The public key. + + .. class:: AsymmetricSignatureContext .. versionadded:: 0.2 @@ -264,7 +377,7 @@ Asymmetric Interfaces .. attribute:: name -Hash Algorithms +Hash algorithms ~~~~~~~~~~~~~~~ .. class:: HashAlgorithm @@ -289,7 +402,7 @@ Hash Algorithms The internal block size of the hash algorithm in bytes. -Key Derivation Functions +Key derivation functions ~~~~~~~~~~~~~~~~~~~~~~~~ .. class:: KeyDerivationFunction @@ -335,3 +448,4 @@ Key Derivation Functions .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem +.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 851dbb0b..269f949d 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -1,6 +1,6 @@ .. hazmat:: -Key Derivation Functions +Key derivation functions ======================== .. currentmodule:: cryptography.hazmat.primitives.kdf @@ -84,6 +84,10 @@ Different KDFs are suitable for different tasks such as: :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` + .. method:: derive(key_material) :param bytes key_material: The input key material. For PBKDF2 this @@ -183,6 +187,10 @@ Different KDFs are suitable for different tasks such as: :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + .. method:: derive(key_material) :param bytes key_material: The input key material. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 2306c5b7..28de611e 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -1,7 +1,7 @@ .. hazmat:: /fernet -Symmetric Encryption +Symmetric encryption ==================== .. currentmodule:: cryptography.hazmat.primitives.ciphers @@ -13,23 +13,25 @@ Symmetric Encryption iv = binascii.unhexlify(b"0" * 32) -Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the sender and receiver both use the same key. Note that symmetric -encryption is **not** sufficient for most applications, because it only -provides secrecy (an attacker can't see the message) but not authenticity (an -attacker can create bogus messages and force the application to decrypt them). +Symmetric encryption is a way to `encrypt`_ or hide the contents of material +where the sender and receiver both use the same secret key. Note that symmetric +encryption is **not** sufficient for most applications because it only +provides secrecy but not authenticity. That means an attacker can't see the +message but an attacker can create bogus messages and force the application to +decrypt them. + For this reason it is *strongly* recommended to combine encryption with a message authentication code, such as :doc:`HMAC </hazmat/primitives/hmac>`, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. class:: Cipher(algorithm, mode, backend) - Cipher objects combine an algorithm (such as - :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a - mode (such as + Cipher objects combine an algorithm such as + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` with a + mode like :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` or - :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`). A simple - example of encrypting (and then decrypting) content with AES is: + :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`. A simple + example of encrypting and then decrypting content with AES is: .. doctest:: @@ -54,6 +56,10 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + .. method:: encryptor() :return: An encrypting @@ -62,7 +68,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. If the backend doesn't support the requested combination of ``cipher`` and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` - will be raised. + exception will be raised. .. method:: decryptor() @@ -72,7 +78,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. If the backend doesn't support the requested combination of ``cipher`` and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` - will be raised. + exception will be raised. .. _symmetric-encryption-algorithms: @@ -87,17 +93,17 @@ Algorithms AES is both fast, and cryptographically strong. It is a good default choice for encryption. - :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``128``, + ``192``, or ``256`` bits long. .. class:: Camellia(key) - Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC. - It is considered to have comparable security and performance to AES, but + Camellia is a block cipher approved for use by `CRYPTREC`_ and ISO/IEC. + It is considered to have comparable security and performance to AES but is not as widely studied or deployed. - :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``128``, + ``192``, or ``256`` bits long. .. class:: TripleDES(key) @@ -107,12 +113,11 @@ Algorithms Nonetheless, Triples DES is not recommended for new applications because it is incredibly slow; old applications should consider moving away from it. - :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits - (note that DES functionally uses ``56``, ``112``, or ``168`` bits of - the key, there is a parity byte in each component of the key), in some - materials these are referred to as being up to three separate keys - (each ``56`` bits long), they can simply be concatenated to produce the - full key. This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``64``, + ``128``, or ``192`` bits long. DES only uses ``56``, ``112``, or ``168`` + bits of the key as there is a parity byte in each component of the key. + Some writing refers to there being up to three separate keys that are each + ``56`` bits long, they can simply be concatenated to produce the full key. .. class:: CAST5(key) @@ -122,10 +127,10 @@ Algorithms Canadian government by the `Communications Security Establishment`_. It is a variable key length cipher and supports keys from 40-128 bits in length. - :param bytes key: The secret key, 40-128 bits in length (in increments of - 8). This must be kept secret. + :param bytes key: The secret key, This must be kept secret. 40 to 128 bits + in length in increments of 8 bits. -Weak Ciphers +Weak ciphers ------------ .. warning:: @@ -138,10 +143,10 @@ Weak Ciphers Blowfish is a block cipher developed by Bruce Schneier. It is known to be susceptible to attacks when using weak keys. The author has recommended - that users of Blowfish move to newer algorithms, such as :class:`AES`. + that users of Blowfish move to newer algorithms such as :class:`AES`. - :param bytes key: The secret key, 32-448 bits in length (in increments of - 8). This must be kept secret. + :param bytes key: The secret key. This must be kept secret. 32 to 448 bits + in length in increments of 8 bits. .. class:: ARC4(key) @@ -149,8 +154,8 @@ Weak Ciphers initial stream output. Its use is strongly discouraged. ARC4 does not use mode constructions. - :param bytes key: The secret key, ``40``, ``56``, ``64``, ``80``, ``128``, - ``192``, or ``256`` bits in length. This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``40``, + ``56``, ``64``, ``80``, ``128``, ``192``, or ``256`` bits in length. .. doctest:: @@ -164,6 +169,16 @@ Weak Ciphers >>> decryptor.update(ct) 'a secret message' +.. class:: IDEA(key) + + IDEA (`International Data Encryption Algorithm`_) is a block cipher created + in 1991. It is an optional component of the `OpenPGP`_ standard. This cipher + is susceptible to attacks when using weak keys. It is recommended that you + do not use this cipher for new applications. + + :param bytes key: The secret key This must be kept secret. ``128`` bits in + length. + .. _symmetric-encryption-modes: @@ -174,16 +189,16 @@ Modes .. class:: CBC(initialization_vector) - CBC (Cipher block chaining) is a mode of operation for block ciphers. It is + CBC (Cipher Block Chaining) is a mode of operation for block ciphers. It is considered cryptographically strong. **Padding is required when using this mode.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). Must - be the same number of bytes as the ``block_size`` of the cipher. Each - time something is encrypted a new ``initialization_vector`` should be - generated. Do not reuse an ``initialization_vector`` with a given + to be kept secret and they can be included in a transmitted message. + Must be the same number of bytes as the ``block_size`` of the cipher. + Each time something is encrypted a new ``initialization_vector`` should + be generated. Do not reuse an ``initialization_vector`` with a given ``key``, and particularly do not use a constant ``initialization_vector``. @@ -223,7 +238,7 @@ Modes compromises the security of every message encrypted with that key. Must be the same number of bytes as the ``block_size`` of the cipher with a given key. The nonce does not need to be kept secret and may be - included alongside the ciphertext. + included with the ciphertext. .. class:: OFB(initialization_vector) @@ -233,9 +248,9 @@ Modes **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). Must - be the same number of bytes as the ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with a given ``key``. + to be kept secret and they can be included in a transmitted message. + Must be the same number of bytes as the ``block_size`` of the cipher. + Do not reuse an ``initialization_vector`` with a given ``key``. .. class:: CFB(initialization_vector) @@ -245,38 +260,38 @@ Modes **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). Must - be the same number of bytes as the ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with a given ``key``. + to be kept secret and they can be included in a transmitted message. + Must be the same number of bytes as the ``block_size`` of the cipher. + Do not reuse an ``initialization_vector`` with a given ``key``. .. class:: GCM(initialization_vector, tag=None) .. danger:: - When using this mode you MUST not use the decrypted data until + When using this mode you **must** not use the decrypted data until :meth:`~cryptography.hazmat.primitives.interfaces.CipherContext.finalize` - has been called. GCM provides NO guarantees of ciphertext integrity + has been called. GCM provides **no** guarantees of ciphertext integrity until decryption is complete. GCM (Galois Counter Mode) is a mode of operation for block ciphers. An AEAD (authenticated encryption with additional data) mode is a type of - block cipher mode that encrypts the message as well as authenticating it - (and optionally additional data that is not encrypted) simultaneously. - Additional means of verifying integrity (like - :doc:`HMAC </hazmat/primitives/hmac>`) are not necessary. + block cipher mode that simultaneously encrypts the message as well as + authenticating it. Additional unencrypted data may also be authenticated. + Additional means of verifying integrity such as + :doc:`HMAC </hazmat/primitives/hmac>` are not necessary. **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). NIST - `recommends 96-bit IV length`_ for performance critical situations, but - it can be up to 2\ :sup:`64` - 1 bits. Do not reuse an + to be kept secret and they can be included in a transmitted message. + NIST `recommends a 96-bit IV length`_ for performance critical + situations but it can be up to 2\ :sup:`64` - 1 bits. Do not reuse an ``initialization_vector`` with a given ``key``. .. note:: - Cryptography will emit a 128-bit tag when finalizing encryption. - You can shorten a tag by truncating it to the desired length, but this + Cryptography will generate a 128-bit tag when finalizing encryption. + You can shorten a tag by truncating it to the desired length but this is **not recommended** as it lowers the security margins of the authentication (`NIST SP-800-38D`_ recommends 96-bits or greater). If you must shorten the tag the minimum allowed length is 4 bytes @@ -298,8 +313,8 @@ Modes # Generate a random 96-bit IV. iv = os.urandom(12) - # Construct a AES-GCM Cipher object with the given and our randomly - # generated IV. + # Construct a AES-GCM Cipher object with the given key and a + # randomly generated IV. encryptor = Cipher( algorithms.AES(key), modes.GCM(iv), @@ -357,7 +372,7 @@ Modes a secret message! -Insecure Modes +Insecure modes -------------- .. warning:: @@ -371,7 +386,7 @@ Insecure Modes ECB (Electronic Code Book) is the simplest mode of operation for block ciphers. Each block of data is encrypted in the same way. This means identical plaintext blocks will always result in identical ciphertext - blocks, and thus result in information leakage + blocks, which can leave `significant patterns in the output`_. **Padding is required when using this mode.** @@ -386,12 +401,13 @@ Interfaces context. Once that is done call ``finalize()`` to finish the operation and obtain the remainder of the data. - Block ciphers require that plaintext or ciphertext always be a multiple of - their block size, because of that **padding** is sometimes required to make - a message the correct size. ``CipherContext`` will not automatically apply - any padding; you'll need to add your own. For block ciphers the recommended - padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you - are using a stream cipher mode (such as + Block ciphers require that the plaintext or ciphertext always be a multiple + of their block size. Because of that **padding** is sometimes required to + make a message the correct size. ``CipherContext`` will not automatically + apply any padding; you'll need to add your own. For block ciphers the + recommended padding is + :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you are using a + stream cipher mode (such as :class:`cryptography.hazmat.primitives.modes.CTR`) you don't have to worry about this. @@ -404,31 +420,31 @@ Interfaces When the ``Cipher`` was constructed in a mode that turns it into a stream cipher (e.g. :class:`cryptography.hazmat.primitives.ciphers.modes.CTR`), this will - return bytes immediately, however in other modes it will return chunks, + return bytes immediately, however in other modes it will return chunks whose size is determined by the cipher's block size. .. method:: finalize() :return bytes: Returns the remainder of the data. :raises ValueError: This is raised when the data provided isn't - correctly padded to be a multiple of the algorithm's block size. + a multiple of the algorithm's block size. Once ``finalize`` is called this object can no longer be used and - :meth:`update` and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. + :meth:`update` and :meth:`finalize` will raise an + :class:`~cryptography.exceptions.AlreadyFinalized` exception. .. class:: AEADCipherContext - When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object + When calling ``encryptor`` or ``decryptor`` on a ``Cipher`` object with an AEAD mode (e.g. :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If it is an encryption context it will additionally be an - ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an - additional method ``authenticate_additional_data`` for adding additional - authenticated but unencrypted data (see note below). You should call this - before calls to ``update``. When you are done call ``finalize()`` to finish - the operation. + ``AEADEncryptionContext`` provider. ``AEADCipherContext`` contains an + additional method :meth:`authenticate_additional_data` for adding + additional authenticated but unencrypted data (see note below). You should + call this before calls to ``update``. When you are done call `finalize`` + to finish the operation. .. note:: @@ -444,12 +460,13 @@ Interfaces .. class:: AEADEncryptionContext - When creating an encryption context using ``encryptor()`` on a ``Cipher`` - object with an AEAD mode (e.g. - :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive - a return object conforming to the ``AEADEncryptionContext`` interface (as - well as ``AEADCipherContext``). This interface provides one additional - attribute ``tag``. ``tag`` can only be obtained after ``finalize()``. + When creating an encryption context using ``encryptor`` on a ``Cipher`` + object with an AEAD mode such as + :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` an object + conforming to both the ``AEADEncryptionContext`` and ``AEADCipherContext`` + interfaces will be returned. This interface provides one + additional attribute ``tag``. ``tag`` can only be obtained after + ``finalize`` has been called. .. attribute:: tag @@ -459,6 +476,11 @@ Interfaces .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -.. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf +.. _`recommends a 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf .. _`NIST SP-800-38D`: http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf .. _`Communications Security Establishment`: http://www.cse-cst.gc.ca +.. _`encrypt`: https://ssd.eff.org/tech/encryption +.. _`CRYPTREC`: http://www.cryptrec.go.jp/english/ +.. _`significant patterns in the output`: http://en.wikipedia.org/wiki/Cipher_block_chaining#Electronic_codebook_.28ECB.29 +.. _`International Data Encryption Algorithm`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm +.. _`OpenPGP`: http://www.openpgp.org diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 3df1a147..f19cf0e6 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -1,6 +1,6 @@ .. hazmat:: -Two-factor Authentication +Two-factor authentication ========================= .. currentmodule:: cryptography.hazmat.primitives.twofactor @@ -47,10 +47,14 @@ codes (HMAC). provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` - is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :raises TypeError: This is raised if the provided ``algorithm`` is not + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or - :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the + ``length`` parameter is not an integer. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` .. method:: generate(counter) @@ -75,7 +79,7 @@ locks out the account for a period of time after a number of failed attempts. The number of allowed attempts should be as low as possible while still ensuring that usability is not significantly impacted. -Re-synchronization of the Counter +Re-synchronization of the counter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The server's counter value should only be incremented on a successful HOTP @@ -142,10 +146,14 @@ similar to the following code. provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` - is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :raises TypeError: This is raised if the provided ``algorithm`` is not + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or - :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the + ``length`` parameter is not an integer. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` .. method:: generate(time) diff --git a/docs/index.rst b/docs/index.rst index 176405b5..58424bfc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -85,10 +85,17 @@ The ``cryptography`` open source project installation development/index security + limitations api-stability doing-a-release changelog community +.. note:: + + ``cryptography`` has not been subjected to an external audit of its code or + documentation. If you're interested in discussing an audit please + :doc:`get in touch </community>`. + .. _`pre-compiled binaries`: https://www.openssl.org/related/binaries.html diff --git a/docs/installation.rst b/docs/installation.rst index 63555abc..c6a2a5c0 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -7,6 +7,18 @@ You can install ``cryptography`` with ``pip``: $ pip install cryptography +Supported platforms +------------------- + +Currently we test ``cryptography`` on Python 2.6, 2.7, 3.2, 3.3 and PyPy on +these operating systems. + +* x86-64 CentOS 6.4 and CentOS 5 +* x86-64 FreeBSD 9.2 and FreeBSD 10 +* OS X 10.9 and OS X 10.8 +* x86-64 Ubuntu 12.04 LTS +* 32-bit Python on 64-bit Windows Server 2008 + On Windows ---------- diff --git a/docs/limitations.rst b/docs/limitations.rst new file mode 100644 index 00000000..5b63ef54 --- /dev/null +++ b/docs/limitations.rst @@ -0,0 +1,19 @@ +Known security limitations +-------------------------- + +Lack of secure memory wiping +============================ + +`Memory wiping`_ is used to protect secret data or key material from attackers +with access to uninitialized memory. This can be either because the attacker +has some kind of local user access or because of how other software uses +uninitialized memory. + +Python exposes no API for us to implement this reliably and as such almost all +software in Python is potentially vulnerable to this attack. However the +`CERT secure coding guidelines`_ consider this issue as "low severity, +unlikely, expensive to repair" and we do not consider this a high risk for most +users. + +.. _`Memory wiping`: http://blogs.msdn.com/b/oldnewthing/archive/2013/05/29/10421912.aspx +.. _`CERT secure coding guidelines`: https://www.securecoding.cert.org/confluence/display/seccode/MEM03-C.+Clear+sensitive+information+stored+in+reusable+resources |