From b7f1d1064ad08bba211240251264aa905b5361f3 Mon Sep 17 00:00:00 2001 From: Siddharth Ravikumar Date: Thu, 24 Dec 2015 16:14:21 -0500 Subject: Rewrote docstrings in combox.crypto module. It is sphinx friendly now. --- combox/crypto.py | 129 ++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 100 insertions(+), 29 deletions(-) (limited to 'combox') diff --git a/combox/crypto.py b/combox/crypto.py index b35a700..b2091e6 100644 --- a/combox/crypto.py +++ b/combox/crypto.py @@ -35,13 +35,26 @@ from datetime import datetime from os import path BLOCK_SIZE = 32 +"""Specifies the block size of the data that is given to crypto functions. + +""" + PAD_CHAR = '#' +"""Character for padding data to make it a multiple of :data:`BLOCK_SIZE`. +""" def pad(data): - """Pad data such that its length is a multiple of BLOCK_SIZE. - """ + """Pad `data` such that its length is a multiple of :data:`BLOCK_SIZE`. + :param str data: + A string that needs to be padded so that its total length is a + multiple of :data:`BLOCK_SIZE`. + :returns: + Padded data whose length is a multiple of :data:`BLOCK_SIZE`. + :rtype: str + + """ padding = (BLOCK_SIZE - (len(data) % BLOCK_SIZE)) * PAD_CHAR data += padding @@ -49,29 +62,53 @@ def pad(data): def encrypt(data, secret): - """Encrypt byestream and return cipher. + """Encrypt `data` and return cipher. + + :param str data: + Data to encrypt. + :param str secret: + The key to encrypt the `data` with. + :returns: + Encrypted `data` as :mod:`base64` encoded string. + :rtype: str + """ aes = AES.new(pad(secret)) cipher = base64.b64encode(aes.encrypt(pad(data))) - + return cipher def decrypt(cipher, secret): - """Decrypt cipher and return data. + """Decrypt `cipher` and return data. + + :param str cipher: + Encrypted data to decrypt. + :param str secret: + The key to decrypt the `cipher` with. + :returns: + Decrypted data. + :rtype: str + """ aes = AES.new(pad(secret)) data = aes.decrypt(base64.b64decode(cipher)).rstrip(PAD_CHAR) return data + def encrypt_shards(shards, secret): - """Encrypt the shards of data and return a list of ciphers. + """Encrypt the `shards` of data and return a list of ciphers. - shards: list of shards (string, bytes). - secret: top secret passphrase - """ + :param list shards: + List of shards (strings). + :param str secret: + The key to encrypt each shard. + :returns: + List containing the encrypted shards. + :rtype: list + """ ciphers = [] for shard in shards: cipher = encrypt(shard, secret) @@ -83,10 +120,15 @@ def encrypt_shards(shards, secret): def decrypt_shards(ciphers, secret): """Decrypt the ciphered shards and return a list of shards. - shards: list of ciphered shards. - secret: top secret passphrase - """ + :param list ciphers: + List of encrypted shards (strings). + :param str secret: + The key to decrypt each shard. + :returns: + List containing the decrypted shards. + :rtype: list + """ shards = [] for cipher in ciphers: shard = decrypt(cipher, secret) @@ -96,17 +138,41 @@ def decrypt_shards(ciphers, secret): def split_and_encrypt(fpath, config, fcontent=None): - """Splits the file, encrypts the shards and writes them to the nodes. - - fpath: The path to file that has to be split. - config: The dictonary containing the combox configuration information. - fcontent: Contents of the file at `fpath' (optional). + """Splits file `fpath` into shards, encrypts the shards and spreads the shards across the node directories. + + Information about the node directories must be contained with the + `config` dictionary; structure of the `config` dict:: + + { + 'combox_dir': '/home/rsd/combox/', + 'nodes_info': { + 'node-1': { + 'available': '1024', + 'path': '/home/rsd/combox-nodes/Dropbox', + 'size': '1024' + }, + 'node-0': { + 'available': '1024', + 'path': '/home/rsd/combox-nodes/Googl-Drive/', + 'size': '1024' + } + }, + 'silo_dir': '/home/rsd/bgc/combox/tests/test-config', + 'topsecret': 'topsecret', + 'combox_name': 'testbox' + } + + :param str fpath: + Path to an existent file. + :param dict config: + A dictionary that contains configuration information about + combox. + :param str fcontent: + Contents of the file at `fpath` (optional). When `None`, the + content of the file is read from disk; otherwise it just + assumes `fcontent` is the content of the file. - If `fcontent' is None, then this function reads the contents of - the file; otherwise it just assumes `fcontent' is the content of - the file. """ - start = datetime.now() rel_path = relative_path(fpath, config) @@ -137,17 +203,22 @@ def split_and_encrypt(fpath, config, fcontent=None): log_i('Took %f ms to split and encrypt %s' % (duration, fpath)) - def decrypt_and_glue(fpath, config, write=True): + """Reads encrypted shards from the node directories, decrypts and reconstructs `fpath`. + + :param str fpath: + The path to a file under the combox directory that has to be + decrypted and glued from the node directories. + :param dict config: + A dictionary that contains configuration information about + combox. + :param bool write: + If `True`, writes the reconstructed content to disk. + :returns: + The glued content. + :rtype: str """ - Reads encrypted shards, decrypts and glues them. - - fpath: The path to file that has to be decrypted & glued from the nodes. - config: The dictionary containing the combox configuration information. - write: If set, writes the reconstructed file's content to disk. - """ - rel_path = relative_path(fpath, config) f = path.abspath(fpath) -- cgit v1.2.3