diff options
Diffstat (limited to 'src/leap/soledad/util.py')
| -rw-r--r-- | src/leap/soledad/util.py | 225 |
1 files changed, 214 insertions, 11 deletions
diff --git a/src/leap/soledad/util.py b/src/leap/soledad/util.py index b8ee4cf3..47e4c78d 100644 --- a/src/leap/soledad/util.py +++ b/src/leap/soledad/util.py @@ -1,3 +1,21 @@ +# -*- coding: utf-8 -*- +# util.py +# Copyright (C) 2013 LEAP +# +# This program is free software: you can redistribute it and/or modify +# it under the terms of the GNU General Public License as published by +# the Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program. If not, see <http://www.gnu.org/licenses/>. + + """ Utilities for Soledad. """ @@ -18,6 +36,12 @@ class ListPackets(): """ def __init__(self, gpg): + """ + Initialize the packet listing handling class. + + @param gpg: GPG object instance. + @type gpg: gnupg.GPG + """ self.gpg = gpg self.nodata = None self.key = None @@ -26,6 +50,14 @@ class ListPackets(): self.userid_hint = None def handle_status(self, key, value): + """ + Handle one line of the --list-packets status message. + + @param key: The status message key. + @type key: str + @param value: The status message value. + @type value: str + """ # TODO: write tests for handle_status if key == 'NODATA': self.nodata = True @@ -52,6 +84,28 @@ class GPGWrapper(gnupg.GPG): def __init__(self, gpgbinary=GNUPG_BINARY, gnupghome=GNUPG_HOME, verbose=False, use_agent=False, keyring=None, options=None): + """ + Initialize a GnuPG process wrapper. + + @param gpgbinary: Name for GnuPG binary executable. + @type gpgbinary: C{str} + @param gpghome: Full pathname to directory containing the public and + private keyrings. + @type gpghome: C{str} + @param keyring: Name of alternative keyring file to use. If specified, + the default keyring is not used. + @param verbose: Should some verbose info be output? + @type verbose: bool + @param use_agent: Should pass `--use-agent` to GPG binary? + @type use_agent: bool + @param keyring: Path for the keyring to use. + @type keyring: str + @options: A list of additional options to pass to the GPG binary. + @type options: list + + @raise: RuntimeError with explanation message if there is a problem + invoking gpg. + """ super(GPGWrapper, self).__init__(gnupghome=gnupghome, gpgbinary=gpgbinary, verbose=verbose, @@ -63,6 +117,14 @@ class GPGWrapper(gnupg.GPG): def find_key_by_email(self, email, secret=False): """ Find user's key based on their email. + + @param email: Email address of key being searched for. + @type email: str + @param secret: Should we search for a secret key? + @type secret: bool + + @return: The fingerprint of the found key. + @rtype: str """ for key in self.list_keys(secret=secret): for uid in key['uids']: @@ -71,6 +133,17 @@ class GPGWrapper(gnupg.GPG): raise LookupError("GnuPG public key for email %s not found!" % email) def find_key_by_subkey(self, subkey, secret=False): + """ + Find user's key based on a subkey fingerprint. + + @param email: Subkey fingerprint of the key being searched for. + @type email: str + @param secret: Should we search for a secret key? + @type secret: bool + + @return: The fingerprint of the found key. + @rtype: str + """ for key in self.list_keys(secret=secret): for sub in key['subkeys']: if sub[0] == subkey: @@ -79,6 +152,17 @@ class GPGWrapper(gnupg.GPG): "GnuPG public key for subkey %s not found!" % subkey) def find_key_by_keyid(self, keyid, secret=False): + """ + Find user's key based on the key ID. + + @param email: The key ID of the key being searched for. + @type email: str + @param secret: Should we search for a secret key? + @type secret: bool + + @return: The fingerprint of the found key. + @rtype: str + """ for key in self.list_keys(secret=secret): if keyid == key['keyid']: return key @@ -86,6 +170,17 @@ class GPGWrapper(gnupg.GPG): "GnuPG public key for keyid %s not found!" % keyid) def find_key_by_fingerprint(self, fingerprint, secret=False): + """ + Find user's key based on the key fingerprint. + + @param email: The fingerprint of the key being searched for. + @type email: str + @param secret: Should we search for a secret key? + @type secret: bool + + @return: The fingerprint of the found key. + @rtype: str + """ for key in self.list_keys(secret=secret): if fingerprint == key['fingerprint']: return key @@ -96,6 +191,24 @@ class GPGWrapper(gnupg.GPG): passphrase=None, symmetric=False): """ Encrypt data using GPG. + + @param data: The data to be encrypted. + @type data: str + @param recipient: The address of the public key to be used. + @type recipient: str + @param sign: Should the encrypted content be signed? + @type sign: bool + @param always_trust: Skip key validation and assume that used keys + are always fully trusted? + @type always_trust: bool + @param passphrase: The passphrase to be used if symmetric encryption + is desired. + @type passphrase: str + @param symmetric: Should we encrypt to a password? + @type symmetric: bool + + @return: An object with encrypted result in the `data` field. + @rtype: gnupg.Crypt """ # TODO: devise a way so we don't need to "always trust". return super(GPGWrapper, self).encrypt(data, recipient, sign=sign, @@ -107,6 +220,18 @@ class GPGWrapper(gnupg.GPG): def decrypt(self, data, always_trust=True, passphrase=None): """ Decrypt data using GPG. + + @param data: The data to be decrypted. + @type data: str + @param always_trust: Skip key validation and assume that used keys + are always fully trusted? + @type always_trust: bool + @param passphrase: The passphrase to be used if symmetric encryption + is desired. + @type passphrase: str + + @return: An object with decrypted result in the `data` field. + @rtype: gnupg.Crypt """ # TODO: devise a way so we don't need to "always trust". return super(GPGWrapper, self).decrypt(data, @@ -116,7 +241,17 @@ class GPGWrapper(gnupg.GPG): def send_keys(self, keyserver, *keyids): """ Send keys to a keyserver + + @param keyserver: The keyserver to send the keys to. + @type keyserver: str + @param keyids: The key ids to send. + @type keyids: list + + @return: A list of keys sent to server. + @rtype: gnupg.ListKeys """ + # TODO: write tests for this. + # TODO: write a SendKeys class to handle status for this. result = self.result_map['list'](self) gnupg.logger.debug('send_keys: %r', keyids) data = gnupg._make_binary_stream("", self.encoding) @@ -131,7 +266,33 @@ class GPGWrapper(gnupg.GPG): always_trust=False, passphrase=None, armor=True, output=None, symmetric=False, cipher_algo=None): - "Encrypt the message read from the file-like object 'file'" + """ + Encrypt the message read from the file-like object 'file'. + + @param file: The file to be encrypted. + @type data: file + @param recipient: The address of the public key to be used. + @type recipient: str + @param sign: Should the encrypted content be signed? + @type sign: bool + @param always_trust: Skip key validation and assume that used keys + are always fully trusted? + @type always_trust: bool + @param passphrase: The passphrase to be used if symmetric encryption + is desired. + @type passphrase: str + @param armor: Create ASCII armored output? + @type armor: bool + @param output: Path of file to write results in. + @type output: str + @param symmetric: Should we encrypt to a password? + @type symmetric: bool + @param cipher_algo: Algorithm to use. + @type cipher_algo: str + + @return: An object with encrypted result in the `data` field. + @rtype: gnupg.Crypt + """ args = ['--encrypt'] if symmetric: args = ['--symmetric'] @@ -158,22 +319,37 @@ class GPGWrapper(gnupg.GPG): logger.debug('encrypt result: %r', result.data) return result - def list_packets(self, raw_data): + def list_packets(self, data): + """ + List the sequence of packets. + + @param data: The data to extract packets from. + @type data: str + + @return: An object with packet info. + @rtype ListPackets + """ args = ["--list-packets"] result = self.result_map['list-packets'](self) self._handle_io( args, - _make_binary_stream(raw_data, self.encoding), + _make_binary_stream(data, self.encoding), result, ) return result - def encrypted_to(self, raw_data): + def encrypted_to(self, data): """ - Return the key to which raw_data is encrypted to. + Return the key to which data is encrypted to. + + @param data: The data to be examined. + @type data: str + + @return: The fingerprint of the key to which data is encrypted to. + @rtype: str """ # TODO: make this support multiple keys. - result = self.list_packets(raw_data) + result = self.list_packets(data) if not result.key: raise LookupError( "Content is not encrypted to a GnuPG key!") @@ -182,13 +358,40 @@ class GPGWrapper(gnupg.GPG): except: return self.find_key_by_subkey(result.key) - def is_encrypted_sym(self, raw_data): - result = self.list_packets(raw_data) + def is_encrypted_sym(self, data): + """ + Say whether some chunk of data is encrypted to a symmetric key. + + @param data: The data to be examined. + @type data: str + + @return: Whether data is encrypted to a symmetric key. + @rtype: bool + """ + result = self.list_packets(data) return bool(result.need_passphrase_sym) - def is_encrypted_asym(self, raw_data): - result = self.list_packets(raw_data) + def is_encrypted_asym(self, data): + """ + Say whether some chunk of data is encrypted to a private key. + + @param data: The data to be examined. + @type data: str + + @return: Whether data is encrypted to a private key. + @rtype: bool + """ + result = self.list_packets(data) return bool(result.key) - def is_encrypted(self, raw_data): + def is_encrypted(self, data): + """ + Say whether some chunk of data is encrypted to a key. + + @param data: The data to be examined. + @type data: str + + @return: Whether data is encrypted to a key. + @rtype: bool + """ self.is_encrypted_asym() or self.is_encrypted_sym() |