diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/conf.py | 104 | ||||
| -rw-r--r-- | docs/development/test-vectors.rst | 5 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 6 | ||||
| -rw-r--r-- | docs/hazmat/primitives/constant-time.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 3 | ||||
| -rw-r--r-- | docs/installation.rst | 4 | ||||
| -rw-r--r-- | docs/security.rst | 37 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 | ||||
| -rw-r--r-- | docs/x509/reference.rst | 44 | ||||
| -rw-r--r-- | docs/x509/tutorial.rst | 4 |
11 files changed, 105 insertions, 109 deletions
diff --git a/docs/conf.py b/docs/conf.py index dcc9c626..85a569a7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -116,10 +116,6 @@ exclude_patterns = ['_build'] # 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 = [] - - # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for @@ -131,73 +127,11 @@ if sphinx_rtd_theme: else: html_theme = "default" -# 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 = {} - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -# html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -# 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 - -# 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 - # 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, # so a file named "default.css" will overwrite the builtin "default.css". 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' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -# html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -# html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -# html_additional_pages = {} - -# If false, no module index is generated. -# html_domain_indices = True - -# If false, no index is generated. -# html_use_index = True - -# If true, the index is split into individual pages for each letter. -# html_split_index = False - -# If true, links to the reST sources are added to the pages. -# html_show_sourcelink = True - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -# html_show_sphinx = True - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is 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 = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -# html_file_suffix = None - # Output file base name for HTML help builder. htmlhelp_basename = 'Cryptographydoc' @@ -214,27 +148,6 @@ latex_documents = [ 'Individual Contributors', 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -# latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -# latex_use_parts = False - -# If true, show page references after internal links. -# latex_show_pagerefs = False - -# If true, show URL addresses after external links. -# latex_show_urls = False - -# Documents to append as an appendix to all manuals. -# latex_appendices = [] - -# If false, no module index is generated. -# latex_domain_indices = True - - # -- Options for manual page output ------------------------------------------- # One entry per manual page. List of tuples @@ -244,10 +157,6 @@ man_pages = [ ['Individual Contributors'], 1) ] -# If true, show URL addresses after external links. -# man_show_urls = False - - # -- Options for Texinfo output ----------------------------------------------- # Grouping the document tree into Texinfo files. List of tuples @@ -260,16 +169,11 @@ texinfo_documents = [ 'Miscellaneous'), ] -# Documents to append as an appendix to all manuals. -# texinfo_appendices = [] - -# If false, no module index is generated. -# texinfo_domain_indices = True - -# How to display URL addresses: 'footnote', 'no', or 'inline'. -# texinfo_show_urls = 'footnote' - # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {'https://docs.python.org/3': None} epub_theme = 'epub' + +# Retry requests in the linkcheck builder so that we're resillient against +# transient network errors. +linkcheck_retries = 2 diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index 4abf9f63..5bb4eefc 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -110,6 +110,9 @@ X.509 containing a SAN extension with an ``ediPartyName`` general name. * ``san_x400address.der`` - A DSA certificate from a `Mozilla bug`_ containing a SAN extension with an ``x400Address`` general name. +* ``department-of-state-root.pem`` - The intermediary CA for the Department of + State, issued by the United States Federal Government's Common Policy CA. + Notably has a ``critical`` policy constraints extensions. Custom X.509 Vectors ~~~~~~~~~~~~~~~~~~~~ @@ -260,6 +263,8 @@ Custom X.509 Vectors policy constraints extension with a require explicit policy element. * ``unsupported_subject_public_key_info.pem`` - A certificate whose public key is an unknown OID (``1.3.6.1.4.1.8432.1.1.2``). +* ``policy_constraints_explicit.pem`` - A self-signed certificate containing + a ``policyConstraints`` extension with a ``requireExplicitPolicy`` value. Custom X.509 Request Vectors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 73011dd0..83ec6f19 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -133,13 +133,15 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: ``True`` if the specified ``algorithm`` is supported for HMAC by this backend, otherwise ``False``. - .. method:: create_hmac_ctx(algorithm) + .. method:: create_hmac_ctx(key, algorithm) Create a :class:`~cryptography.hazmat.primitives.hashes.HashContext` that uses the specified ``algorithm`` to calculate a hash-based message authentication code. + :param bytes key: Secret key as ``bytes``. + :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` provider. diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index bc2402de..1e18915c 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -271,7 +271,7 @@ Padding Pass this attribute to ``salt_length`` to get the maximum salt length available. -.. class:: OAEP(mgf, label) +.. class:: OAEP(mgf, algorithm, label) .. versionadded:: 0.4 @@ -283,6 +283,10 @@ Padding :param mgf: A mask generation function object. At this time the only supported MGF is :class:`MGF1`. + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` + provider. + :param bytes label: A label to apply. This is a rarely used field and should typically be set to ``None`` or ``b""``, which are equivalent. diff --git a/docs/hazmat/primitives/constant-time.rst b/docs/hazmat/primitives/constant-time.rst index 1394b6b3..1c1d544f 100644 --- a/docs/hazmat/primitives/constant-time.rst +++ b/docs/hazmat/primitives/constant-time.rst @@ -40,4 +40,4 @@ about the timing attacks on KeyCzar and Java's ``MessageDigest.isEqual()``. ``bytes``. -.. _`Coda Hale's blog post`: http://codahale.com/a-lesson-in-timing-attacks/ +.. _`Coda Hale's blog post`: https://codahale.com/a-lesson-in-timing-attacks/ diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 309c6fd0..d5884897 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -334,6 +334,9 @@ Modes :raises ValueError: This is raised if ``len(tag) < min_tag_length``. + An example of securely encrypting and decrypting data with ``AES`` in the + ``GCM`` mode looks like: + .. testcode:: import os diff --git a/docs/installation.rst b/docs/installation.rst index f9d2261a..1804989b 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -39,8 +39,8 @@ OpenSSL releases: .. warning:: OpenSSL versions 0.9.8 and 1.0.0 are no longer supported by the OpenSSL - project. A future version of cryptography will drop support for these - releases. + project. Support for OpenSSL 0.9.8 will be removed in the next + ``cryptography`` release. On Windows ---------- diff --git a/docs/security.rst b/docs/security.rst index 13f99960..1cc1273d 100644 --- a/docs/security.rst +++ b/docs/security.rst @@ -5,6 +5,39 @@ We take the security of ``cryptography`` seriously. The following are a set of policies we have adopted to ensure that security issues are addressed in a timely fashion. +What is a security issue? +------------------------- + +Anytime it's possible to write code using ``cryptography``'s public API which +does not provide the guarantees that a reasonable developer would expect it to +based on our documentation. + +That's a bit academic, but basically it means the scope of what we consider a +vulnerability is broad, and we do not require a proof of concept or even a +specific exploit, merely a reasonable threat model under which ``cryptography`` +could be attacked. + +To give a few examples of things we would consider security issues: + +* If a recipe, such as Fernet, made it easy for a user to bypass + confidentiality or integrity with the public API (e.g. if the API let a user + reuse nonces). +* If, under any circumstances, we used a CSPRNG which wasn't fork-safe. +* If ``cryptography`` used an API in an underlying C library and failed to + handle error conditions safely. + +Examples of things we wouldn't consider security issues: + +* Offering ECB mode for symmetric encryption in the *Hazmat* layer. Though ECB + is critically weak, it is documented as being weak in our documentation. +* Using a variable time comparison somewhere, if it's not possible to + articulate any particular program in which this would result in problematic + information disclosure. + +In general, if you're unsure, we request that you to default to treating things +as security issues and handling them sensitively, the worst thing that can +happen is that we'll ask you to file a bug issue. + Reporting a security issue -------------------------- @@ -14,7 +47,7 @@ tracker. If you believe you've identified a security issue with ``cryptography``, please report it to ``alex.gaynor@gmail.com``. Messages may be optionally encrypted with PGP using key fingerprint -``E27D 4AA0 1651 72CB C5D2 AF2B 125F 5C67 DFE9 4084`` (this public key is +``F7FC 698F AAE2 D2EF BECD E98E D1B3 ADC0 E023 8CA6`` (this public key is available from most commonly-used key servers). Once you've submitted an issue via email, you should receive an acknowledgment @@ -25,7 +58,7 @@ Supported Versions ------------------ At any given time, we will provide security support for the `master`_ branch -as well as the 2 most recent releases. +as well as the most recent release. New releases for OpenSSL updates -------------------------------- diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 6def7959..47415a7e 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -45,6 +45,7 @@ multi naïve namespace namespaces +nonces Nonces online paddings diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 3b14567e..67427ddb 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -1866,6 +1866,44 @@ X.509 Extensions :type: int +.. class:: PolicyConstraints + + .. versionadded:: 1.3 + + The policy constraints extension is used to inhibit policy mapping or + require that each certificate in a chain contain an acceptable policy + identifier. For more information about the use of this extension see + :rfc:`5280`. + + .. attribute:: oid + + :type: :class:`ObjectIdentifier` + + Returns :attr:`~cryptography.x509.oid.ExtensionOID.POLICY_CONSTRAINTS`. + + .. attribute:: require_explicit_policy + + :type: int or None + + If this field is not None, the value indicates the number of additional + certificates that may appear in the chain before an explicit policy is + required for the entire path. When an explicit policy is required, it + is necessary for all certificates in the chain to contain an acceptable + policy identifier in the certificate policies extension. An + acceptable policy identifier is the identifier of a policy required + by the user of the certification path or the identifier of a policy + that has been declared equivalent through policy mapping. + + .. attribute:: inhibit_policy_mapping + + :type: int or None + + If this field is not None, the value indicates the number of additional + certificates that may appear in the chain before policy mapping is no + longer permitted. For example, a value of one indicates that policy + mapping may be processed in certificates issued by the subject of this + certificate, but not in additional certificates in the chain. + .. class:: CRLNumber(crl_number) .. versionadded:: 1.2 @@ -2398,6 +2436,12 @@ instances. The following common OIDs are available as constants. the ``CRLNumber`` extension type. This extension only has meaning for certificate revocation lists. + .. attribute:: POLICY_CONSTRAINTS + + Corresponds to the dotted string ``"2.5.29.36"``. The identifier for the + :class:`~cryptography.x509.PolicyConstraints` extension type. + + .. class:: CRLEntryExtensionOID .. versionadded:: 1.2 diff --git a/docs/x509/tutorial.rst b/docs/x509/tutorial.rst index 0fa061a2..7252e43a 100644 --- a/docs/x509/tutorial.rst +++ b/docs/x509/tutorial.rst @@ -1,8 +1,8 @@ Tutorial ======== -X.509 certificates are used to authenticate clients on servers. The most common -use case is for web servers using HTTPS. +X.509 certificates are used to authenticate clients and servers. The most +common use case is for web servers using HTTPS. Creating a Certificate Signing Request (CSR) -------------------------------------------- |