From d92b667ac4e5380360eac01b5324fbe0c7dab976 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Sun, 31 Jul 2011 17:44:44 +0200 Subject: More documentation --- doc/compatibility.rst | 1 + doc/conf.py | 6 ++-- doc/index.rst | 1 + doc/intro.rst | 2 +- doc/reference.rst | 29 +++++++++++++++++++ doc/usage.rst | 80 ++++++++++++++++++++++++++++++++++++++++++++++++--- 6 files changed, 112 insertions(+), 7 deletions(-) create mode 100644 doc/reference.rst (limited to 'doc') 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 @@ through the ``pyrsa-priv2pub`` command:: --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 @@ import sys, os # 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 @@ templates_path = ['_templates'] 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 @@ Contents 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 @@ numbers. It also included generating public and private keys. There 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 @@ 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. @@ -15,10 +11,86 @@ and a public key. 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 -------------------------------------------------- -- cgit v1.2.1