diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/reference.rst | 9 | ||||
-rw-r--r-- | doc/usage.rst | 67 |
2 files changed, 71 insertions, 5 deletions
diff --git a/doc/reference.rst b/doc/reference.rst index 69a89bc..c667840 100644 --- a/doc/reference.rst +++ b/doc/reference.rst @@ -25,5 +25,14 @@ Classes :members: :inherited-members: +Exceptions +-------------------------------------------------- + +.. autoclass:: rsa.pkcs1.CryptoError(Exception) + +.. autoclass:: rsa.pkcs1.DecryptionError(CryptoError) + +.. autoclass:: rsa.pkcs1.VerificationError(CryptoError) + diff --git a/doc/usage.rst b/doc/usage.rst index 61121e0..7ca4fed 100644 --- a/doc/usage.rst +++ b/doc/usage.rst @@ -24,9 +24,16 @@ 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. +You can use the :py:func:`rsa.newkeys` function to create a keypair: + + >>> (pubkey, privkey) = rsa.newkeys(512) + +Alternatively you can use :py:meth:`rsa.PrivateKey.load_pkcs1` and +:py:meth:`rsa.PublicKey.load_pkcs1` to load keys from a file: + + >>> with open('private.pem') as privatefile: + ... keydata = privatefile.read() + >>> pubkey = rsa.PrivateKey.load_pkcs1(keydata) Generating a keypair may take a long time, depending on the number of bits required. The number of bits determines the cryptographic @@ -72,16 +79,30 @@ that only Bob can read. 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). + >>> (bob_pub, bob_priv) = rsa.newkeys(512) + #. Alice writes a message + >>> message = 'hello Bob!' + #. Alice encrypts the message using Bob's public key, and sends the encrypted message. + >>> cryto = rsa.encrypt(message, bob_pub) + #. Bob receives the message, and decrypts it with his private key. + >>> message = rsa.decrypt(crypto, bob_priv) + >>> print message + hello Bob! + 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. +the only one who can read the message. + +.. note:: + + Bob does *not* know for sure that it was Alice that sent the + message, since she didn't sign it. Low-level operations @@ -95,6 +116,42 @@ functions. Signing and verification -------------------------------------------------- +You can create a detached signature for a message using the +:py:func:`rsa.sign` function: + + >>> (pubkey, privkey) = rsa.newkeys(512) + >>> message = 'Go left at the blue tree' + >>> signature = rsa.sign(message, privkey, 'SHA-1') + +This hashes the message using SHA-1. Other hash methods are also +possible, check the :py:func:`rsa.sign` function documentation for +details. The hash is then signed with the private key. + +In order to verify the signature, use the :py:func:`rsa.verify` +function. + + >>> message = 'Go left at the blue tree' + >>> rsa.verify(message, signature, pubkey) + +Modify the message, and the signature is no longer valid and a +:py:class:`rsa.pkcs1.VerificationError` is thrown: + + >>> message = 'Go right at the blue tree' + >>> rsa.verify(message, signature, pubkey) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + File "/home/sybren/workspace/python-rsa/rsa/pkcs1.py", line 289, in verify + raise VerificationError('Verification failed') + rsa.pkcs1.VerificationError: Verification failed + +.. note:: + + Never display the stack trace of a + :py:class:`rsa.pkcs1.VerificationError` exception. It shows where + in the code the exception occurred, and thus leaks information + about the key. It's only a tiny bit of information, but every bit + makes cracking the keys easier. + Working with big files -------------------------------------------------- |