Finished documentation of basic functions

2 files changed, 71 insertions, 5 deletions

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 @@ Classes
     :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 @@ 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.
+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 @@ that only Bob can read.
    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 @@ functions.
 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
 --------------------------------------------------