Skip to content

Commit a3fd61a

Browse files
sybrenstuvelsybrenstuvel
committed
More documentation
1 parent aa28c04 commit a3fd61a

5 files changed

Lines changed: 153 additions & 12 deletions

File tree

‎doc/compatibility.rst‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
Compatibility with standards and other software
2+
==================================================
3+
4+
Python-RSA implements encryption and signatures according to PKCS#1
5+
version 1.5. This makes it compatible with the OpenSSL RSA module.
6+
7+
Keys are stored in PEM or DER format according to PKCS#1 v1.5. Private
8+
keys are compatible with OpenSSL. However, OpenSSL uses X.509 for its
9+
public keys, which are not supported.
10+
11+
:Encryption:
12+
PKCS#1 v1.5 with at least 8 bytes of random padding
13+
14+
:Signatures:
15+
PKCS#1 v1.5 using the following hash methods:
16+
MD5, SHA-1, SHA-256, SHA-384, SHA-512
17+
18+
:Private keys:
19+
PKCS#1 v1.5 in PEM and DER format, ASN.1 type RSAPrivateKey
20+
21+
:Public keys:
22+
PKCS#1 v1.5 in PEM and DER format, ASN.1 type RSAPublicKey
23+
24+
25+
26+
Public keys from OpenSSL
27+
--------------------------------------------------
28+
29+
To get a Python-RSA-compatible public key from OpenSSL, you need the
30+
private key. Get the private key in PEM or DER format and run it
31+
through the ``pyrsa-priv2pub`` command::
32+
33+
34+
Usage: pyrsa-priv2pub [options]
35+
36+
Reads a private key and outputs the corresponding public key. Both
37+
private and public keys use the format described in PKCS#1 v1.5
38+
39+
Options:
40+
-h, --help show this help message and exit
41+
--in=INFILENAME Input filename. Reads from stdin if not specified
42+
--out=OUTFILENAME Output filename. Writes to stdout of not specified
43+
--inform=INFORM key format of input - default PEM
44+
--outform=OUTFORM key format of output - default PEM

‎doc/index.rst‎

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,16 +10,35 @@ Python-RSA is a pure-Python RSA implementation. It supports
1010
encryption and decryption, signing and verifying signatures, and key
1111
generation according to PKCS#1 version 1.5.
1212

13-
Contents:
13+
14+
Security notice
15+
--------------------------------------------------
16+
17+
This RSA implementation has seen the eyes of a security expert, and it
18+
uses an industry standard random padding method. However, there are
19+
still possible vectors of attack. Just to name one example, it doesn't
20+
compress the input stream to remove repetitions, and if you display
21+
the stack trace of a ``Decryptionerror`` exception you'll leak
22+
information about the reason why decryption failed. And I'm sure that
23+
those aren't the only insecurities. Use your own judgement to decide
24+
whether this module is secure enough for your application.
25+
26+
If you have the time and skill to improve the implementation, by all
27+
means be my guest. The best way is to clone the Mercurial repository
28+
and send me a merge request when you've got something worth merging.
29+
30+
31+
Contents
32+
--------------------------------------------------
1433

1534
.. toctree::
16-
:maxdepth: 2
35+
:maxdepth: 2
1736

18-
intro
19-
installation
20-
license
21-
usage
22-
compatibility
37+
intro
38+
installation
39+
licence
40+
usage
41+
compatibility
2342

2443

2544
Indices and tables

‎doc/installation.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,44 @@ or easy_install. Either one will work::
1010
Depending on your system you may need to use ``sudo pip`` or ``sudo
1111
easy_install``.
1212

13+
Installation from source is also quite easy. Download the source and
14+
then type::
1315

16+
python setup.py install
17+
18+
or if that doesn't work::
19+
20+
sudo python setup.py install
21+
22+
23+
.. todo::
24+
25+
Add a source link here
26+
27+
28+
Dependencies
29+
--------------------------------------------------
30+
31+
Python-RSA has very few dependencies. As a matter of fact, to use it
32+
you only need Python itself. Loading and saving keys does require an
33+
extra module, though: pyasn1. If you used pip or easy_install like
34+
described above, you should be ready to go.
35+
36+
Development dependencies
37+
--------------------------------------------------
38+
39+
In order to start developing on Python-RSA you need a bit more. Use
40+
pip or easy_install to install the following packages:
41+
42+
- Mercurial
43+
- nose
44+
- sphinx
45+
- pyasn1
46+
47+
Once these are installed, use Mercurial_ to get a copy of the source::
48+
49+
hg clone http://hg.stuvel.eu/python-rsa
50+
sudo python setup.py develop
51+
52+
53+
.. _Mercurial: http://hg-scm.com/

‎doc/licence.rst‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
Licence
2+
==================================================
3+
4+
The source code and documentation are protected under copyright by
5+
Sybren A. Stüvel <sybren@stuvel.eu>
6+
7+
The software is licensed under the Apache License, Version 2.0 (the
8+
"License"); you may not use the software except in compliance with the
9+
License. You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
16+
implied. See the License for the specific language governing
17+
permissions and limitations under the License.
18+

‎doc/usage.rst‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,31 @@
11
Usage
22
==================================================
33

4+
This section describes the usage of the Python-RSA module.
5+
6+
7+
Generating keys
8+
--------------------------------------------------
9+
10+
Before you can use RSA you need keys. You will receive a private key
11+
and a public key.
12+
13+
.. note::
14+
15+
The private key is called *private* for a reason. Never share this
16+
key with anyone.
17+
18+
19+
Encryption and decryption
20+
--------------------------------------------------
21+
22+
23+
Signing and verification
24+
--------------------------------------------------
25+
26+
27+
Working with big files
28+
--------------------------------------------------
429

5-
.. toctree::
630

7-
keygen
8-
simple_enc_dec
9-
sign_verify
10-
big_files
1131

0 commit comments

Comments
 (0)