diff options
Diffstat (limited to 'docs/hazmat/primitives/asymmetric')
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 101 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 51 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 100 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/serialization.rst | 100 |
5 files changed, 312 insertions, 42 deletions
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 2819bbdb..6848d84c 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -38,11 +38,11 @@ DSA Generate a new ``DSAParameters`` instance using ``backend``. :param int key_size: The length of the modulus in bits. It should be - either "1024, 2048 or 3072". For keys generated in 2014 this should - be `at least 2048`_ (See page 41). - Note that some applications (such as SSH) have not yet gained support - for larger key sizes specified in FIPS 186-3 and are still restricted - to only the 1024-bit keys specified in FIPS 186-2. + either 1024, 2048 or 3072. For keys generated in 2014 this should + be `at least 2048`_ (See page 41). Note that some applications + (such as SSH) have not yet gained support for larger key sizes + specified in FIPS 186-3 and are still restricted to only the + 1024-bit keys specified in FIPS 186-2. :return: A new instance of ``DSAParameters`` @@ -97,6 +97,48 @@ DSA or if the OpenSSL version is older than 1.0.0 and the key size is larger than 1024 because older OpenSSL versions don't support a key size larger than 1024. + .. method:: signer(algorithm, backend) + + .. versionadded:: 0.4 + + Sign data which can be verified later by others using the public key. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import dsa + >>> parameters = dsa.DSAParameters.generate( + ... key_size=1024, + ... backend=default_backend() + ... ) + >>> private_key = dsa.DSAPrivateKey.generate( + ... parameters=parameters, + ... backend=default_backend() + ... ) + >>> signer = private_key.signer( + ... hashes.SHA256(), + ... default_backend() + ... ) + >>> data = b"this is some data I'd like to sign" + >>> signer.update(data) + >>> signature = signer.finalize() + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.DSABackend` + .. class:: DSAPublicKey(modulus, subgroup_order, generator, y) @@ -118,6 +160,55 @@ DSA ``subgroup_order``, ``generator``, or ``y`` do not match the bounds specified in `FIPS 186-4`_. + .. method:: verifier(signature, algorithm, backend) + + .. versionadded:: 0.4 + + Verify data was signed by the private key associated with this public + key. + + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import dsa + >>> parameters = dsa.DSAParameters.generate( + ... key_size=1024, + ... backend=default_backend() + ... ) + >>> private_key = dsa.DSAPrivateKey.generate( + ... parameters=parameters, + ... backend=default_backend() + ... ) + >>> signer = private_key.signer( + ... hashes.SHA256(), + ... default_backend() + ... ) + >>> data = b"this is some data I'd like to sign" + >>> signer.update(data) + >>> signature = signer.finalize() + >>> public_key = private_key.public_key() + >>> verifier = public_key.verifier( + ... signature, + ... hashes.SHA256(), + ... default_backend() + ... ) + >>> verifier.update(data) + >>> verifier.verify() + + :param bytes signature: The signature to verify. DER encoded as + specified in :rfc:`6979`. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.DSABackend` + provider. + + :returns: + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` .. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst new file mode 100644 index 00000000..f88b965a --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -0,0 +1,51 @@ +.. hazmat:: + +Elliptic Curve +============== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.ec + + +.. class:: EllipticCurvePrivateNumbers(private_value, public_numbers) + + .. versionadded:: 0.5 + + The collection of integers that make up an EC private key. + + .. attribute:: public_numbers + + :type: :class:`~cryptography.hazmat.primitives.ec.EllipticCurvePublicNumbers` + + The :class:`EllipticCurvePublicNumbers` which makes up the EC public + key associated with this EC private key. + + .. attribute:: private_value + + :type: int + + The private value. + + +.. class:: EllipticCurvePublicNumbers(x, y, curve) + + .. versionadded:: 0.5 + + The collection of integers that make up an EC public key. + + .. attribute:: curve + + :type: :class:`~cryptography.hazmat.primitives.interfaces.EllipticCurve` + + The elliptic curve for this key. + + .. attribute:: x + + :type: int + + The affine x component of the public point used for verifying. + + .. attribute:: y + + :type: int + + The affine y component of the public point used for verifying. diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index ca048d11..6a5228ba 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -7,5 +7,7 @@ Asymmetric algorithms :maxdepth: 1 dsa + ec rsa padding + serialization diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 8c34497e..54839119 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -85,7 +85,10 @@ RSA :param padding: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` - provider. + provider. Valid values are + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` and + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` + (``PSS`` is recommended for all new applications). :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` @@ -154,21 +157,39 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. code-block:: python + .. doctest:: - from cryptography.hazmat.backends import default_backend - from cryptography.hazmat.primitives import hashes - from cryptography.hazmat.primitives.asymmetric import padding + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import padding - plaintext = private_key.decrypt( - ciphertext, - padding.OAEP( - mgf=padding.MGF1(algorithm=hashes.SHA1()), - algorithm=hashes.SHA1(), - label=None - ), - default_backend() - ) + >>> # Generate a key + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = private_key.public_key() + >>> # encrypt some data + >>> ciphertext = public_key.encrypt( + ... b"encrypted data", + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) + >>> # Now do the actual decryption + >>> plaintext = private_key.decrypt( + ... ciphertext, + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) .. class:: RSAPublicKey(public_exponent, modulus) @@ -216,7 +237,7 @@ RSA ... hashes.SHA256(), ... default_backend() ... ) - >>> data= b"this is some data I'd like to sign" + >>> data = b"this is some data I'd like to sign" >>> signer.update(data) >>> signature = signer.finalize() >>> public_key = private_key.public_key() @@ -236,7 +257,10 @@ RSA :param padding: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` - provider. + provider. Valid values are + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` and + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` + (``PSS`` is recommended for all new applications). :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` @@ -306,27 +330,29 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. code-block:: python - - from cryptography.hazmat.backends import default_backend - from cryptography.hazmat.primitives import hashes - from cryptography.hazmat.primitives.asymmetric import padding, rsa - - private_key = rsa.RSAPrivateKey.generate( - public_exponent=65537, - key_size=2048, - backend=default_backend() - ) - public_key = private_key.public_key() - ciphertext = public_key.encrypt( - plaintext, - padding.OAEP( - mgf=padding.MGF1(algorithm=hashes.SHA1()), - algorithm=hashes.SHA1(), - label=None - ), - default_backend() - ) + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import padding + + >>> # Generate a key + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = private_key.public_key() + >>> # encrypt some data + >>> ciphertext = public_key.encrypt( + ... b"encrypted data", + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) .. class:: RSAPublicNumbers(e, n) diff --git a/docs/hazmat/primitives/asymmetric/serialization.rst b/docs/hazmat/primitives/asymmetric/serialization.rst new file mode 100644 index 00000000..2b3eb511 --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/serialization.rst @@ -0,0 +1,100 @@ +.. hazmat:: + +Key Serialization +================= + +.. currentmodule:: cryptography.hazmat.primitives.serialization + +There are several common schemes for serializing asymmetric private and public +keys to bytes. They generally support encryption of private keys and additional +key metadata. + +Many serialization formats support multiple different types of asymmetric keys +and will return an an instance of the appropriate type. You should check that +the returned key matches the type your application expects when using these +methods. + + .. code-block:: pycon + + >>> key = load_pkcs8_private_key(pem_data, None, backend) + >>> if isinstance(key, rsa.RSAPrivateKey): + >>> signature = sign_with_rsa_key(key, message) + >>> elif isinstance(key, dsa.DSAPrivateKey): + >>> signature = sign_with_dsa_key(key, message) + >>> else: + >>> raise TypeError + + +PKCS #8 Format +~~~~~~~~~~~~~~ + +PKCS #8 is a serialization format originally standardized by RSA and +currently maintained by the IETF in :rfc:`5208`. It supports password based +encryption and additional key metadata attributes. + + +.. function:: load_pkcs8_private_key(data, password, backend) + + .. versionadded:: 0.5 + + Deserialize a private key from PEM encoded data to one of the supported + asymmetric private key types. + + :param bytes data: The PEM encoded key data. + + :param bytes password: The password to use to decrypt the data. Should + be ``None`` if the private key is not encrypted. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.PKCS8SerializationBackend` + provider. + + :returns: A new instance of a private key. + + :raises ValueError: If the PEM data could not be decrypted or if its + structure could not be decoded successfully. + + :raises TypeError: If a ``password`` was given and the private key was + not encrypted. Or if the key was encrypted but no + password was supplied. + + :raises UnsupportedAlgorithm: If the serialized key is of a type that + is not supported by the backend or if the key is encrypted with a + symmetric cipher that is not supported by the backend. + + +Traditional OpenSSL Format +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The "traditional" PKCS #1 based serialization format used by OpenSSL. +It supports password based symmetric key encryption. Commonly found in +OpenSSL based TLS applications. It is usually found in PEM format with a +header that mentions the type of the serialized key. e.g. +``-----BEGIN RSA PRIVATE KEY-----``. + +.. function:: load_pem_traditional_openssl_private_key(data, password, backend) + + .. versionadded:: 0.5 + + Deserialize a private key from PEM encoded data to one of the supported + asymmetric private key types. + + :param bytes data: The PEM encoded key data. + + :param bytes password: The password to use to decrypt the data. Should + be ``None`` if the private key is not encrypted. + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.TraditionalOpenSSLSerializationBackend` + provider. + + :returns: A new instance of a private key. + + :raises ValueError: If the PEM data could not be decrypted or if its + structure could not be decoded successfully. + + :raises TypeError: If a ``password`` was given and the private key was + not encrypted. Or if the key was encrypted but no + password was supplied. + + :raises UnsupportedAlgorithm: If the serialized key is of a type that + is not supported by the backend or if the key is encrypted with a + symmetric cipher that is not supported by the backend. |