summaryrefslogtreecommitdiff
path: root/src/leap/soledad/util.py
diff options
context:
space:
mode:
authordrebs <drebs@leap.se>2013-04-08 12:15:30 -0300
committerdrebs <drebs@leap.se>2013-04-08 12:15:30 -0300
commite6ca75a9e2a7a634f92ae54238df7d86100fbdab (patch)
treedd780d232253867ff26074dde1a7acc2dfb63fee /src/leap/soledad/util.py
parentd2d35a449beb05799bd68a7679f58382f8599152 (diff)
Add a LOT of docstrings.
Diffstat (limited to 'src/leap/soledad/util.py')
-rw-r--r--src/leap/soledad/util.py225
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()