More documentation
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 @@
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 @@
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
--------------------------------------------------