diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/custom-vectors/secp256k1.rst | 32 | ||||
| -rw-r--r-- | docs/development/custom-vectors/secp256k1/generate_secp256k1.py | 89 | ||||
| -rw-r--r-- | docs/development/custom-vectors/secp256k1/verify_secp256k1.py | 59 | ||||
| -rw-r--r-- | docs/development/test-vectors.rst | 70 | ||||
| -rw-r--r-- | docs/glossary.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 85 | ||||
| -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 | 2 | ||||
| -rw-r--r-- | docs/x509.rst | 368 |
10 files changed, 719 insertions, 15 deletions
diff --git a/docs/development/custom-vectors/secp256k1.rst b/docs/development/custom-vectors/secp256k1.rst new file mode 100644 index 00000000..b19bf4e4 --- /dev/null +++ b/docs/development/custom-vectors/secp256k1.rst @@ -0,0 +1,32 @@ +SECP256K1 vector creation +========================= + +This page documents the code that was used to generate the SECP256K1 elliptic +curve test vectors as well as code used to verify them against another +implementation. + + +Creation +-------- + +The vectors are generated using a `pure Python ecdsa`_ implementation. The test +messages and combinations of algorithms are derived from the NIST vector data. + +.. literalinclude:: /development/custom-vectors/secp256k1/generate_secp256k1.py + +Download link: :download:`generate_secp256k1.py +</development/custom-vectors/secp256k1/generate_secp256k1.py>` + + +Verification +------------ + +``cryptography`` was modified to support the SECP256K1 curve. Then +the following python script was run to generate the vector files. + +.. literalinclude:: /development/custom-vectors/secp256k1/verify_secp256k1.py + +Download link: :download:`verify_secp256k1.py +</development/custom-vectors/secp256k1/verify_secp256k1.py>` + +.. _`pure Python ecdsa`: https://pypi.python.org/pypi/ecdsa diff --git a/docs/development/custom-vectors/secp256k1/generate_secp256k1.py b/docs/development/custom-vectors/secp256k1/generate_secp256k1.py new file mode 100644 index 00000000..502a3ff6 --- /dev/null +++ b/docs/development/custom-vectors/secp256k1/generate_secp256k1.py @@ -0,0 +1,89 @@ +from __future__ import absolute_import, print_function + +import hashlib +import os +from binascii import hexlify +from collections import defaultdict + +from ecdsa import SECP256k1, SigningKey +from ecdsa.util import sigdecode_der, sigencode_der + +from cryptography_vectors import open_vector_file + +from tests.utils import ( + load_fips_ecdsa_signing_vectors, load_vectors_from_file +) + +HASHLIB_HASH_TYPES = { + "SHA-1": hashlib.sha1, + "SHA-224": hashlib.sha224, + "SHA-256": hashlib.sha256, + "SHA-384": hashlib.sha384, + "SHA-512": hashlib.sha512, +} + + +class TruncatedHash(object): + def __init__(self, hasher): + self.hasher = hasher + + def __call__(self, data): + self.hasher.update(data) + return self + + def digest(self): + return self.hasher.digest()[:256 // 8] + + +def build_vectors(fips_vectors): + vectors = defaultdict(list) + for vector in fips_vectors: + vectors[vector['digest_algorithm']].append(vector['message']) + + for digest_algorithm, messages in vectors.items(): + if digest_algorithm not in HASHLIB_HASH_TYPES: + continue + + yield "" + yield "[K-256,{0}]".format(digest_algorithm) + yield "" + + for message in messages: + # Make a hash context + hash_func = TruncatedHash(HASHLIB_HASH_TYPES[digest_algorithm]()) + + # Sign the message using warner/ecdsa + secret_key = SigningKey.generate(curve=SECP256k1) + public_key = secret_key.get_verifying_key() + signature = secret_key.sign(message, hashfunc=hash_func, + sigencode=sigencode_der) + + r, s = sigdecode_der(signature, None) + + yield "Msg = {0}".format(hexlify(message)) + yield "d = {0:x}".format(secret_key.privkey.secret_multiplier) + yield "Qx = {0:x}".format(public_key.pubkey.point.x()) + yield "Qy = {0:x}".format(public_key.pubkey.point.y()) + yield "R = {0:x}".format(r) + yield "S = {0:x}".format(s) + yield "" + + +def write_file(lines, dest): + for line in lines: + print(line) + print(line, file=dest) + +source_path = os.path.join("asymmetric", "ECDSA", "FIPS_186-3", "SigGen.txt") +dest_path = os.path.join("asymmetric", "ECDSA", "SECP256K1", "SigGen.txt") + +fips_vectors = load_vectors_from_file( + source_path, + load_fips_ecdsa_signing_vectors +) + +with open_vector_file(dest_path, "w") as dest_file: + write_file( + build_vectors(fips_vectors), + dest_file + ) diff --git a/docs/development/custom-vectors/secp256k1/verify_secp256k1.py b/docs/development/custom-vectors/secp256k1/verify_secp256k1.py new file mode 100644 index 00000000..3d2c25b9 --- /dev/null +++ b/docs/development/custom-vectors/secp256k1/verify_secp256k1.py @@ -0,0 +1,59 @@ +from __future__ import absolute_import, print_function + +import os + +from cryptography.hazmat.backends import default_backend +from cryptography.hazmat.primitives import hashes +from cryptography.hazmat.primitives.asymmetric import ec +from cryptography.hazmat.primitives.asymmetric.utils import ( + encode_rfc6979_signature +) + +from tests.utils import ( + load_fips_ecdsa_signing_vectors, load_vectors_from_file +) + +CRYPTOGRAPHY_HASH_TYPES = { + "SHA-1": hashes.SHA1, + "SHA-224": hashes.SHA224, + "SHA-256": hashes.SHA256, + "SHA-384": hashes.SHA384, + "SHA-512": hashes.SHA512, +} + + +def verify_one_vector(vector): + digest_algorithm = vector['digest_algorithm'] + message = vector['message'] + x = vector['x'] + y = vector['y'] + signature = encode_rfc6979_signature(vector['r'], vector['s']) + + numbers = ec.EllipticCurvePublicNumbers( + x, y, + ec.SECP256K1() + ) + + key = numbers.public_key(default_backend()) + + verifier = key.verifier( + signature, + ec.ECDSA(CRYPTOGRAPHY_HASH_TYPES[digest_algorithm]()) + ) + verifier.update(message) + return verifier.verify() + + +def verify_vectors(vectors): + for vector in vectors: + assert verify_one_vector(vector) + + +vector_path = os.path.join("asymmetric", "ECDSA", "SECP256K1", "SigGen.txt") + +secp256k1_vectors = load_vectors_from_file( + vector_path, + load_fips_ecdsa_signing_vectors +) + +verify_vectors(secp256k1_vectors) diff --git a/docs/development/test-vectors.rst b/docs/development/test-vectors.rst index 69f54d3a..b4f23eda 100644 --- a/docs/development/test-vectors.rst +++ b/docs/development/test-vectors.rst @@ -37,9 +37,14 @@ Asymmetric ciphers Ruby test suite. -Custom Asymmetric Vectors +Custom asymmetric vectors ~~~~~~~~~~~~~~~~~~~~~~~~~ +.. toctree:: + :maxdepth: 1 + + custom-vectors/secp256k1 + * ``asymmetric/PEM_Serialization/ec_private_key.pem`` and ``asymmetric/DER_Serialization/ec_private_key.der`` - Contains an Elliptic Curve key generated by OpenSSL from the curve ``secp256r1``. @@ -78,6 +83,7 @@ Custom Asymmetric Vectors ``asymmetric/public/PKCS1/rsa.pub.der`` are PKCS1 conversions of the public key from ``asymmetric/PKCS8/unenc-rsa-pkcs8.pem`` using PEM and DER encoding. + Key exchange ~~~~~~~~~~~~ @@ -140,14 +146,63 @@ Custom X.509 Vectors subject alternative name extension with the ``registeredID`` general name. * ``all_key_usages.pem`` - An RSA 2048 bit self-signed certificate containing a key usage extension with all nine purposes set to true. +* ``extended_key_usage.pem`` - An RSA 2048 bit self-signed certificate + containing an extended key usage extension with eight usages. * ``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 + a subject alternative name extension with an IDNA ``rfc822Name``. * ``san_uri_with_port.pem`` - An RSA 2048 bit self-signed certificate containing a subject alternative name extension with various ``uniformResourceIdentifier`` values. +* ``san_ipaddr.pem`` - An RSA 2048 bit self-signed certificate containing a + subject alternative name extension with an ``iPAddress`` value. +* ``san_dirname.pem`` - An RSA 2048 bit self-signed certificate containing a + subject alternative name extension with a ``directoryName`` value. +* ``inhibit_any_policy_5.pem`` - An RSA 2048 bit self-signed certificate + containing an inhibit any policy extension with the value 5. +* ``inhibit_any_policy_negative.pem`` - An RSA 2048 bit self-signed certificate + containing an inhibit any policy extension with the value -1. +* ``authority_key_identifier.pem`` - An RSA 2048 bit self-signed certificate + containing an authority key identifier extension with key identifier, + authority certificate issuer, and authority certificate serial number fields. +* ``authority_key_identifier_no_keyid.pem`` - An RSA 2048 bit self-signed + certificate containing an authority key identifier extension with authority + certificate issuer and authority certificate serial number fields. +* ``aia_ocsp_ca_issuers.pem`` - An RSA 2048 bit self-signed certificate + containing an authority information access extension with two OCSP and one + CA issuers entry. +* ``aia_ocsp.pem`` - An RSA 2048 bit self-signed certificate + 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -165,6 +220,19 @@ 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. 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/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 8866cf71..4da0d753 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -518,3 +518,88 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: An instance of :class:`~cryptography.x509.CertificateSigningRequest`. + + +.. class:: DHBackend + + .. versionadded:: 0.9 + + A backend with methods for doing Diffie-Hellman key exchange. + + .. method:: generate_dh_parameters(key_size) + + :param int key_size: The bit length of the prime modulus to generate. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` + provider. + + :raises ValueError: If ``key_size`` is not at least 512. + + .. method:: generate_dh_private_key(parameters) + + :param parameters: A + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` + provider. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey` + provider. + + .. method:: generate_dh_private_key_and_parameters(self, key_size) + + :param int key_size: The bit length of the prime modulus to generate. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey` + provider. + + :raises ValueError: If ``key_size`` is not at least 512. + + .. method:: load_dh_private_numbers(numbers) + + :param numbers: A + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateNumbers` + instance. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPrivateKey` + provider. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised + when any backend specific criteria are not met. + + .. method:: load_dh_public_numbers(numbers) + + :param numbers: A + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicNumbers` + instance. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicKey` + provider. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised + when any backend specific criteria are not met. + + .. method:: load_dh_parameter_numbers(numbers) + + :param numbers: A + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers` + instance. + + :return: A new instance of a + :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameters` + provider. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised + when any backend specific criteria are not met. + + .. method:: dh_parameters_supported(p, g) + + :param int p: The p value of the DH key. + + :param int g: The g value of the DH key. + + :returns: ``True`` if the given values of ``p`` and ``g`` are supported + by this backend, otherwise ``False``. 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 b7c4c6c2..81510134 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -40,6 +40,8 @@ multi naïve namespace namespaces +Nonces +online paddings pickleable plaintext diff --git a/docs/x509.rst b/docs/x509.rst index 035fa87f..5e4d9bfa 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -50,6 +50,42 @@ X.509 -----END CERTIFICATE----- """.strip() + cryptography_cert_pem = b""" + -----BEGIN CERTIFICATE----- + MIIFvTCCBKWgAwIBAgICPyAwDQYJKoZIhvcNAQELBQAwRzELMAkGA1UEBhMCVVMx + FjAUBgNVBAoTDUdlb1RydXN0IEluYy4xIDAeBgNVBAMTF1JhcGlkU1NMIFNIQTI1 + NiBDQSAtIEczMB4XDTE0MTAxNTEyMDkzMloXDTE4MTExNjAxMTUwM1owgZcxEzAR + BgNVBAsTCkdUNDg3NDI5NjUxMTAvBgNVBAsTKFNlZSB3d3cucmFwaWRzc2wuY29t + L3Jlc291cmNlcy9jcHMgKGMpMTQxLzAtBgNVBAsTJkRvbWFpbiBDb250cm9sIFZh + bGlkYXRlZCAtIFJhcGlkU1NMKFIpMRwwGgYDVQQDExN3d3cuY3J5cHRvZ3JhcGh5 + LmlvMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAom/FebKJIot7Sp3s + itG1sicpe3thCssjI+g1JDAS7I3GLVNmbms1DOdIIqwf01gZkzzXBN2+9sOnyRaR + PPfCe1jTr3dk2y6rPE559vPa1nZQkhlzlhMhlPyjaT+S7g4Tio4qV2sCBZU01DZJ + CaksfohN+5BNVWoJzTbOcrHOEJ+M8B484KlBCiSxqf9cyNQKru4W3bHaCVNVJ8eu + 6i6KyhzLa0L7yK3LXwwXVs583C0/vwFhccGWsFODqD/9xHUzsBIshE8HKjdjDi7Y + 3BFQzVUQFjBB50NSZfAA/jcdt1blxJouc7z9T8Oklh+V5DDBowgAsrT4b6Z2Fq6/ + r7D1GqivLK/ypUQmxq2WXWAUBb/Q6xHgxASxI4Br+CByIUQJsm8L2jzc7k+mF4hW + ltAIUkbo8fGiVnat0505YJgxWEDKOLc4Gda6d/7GVd5AvKrz242bUqeaWo6e4MTx + diku2Ma3rhdcr044Qvfh9hGyjqNjvhWY/I+VRWgihU7JrYvgwFdJqsQ5eiKT4OHi + gsejvWwkZzDtiQ+aQTrzM1FsY2swJBJsLSX4ofohlVRlIJCn/ME+XErj553431Lu + YQ5SzMd3nXzN78Vj6qzTfMUUY72UoT1/AcFiUMobgIqrrmwuNxfrkbVE2b6Bga74 + FsJX63prvrJ41kuHK/16RQBM7fcCAwEAAaOCAWAwggFcMB8GA1UdIwQYMBaAFMOc + 8/zTRgg0u85Gf6B8W/PiCMtZMFcGCCsGAQUFBwEBBEswSTAfBggrBgEFBQcwAYYT + aHR0cDovL2d2LnN5bWNkLmNvbTAmBggrBgEFBQcwAoYaaHR0cDovL2d2LnN5bWNi + LmNvbS9ndi5jcnQwDgYDVR0PAQH/BAQDAgWgMB0GA1UdJQQWMBQGCCsGAQUFBwMB + BggrBgEFBQcDAjAvBgNVHREEKDAmghN3d3cuY3J5cHRvZ3JhcGh5Lmlvgg9jcnlw + dG9ncmFwaHkuaW8wKwYDVR0fBCQwIjAgoB6gHIYaaHR0cDovL2d2LnN5bWNiLmNv + bS9ndi5jcmwwDAYDVR0TAQH/BAIwADBFBgNVHSAEPjA8MDoGCmCGSAGG+EUBBzYw + LDAqBggrBgEFBQcCARYeaHR0cHM6Ly93d3cucmFwaWRzc2wuY29tL2xlZ2FsMA0G + CSqGSIb3DQEBCwUAA4IBAQAzIYO2jx7h17FBT74tJ2zbV9OKqGb7QF8y3wUtP4xc + dH80vprI/Cfji8s86kr77aAvAqjDjaVjHn7UzebhSUivvRPmfzRgyWBacomnXTSt + Xlt2dp2nDQuwGyK2vB7dMfKnQAkxwq1sYUXznB8i0IhhCAoXp01QGPKq51YoIlnF + 7DRMk6iEaL1SJbkIrLsCQyZFDf0xtfW9DqXugMMLoxeCsBhZJQzNyS2ryirrv9LH + aK3+6IZjrcyy9bkpz/gzJucyhU+75c4My/mnRCrtItRbCQuiI5pd5poDowm+HH9i + GVI9+0lAFwxOUnOnwsoI40iOoxjLMGB+CgFLKCGUcWxP + -----END CERTIFICATE----- + """.strip() + X.509 is an ITU-T standard for a `public key infrastructure`_. X.509v3 is defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`). X.509 certificates are commonly used in protocols like `TLS`_. @@ -277,14 +313,28 @@ 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: ... print(ext) + <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 CSR (Certificate Signing Request) Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -328,6 +378,17 @@ 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. + + .. class:: Name .. versionadded:: 0.8 @@ -452,7 +513,12 @@ General Name Classes .. versionadded:: 0.9 This corresponds to a uniform resource identifier. For example, - ``https://cryptography.io``. + ``https://cryptography.io``. The URI is parsed and IDNA decoded (see + :rfc:`5895`). + + .. note:: + + URIs that do not contain ``://`` in them will not be decoded. .. attribute:: value @@ -466,8 +532,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 @@ -641,10 +708,10 @@ X.509 Extensions certificate. This attribute only has meaning if ``ca`` is true. If ``ca`` is true then a path length of None means there's no restriction on the number of subordinate CAs in the certificate chain. - If it is zero or greater then that number defines the maximum length. - For example, a ``path_length`` of 1 means the certificate can sign a - subordinate CA, but the subordinate CA is not allowed to create - subordinates with ``ca`` set to true. + If it is zero or greater then it defines the maximum length for a + subordinate CA's certificate chain. For example, a ``path_length`` of 1 + means the certificate can sign a subordinate CA, but the subordinate CA + is not allowed to create subordinates with ``ca`` set to true. .. class:: ExtendedKeyUsage @@ -655,6 +722,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:: 0.10 + + 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 @@ -713,6 +793,217 @@ X.509 Extensions :returns: A list of values extracted from the matched general names. + .. doctest:: + + >>> from cryptography import x509 + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> cert = x509.load_pem_x509_certificate(cryptography_cert_pem, default_backend()) + >>> # Get the subjectAltName extension from the certificate + >>> ext = cert.extensions.get_extension_for_oid(x509.OID_SUBJECT_ALTERNATIVE_NAME) + >>> # Get the dNSName entries from the SAN extension + >>> ext.value.get_values_for_type(x509.DNSName) + [u'www.cryptography.io', u'cryptography.io'] + + +.. class:: AuthorityInformationAccess + + .. versionadded:: 0.9 + + The authority information access extension indicates how to access + information and services for the issuer of the certificate in which + the extension appears. Information and services may include online + validation services (such as OCSP) and issuer data. It is an iterable, + containing one or more :class:`AccessDescription` instances. + + +.. class:: AccessDescription + + .. versionadded:: 0.9 + + .. attribute:: access_method + + :type: :class:`ObjectIdentifier` + + The access method defines what the ``access_location`` means. It must + be either :data:`OID_OCSP` or :data:`OID_CA_ISSUERS`. If it is + :data:`OID_OCSP` the access location will be where to obtain OCSP + information for the certificate. If it is :data:`OID_CA_ISSUERS` the + access location will provide additional information about the issuing + certificate. + + .. attribute:: access_location + + :type: :class:`GeneralName` + + 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:: 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 ~~~~~~~~~~~~~~~~~~ @@ -906,6 +1197,30 @@ Extended Key Usage OIDs Corresponds to the dotted string ``"1.3.6.1.5.5.7.3.9"``. This is used to denote that a certificate may be used for signing OCSP responses. +Authority Information Access OIDs +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. data:: OID_OCSP + + Corresponds to the dotted string ``"1.3.6.1.5.5.7.48.1"``. Used as the + identifier for OCSP data in :class:`AccessDescription` objects. + +.. data:: OID_CA_ISSUERS + + 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"``. + .. _extension_oids: Extension OIDs @@ -921,6 +1236,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 ~~~~~~~~~~ |