diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dh.rst | 64 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 44 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 69 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 1 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 130 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/serialization.rst | 105 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 5 | ||||
| -rw-r--r-- | docs/hazmat/primitives/twofactor.rst | 4 |
8 files changed, 416 insertions, 6 deletions
diff --git a/docs/hazmat/primitives/asymmetric/dh.rst b/docs/hazmat/primitives/asymmetric/dh.rst new file mode 100644 index 00000000..fdf113f7 --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/dh.rst @@ -0,0 +1,64 @@ +.. hazmat:: + +Diffie-Hellman key exchange +=========================== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.dh + + +.. class:: DHPrivateNumbers(x, public_numbers) + + .. versionadded:: 0.8 + + The collection of integers that make up a Diffie-Hellman private key. + + .. attribute:: public_numbers + + :type: :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHPublicNumbers` + + The :class:`DHPublicNumbers` which makes up the DH public + key associated with this DH private key. + + .. attribute:: x + + :type: int + + The private value. + + +.. class:: DHPublicNumbers(parameters, y) + + .. versionadded:: 0.8 + + The collection of integers that make up a Diffie-Hellman public key. + + .. attribute:: parameter_numbers + + :type: :class:`~cryptography.hazmat.primitives.asymmetric.dh.DHParameterNumbers` + + The parameters for this DH group. + + .. attribute:: y + + :type: int + + The public value. + + +.. class:: DHParameterNumbers(p, g) + + .. versionadded:: 0.8 + + The collection of integers that define a Diffie-Hellman group. + + .. attribute:: p + + :type: int + + The prime modulus value. + + .. attribute:: g + + :type: int + + The generator value. diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 3a47da45..bd02423f 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -301,6 +301,50 @@ Key interfaces instance. +.. class:: DSAPrivateKeyWithSerialization + + .. versionadded:: 0.8 + + Extends :class:`DSAPrivateKey`. + + .. method:: private_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers` + object. + + :returns: A + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers` + instance. + + .. method:: private_bytes(encoding, format, encryption_algorithm) + + Allows serialization of the key to bytes. Encoding ( + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`), + format ( + :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL` + or + :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`) + and encryption algorithm (such as + :class:`~cryptography.hazmat.primitives.serialization.BestAvailableEncryption` + or :class:`~cryptography.hazmat.primitives.serialization.NoEncryption`) + are chosen to define the exact serialization. + + :param encoding: A value from the + :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum. + + :param format: A value from the + :class:`~cryptography.hazmat.primitives.serialization.PrivateFormat` + enum. + + :param encryption_algorithm: An instance of an object conforming to the + :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption` + interface. + + :return bytes: Serialized key. + + .. class:: DSAPublicKey .. versionadded:: 0.3 diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 8b9a584b..6c03d773 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -326,6 +326,45 @@ Key Interfaces :returns: An :class:`EllipticCurvePrivateNumbers` instance. +.. class:: EllipticCurvePrivateKeyWithSerialization + + .. versionadded:: 0.8 + + Extends :class:`EllipticCurvePrivateKey`. + + .. method:: private_numbers() + + Create a :class:`EllipticCurvePrivateNumbers` object. + + :returns: An :class:`EllipticCurvePrivateNumbers` instance. + + .. method:: private_bytes(encoding, format, encryption_algorithm) + + Allows serialization of the key to bytes. Encoding ( + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`), + format ( + :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL` + or + :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`) + and encryption algorithm (such as + :class:`~cryptography.hazmat.primitives.serialization.BestAvailableEncryption` + or :class:`~cryptography.hazmat.primitives.serialization.NoEncryption`) + are chosen to define the exact serialization. + + :param encoding: A value from the + :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum. + + :param format: A value from the + :class:`~cryptography.hazmat.primitives.serialization.PrivateFormat` enum. + + :param encryption_algorithm: An instance of an object conforming to the + :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption` + interface. + + :return bytes: Serialized key. + + .. class:: EllipticCurvePublicKey .. versionadded:: 0.5 @@ -366,6 +405,36 @@ Key Interfaces :returns: An :class:`EllipticCurvePublicNumbers` instance. +.. class:: EllipticCurvePublicKeyWithSerialization + + .. versionadded:: 0.6 + + Extends :class:`EllipticCurvePublicKey`. + + .. method:: public_numbers() + + Create a :class:`EllipticCurvePublicNumbers` object. + + :returns: An :class:`EllipticCurvePublicNumbers` instance. + + .. method:: public_bytes(encoding, format) + + Allows serialization of the key to bytes. Encoding ( + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`) and + format ( + :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo`) + are chosen to define the exact serialization. + + :param encoding: A value from the + :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum. + + :param format: A value from the + :class:`~cryptography.hazmat.primitives.serialization.PublicFormat` enum. + + :return bytes: Serialized key. + + .. _`FIPS 186-3`: http://csrc.nist.gov/publications/fips/fips186-3/fips_186-3.pdf .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf .. _`some concern`: https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 59f00c5d..4242a0bd 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -29,6 +29,7 @@ and Elliptic Curve. dsa ec rsa + dh serialization interfaces utils diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index fd97d75b..e7033100 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -80,6 +80,56 @@ password. If the key is encrypted we can pass a ``bytes`` object as the There is also support for :func:`loading public keys in the SSH format <cryptography.hazmat.primitives.serialization.load_ssh_public_key>`. +Key serialization +~~~~~~~~~~~~~~~~~ + +If you have a private key that you've loaded or generated which implements the +:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization` +interface you can use +:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes` +to serialize the key. + +.. doctest:: + + >>> from cryptography.hazmat.primitives import serialization + >>> pem = private_key.private_bytes( + ... encoding=serialization.Encoding.PEM, + ... format=serialization.PrivateFormat.PKCS8, + ... encryption_algorithm=serialization.BestAvailableEncryption(b'mypassword') + ... ) + >>> pem.splitlines()[0] + '-----BEGIN ENCRYPTED PRIVATE KEY-----' + +It is also possible to serialize without encryption using +:class:`~cryptography.hazmat.primitives.serialization.NoEncryption`. + +.. doctest:: + + >>> pem = private_key.private_bytes( + ... encoding=serialization.Encoding.PEM, + ... format=serialization.PrivateFormat.TraditionalOpenSSL, + ... encryption_algorithm=serialization.NoEncryption() + ... ) + >>> pem.splitlines()[0] + '-----BEGIN RSA PRIVATE KEY-----' + +Similarly, if your public key implements +:class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization` +interface you can use +:meth:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization.public_bytes` +to serialize the key. + +.. doctest:: + + >>> from cryptography.hazmat.primitives import serialization + >>> public_key = private_key.public_key() + >>> pem = public_key.public_bytes( + ... encoding=serialization.Encoding.PEM, + ... format=serialization.PublicFormat.SubjectPublicKeyInfo + ... ) + >>> pem.splitlines()[0] + '-----BEGIN PUBLIC KEY-----' + Signing ~~~~~~~ @@ -485,6 +535,50 @@ Key interfaces instance. +.. class:: RSAPrivateKeyWithSerialization + + .. versionadded:: 0.8 + + Extends :class:`RSAPrivateKey`. + + .. method:: private_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers` + object. + + :returns: An + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateNumbers` + instance. + + .. method:: private_bytes(encoding, format, encryption_algorithm) + + Allows serialization of the key to bytes. Encoding ( + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`), + format ( + :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.TraditionalOpenSSL` + or + :attr:`~cryptography.hazmat.primitives.serialization.PrivateFormat.PKCS8`) + and encryption algorithm (such as + :class:`~cryptography.hazmat.primitives.serialization.BestAvailableEncryption` + or :class:`~cryptography.hazmat.primitives.serialization.NoEncryption`) + are chosen to define the exact serialization. + + :param encoding: A value from the + :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum. + + :param format: A value from the + :class:`~cryptography.hazmat.primitives.serialization.PrivateFormat` + enum. + + :param encryption_algorithm: An instance of an object conforming to the + :class:`~cryptography.hazmat.primitives.serialization.KeySerializationEncryption` + interface. + + :return bytes: Serialized key. + + .. class:: RSAPublicKey .. versionadded:: 0.2 @@ -549,6 +643,42 @@ Key interfaces instance. +.. class:: RSAPublicKeyWithSerialization + + .. versionadded:: 0.8 + + Extends :class:`RSAPublicKey`. + + .. method:: public_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers` + object. + + :returns: An + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicNumbers` + instance. + + .. method:: public_bytes(encoding, format) + + Allows serialization of the key to bytes. Encoding ( + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.PEM` or + :attr:`~cryptography.hazmat.primitives.serialization.Encoding.DER`) and + format ( + :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.SubjectPublicKeyInfo` + or + :attr:`~cryptography.hazmat.primitives.serialization.PublicFormat.PKCS1`) + are chosen to define the exact serialization. + + :param encoding: A value from the + :class:`~cryptography.hazmat.primitives.serialization.Encoding` enum. + + :param format: A value from the + :class:`~cryptography.hazmat.primitives.serialization.PublicFormat` enum. + + :return bytes: Serialized key. + + .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography .. _`specific mathematical properties`: https://en.wikipedia.org/wiki/RSA_(cryptosystem)#Key_generation diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst index 87f3c0b0..ff69973a 100644 --- a/docs/hazmat/primitives/asymmetric/serialization.rst +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -3,7 +3,7 @@ Key Serialization ================= -.. currentmodule:: cryptography.hazmat.primitives.serialization +.. module:: cryptography.hazmat.primitives.serialization .. testsetup:: @@ -282,3 +282,106 @@ DSA keys look almost identical but begin with ``ssh-dss`` rather than :raises cryptography.exceptions.UnsupportedAlgorithm: If the serialized key is of a type that is not supported. + +Serialization Formats +~~~~~~~~~~~~~~~~~~~~~ + +.. class:: PrivateFormat + + .. versionadded:: 0.8 + + An enumeration for private key formats. Used with the ``private_bytes`` + method available on + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization` + , + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization` + and + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKeyWithSerialization`. + + .. attribute:: TraditionalOpenSSL + + Frequently known as PKCS#1 format. Still a widely used format, but + generally considered legacy. + + .. attribute:: PKCS8 + + A more modern format for serializing keys which allows for better + encryption. Choose this unless you have explicit legacy compatibility + requirements. + +.. class:: PublicFormat + + .. versionadded:: 0.8 + + An enumeration for public key formats. Used with the ``public_bytes`` + method available on + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization` + and + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKeyWithSerialization`. + + .. attribute:: SubjectPublicKeyInfo + + This is the typical public key format. It consists of an algorithm + identifier and the public key as a bit string. Choose this unless + you have specific needs. + + .. attribute:: PKCS1 + + Just the public key elements (without the algorithm identifier). This + format is RSA only, but is used by some older systems. + +Serialization Encodings +~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: Encoding + + .. versionadded:: 0.8 + + An enumeration for encoding types. Used with the ``private_bytes`` method + available on + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization` + , + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization` + and + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKeyWithSerialization` + as well as ``public_bytes`` on + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPublicKeyWithSerialization` + and + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePublicKeyWithSerialization`. + + .. attribute:: PEM + + For PEM format. This is a base64 format with delimiters. + + .. attribute:: DER + + For DER format. This is a binary format. + + +Serialization Encryption Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: KeySerializationEncryption + + Objects with this interface are usable as encryption types with methods + like ``private_bytes`` available on + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization` + , + :class:`~cryptography.hazmat.primitives.asymmetric.ec.EllipticCurvePrivateKeyWithSerialization` + and + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateKeyWithSerialization`. + All other classes in this section represent the available choices for + encryption and have this interface. They are used with + :class:`~cryptography.hazmat.primitives.asymmetric.rsa.RSAPrivateKeyWithSerialization.private_bytes`. + +.. class:: BestAvailableEncryption(password) + + Encrypt using the best available encryption for a given key's backend. + This is a curated encryption choice and the algorithm may change over + time. + + :param bytes password: The password to use for encryption. + +.. class:: NoEncryption + + Do not encrypt. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 0f7e0377..47486895 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -6,7 +6,6 @@ Symmetric encryption .. module:: cryptography.hazmat.primitives.ciphers - Symmetric encryption is a way to `encrypt`_ or hide the contents of material where the sender and receiver both use the same secret key. Note that symmetric encryption is **not** sufficient for most applications because it only @@ -475,7 +474,7 @@ Interfaces ``AEADEncryptionContext`` provider. ``AEADCipherContext`` contains an additional method :meth:`authenticate_additional_data` for adding additional authenticated but unencrypted data (see note below). You should - call this before calls to ``update``. When you are done call `finalize`` + call this before calls to ``update``. When you are done call ``finalize`` to finish the operation. .. note:: @@ -555,7 +554,7 @@ Interfaces used by the symmetric cipher modes described in .. method:: validate_for_algorithm(algorithm) - :param CipherAlgorithm algorithm: + :param cryptography.hazmat.primitives.ciphers.CipherAlgorithm algorithm: Checks that the combination of this mode with the provided algorithm meets any necessary invariants. This should raise an exception if they diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 0d86f7cc..89d81222 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -39,7 +39,7 @@ codes (HMAC). and be at least 128 bits. It is recommended that the key be 160 bits. :param int length: Length of generated one time password as ``int``. - :param HashAlgorithm algorithm: A + :param cryptography.hazmat.primitives.hashes.HashAlgorithm algorithm: A :class:`~cryptography.hazmat.primitives.hashes` provider. :param backend: A @@ -137,7 +137,7 @@ similar to the following code. and be at least 128 bits. It is recommended that the key be 160 bits. :param int length: Length of generated one time password as ``int``. - :param HashAlgorithm algorithm: A + :param cryptography.hazmat.primitives.hashes.HashAlgorithm algorithm: A :class:`~cryptography.hazmat.primitives.hashes` provider. :param int time_step: The time step size. The recommended size is 30. |