Finished documentation of basic functions
diff --git a/doc/reference.rst b/doc/reference.rst
index 69a89bc..c667840 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -25,5 +25,14 @@
:members:
:inherited-members:
+Exceptions
+--------------------------------------------------
+
+.. autoclass:: rsa.pkcs1.CryptoError(Exception)
+
+.. autoclass:: rsa.pkcs1.DecryptionError(CryptoError)
+
+.. autoclass:: rsa.pkcs1.VerificationError(CryptoError)
+
diff --git a/doc/usage.rst b/doc/usage.rst
index 61121e0..7ca4fed 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -24,9 +24,16 @@
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.
+You can use the :py:func:`rsa.newkeys` function to create a keypair:
+
+ >>> (pubkey, privkey) = rsa.newkeys(512)
+
+Alternatively you can use :py:meth:`rsa.PrivateKey.load_pkcs1` and
+:py:meth:`rsa.PublicKey.load_pkcs1` to load keys from a file:
+
+ >>> with open('private.pem') as privatefile:
+ ... keydata = privatefile.read()
+ >>> pubkey = rsa.PrivateKey.load_pkcs1(keydata)
Generating a keypair may take a long time, depending on the number of
bits required. The number of bits determines the cryptographic
@@ -72,16 +79,30 @@
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).
+ >>> (bob_pub, bob_priv) = rsa.newkeys(512)
+
#. Alice writes a message
+ >>> message = 'hello Bob!'
+
#. Alice encrypts the message using Bob's public key, and sends the
encrypted message.
+ >>> cryto = rsa.encrypt(message, bob_pub)
+
#. Bob receives the message, and decrypts it with his private key.
+ >>> message = rsa.decrypt(crypto, bob_priv)
+ >>> print message
+ hello Bob!
+
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.
+the only one who can read the message.
+
+.. note::
+
+ Bob does *not* know for sure that it was Alice that sent the
+ message, since she didn't sign it.
Low-level operations
@@ -95,6 +116,42 @@
Signing and verification
--------------------------------------------------
+You can create a detached signature for a message using the
+:py:func:`rsa.sign` function:
+
+ >>> (pubkey, privkey) = rsa.newkeys(512)
+ >>> message = 'Go left at the blue tree'
+ >>> signature = rsa.sign(message, privkey, 'SHA-1')
+
+This hashes the message using SHA-1. Other hash methods are also
+possible, check the :py:func:`rsa.sign` function documentation for
+details. The hash is then signed with the private key.
+
+In order to verify the signature, use the :py:func:`rsa.verify`
+function.
+
+ >>> message = 'Go left at the blue tree'
+ >>> rsa.verify(message, signature, pubkey)
+
+Modify the message, and the signature is no longer valid and a
+:py:class:`rsa.pkcs1.VerificationError` is thrown:
+
+ >>> message = 'Go right at the blue tree'
+ >>> rsa.verify(message, signature, pubkey)
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ File "/home/sybren/workspace/python-rsa/rsa/pkcs1.py", line 289, in verify
+ raise VerificationError('Verification failed')
+ rsa.pkcs1.VerificationError: Verification failed
+
+.. note::
+
+ Never display the stack trace of a
+ :py:class:`rsa.pkcs1.VerificationError` exception. It shows where
+ in the code the exception occurred, and thus leaks information
+ about the key. It's only a tiny bit of information, but every bit
+ makes cracking the keys easier.
+
Working with big files
--------------------------------------------------