diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/test-vectors.rst | 53 | ||||
| -rw-r--r-- | docs/glossary.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 13 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 1 | ||||
| -rw-r--r-- | docs/x509.rst | 364 |
6 files changed, 437 insertions, 10 deletions
diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index c40a6621..0bd1f69e 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -151,6 +151,9 @@ Custom X.509 Vectors * ``san_idna_names.pem`` - An RSA 2048 bit self-signed certificate containing a subject alternative name extension with ``rfc822Name``, ``dNSName``, and ``uniformResourceIdentifier`` general names with IDNA (:rfc:`5895`) encoding. +* ``san_idna2003_dnsname.pem`` - An RSA 2048 bit self-signed certificate + containing a subject alternative name extension with an IDNA 2003 + (:rfc:`3490`) ``dNSName``. * ``san_rfc822_names.pem`` - An RSA 2048 bit self-signed certificate containing a subject alternative name extension with various ``rfc822Name`` values. * ``san_rfc822_idna.pem`` - An RSA 2048 bit self-signed certificate containing @@ -179,6 +182,27 @@ Custom X.509 Vectors containing an authority information access extension with an OCSP entry. * ``aia_ca_issuers.pem`` - An RSA 2048 bit self-signed certificate containing an authority information access extension with a CA issuers entry. +* ``cdp_fullname_reasons_crl_issuer.pem`` - An RSA 1024 bit certificate + containing a CRL distribution points extension with ``fullName``, + ``cRLIssuer``, and ``reasons`` data. +* ``cdp_crl_issuer.pem`` - An RSA 1024 bit certificate containing a CRL + distribution points extension with ``cRLIssuer`` data. +* ``cdp_all_reasons.pem`` - An RSA 1024 bit certificate containing a CRL + distribution points extension with all ``reasons`` bits set. +* ``cdp_reason_aa_compromise.pem`` - An RSA 1024 bit certificate containing a + CRL distribution points extension with the ``AACompromise`` ``reasons`` bit + set. +* ``cp_user_notice_with_notice_reference.pem`` - An RSA 2048 bit self-signed + certificate containing a certificate policies extension with a + notice reference in the user notice. +* ``cp_user_notice_with_explicit_text.pem`` - An RSA 2048 bit self-signed + certificate containing a certificate policies extension with explicit + text and no notice reference. +* ``cp_cps_uri.pem`` - An RSA 2048 bit self-signed certificate containing a + certificate policies extension with a CPS URI and no user notice. +* ``cp_user_notice_no_explicit_text.pem`` - An RSA 2048 bit self-signed + certificate containing a certificate policies extension with a user notice + with no explicit text. Custom X.509 Request Vectors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -196,6 +220,35 @@ Custom X.509 Request Vectors * ``san_rsa_sha1.pem`` and ``san_rsa_sha1.der`` - Contain a certificate request using RSA and SHA1 with a subject alternative name extension generated using OpenSSL. +* ``two_basic_constraints.pem`` - A certificate signing request + for a RSA 2048 bit key containing two basic constraints extensions. +* ``unsupported_extension.pem`` - A certificate signing request + for an RSA 2048 bit key containing containing an unsupported + extension type. The OID was encoded as "1.2.3.4" with an + ``extnValue`` of "value". +* ``unsupported_extension_critical.pem`` - A certificate signing + request for an RSA 2048 bit key containing containing an unsupported + extension type marked critical. The OID was encoded as "1.2.3.4" + with an ``extnValue`` of "value". +* ``basic_constraints.pem`` - A certificate signing request for a RSA + 2048 bit key containing a basic constraints extension marked as + critical. + +Custom X.509 Certificate Revocation List Vectors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +* ``crl_all_reasons.pem`` - Contains a CRL with 12 revoked certificates, whose + serials match their list position. It includes one revocation without + any entry extensions, 10 revocations with every supported reason code and one + revocation with an unsupported, non-critical entry extension with the OID + value set to "1.2.3.4". +* ``crl_dup_entry_ext.pem`` - Contains a CRL with one revocation which has a + duplicate entry extension. +* ``crl_md2_unknown_crit_entry_ext.pem`` - Contains a CRL with one revocation + which contains an unsupported critical entry extension with the OID value set + to "1.2.3.4". The CRL uses an unsupported MD2 signature algorithm. +* ``crl_unsupported_reason.pem`` - Contains a CRL with one revocation which has + an unsupported reason code. Hashes ~~~~~~ diff --git a/docs/glossary.rst b/docs/glossary.rst index dc6f3ebf..202fa2de 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -64,3 +64,11 @@ Glossary text This type corresponds to ``unicode`` on Python 2 and ``str`` on Python 3. This is equivalent to ``six.text_type``. + + nonce + A nonce is a **n**\ umber used **once**. Nonces are used in many + cryptographic protocols. Generally, a nonce does not have to be secret + or unpredictable, but it must be unique. A nonce is often a random + or pseudo-random number (see :doc:`Random number generation + </random-numbers>`). Since a nonce does not have to be unpredictable, + it can also take a form of a counter. diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 6f4afe7d..71f6e6fd 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -251,6 +251,14 @@ All named curves are providers of :class:`EllipticCurve`. SECG curve ``secp192r1``. Also called NIST P-192. + +.. class:: SECP256K1 + + .. versionadded:: 0.9 + + SECG curve ``secp256k1``. + + Key Interfaces ~~~~~~~~~~~~~~ diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 47486895..309c6fd0 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -240,7 +240,7 @@ Modes **This mode does not require padding.** - :param bytes nonce: Should be :doc:`random bytes </random-numbers>`. It is + :param bytes nonce: Should be unique, a :term:`nonce`. It is critical to never reuse a ``nonce`` with a given key. Any reuse of a nonce with the same key compromises the security of every message encrypted with that key. Must be the same number of bytes as the @@ -305,12 +305,11 @@ Modes **This mode does not require padding.** - :param bytes initialization_vector: Must be :doc:`random bytes - </random-numbers>`. They do not need 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``. + :param bytes initialization_vector: Must be unique, a :term:`nonce`. + They do not need 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:: diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index badb500c..81510134 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -40,6 +40,7 @@ multi naïve namespace namespaces +Nonces online paddings pickleable diff --git a/docs/x509.rst b/docs/x509.rst index f4ea2a52..bdcd60b1 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -208,7 +208,7 @@ X.509 Certificate Object :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` that will be used to generate the fingerprint. - :return bytes: The fingerprint using the supplied hash algorithm as + :return bytes: The fingerprint using the supplied hash algorithm, as bytes. .. doctest:: @@ -313,6 +313,9 @@ X.509 Certificate Object :raises cryptography.x509.UnsupportedGeneralNameType: If an extension contains a general name that is not supported. + :raises UnicodeError: If an extension contains IDNA encoding that is + invalid or not compliant with IDNA 2008. + .. doctest:: >>> for ext in cert.extensions: @@ -320,8 +323,73 @@ X.509 Certificate Object <Extension(oid=<ObjectIdentifier(oid=2.5.29.35, name=authorityKeyIdentifier)>, critical=False, value=<AuthorityKeyIdentifier(key_identifier='\xe4}_\xd1\\\x95\x86\x08,\x05\xae\xbeu\xb6e\xa7\xd9]\xa8f', authority_cert_issuer=None, authority_cert_serial_number=None)>)> <Extension(oid=<ObjectIdentifier(oid=2.5.29.14, name=subjectKeyIdentifier)>, critical=False, value=<SubjectKeyIdentifier(digest='X\x01\x84$\x1b\xbc+R\x94J=\xa5\x10r\x14Q\xf5\xaf:\xc9')>)> <Extension(oid=<ObjectIdentifier(oid=2.5.29.15, name=keyUsage)>, critical=True, value=<KeyUsage(digital_signature=False, content_commitment=False, key_encipherment=False, data_encipherment=False, key_agreement=False, key_cert_sign=True, crl_sign=True, encipher_only=None, decipher_only=None)>)> + <Extension(oid=<ObjectIdentifier(oid=2.5.29.32, name=certificatePolicies)>, critical=False, value=<CertificatePolicies([<PolicyInformation(policy_identifier=<ObjectIdentifier(oid=2.16.840.1.101.3.2.1.48.1, name=Unknown OID)>, policy_qualifiers=None)>])>)> <Extension(oid=<ObjectIdentifier(oid=2.5.29.19, name=basicConstraints)>, critical=True, value=<BasicConstraints(ca=True, path_length=None)>)> + .. method:: public_bytes(encoding) + + :param encoding: The + :class:`~cryptography.hazmat.primitives.serialization.Encoding` + that will be used to serialize the certificate. + + :return bytes: The data that can be written to a file or sent + over the network to be verified by clients. + +X.509 CRL (Certificate Revocation List) Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: CertificateRevocationList + + .. versionadded:: 1.0 + + .. method:: fingerprint(algorithm) + + :param algorithm: The + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` + that will be used to generate the fingerprint. + + :return bytes: The fingerprint using the supplied hash algorithm, as + bytes. + + .. attribute:: signature_hash_algorithm + + :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` + + Returns the + :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which + was used in signing this CRL. + + .. attribute:: issuer + + :type: :class:`Name` + + The :class:`Name` of the issuer. + + .. attribute:: next_update + + :type: :class:`datetime.datetime` + + A naïve datetime representing when the next update to this CRL is + expected. + + .. attribute:: last_update + + :type: :class:`datetime.datetime` + + A naïve datetime representing when the this CRL was last updated. + + .. attribute:: revoked_certificates + + :type: list of :class:`RevokedCertificate` + + The revoked certificates listed in this CRL. + + .. attribute:: extensions + + :type: :class:`Extensions` + + The extensions encoded in the CRL. + X.509 CSR (Certificate Signing Request) Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -365,6 +433,41 @@ X.509 CSR (Certificate Signing Request) Object >>> isinstance(csr.signature_hash_algorithm, hashes.SHA1) True + .. method:: public_bytes(encoding) + + :param encoding: The + :class:`~cryptography.hazmat.primitives.serialization.Encoding` + that will be used to serialize the certificate request. + + :return bytes: The data that can be written to a file or sent + over the network to be signed by the certificate + authority. + +X.509 Revoked Certificate Object +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: RevokedCertificate + + .. versionadded:: 1.0 + + .. attribute:: serial_number + + :type: :class:`int` + + An integer representing the serial number of the revoked certificate. + + .. attribute:: revocation_date + + :type: :class:`datetime.datetime` + + A naïve datetime representing the date this certificates was revoked. + + .. attribute:: extensions + + :type: :class:`Extensions` + + The extensions encoded in the revoked certificate. + .. class:: Name .. versionadded:: 0.8 @@ -508,8 +611,9 @@ General Name Classes .. attribute:: value - :type: :class:`~ipaddress.IPv4Address` or - :class:`~ipaddress.IPv6Address`. + :type: :class:`~ipaddress.IPv4Address`, + :class:`~ipaddress.IPv6Address`, :class:`~ipaddress.IPv4Network`, + or :class:`~ipaddress.IPv6Network`. .. class:: RegisteredID @@ -697,6 +801,19 @@ X.509 Extensions purposes indicated in the key usage extension. The object is iterable to obtain the list of :ref:`extended key usage OIDs <eku_oids>`. +.. class:: OCSPNoCheck + + .. versionadded:: 1.0 + + This presence of this extension indicates that an OCSP client can trust a + responder for the lifetime of the responder's certificate. CAs issuing + such a certificate should realize that a compromise of the responder's key + is as serious as the compromise of a CA key used to sign CRLs, at least for + the validity period of this certificate. CA's may choose to issue this type + of certificate with a very short lifetime and renew it frequently. This + extension is only relevant when the certificate is an authorized OCSP + responder. + .. class:: AuthorityKeyIdentifier .. versionadded:: 0.9 @@ -781,6 +898,8 @@ X.509 Extensions .. class:: AccessDescription + .. versionadded:: 0.9 + .. attribute:: access_method :type: :class:`ObjectIdentifier` @@ -798,6 +917,191 @@ X.509 Extensions Where to access the information defined by the access method. +.. class:: CRLDistributionPoints + + .. versionadded:: 0.9 + + The CRL distribution points extension identifies how CRL information is + obtained. It is an iterable, containing one or more + :class:`DistributionPoint` instances. + +.. class:: DistributionPoint + + .. versionadded:: 0.9 + + .. attribute:: full_name + + :type: list of :class:`GeneralName` instances or None + + This field describes methods to retrieve the CRL. At most one of + ``full_name`` or ``relative_name`` will be non-None. + + .. attribute:: relative_name + + :type: :class:`Name` or None + + This field describes methods to retrieve the CRL relative to the CRL + issuer. At most one of ``full_name`` or ``relative_name`` will be + non-None. + + .. attribute:: crl_issuer + + :type: list of :class:`GeneralName` instances or None + + Information about the issuer of the CRL. + + .. attribute:: reasons + + :type: frozenset of :class:`ReasonFlags` or None + + The reasons a given distribution point may be used for when performing + revocation checks. + +.. class:: ReasonFlags + + .. versionadded:: 0.9 + + An enumeration for CRL reasons. + + .. attribute:: unspecified + + It is unspecified why the certificate was revoked. This reason cannot + be used as a reason flag in a :class:`DistributionPoint`. + + .. attribute:: key_compromise + + This reason indicates that the private key was compromised. + + .. attribute:: ca_compromise + + This reason indicates that the CA issuing the certificate was + compromised. + + .. attribute:: affiliation_changed + + This reason indicates that the subject's name or other information has + changed. + + .. attribute:: superseded + + This reason indicates that a certificate has been superseded. + + .. attribute:: cessation_of_operation + + This reason indicates that the certificate is no longer required. + + .. attribute:: certificate_hold + + This reason indicates that the certificate is on hold. + + .. attribute:: privilege_withdrawn + + This reason indicates that the privilege granted by this certificate + have been withdrawn. + + .. attribute:: aa_compromise + + When an attribute authority has been compromised. + + .. attribute:: remove_from_crl + + This reason indicates that the certificate was on hold and should be + removed from the CRL. This reason cannot be used as a reason flag + in a :class:`DistributionPoint`. + +.. class:: InhibitAnyPolicy + + .. versionadded:: 1.0 + + The inhibit ``anyPolicy`` extension indicates that the special OID + :data:`OID_ANY_POLICY`, is not considered an explicit match for other + :class:`CertificatePolicies` except when it appears in an intermediate + self-issued CA certificate. The value indicates the number of additional + non-self-issued certificates that may appear in the path before + :data:`OID_ANY_POLICY` is no longer permitted. For example, a value + of one indicates that :data:`OID_ANY_POLICY` may be processed in + certificates issued by the subject of this certificate, but not in + additional certificates in the path. + + .. attribute:: skip_certs + + :type: int + +.. class:: CertificatePolicies + + .. versionadded:: 0.9 + + The certificate policies extension is an iterable, containing one or more + :class:`PolicyInformation` instances. + +Certificate Policies Classes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These classes may be present within a :class:`CertificatePolicies` instance. + +.. class:: PolicyInformation + + .. versionadded:: 0.9 + + Contains a policy identifier and an optional list of qualifiers. + + .. attribute:: policy_identifier + + :type: :class:`ObjectIdentifier` + + .. attribute:: policy_qualifiers + + :type: list + + A list consisting of :term:`text` and/or :class:`UserNotice` objects. + If the value is text it is a pointer to the practice statement + published by the certificate authority. If it is a user notice it is + meant for display to the relying party when the certificate is + used. + +.. class:: UserNotice + + .. versionadded:: 0.9 + + User notices are intended for display to a relying party when a certificate + is used. In practice, few if any UIs expose this data and it is a rarely + encoded component. + + .. attribute:: notice_reference + + :type: :class:`NoticeReference` or None + + The notice reference field names an organization and identifies, + by number, a particular statement prepared by that organization. + + .. attribute:: explicit_text + + This field includes an arbitrary textual statement directly in the + certificate. + + :type: :term:`text` + +.. class:: NoticeReference + + Notice reference can name an organization and provide information about + notices related to the certificate. For example, it might identify the + organization name and notice number 1. Application software could + have a notice file containing the current set of notices for the named + organization; the application would then extract the notice text from the + file and display it. In practice this is rarely seen. + + .. versionadded:: 0.9 + + .. attribute:: organization + + :type: :term:`text` + + .. attribute:: notice_numbers + + :type: list + + A list of integers. + Object Identifiers ~~~~~~~~~~~~~~~~~~ @@ -1003,6 +1307,21 @@ Authority Information Access OIDs Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.2"``. Used as the identifier for CA issuer data in :class:`AccessDescription` objects. +Policy Qualifier OIDs +~~~~~~~~~~~~~~~~~~~~~ + +.. data:: OID_CPS_QUALIFIER + + Corresponds to the dotted string ``"1.3.6.1.5.5.7.2.1"``. + +.. data:: OID_CPS_USER_NOTICE + + Corresponds to the dotted string ``"1.3.6.1.5.5.7.2.2"``. + +.. data:: OID_ANY_POLICY + + Corresponds to the dotted string ``"2.5.29.32.0"``. + .. _extension_oids: Extension OIDs @@ -1018,6 +1337,45 @@ Extension OIDs Corresponds to the dotted string ``"2.5.29.15"``. The identifier for the :class:`KeyUsage` extension type. +.. data:: OID_SUBJECT_ALTERNATIVE_NAME + + Corresponds to the dotted string ``"2.5.29.17"``. The identifier for the + :class:`SubjectAlternativeName` extension type. + +.. data:: OID_SUBJECT_KEY_IDENTIFIER + + Corresponds to the dotted string ``"2.5.29.14"``. The identifier for the + :class:`SubjectKeyIdentifier` extension type. + +.. data:: OID_CRL_DISTRIBUTION_POINTS + + Corresponds to the dotted string ``"2.5.29.31"``. The identifier for the + :class:`CRLDistributionPoints` extension type. + +.. data:: OID_CERTIFICATE_POLICIES + + Corresponds to the dotted string ``"2.5.29.32"``. The identifier for the + :class:`CertificatePolicies` extension type. + +.. data:: OID_AUTHORITY_KEY_IDENTIFIER + + Corresponds to the dotted string ``"2.5.29.35"``. The identifier for the + :class:`AuthorityKeyIdentifier` extension type. + +.. data:: OID_EXTENDED_KEY_USAGE + + Corresponds to the dotted string ``"2.5.29.37"``. The identifier for the + :class:`ExtendedKeyUsage` extension type. + +.. data:: OID_AUTHORITY_INFORMATION_ACCESS + + Corresponds to the dotted string ``"1.3.6.1.5.5.7.1.1"``. The identifier + for the :class:`AuthorityInformationAccess` extension type. + +.. data:: OID_OCSP_NO_CHECK + + Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.1.5"``. The identifier + for the :class:`OCSPNoCheck` extension type. Exceptions ~~~~~~~~~~ |