Arthur de Jong

Open Source / Free Software developer

summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorArthur de Jong <arthur@arthurdejong.org>2014-04-19 17:58:00 +0200
committerArthur de Jong <arthur@arthurdejong.org>2014-04-19 21:53:58 +0200
commit285860e4bad7ed442be267b3e537ebb11978bfa7 (patch)
treebf099b825eb17b3d046eec679230584d79b9d3ce
parent8c9e03d942397603fa653b96c62ecaa5b52e303f (diff)
Provide pskc.encryption docstrings
This documents classes in the pskc.encryption module.
-rw-r--r--pskc/encryption.py46
1 files changed, 41 insertions, 5 deletions
diff --git a/pskc/encryption.py b/pskc/encryption.py
index d98871a..a1412d1 100644
--- a/pskc/encryption.py
+++ b/pskc/encryption.py
@@ -18,6 +18,16 @@
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
# 02110-1301 USA
+"""Module that handles encrypted PSKC values.
+
+This module defines an Encryption class that handles the encryption key
+and an EncryptedValue wrapper class that can decrypt values using the
+encryption key.
+
+The encryption key can be derived using the KeyDerivation class.
+"""
+
+
import base64
from Crypto.Cipher import AES
@@ -38,13 +48,13 @@ class EncryptedValue(object):
def __init__(self, encryption, encrypted_value=None):
"""Initialise an encrypted value for the provided Key."""
+ self.encryption = encryption
self.algorithm = None
self.cipher_value = None
- self.encryption = encryption
self.parse(encrypted_value)
def parse(self, encrypted_value):
- """Read encrypted data from the EncryptedValue XML tree."""
+ """Read encrypted data from the <EncryptedValue> XML tree."""
from pskc.parse import g_e_v, namespaces
if encrypted_value is None:
return
@@ -76,7 +86,16 @@ PBKDF2_URIS = [
class KeyDerivation(object):
- """Handle derived keys."""
+ """Handle key derivation.
+
+ The algorithm property contains the key derivation algorithm to use. For
+ PBDKF2 the following parameters are set:
+
+ pbkdf2_salt: salt value
+ pbkdf2_iterations: number of iterations to use
+ pbkdf2_key_length: required key lengt
+ pbkdf2_prf: name of pseudorandom function used (HMAC-SHA1 is assumed)
+ """
def __init__(self, key_deriviation=None):
self.algorithm = None
@@ -88,6 +107,7 @@ class KeyDerivation(object):
self.parse(key_deriviation)
def parse(self, key_deriviation):
+ """Read derivation parameters from a <KeyDerivationMethod> element."""
from pskc.parse import g_e_v, g_e_i, namespaces
if key_deriviation is None:
return
@@ -113,6 +133,7 @@ class KeyDerivation(object):
self.pbkdf2_prf = prf.attrib.get('Algorithm')
def generate(self, password):
+ """Derive a key from the password."""
if self.algorithm in PBKDF2_URIS:
# TODO: support pseudorandom function (prf)
return PBKDF2(
@@ -121,7 +142,20 @@ class KeyDerivation(object):
class Encryption(object):
- """Class for handling encryption keys that are used in the PSKC file."""
+ """Class for handling encryption keys that are used in the PSKC file.
+
+ Encryption generally uses a symmetric key that is used to encrypt some
+ of the information stored in PSKC files (typically the seed). This
+ class provides the following values:
+
+ id: identifier of the key
+ key_names: list of names for the key
+ key_name: (first) name of the key (usually there is only one)
+ key: the key value itself (binary form)
+
+ The key can either be included in the PSKC file (in that case it
+ automatically picked up) or derived using the derive_key() method.
+ """
def __init__(self, key_info=None):
self.id = None
@@ -131,7 +165,7 @@ class Encryption(object):
self.parse(key_info)
def parse(self, key_info):
- """Read encryption information from the EncryptionKey XML tree."""
+ """Read encryption information from the <EncryptionKey> XML tree."""
from pskc.parse import g_e_v, namespaces
if key_info is None:
return
@@ -148,8 +182,10 @@ class Encryption(object):
@property
def key_name(self):
+ """Provide the name of the (first) key."""
if self.key_names:
return self.key_names[0]
def derive_key(self, password):
+ """Derive a key from the password."""
self.key = self.derivation.generate(password)