From a3fd61a422a317b7331c56afbcb564ae7901a026 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sybren=20A=2E=20St=C3=BCvel?= Date: Sun, 31 Jul 2011 00:22:31 +0200 Subject: More documentation --- doc/compatibility.rst | 44 ++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 33 ++++++++++++++++++++++++++------- doc/installation.rst | 40 ++++++++++++++++++++++++++++++++++++++++ doc/licence.rst | 18 ++++++++++++++++++ doc/usage.rst | 30 +++++++++++++++++++++++++----- 5 files changed, 153 insertions(+), 12 deletions(-) create mode 100644 doc/compatibility.rst create mode 100644 doc/licence.rst (limited to 'doc') 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 + +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 -- cgit v1.2.1