1.. -*- coding: utf-8; mode: rst; -*-
2
3*******************************************************
4pretty-bad-protocol (a.k.a. python-gnupg) |On PyPI|
5*******************************************************
6
7Complete rewrite of `Vinay Sajip's python-gnupg <https://bitbucket.org/vinay.sajip/python-gnupg>`__,
8including patches to fix a shell injection vulnerability due to unsanitised
9inputs being passed to ``subprocess.Popen([...], shell=True)``.
10
11.. |On PyPI| image:: https://badge.fury.io/py/gnupg.png
12   :target: https://pypi.python.org/pypi/gnupg
13
14==============
15Installation
16==============
17
18----------------------------------------
19From `PyPI <https://pypi.python.org>`__
20----------------------------------------
21
22It's simple. Just do::
23
24    [sudo] pip install pretty-bad-protocol
25
26Additionally, the legacy way to install versions of this library <
273.0.0 is::
28
29    [sudo] pip install gnupg
30
31--------
32From git
33--------
34
35To install this package from this git repository, do::
36
37    git clone https://github.com/isislovecruft/python-gnupg.git
38    cd python-gnupg
39    make install
40    make test
41
42Optionally, to build the Sphinx documentation_, do::
43
44    make docs
45
46
47To get started using python-gnupg's API, see the documentation_,
48and import the module like so::
49
50.. code-block:: python
51
52    >>> from pretty_bad_protocol import gnupg
53
54The primary interface class you'll likely want to interact with is ``gnupg.GPG``:
55
56.. code-block:: python
57
58    >>> gpg = gnupg.GPG(binary='/usr/bin/gpg',
59    ...     homedir='./keys',
60    ...     keyring='pubring.gpg',
61    ...     secring='secring.gpg')
62    >>> batch_key_input = gpg.gen_key_input(
63    ...     key_type='RSA',
64    ...     key_length=4096)
65    >>> print batch_key_input
66    Key-Type: RSA
67    Name-Email: isis@wintermute
68    Key-Length: 4096
69    Name-Real: Autogenerated Key
70    %commit
71
72    >>> key = gpg.gen_key(batch_key_input)
73    >>> print key.fingerprint
74    245D8FA30F543B742053949F553C0E154F2E7A98
75
76    >>> message = "The crow flies at midnight."
77    >>> encrypted = str(gpg.encrypt(message, key.fingerprint))
78    >>> decrypted = str(gpg.decrypt(encrypted))
79    >>> assert decrypted == message
80
81.. _documentation: https://pythonhosted.org/gnupg/
82
83==============================
84Bug Reports & Feature Requests
85==============================
86
87Our bugtracker can be found `on Github
88<https://github.com/isislovecruft/python-gnupg/issues>`__.  Public comments and
89discussions are also welcome on the bugtracker.  Patches are always welcome.
90
91I increasingly have less and less time to deal with maintaining this
92module.  Please be patient, and if there is a patch your project
93urgently needs, please consider temporarily forking until I or one of
94the other maintainers can get to your issue.
95