More documentation

1 files changed, 76 insertions, 4 deletions

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
 --------------------------------------------------