Unsignedio
/
python-gnupg
mirror of https://github.com/markqvist/python-gnupg.git
1
0
Fork 0
Code Issues Releases Wiki Activity

Cleanup Sphinx directives in docstrings in _parsers.py.

fix/30-hidden-recipient
Isis Lovecruft 2013-12-03 22:26:26 +00:00
parent 4f2dc555a5
commit 82cdfaf45e
No known key found for this signature in database
GPG Key ID: 5C17776E27F7E84D
1 changed files with 63 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
gnupg/_parsers.py
View File

@ -50,7 +50,7 @@ def _check_keyserver(location):
should contain the desired keyserver protocol which should contain the desired keyserver protocol which
is supported by the keyserver, for example, the is supported by the keyserver, for example, the
default is ``'hkp://subkeys.pgp.net'``. default is ``'hkp://subkeys.pgp.net'``.
:rtype: str or None :rtype: :obj:`str` or :obj:`None`
:returns: A string specifying the protocol and keyserver hostname, if the :returns: A string specifying the protocol and keyserver hostname, if the
checks passed. If not, returns None. checks passed. If not, returns None.
""" """
@ -73,10 +73,11 @@ def _check_keyserver(location):
def _check_preferences(prefs, pref_type=None): def _check_preferences(prefs, pref_type=None):
"""Check cipher, digest, and compression preference settings. """Check cipher, digest, and compression preference settings.
MD5 is not allowed. This is not 1994.[0] SHA1 is allowed grudgingly.[1] MD5 is not allowed. This is `not 1994`__. SHA1 is allowed_ grudgingly_.
[0]: http://www.cs.colorado.edu/~jrblack/papers/md5e-full.pdf __ http://www.cs.colorado.edu/~jrblack/papers/md5e-full.pdf
[1]: http://eprint.iacr.org/2008/469.pdf .. _allowed: http://eprint.iacr.org/2008/469.pdf
.. _grudgingly: https://www.schneier.com/blog/archives/2012/10/when_will_we_se.html
""" """
if prefs is None: return if prefs is None: return
@ -114,8 +115,8 @@ def _check_preferences(prefs, pref_type=None):
return allowed return allowed
def _fix_unsafe(shell_input): def _fix_unsafe(shell_input):
"""Find characters used to escape from a string into a shell, and wrap them """Find characters used to escape from a string into a shell, and wrap them in
in quotes if they exist. Regex pilfered from python-3.x shlex module. quotes if they exist. Regex pilfered from Python3 :mod:`shlex` module.
:param str shell_input: The input intended for the GnuPG process. :param str shell_input: The input intended for the GnuPG process.
""" """
@ -160,11 +161,15 @@ def _is_allowed(input):
class and its name will need to be added to this class and its name will need to be added to this
set. set.
:rtype: Exception or str :raises: :exc:`UsageError` if **input** is not a subset of the hard-coded
:raise: :exc:UsageError if ``_allowed`` is not a subset of ``_possible``. set of all GnuPG options in :func:`_get_all_gnupg_options`.
ProtectedOption if ``input`` is not in the set ``_allowed``.
:return: The original parameter ``input``, unmodified and unsanitized, :exc:`ProtectedOption` if **input** is not in the set of allowed
if no errors occur. options.
:rtype: str
:return: The original **input** parameter, unmodified and unsanitized, if
no errors occur.
""" """
gnupg_options = _get_all_gnupg_options() gnupg_options = _get_all_gnupg_options()
allowed = _get_options_group("allowed") allowed = _get_options_group("allowed")
@ -219,12 +224,12 @@ def _is_hex(string):
def _is_string(thing): def _is_string(thing):
"""Python character arrays are a mess. """Python character arrays are a mess.
If Python2, check if ``thing`` is a ``unicode()`` or ``str()``. If Python2, check if **thing** is an :obj:`unicode` or a :obj:`str`.
If Python3, check if ``thing`` is a ``str()``. If Python3, check if **thing** is a :obj:`str`.
:param thing: The thing to check. :param thing: The thing to check.
:returns: ``True`` if ``thing`` is a "string" according to whichever :returns: ``True`` if **thing** is a string according to whichever version
version of Python we're running in. of Python we're running in.
""" """
if _util._py3k: return isinstance(thing, str) if _util._py3k: return isinstance(thing, str)
else: return isinstance(thing, basestring) else: return isinstance(thing, basestring)
@ -237,18 +242,20 @@ def _sanitise(*args):
sanitised, allowed options. sanitised, allowed options.
Each new option that we support that is not a boolean, but instead has Each new option that we support that is not a boolean, but instead has
some extra inputs, i.e. "--encrypt-file foo.txt", will need some basic some additional inputs following it, i.e. "--encrypt-file foo.txt", will
safety checks added here. need some basic safety checks added here.
GnuPG has three-hundred and eighteen commandline flags. Also, not all GnuPG has three-hundred and eighteen commandline flags. Also, not all
implementations of OpenPGP parse PGP packets and headers in the same way, implementations of OpenPGP parse PGP packets and headers in the same way,
so there is added potential there for messing with calls to GPG. so there is added potential there for messing with calls to GPG.
For information on the PGP message format specification, see: For information on the PGP message format specification, see
https://www.ietf.org/rfc/rfc1991.txt :rfc:`1991`.
If you're asking, "Is this *really* necessary?": No, not really -- we could If you're asking, "Is this *really* necessary?": No, not really -- we could
just do a check as described here: https://xkcd.com/1181/ just follow the security precautions recommended by `this xkcd`__.
__ https://xkcd.com/1181/
:param str args: (optional) The boolean arguments which will be passed to :param str args: (optional) The boolean arguments which will be passed to
the GnuPG process. the GnuPG process.
@ -259,22 +266,23 @@ def _sanitise(*args):
## see TODO file, tag :cleanup:sanitise: ## see TODO file, tag :cleanup:sanitise:
def _check_option(arg, value): def _check_option(arg, value):
""" """Check that a single ``arg`` is an allowed option.
Check that a single :param:arg is an allowed option. If it is allowed,
quote out any escape characters in :param:values, and add the pair to If it is allowed, quote out any escape characters in ``value``, and
:ivar:sanitised. add the pair to :ivar:`sanitised`. Otherwise, drop them.
:param str arg: The arguments which will be passed to the GnuPG :param str arg: The arguments which will be passed to the GnuPG
process, and, optionally their corresponding values. process, and, optionally their corresponding values.
The values are any additional arguments following the The values are any additional arguments following the
GnuPG option or flag. For example, if we wanted to pass GnuPG option or flag. For example, if we wanted to
"--encrypt --recipient isis@leap.se" to gpg, then pass ``"--encrypt --recipient isis@leap.se"`` to
"--encrypt" would be an arg without a value, and GnuPG, then ``"--encrypt"`` would be an arg without a
"--recipient" would also be an arg, with a value of value, and ``"--recipient"`` would also be an arg,
"isis@leap.se". with a value of ``"isis@leap.se"``.
:ivar list checked: The sanitised, allowed options and values. :ivar list checked: The sanitised, allowed options and values.
:rtype: str :rtype: str
:returns: A string of the items in ``checked`` delimited by spaces. :returns: A string of the items in ``checked``, delimited by spaces.
""" """
checked = str() checked = str()
none_options = _get_options_group("none_options") none_options = _get_options_group("none_options")
@ -573,21 +581,22 @@ def _get_all_gnupg_options():
This is hardcoded within a local scope to reduce the chance of a tampered This is hardcoded within a local scope to reduce the chance of a tampered
GnuPG binary reporting falsified option sets, i.e. because certain options GnuPG binary reporting falsified option sets, i.e. because certain options
(namedly the '--no-options' option, which prevents the usage of gpg.conf (namedly the ``--no-options`` option, which prevents the usage of gpg.conf
files) are necessary and statically specified in files) are necessary and statically specified in
:meth:`gnupg.GPG._makeargs`, if the inputs into Python are already :meth:`gnupg._meta.GPGBase._make_args`, if the inputs into Python are
controlled, and we were to summon the GnuPG binary to ask it for its already controlled, and we were to summon the GnuPG binary to ask it for
options, it would be possible to receive a falsified options set missing its options, it would be possible to receive a falsified options set
the '--no-options' option in response. This seems unlikely, and the method missing the ``--no-options`` option in response. This seems unlikely, and
is stupid and ugly, but at least we'll never have to debug whether or not the method is stupid and ugly, but at least we'll never have to debug
an option *actually* disappeared in a different GnuPG version, or some whether or not an option *actually* disappeared in a different GnuPG
funny business is happening. version, or some funny business is happening.
These are the options as of GnuPG 1.4.12; the current stable branch of the These are the options as of GnuPG 1.4.12; the current stable branch of the
2.1.x tree contains a few more -- if you need them you'll have to add them 2.1.x tree contains a few more -- if you need them you'll have to add them
in here. in here.
:ivar frozenset gnupg_options: All known GPG options and flags. :type gnupg_options: frozenset
:ivar gnupg_options: All known GPG options and flags.
:rtype: frozenset :rtype: frozenset
:returns: ``gnupg_options`` :returns: ``gnupg_options``
""" """
@ -790,8 +799,8 @@ def progress(status_code):
class GenKey(object): class GenKey(object):
"""Handle status messages for key generation. """Handle status messages for key generation.
Calling the GenKey.__str__() method of this class will return the Calling the ``__str__()`` method of this class will return the generated
generated key's fingerprint, or a status string explaining the results. key's fingerprint, or a status string explaining the results.
""" """
def __init__(self, gpg): def __init__(self, gpg):
self._gpg = gpg self._gpg = gpg
@ -802,11 +811,13 @@ class GenKey(object):
self.status = None self.status = None
self.subkey_created = False self.subkey_created = False
self.primary_created = False self.primary_created = False
#: This will store the filename of the key's public keyring if #: This will store the key's public keyring filename, if
#: :meth:`GPG.gen_key_input` was called with ``separate_keyring=True`` #: :meth:`~gnupg.GPG.gen_key_input` was called with
#: ``separate_keyring=True``.
self.keyring = None self.keyring = None
#: This will store the filename of the key's secret keyring if #: This will store the key's secret keyring filename, if :
#: :meth:`GPG.gen_key_input` was called with ``separate_keyring=True`` #: :meth:`~gnupg.GPG.gen_key_input` was called with
#: ``separate_keyring=True``.
self.secring = None self.secring = None
def __nonzero__(self): def __nonzero__(self):
@ -826,7 +837,7 @@ class GenKey(object):
def _handle_status(self, key, value): def _handle_status(self, key, value):
"""Parse a status code from the attached GnuPG process. """Parse a status code from the attached GnuPG process.
:raises: :exc:`ValueError` if the status message is unknown. :raises: :exc:`~exceptions.ValueError` if the status message is unknown.
""" """
if key in ("GOOD_PASSPHRASE"): if key in ("GOOD_PASSPHRASE"):
pass pass
@ -863,7 +874,7 @@ class DeleteResult(object):
def _handle_status(self, key, value): def _handle_status(self, key, value):
"""Parse a status code from the attached GnuPG process. """Parse a status code from the attached GnuPG process.
:raises: :exc:`ValueError` if the status message is unknown. :raises: :exc:`~exceptions.ValueError` if the status message is unknown.
""" """
if key == "DELETE_PROBLEM": if key == "DELETE_PROBLEM":
self.status = self.problem_reason.get(value, "Unknown error: %r" self.status = self.problem_reason.get(value, "Unknown error: %r"
@ -908,7 +919,7 @@ class Sign(object):
def _handle_status(self, key, value): def _handle_status(self, key, value):
"""Parse a status code from the attached GnuPG process. """Parse a status code from the attached GnuPG process.
:raises: :exc:`ValueError` if the status message is unknown. :raises: :exc:`~exceptions.ValueError` if the status message is unknown.
""" """
if key in ("USERID_HINT", "NEED_PASSPHRASE", "BAD_PASSPHRASE", if key in ("USERID_HINT", "NEED_PASSPHRASE", "BAD_PASSPHRASE",
"GOOD_PASSPHRASE", "BEGIN_SIGNING", "CARDCTRL", "GOOD_PASSPHRASE", "BEGIN_SIGNING", "CARDCTRL",
@ -1040,7 +1051,7 @@ class ImportResult(object):
def _handle_status(self, key, value): def _handle_status(self, key, value):
"""Parse a status code from the attached GnuPG process. """Parse a status code from the attached GnuPG process.
:raises: :exc:`ValueError` if the status message is unknown. :raises: :exc:`~exceptions.ValueError` if the status message is unknown.
""" """
if key == "IMPORTED": if key == "IMPORTED":
# this duplicates info we already see in import_ok & import_problem # this duplicates info we already see in import_ok & import_problem
@ -1186,7 +1197,7 @@ class Verify(object):
def _handle_status(self, key, value): def _handle_status(self, key, value):
"""Parse a status code from the attached GnuPG process. """Parse a status code from the attached GnuPG process.
:raises: :exc:`ValueError` if the status message is unknown. :raises: :exc:`~exceptions.ValueError` if the status message is unknown.
""" """
if key in self.TRUST_LEVELS: if key in self.TRUST_LEVELS:
self.trust_text = key self.trust_text = key
@ -1281,7 +1292,7 @@ class Crypt(Verify):
def _handle_status(self, key, value): def _handle_status(self, key, value):
"""Parse a status code from the attached GnuPG process. """Parse a status code from the attached GnuPG process.
:raises: :exc:`ValueError` if the status message is unknown. :raises: :exc:`~exceptions.ValueError` if the status message is unknown.
""" """
if key in ("ENC_TO", "USERID_HINT", "GOODMDC", "END_DECRYPTION", if key in ("ENC_TO", "USERID_HINT", "GOODMDC", "END_DECRYPTION",
"BEGIN_SIGNING", "NO_SECKEY", "ERROR", "NODATA", "BEGIN_SIGNING", "NO_SECKEY", "ERROR", "NODATA",
@ -1348,7 +1359,7 @@ class ListPackets(object):
def _handle_status(self, key, value): def _handle_status(self, key, value):
"""Parse a status code from the attached GnuPG process. """Parse a status code from the attached GnuPG process.
:raises: :exc:`ValueError` if the status message is unknown. :raises: :exc:`~exceptions.ValueError` if the status message is unknown.
""" """
if key == 'NODATA': if key == 'NODATA':
self.status = nodata(value) self.status = nodata(value)