From dc13538d6a72ac84c21e05e9a79fb3df044b24b8 Mon Sep 17 00:00:00 2001 From: "Sybren A. St?vel" Date: Sun, 31 Jul 2011 17:44:44 +0200 Subject: More documentation --- doc/usage.rst | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 76 insertions(+), 4 deletions(-) (limited to 'doc/usage.rst') diff --git a/doc/usage.rst b/doc/usage.rst index bd499a9..61121e0 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -3,10 +3,6 @@ Usage This section describes the usage of the Python-RSA module. - -Generating keys --------------------------------------------------- - Before you can use RSA you need keys. You will receive a private key and a public key. @@ -15,10 +11,86 @@ and a public key. The private key is called *private* for a reason. Never share this key with anyone. +The public key is used for encypting a message such that it can only +be read by the owner of the private key. As such it's also referred to +as the *encryption key*. Decrypting a message can only be done using +the private key, hence it's also called the *decryption key*. + +The private key is used for signing a message. With this signature and +the public key, the receiver can verifying that a message was signed +by the owner of the private key, and that the message was not modified +after signing. + +Generating keys +-------------------------------------------------- + +You can use the :py:func:`rsa.newkeys` function to create a keypair. +Alternatively you can use :py:func:`rsa.PrivateKey.load_pkcs1` and +:py:func:`rsa.PublicKey.load_pkcs1` to load keys from a file. + +Generating a keypair may take a long time, depending on the number of +bits required. The number of bits determines the cryptographic +strength of the key, as well as the size of the message you can +encrypt. If you don't mind having a slightly smaller key than you +requested, you can pass ``accurate=False`` to speed up the key +generation process. + +These are some timings from my netbook (Linux 2.6, 1.6 GHz Intel Atom +N270 CPU, 2 GB RAM): + ++----------------+------------------+ +| Keysize (bits) | Time to generate | ++================+==================+ +| 32 | 0.01 sec. | ++----------------+------------------+ +| 64 | 0.03 sec. | ++----------------+------------------+ +| 96 | 0.04 sec. | ++----------------+------------------+ +| 128 | 0.08 sec. | ++----------------+------------------+ +| 256 | 0.27 sec. | ++----------------+------------------+ +| 384 | 0.93 sec. | ++----------------+------------------+ +| 512 | 1.21 sec. | ++----------------+------------------+ +| 1024 | 7.93 sec. | ++----------------+------------------+ +| 2048 | 132.97 sec. | ++----------------+------------------+ + Encryption and decryption -------------------------------------------------- +To encrypt or decrypt a message, use :py:func:`rsa.encrypt` resp. +:py:func:`rsa.decrypt`. Let's say that Alice wants to send a message +that only Bob can read. + +#. Bob generates a keypair, and gives the public key to Alice. This is + done such that Alice knows for sure that the key is really Bob's + (for example by handing over a USB stick that contains the key). + +#. Alice writes a message + +#. Alice encrypts the message using Bob's public key, and sends the + encrypted message. + +#. Bob receives the message, and decrypts it with his private key. + +Since Bob kept his private key *private*, Alice can be sure that he is +the only one who can read the message. Bob does *not* know for sure +that it was Alice that sent the message, since she didn't sign it. + + +Low-level operations +++++++++++++++++++++++++++++++ + +The core RSA algorithm operates on large integers. These operations +are considered low-level and are supported by the +:py:func:`rsa.core.encrypt_int` and :py:func:`rsa.core.decrypt_int` +functions. Signing and verification -------------------------------------------------- -- cgit v1.2.1