More documentation

5 files changed, 153 insertions, 12 deletions

diff --git a/doc/compatibility.rst b/doc/compatibility.rst
new file mode 100644
index 0000000..cbc0eb3
--- /dev/null
+++ b/doc/compatibility.rst
@@ -0,0 +1,44 @@
+Compatibility with standards and other software
+==================================================
+
+Python-RSA implements encryption and signatures according to PKCS#1
+version 1.5. This makes it compatible with the OpenSSL RSA module.
+
+Keys are stored in PEM or DER format according to PKCS#1 v1.5. Private
+keys are compatible with OpenSSL. However, OpenSSL uses X.509 for its
+public keys, which are not supported.
+
+:Encryption:
+    PKCS#1 v1.5 with at least 8 bytes of random padding
+
+:Signatures:
+    PKCS#1 v1.5 using the following hash methods:
+    MD5, SHA-1, SHA-256, SHA-384, SHA-512
+
+:Private keys:
+    PKCS#1 v1.5 in PEM and DER format, ASN.1 type RSAPrivateKey
+
+:Public keys:
+    PKCS#1 v1.5 in PEM and DER format, ASN.1 type RSAPublicKey
+
+
+
+Public keys from OpenSSL
+--------------------------------------------------
+
+To get a Python-RSA-compatible public key from OpenSSL, you need the
+private key. Get the private key in PEM or DER format and run it
+through the ``pyrsa-priv2pub`` command::
+
+ 
+ Usage: pyrsa-priv2pub [options]
+ 
+ Reads a private key and outputs the corresponding public key. Both
+ private and public keys use the format described in PKCS#1 v1.5
+ 
+ Options:
+   -h, --help         show this help message and exit
+   --in=INFILENAME    Input filename. Reads from stdin if not specified
+   --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/index.rst b/doc/index.rst
index 4963221..addc869 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -10,16 +10,35 @@ Python-RSA is a pure-Python RSA implementation. It supports
 encryption and decryption, signing and verifying signatures, and key
 generation according to PKCS#1 version 1.5.
 
-Contents:
+
+Security notice
+--------------------------------------------------
+
+This RSA implementation has seen the eyes of a security expert, and it
+uses an industry standard random padding method. However, there are
+still possible vectors of attack. Just to name one example, it doesn't
+compress the input stream to remove repetitions, and if you display
+the stack trace of a ``Decryptionerror`` exception you'll leak
+information about the reason why decryption failed. And I'm sure that
+those aren't the only insecurities. Use your own judgement to decide
+whether this module is secure enough for your application.
+
+If you have the time and skill to improve the implementation, by all
+means be my guest. The best way is to clone the Mercurial repository
+and send me a merge request when you've got something worth merging.
+
+
+Contents
+--------------------------------------------------
 
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   intro
-   installation
-   license
-   usage
-   compatibility
+    intro
+    installation
+    licence
+    usage
+    compatibility
 
 
 Indices and tables
diff --git a/doc/installation.rst b/doc/installation.rst
index 595793a..47f137f 100644
--- a/doc/installation.rst
+++ b/doc/installation.rst
@@ -10,4 +10,44 @@ or easy_install. Either one will work::
 Depending on your system you may need to use ``sudo pip`` or ``sudo
 easy_install``.
 
+Installation from source is also quite easy. Download the source and
+then type::
 
+    python setup.py install
+
+or if that doesn't work::
+
+    sudo python setup.py install
+
+
+.. todo::
+
+    Add a source link here
+
+
+Dependencies
+--------------------------------------------------
+
+Python-RSA has very few dependencies. As a matter of fact, to use it
+you only need Python itself. Loading and saving keys does require an
+extra module, though: pyasn1. If you used pip or easy_install like
+described above, you should be ready to go.
+
+Development dependencies
+--------------------------------------------------
+
+In order to start developing on Python-RSA you need a bit more. Use
+pip or easy_install to install the following packages:
+
+    - Mercurial
+    - nose
+    - sphinx
+    - pyasn1
+
+Once these are installed, use Mercurial_ to get a copy of the source::
+
+    hg clone http://hg.stuvel.eu/python-rsa
+    sudo python setup.py develop
+
+
+.. _Mercurial: http://hg-scm.com/
diff --git a/doc/licence.rst b/doc/licence.rst
new file mode 100644
index 0000000..91465a8
--- /dev/null
+++ b/doc/licence.rst
@@ -0,0 +1,18 @@
+Licence
+==================================================
+
+The source code and documentation are protected under copyright by
+Sybren A. Stüvel <sybren@stuvel.eu>
+
+The software is licensed under the Apache License, Version 2.0 (the
+"License"); you may not use the software except in compliance with the
+License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing
+permissions and limitations under the License.
+
diff --git a/doc/usage.rst b/doc/usage.rst
index 2c01cec..bd499a9 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -1,11 +1,31 @@
 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.
+
+.. note::
+
+    The private key is called *private* for a reason. Never share this
+    key with anyone.
+
+
+Encryption and decryption
+--------------------------------------------------
+
+
+Signing and verification
+--------------------------------------------------
+
+
+Working with big files
+--------------------------------------------------
 
-.. toctree::
 
-   keygen
-   simple_enc_dec
-   sign_verify
-   big_files