From 016e08abddf9fdc507da4f6c6f548c3dfee1b389 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 26 Nov 2014 09:41:18 -1000 Subject: move x509 to top level, add more docs --- docs/x509.rst | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 docs/x509.rst (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst new file mode 100644 index 00000000..5d18297a --- /dev/null +++ b/docs/x509.rst @@ -0,0 +1,97 @@ +.. hazmat:: + +X.509 +===== + +.. currentmodule:: cryptography.hazmat.primitives.x509 + +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`). + +Loading +~~~~~~~ + +.. function:: load_pem_x509_certificate(data, backend) + + .. versionadded:: 0.7 + + Deserialize a certificate from PEM encoded data. + + :param bytes data: The PEM encoded certificate data. + + :param backend: A backend supporting the + :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + interface. + + :returns: An instance of + :class:`~cryptography.hazmat.primitives.interfaces.X509Certificate`. + +.. function:: load_der_x509_certificate(data, backend) + + .. versionadded:: 0.7 + + Deserialize a certificate from DER encoded data. + + :param bytes data: The DER encoded certificate data. + + :param backend: A backend supporting the + :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + interface. + + :returns: An instance of + :class:`~cryptography.hazmat.primitives.interfaces.X509Certificate`. + +.. testsetup:: + + pem_data = b""" + -----BEGIN CERTIFICATE----- + MIIDfDCCAmSgAwIBAgIBAjANBgkqhkiG9w0BAQsFADBFMQswCQYDVQQGEwJVUzEf + MB0GA1UEChMWVGVzdCBDZXJ0aWZpY2F0ZXMgMjAxMTEVMBMGA1UEAxMMVHJ1c3Qg + QW5jaG9yMB4XDTEwMDEwMTA4MzAwMFoXDTMwMTIzMTA4MzAwMFowQDELMAkGA1UE + BhMCVVMxHzAdBgNVBAoTFlRlc3QgQ2VydGlmaWNhdGVzIDIwMTExEDAOBgNVBAMT + B0dvb2QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCQWJpHYo37 + Xfb7oJSPe+WvfTlzIG21WQ7MyMbGtK/m8mejCzR6c+f/pJhEH/OcDSMsXq8h5kXa + BGqWK+vSwD/Pzp5OYGptXmGPcthDtAwlrafkGOS4GqIJ8+k9XGKs+vQUXJKsOk47 + RuzD6PZupq4s16xaLVqYbUC26UcY08GpnoLNHJZS/EmXw1ZZ3d4YZjNlpIpWFNHn + UGmdiGKXUPX/9H0fVjIAaQwjnGAbpgyCumWgzIwPpX+ElFOUr3z7BoVnFKhIXze+ + VmQGSWxZxvWDUN90Ul0tLEpLgk3OVxUB4VUGuf15OJOpgo1xibINPmWt14Vda2N9 + yrNKloJGZNqLAgMBAAGjfDB6MB8GA1UdIwQYMBaAFOR9X9FclYYILAWuvnW2ZafZ + XahmMB0GA1UdDgQWBBRYAYQkG7wrUpRKPaUQchRR9a86yTAOBgNVHQ8BAf8EBAMC + AQYwFwYDVR0gBBAwDjAMBgpghkgBZQMCATABMA8GA1UdEwEB/wQFMAMBAf8wDQYJ + KoZIhvcNAQELBQADggEBADWHlxbmdTXNwBL/llwhQqwnazK7CC2WsXBBqgNPWj7m + tvQ+aLG8/50Qc2Sun7o2VnwF9D18UUe8Gj3uPUYH+oSI1vDdyKcjmMbKRU4rk0eo + 3UHNDXwqIVc9CQS9smyV+x1HCwL4TTrq+LXLKx/qVij0Yqk+UJfAtrg2jnYKXsCu + FMBQQnWCGrwa1g1TphRp/RmYHnMynYFmZrXtzFz+U9XEA7C+gPq4kqDI/iVfIT1s + 6lBtdB50lrDVwl2oYfAvW/6sC2se2QleZidUmrziVNP4oEeXINokU6T6p//HM1FG + QYw2jOvpKcKtWCSAnegEbgsGYzATKjmPJPJ0npHFqzM= + -----END CERTIFICATE----- + """.strip() + +.. doctest:: + + >>> from cryptography.x509 import load_pem_x509_certificate + >>> from cryptography.hazmat.backends import default_backend + >>> cert = load_pem_x509_certificate(pem_data, default_backend()) + >>> cert.serial + 2 + +Support Classes +~~~~~~~~~~~~~~~ + +.. class:: X509Version + + .. versionadded:: 0.7 + + An enumeration for X.509 versions. + + .. attribute:: v1 + + For version 1 X.509 certificates. + + .. attribute:: v3 + + For version 3 X.509 certificates. + + + +.. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure -- cgit v1.2.3 From a9d78c13ea2996c896d3dfda8b7e887c444ec4cb Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 26 Nov 2014 10:59:03 -1000 Subject: update docs, test invalid x509 version --- docs/x509.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index 5d18297a..2c9c0f46 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -3,7 +3,7 @@ X.509 ===== -.. currentmodule:: cryptography.hazmat.primitives.x509 +.. currentmodule:: cryptography.x509 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`). -- cgit v1.2.3 From a68fd33ca8518a734b655457eca9ab28ccbcb7bb Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 27 Nov 2014 07:08:40 -1000 Subject: address review feedback --- docs/x509.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index 2c9c0f46..ba52d91a 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -6,7 +6,8 @@ X.509 .. currentmodule:: cryptography.x509 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`). +defined in :rfc:`5280` (which obsoletes :rfc:`2459` and :rfc:`3280`). X.509 +certificates are commonly used in protocols like `TLS`_. Loading ~~~~~~~ @@ -92,6 +93,10 @@ Support Classes For version 3 X.509 certificates. +.. class:: InvalidX509Version + + This is raised when an X.509 certificate has an invalid version number. .. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure +.. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security -- cgit v1.2.3 From b2de948b18316ac5f08b22d1ab22bdd49da9cc5f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Thu, 11 Dec 2014 14:54:48 -0600 Subject: reorganize a bunch of things related to the x509certificate interface --- docs/x509.rst | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 57 insertions(+), 6 deletions(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index ba52d91a..ba84f6e7 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -9,8 +9,9 @@ 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`_. -Loading -~~~~~~~ + +Loading Certificates +~~~~~~~~~~~~~~~~~~~~ .. function:: load_pem_x509_certificate(data, backend) @@ -24,8 +25,7 @@ Loading :class:`~cryptography.hazmat.backends.interfaces.X509Backend` interface. - :returns: An instance of - :class:`~cryptography.hazmat.primitives.interfaces.X509Certificate`. + :returns: An instance of :class:`~cryptography.x509.X509Certificate`. .. function:: load_der_x509_certificate(data, backend) @@ -39,8 +39,7 @@ Loading :class:`~cryptography.hazmat.backends.interfaces.X509Backend` interface. - :returns: An instance of - :class:`~cryptography.hazmat.primitives.interfaces.X509Certificate`. + :returns: An instance of :class:`~cryptography.x509.X509Certificate`. .. testsetup:: @@ -76,6 +75,58 @@ Loading >>> cert.serial 2 +Interface +~~~~~~~~~ + +.. class:: X509Certificate + + .. versionadded:: 0.7 + + .. attribute:: version + + :type: :class:`~cryptography.x509.X509Version` + + The certificate version as an enumeration. + + .. method:: fingerprint(algorithm) + + :param algorithm: The + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + that will be used to generate the fingerprint. + + :return bytes: The fingerprint using the supplied hash algorithm as + bytes. + + .. attribute:: serial + + :type: int + + The serial as a Python integer. + + .. method:: public_key() + + :type: + :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` or + :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` or + :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurvePublicKey` + + The public key associated with the certificate. + + .. attribute:: not_valid_before + + :type: :class:`datetime.datetime` + + A naïve datetime representing the beginning of the validity period for the + certificate in UTC. This value is inclusive. + + .. attribute:: not_valid_after + + :type: :class:`datetime.datetime` + + A naïve datetime representing the end of the validity period for the + certificate in UTC. This value is inclusive. + + Support Classes ~~~~~~~~~~~~~~~ -- cgit v1.2.3 From e76cd27c28f75f3972ddcf5e15d5e37e6da2098e Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sun, 14 Dec 2014 19:00:51 -0600 Subject: rename X509 classes to remove X509 and improve some tests --- docs/x509.rst | 30 ++++++++++++++++-------------- 1 file changed, 16 insertions(+), 14 deletions(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index ba84f6e7..c682e5e8 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -17,7 +17,9 @@ Loading Certificates .. versionadded:: 0.7 - Deserialize a certificate from PEM encoded data. + Deserialize a certificate from PEM encoded data. PEM certificates are + base64 decoded and have delimiters that look like + ``-----BEGIN CERTIFICATE-----``. :param bytes data: The PEM encoded certificate data. @@ -25,13 +27,15 @@ Loading Certificates :class:`~cryptography.hazmat.backends.interfaces.X509Backend` interface. - :returns: An instance of :class:`~cryptography.x509.X509Certificate`. + :returns: An instance of :class:`~cryptography.x509.Certificate`. .. function:: load_der_x509_certificate(data, backend) .. versionadded:: 0.7 - Deserialize a certificate from DER encoded data. + Deserialize a certificate from DER encoded data. DER is a binary format + and is commonly found in files with the ``cer`` suffix (although file + suffixes are not a guarantee of encoding type). :param bytes data: The DER encoded certificate data. @@ -39,7 +43,7 @@ Loading Certificates :class:`~cryptography.hazmat.backends.interfaces.X509Backend` interface. - :returns: An instance of :class:`~cryptography.x509.X509Certificate`. + :returns: An instance of :class:`~cryptography.x509.Certificate`. .. testsetup:: @@ -75,18 +79,19 @@ Loading Certificates >>> cert.serial 2 -Interface -~~~~~~~~~ +X.509 Certificate Object +~~~~~~~~~~~~~~~~~~~~~~~~ -.. class:: X509Certificate +.. class:: Certificate .. versionadded:: 0.7 .. attribute:: version - :type: :class:`~cryptography.x509.X509Version` + :type: :class:`~cryptography.x509.Version` - The certificate version as an enumeration. + The certificate version as an enumeration. Version 3 certificates are + the latest version and also the only type you should see in practice. .. method:: fingerprint(algorithm) @@ -127,10 +132,7 @@ Interface certificate in UTC. This value is inclusive. -Support Classes -~~~~~~~~~~~~~~~ - -.. class:: X509Version +.. class:: Version .. versionadded:: 0.7 @@ -144,7 +146,7 @@ Support Classes For version 3 X.509 certificates. -.. class:: InvalidX509Version +.. class:: InvalidVersion This is raised when an X.509 certificate has an invalid version number. -- cgit v1.2.3 From 92aac3891715aea562ffb51985bd142cbabb64ce Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 15 Dec 2014 16:25:28 -0600 Subject: improve the docs a bit more --- docs/x509.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index c682e5e8..5278d07b 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -34,8 +34,8 @@ Loading Certificates .. versionadded:: 0.7 Deserialize a certificate from DER encoded data. DER is a binary format - and is commonly found in files with the ``cer`` suffix (although file - suffixes are not a guarantee of encoding type). + and is commonly found in files with the ``.cer`` extension (although file + extensions are not a guarantee of encoding type). :param bytes data: The DER encoded certificate data. @@ -93,6 +93,9 @@ X.509 Certificate Object The certificate version as an enumeration. Version 3 certificates are the latest version and also the only type you should see in practice. + :raises cryptography.x509.InvalidVersion: If the version is + not valid. + .. method:: fingerprint(algorithm) :param algorithm: The -- cgit v1.2.3 From d5cccf7a376f4cf81cab6649646af0f09f5389ac Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 15 Dec 2014 17:20:33 -0600 Subject: add parsed_version attribute to InvalidVersion --- docs/x509.rst | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index 5278d07b..e44f16c1 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -153,6 +153,10 @@ X.509 Certificate Object This is raised when an X.509 certificate has an invalid version number. + .. attribute:: parsed_version + + Returns the version that was parsed from the certificate. + .. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure .. _`TLS`: https://en.wikipedia.org/wiki/Transport_Layer_Security -- cgit v1.2.3 From cc8a26e32bd0dfc0624a6e33edba2172371f1686 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 16 Dec 2014 12:40:16 -0600 Subject: add examples for accessing each attr --- docs/x509.rst | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index e44f16c1..1e86df21 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -73,9 +73,9 @@ Loading Certificates .. doctest:: - >>> from cryptography.x509 import load_pem_x509_certificate + >>> from cryptography import x509 >>> from cryptography.hazmat.backends import default_backend - >>> cert = load_pem_x509_certificate(pem_data, default_backend()) + >>> cert = x509.load_pem_x509_certificate(pem_data, default_backend()) >>> cert.serial 2 @@ -96,6 +96,11 @@ X.509 Certificate Object :raises cryptography.x509.InvalidVersion: If the version is not valid. + .. doctest:: + + >>> cert.version + + .. method:: fingerprint(algorithm) :param algorithm: The @@ -105,12 +110,23 @@ X.509 Certificate Object :return bytes: The fingerprint using the supplied hash algorithm as bytes. + .. doctest:: + + >>> from cryptography.hazmat.primitives import hashes + >>> cert.fingerprint(hashes.SHA256()) + '...' + .. attribute:: serial :type: int The serial as a Python integer. + .. doctest:: + + >>> cert.serial + 2 + .. method:: public_key() :type: @@ -120,6 +136,13 @@ X.509 Certificate Object The public key associated with the certificate. + .. doctest:: + + >>> from cryptography.hazmat.primitives import interfaces + >>> public_key = cert.public_key() + >>> isinstance(public_key, interfaces.RSAPublicKey) + True + .. attribute:: not_valid_before :type: :class:`datetime.datetime` @@ -127,6 +150,11 @@ X.509 Certificate Object A naïve datetime representing the beginning of the validity period for the certificate in UTC. This value is inclusive. + .. doctest:: + + >>> cert.not_valid_before + datetime.datetime(2010, 1, 1, 8, 30) + .. attribute:: not_valid_after :type: :class:`datetime.datetime` @@ -134,6 +162,11 @@ X.509 Certificate Object A naïve datetime representing the end of the validity period for the certificate in UTC. This value is inclusive. + .. doctest:: + + >>> cert.not_valid_after + datetime.datetime(2030, 12, 31, 8, 30) + .. class:: Version -- cgit v1.2.3 From 78a815099106a372db5eb0a49fe5c91767a7438b Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 16 Dec 2014 14:47:52 -0600 Subject: fix some docs --- docs/x509.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index 1e86df21..50790b94 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -114,7 +114,7 @@ X.509 Certificate Object >>> from cryptography.hazmat.primitives import hashes >>> cert.fingerprint(hashes.SHA256()) - '...' + '\x86\xd2\x187Gc\xfc\xe7}[+E9\x8d\xb4\x8f\x10\xe5S\xda\x18u\xbe}a\x03\x08[\xac\xa04?' .. attribute:: serial @@ -147,8 +147,8 @@ X.509 Certificate Object :type: :class:`datetime.datetime` - A naïve datetime representing the beginning of the validity period for the - certificate in UTC. This value is inclusive. + A naïve datetime representing the beginning of the validity period for + the certificate in UTC. This value is inclusive. .. doctest:: @@ -159,8 +159,8 @@ X.509 Certificate Object :type: :class:`datetime.datetime` - A naïve datetime representing the end of the validity period for the - certificate in UTC. This value is inclusive. + A naïve datetime representing the end of the validity period for the + certificate in UTC. This value is inclusive. .. doctest:: -- cgit v1.2.3 From 89c4dc87ecff2d562411bc6aeea8f6130ecc5dbc Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 16 Dec 2014 16:49:33 -0800 Subject: Slightly more descriptive docs --- docs/x509.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index 50790b94..60a375b5 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -93,8 +93,8 @@ X.509 Certificate Object The certificate version as an enumeration. Version 3 certificates are the latest version and also the only type you should see in practice. - :raises cryptography.x509.InvalidVersion: If the version is - not valid. + :raises cryptography.x509.InvalidVersion: If the version in the + certificate is not a known :class:`X.509 version .. doctest:: -- cgit v1.2.3 From 6d7ab4cad8c97a3a0d7b46d524e0faf39e5b6e62 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 16 Dec 2014 16:50:33 -0800 Subject: Markup fix. --- docs/x509.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index 60a375b5..e4b5e176 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -94,7 +94,8 @@ X.509 Certificate Object the latest version and also the only type you should see in practice. :raises cryptography.x509.InvalidVersion: If the version in the - certificate is not a known :class:`X.509 version + certificate is not a known + :class:`X.509 version `. .. doctest:: -- cgit v1.2.3 From bbffc4067c1278a5d96f73bb89255becd43da29e Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Wed, 17 Dec 2014 13:33:55 -0600 Subject: doc update for x509 --- docs/x509.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs/x509.rst') diff --git a/docs/x509.rst b/docs/x509.rst index e4b5e176..18894ce5 100644 --- a/docs/x509.rst +++ b/docs/x509.rst @@ -189,7 +189,9 @@ X.509 Certificate Object .. attribute:: parsed_version - Returns the version that was parsed from the certificate. + :type: int + + Returns the raw version that was parsed from the certificate. .. _`public key infrastructure`: https://en.wikipedia.org/wiki/Public_key_infrastructure -- cgit v1.2.3