diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/keywrap.rst | 59 | ||||
| -rw-r--r-- | docs/x509/reference.rst | 121 |
4 files changed, 185 insertions, 4 deletions
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index e4df9b10..90e73711 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -147,6 +147,11 @@ Elliptic Curve Key Exchange algorithm ... ).public_key() >>> shared_key = private_key.exchange(ec.ECDH(), peer_public_key) + ECDHE (or EECDH), the ephemeral form of this exchange, is **strongly + preferred** over simple ECDH and provides `forward secrecy`_ when used. + You must generate a new private key using :func:`generate_private_key` for + each :meth:`~EllipticCurvePrivateKey.exchange` when performing an ECDHE key + exchange. Elliptic Curves --------------- @@ -342,6 +347,8 @@ Key Interfaces .. method:: exchange(algorithm, peer_public_key) + .. versionadded:: 1.1 + Perform's a key exchange operation using the provided algorithm with the peer's public key. @@ -470,3 +477,4 @@ Key Interfaces .. _`SafeCurves`: http://safecurves.cr.yp.to/ .. _`ECDSA`: https://en.wikipedia.org/wiki/ECDSA .. _`EdDSA`: https://en.wikipedia.org/wiki/EdDSA +.. _`forward secrecy`: https://en.wikipedia.org/wiki/Forward_secrecy diff --git a/docs/hazmat/primitives/index.rst b/docs/hazmat/primitives/index.rst index a9ab38a0..cf27622a 100644 --- a/docs/hazmat/primitives/index.rst +++ b/docs/hazmat/primitives/index.rst @@ -11,6 +11,7 @@ Primitives symmetric-encryption padding key-derivation-functions + keywrap asymmetric/index constant-time interfaces diff --git a/docs/hazmat/primitives/keywrap.rst b/docs/hazmat/primitives/keywrap.rst new file mode 100644 index 00000000..e4f9ffeb --- /dev/null +++ b/docs/hazmat/primitives/keywrap.rst @@ -0,0 +1,59 @@ +.. hazmat:: + +.. module:: cryptography.hazmat.primitives.keywrap + +Key wrapping +============ + +Key wrapping is a cryptographic construct that uses symmetric encryption to +encapsulate key material. Key wrapping algorithms are occasionally utilized +to protect keys at rest or transmit them over insecure networks. Many of the +protections offered by key wrapping are also offered by using authenticated +:doc:`symmetric encryption </hazmat/primitives/symmetric-encryption>`. + +.. function:: aes_key_wrap(wrapping_key, key_to_wrap, backend) + + .. versionadded:: 1.1 + + This function performs AES key wrap (without padding) as specified in + :rfc:`3394`. + + :param bytes wrapping_key: The wrapping key. + + :param bytes key_to_wrap: The key to wrap. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + provider that supports + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`. + + :return bytes: The wrapped key as bytes. + +.. function:: aes_key_unwrap(wrapping_key, wrapped_key, backend) + + .. versionadded:: 1.1 + + This function performs AES key unwrap (without padding) as specified in + :rfc:`3394`. + + :param bytes wrapping_key: The wrapping key. + + :param bytes wrapped_key: The wrapped key. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + provider that supports + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`. + + :return bytes: The unwrapped key as bytes. + + :raises cryptography.hazmat.primitives.keywrap.InvalidUnwrap: This is + raised if the key is not successfully unwrapped. + +Exceptions +~~~~~~~~~~ + +.. class:: InvalidUnwrap + + This is raised when a wrapped key fails to unwrap. It can be caused by a + corrupted or invalid wrapped key or an invalid wrapping key. diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 97224c9f..e7e02de3 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -5,6 +5,21 @@ X.509 Reference .. testsetup:: + pem_crl_data = b""" + -----BEGIN X509 CRL----- + MIIBtDCBnQIBAjANBgkqhkiG9w0BAQsFADAnMQswCQYDVQQGEwJVUzEYMBYGA1UE + AwwPY3J5cHRvZ3JhcGh5LmlvGA8yMDE1MDEwMTAwMDAwMFoYDzIwMTYwMTAxMDAw + MDAwWjA+MDwCAQAYDzIwMTUwMTAxMDAwMDAwWjAmMBgGA1UdGAQRGA8yMDE1MDEw + MTAwMDAwMFowCgYDVR0VBAMKAQEwDQYJKoZIhvcNAQELBQADggEBABRA4ww50Lz5 + zk1j2+aluC4HPHqb7o06h4pTDcCGeXUKXIGeP5ntGGmIoxa26sNoLeOr8+5b43Gf + yWraHertllOwaOpNFEe+YZFaE9femtoDbf+GLMvRx/0wDfd3KxPoXnXKMXb2d1w4 + RCLgmkYx6JyvS+5ciuLQVIKC+l7jwIUeZFLJMUJ8msM4pFYoGameeZmtjMbd/TNg + cVBfmZxNMHuLladJxvSo2esARo0TYPhYsgrREKoHwhpzSxdynjn4bOVkILfguwsN + qtEEMZFEv5Kb0GqRp2+Iagv2S6dg9JGvxVdsoGjaB6EbYSZ3Psx4aODasIn11uwo + X4B9vUQNXqc= + -----END X509 CRL----- + """.strip() + pem_req_data = b""" -----BEGIN CERTIFICATE REQUEST----- MIIC0zCCAbsCAQAwWTELMAkGA1UEBhMCVVMxETAPBgNVBAgMCElsbGlub2lzMRAw @@ -129,6 +144,51 @@ Loading Certificates >>> cert.serial 2 +Loading Certificate Revocation Lists +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. function:: load_pem_x509_crl(data, backend) + + .. versionadded:: 1.1 + + Deserialize a certificate revocation list (CRL) from PEM encoded data. PEM + requests are base64 decoded and have delimiters that look like + ``-----BEGIN X509 CRL-----``. + + :param bytes data: The PEM encoded request data. + + :param backend: A backend supporting the + :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + interface. + + :returns: An instance of + :class:`~cryptography.x509.CertificateRevocationList`. + +.. function:: load_der_x509_crl(data, backend) + + .. versionadded:: 1.1 + + Deserialize a certificate revocation list (CRL) from DER encoded data. DER + is a binary format. + + :param bytes data: The DER encoded request data. + + :param backend: A backend supporting the + :class:`~cryptography.hazmat.backends.interfaces.X509Backend` + interface. + + :returns: An instance of + :class:`~cryptography.x509.CertificateRevocationList`. + +.. doctest:: + + >>> from cryptography import x509 + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> crl = x509.load_pem_x509_crl(pem_crl_data, default_backend()) + >>> isinstance(crl.signature_hash_algorithm, hashes.SHA256) + True + Loading Certificate Signing Requests ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -340,6 +400,21 @@ X.509 CRL (Certificate Revocation List) Object .. versionadded:: 1.0 + A CertificateRevocationList is an object representing a list of revoked + certificates. The object is iterable and will yield the RevokedCertificate + objects stored in this CRL. + + .. doctest:: + + >>> len(crl) + 1 + >>> revoked_certificate = crl[0] + >>> type(revoked_certificate) + <class 'cryptography.hazmat.backends.openssl.x509._RevokedCertificate'> + >>> for r in crl: + ... print(r.serial_number) + 0 + .. method:: fingerprint(algorithm) :param algorithm: The @@ -349,6 +424,12 @@ X.509 CRL (Certificate Revocation List) Object :return bytes: The fingerprint using the supplied hash algorithm, as bytes. + .. doctest:: + + >>> from cryptography.hazmat.primitives import hashes + >>> crl.fingerprint(hashes.SHA256()) + 'e\xcf.\xc4:\x83?1\xdc\xf3\xfc\x95\xd7\xb3\x87\xb3\x8e\xf8\xb93!\x87\x07\x9d\x1b\xb4!\xb9\xe4W\xf4\x1f' + .. attribute:: signature_hash_algorithm :type: :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` @@ -357,12 +438,23 @@ X.509 CRL (Certificate Revocation List) Object :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` which was used in signing this CRL. + .. doctest:: + + >>> from cryptography.hazmat.primitives import hashes + >>> isinstance(crl.signature_hash_algorithm, hashes.SHA256) + True + .. attribute:: issuer :type: :class:`Name` The :class:`Name` of the issuer. + .. doctest:: + + >>> crl.issuer + <Name([<NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.6, name=countryName)>, value=u'US')>, <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=u'cryptography.io')>])> + .. attribute:: next_update :type: :class:`datetime.datetime` @@ -370,17 +462,21 @@ X.509 CRL (Certificate Revocation List) Object A naïve datetime representing when the next update to this CRL is expected. + .. doctest:: + + >>> crl.next_update + datetime.datetime(2016, 1, 1, 0, 0) + .. 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` + .. doctest:: - The revoked certificates listed in this CRL. + >>> crl.last_update + datetime.datetime(2015, 1, 1, 0, 0) .. attribute:: extensions @@ -611,18 +707,35 @@ X.509 Revoked Certificate Object An integer representing the serial number of the revoked certificate. + .. doctest:: + + >>> revoked_certificate.serial_number + 0 + .. attribute:: revocation_date :type: :class:`datetime.datetime` A naïve datetime representing the date this certificates was revoked. + .. doctest:: + + >>> revoked_certificate.revocation_date + datetime.datetime(2015, 1, 1, 0, 0) + .. attribute:: extensions :type: :class:`Extensions` The extensions encoded in the revoked certificate. + .. doctest:: + + >>> for ext in revoked_certificate.extensions: + ... print(ext) + <Extension(oid=<ObjectIdentifier(oid=2.5.29.24, name=invalidityDate)>, critical=False, value=2015-01-01 00:00:00)> + <Extension(oid=<ObjectIdentifier(oid=2.5.29.21, name=cRLReason)>, critical=False, value=ReasonFlags.key_compromise)> + X.509 CSR (Certificate Signing Request) Builder Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |