More documentation
diff --git a/doc/compatibility.rst b/doc/compatibility.rst
index cbc0eb3..0cb2ba6 100644
--- a/doc/compatibility.rst
+++ b/doc/compatibility.rst
@@ -42,3 +42,4 @@
--out=OUTFILENAME Output filename. Writes to stdout of not specified
--inform=INFORM key format of input - default PEM
--outform=OUTFORM key format of output - default PEM
+
diff --git a/doc/conf.py b/doc/conf.py
index 3ee83f1..ad49886 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -26,7 +26,9 @@
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo',
- 'sphinx.ext.coverage', 'sphinx.ext.viewcode', 'sphinx.ext.pngmath']
+ 'sphinx.ext.coverage', 'sphinx.ext.pngmath']
+
+# I would like to add 'sphinx.ext.viewcode', but it causes a UnicodeDecodeError
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
@@ -35,7 +37,7 @@
source_suffix = '.rst'
# The encoding of source files.
-#source_encoding = 'utf-8-sig'
+source_encoding = 'utf-8'
# The master toctree document.
master_doc = 'index'
diff --git a/doc/index.rst b/doc/index.rst
index addc869..df81a77 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -39,6 +39,7 @@
licence
usage
compatibility
+ reference
Indices and tables
diff --git a/doc/intro.rst b/doc/intro.rst
index e27a7a2..cc89a19 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -14,6 +14,6 @@
was no functionality for working with byte sequences (such as files)
yet.
-.. TODO:: write more history
+.. todo:: write more history
diff --git a/doc/reference.rst b/doc/reference.rst
new file mode 100644
index 0000000..69a89bc
--- /dev/null
+++ b/doc/reference.rst
@@ -0,0 +1,29 @@
+Reference
+==================================================
+
+Functions
+--------------------------------------------------
+
+.. autofunction:: rsa.encrypt
+
+.. autofunction:: rsa.decrypt
+
+.. autofunction:: rsa.sign
+
+.. autofunction:: rsa.verify
+
+.. autofunction:: rsa.newkeys(keysize)
+
+Classes
+--------------------------------------------------
+
+.. autoclass:: rsa.PublicKey
+ :members:
+ :inherited-members:
+
+.. autoclass:: rsa.PrivateKey
+ :members:
+ :inherited-members:
+
+
+
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
--------------------------------------------------