1.0.0

Author: Integralist

.gitignore

@@ -0,0 +1 @@
+.mypy_cache

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Change Log
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](http://keepachangelog.com/)
+and this project adheres to [Semantic Versioning](http://semver.org/).
+
+## [1.0.0] - 2018-04-23
+### Added
+- initial release.

MANIFEST.in

@@ -0,0 +1,2 @@
+include VERSION
+include README.md

README.md

@@ -0,0 +1,50 @@
+# Python Encryption
+
+This library provides three functions:
+
+1. `generate_digest`
+2. `decrypt_digest`
+3. `validate_digest`
+
+### generate_digest
+
+This is a multi-arity function that will generate a digest using either a password-based key derivation function ([KDF](https://en.wikipedia.org/wiki/Key_derivation_function)) or a [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) depending on the input given.
+
+If a `password` argument is provided, then KDF will be used (along with a random salt) to generate a _non-deterministic_ digest.
+
+If a `salt` is provided, then a PBKDF2 will be used to generate a _deterministic_ digest.
+
+> Note: salts should be a minimum of 128bits (~16 characters) in length.
+
+### KDF or PBKDF2 ?
+
+It's recommended you use KDF (i.e. provide a `password` argument to the `generate_digest` function), this is because they're designed to be more computationally intensive than standard hashing functions and so are harder to use dictionary or rainbow table style attacks (as they would require a lot of extra memory resources and become more unfeasible as an attack vector).
+
+By default the KDF will have a maximum computational time of `0.5`, but this can be overridden using the `maxtime` argument.
+
+A PBKDF2 is able to provide deterministic output (and the ability to specify an explicit salt value). The internal implementation will repeat its process multiple times, thus reducing the feasibility of automated password cracking attempts.
+
+> Note: when specifying a maxtime with `generate_digest`, ensure you include that same value when decrypting with `decrypt_digest` or validating via `validate_digest`.
+
+### decrypt_digest and validate_digest
+
+The `decrypt_digest` and `validate_digest` functions only apply to digests that have been generated using a password (i.e. KDF). Given the right password `decrypt_digest` will return the original message, and thus is considered more a form of symmetrical encryption than a straight one-way hash function. The `validate_digest` function will return a boolean true or false if the given password was able to decrypt the message.
+
+## Usage
+
+See the [tests](tests/test_interface.py) for examples of how to use these functions.
+
+## Tests
+
+See [tests](tests/test_interface.py).
+
+## Dependencies
+
+We have two dependency files:
+
+* `requirements.txt`
+* `requirements-to-freeze.txt`
+
+The latter should contain both 'explicit' versions (i.e. versions of dependencies our service is known to support) and 'non-explicit' versions (e.g. no versions defined), where as the former (`requirements.txt`) simply acts as a lockfile.
+
+If we execute `pip freeze` the output will include dependencies that have the explicit versions we requested and the _latest_ version for those dependencies where we defined no explicit version. We can direct that output to a new file called `requirements.txt`.

VERSION

@@ -0,0 +1 @@
+1.0.0

requirements-to-freeze.txt

@@ -0,0 +1,7 @@
+scrypt>=0.8.6
+
+# dev requirements
+flake8
+mock
+pytest
+pytest-cov

requirements.txt

@@ -0,0 +1,18 @@
+scrypt==0.8.6
+
+# dev requirements
+flake8==3.5.0
+mock==2.0.0
+pytest==3.5.1
+pytest-cov==2.5.1
+## The following requirements were added by pip freeze:
+attrs==17.4.0
+coverage==4.5.1
+mccabe==0.6.1
+more-itertools==4.1.0
+pbr==4.0.2
+pluggy==0.6.0
+py==1.5.3
+pycodestyle==2.3.1
+pyflakes==1.6.0
+six==1.11.0

secure/__init__.py

@@ -0,0 +1,50 @@
+import scrypt
+
+from typing import Union
+
+
+class ArgumentError(Exception):
+    pass
+
+
+def generate_digest(message: str,
+                    password: str = None,
+                    maxtime: Union[float, int] = 0.5,
+                    salt: str = "",
+                    length: int = 64) -> bytes:
+    """Multi-arity function for generating a digest.
+
+    Use KDF symmetric encryption given a password.
+    Use deterministic hash function given a salt (or lack of password).
+    """
+
+    if password and salt:
+        raise ArgumentError("only provide a password or a salt, not both")
+
+    if salt != "" and len(salt) < 16:
+        raise ArgumentError("salts need to be minimum of 128bits (~16 characters)")
+
+    if password:
+        return scrypt.encrypt(message, password, maxtime=maxtime)
+    else:
+        return scrypt.hash(message, salt, buflen=length)
+
+
+def decrypt_digest(digest: bytes,
+                   password: str,
+                   maxtime: Union[float, int] = 0.5) -> bytes:
+    """Decrypts digest using given password."""
+
+    return scrypt.decrypt(digest, password, maxtime)
+
+
+def validate_digest(digest: bytes,
+                    password: str,
+                    maxtime: Union[float, int] = 0.5) -> bool:
+    """Validate digest using given password."""
+
+    try:
+        scrypt.decrypt(digest, password, maxtime)
+        return True
+    except scrypt.error:
+        return False

secure/interface.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+
+from os import path
+from setuptools import setup, find_packages
+
+BASE_DIR = path.abspath(path.dirname(__file__))
+
+
+def read(f):
+    with open(path.join(BASE_DIR, f)) as fh:
+        return fh.read()
+
+
+def get_version():
+    version = read('VERSION').strip()
+    if not version:
+        raise RuntimeError('Cannot find version information')
+    return version
+
+
+install_requires = []
+
+setup(
+    name='secure',
+    version=get_version(),
+    description='Provides standard interface for hashing, encrypting, decrypting and verifying user input',
+    long_description=read('README.md'),
+    author='Integralist',
+    url='https://github.com/integralist/Python-Encryption',
+    packages=find_packages(),
+    install_requires=install_requires,
+    keywords='integralist hash hashing encryption decryption library scrypt'
+)