From 78515f2b57e84586ba71ad905a1cd53c1d7cda61 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 19 Dec 2014 16:17:45 -0800 Subject: Describe key generation and key loading in the RSA docs --- docs/hazmat/primitives/asymmetric/rsa.rst | 38 ++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 7f902fff..0a25e68f 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -10,11 +10,20 @@ RSA Generation ~~~~~~~~~~ +Unlike symmetric cryptography, where the key is typically just a random series +of bytes, RSA keys have a complex internal structure with `specific +mathematical properties`_. + .. function:: generate_private_key(public_exponent, key_size, backend) .. versionadded:: 0.5 - Generate an RSA private key using the provided ``backend``. + Generates a new RSA private key using the provided ``backend``. + ``key_size`` describes how many bits long the key should be, larger keys + provide more security, currently ``1024`` and below are considered + breakable, and ``2048`` or ``4096`` are reasonable default key sizes for + new keys. The ``public_exponent`` indicates what one mathematical property + of the key generation will be, ``65537`` should almost always be used. .. doctest:: @@ -42,6 +51,32 @@ Generation the provided ``backend`` does not implement :class:`~cryptography.hazmat.backends.interfaces.RSABackend` +Key loading +~~~~~~~~~~~ + +If you already have an on-disk key in the PEM format (which are recognizable by +the distinctive ``-----BEGIN {format}-----`` and ``-----END {format}-----`` +markers), you can load it: + +.. code-block:: pycon + + >>> from cryptography.hazmat.primitives import serialization + + >>> with open("path/to/key.pem", "rb") as key_file: + ... private_key = serialization.load_pem_private_key( + ... key_file.read(), + ... password=None, + ... backend=default_backend() + ... ) + +Serialized keys may optionally be encrypted on disk using a password. In this +example we loaded an unencrypted key, and therefore we did not provide a +password. If the key is encrypted we can pass a ``bytes`` object as the +``password`` argument. + +There is also support for :func:`loading public keys in the SSH format +