More documentation about key size and OpenSSL compatibility

2 files changed, 50 insertions, 18 deletions

diff --git a/doc/compatibility.rst b/doc/compatibility.rst
index ab9e2e4..d82d1fa 100644
--- a/doc/compatibility.rst
+++ b/doc/compatibility.rst
@@ -27,24 +27,25 @@ Public keys:
 :ref:`VARBLOCK <bigfiles>` encryption:
     Python-RSA only, not compatible with any other known application.
 
+.. _openssl:
 
-Public keys from OpenSSL
+Interoperability with OpenSSL
 --------------------------------------------------
 
+You can create a 512-bit RSA key in OpenSSL as follows::
+
+    openssl genrsa -out myprivatekey.pem 512
+
 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
+private key first, then run it through the ``pyrsa-priv2pub``
+command::
+
+    pyrsa-priv2pub -i myprivatekey.pem -o mypublickey.pem
+
+Encryption and decryption is also compatible::
+
+    $ echo hello there > testfile.txt
+    $ pyrsa-encrypt -i testfile.txt -o testfile.rsa publickey.pem
+    $ openssl rsautl -in testfile.rsa -inkey privatekey.pem -decrypt
+    hello there
 
diff --git a/doc/usage.rst b/doc/usage.rst
index 9b5fc17..e4436e4 100644
--- a/doc/usage.rst
+++ b/doc/usage.rst
@@ -44,8 +44,9 @@ 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):
+These are some average timings from my netbook (Linux 2.6, 1.6 GHz
+Intel Atom N270 CPU, 2 GB RAM). Since key generation is a random
+process, times may differ.
 
 +----------------+------------------+
 | Keysize (bits) | Time to generate |
@@ -69,6 +70,36 @@ N270 CPU, 2 GB RAM):
 | 2048           | 132.97 sec.      |
 +----------------+------------------+
 
+If key generation is too slow for you, you could use OpenSSL to
+generate them for you, then load them in your Python code. See
+:ref:`openssl` for more information.
+
+Key size requirements
+--------------------------------------------------
+
+Python-RSA version 3.0 introduced PKCS#1-style random padding. This
+means that 11 bytes (88 bits) of your key are no longer usable for
+encryption, so keys smaller than this are unusable. The larger the
+key, the higher the security.
+
+Creating signatures also requires a key of a certain size, depending
+on the used hash method:
+
++-------------+-----------------------------------+
+| Hash method | Suggested minimum key size (bits) |
++=============+===================================+
+| MD5         | 360                               |
++-------------+-----------------------------------+
+| SHA-1       | 368                               |
++-------------+-----------------------------------+
+| SHA-256     | 496                               |
++-------------+-----------------------------------+
+| SHA-384     | 624                               |
++-------------+-----------------------------------+
+| SHA-512     | 752                               |
++-------------+-----------------------------------+
+
+
 
 Encryption and decryption
 --------------------------------------------------