spaste Documentation Release 1.0 Ben Webster May 28, 2015
Contents 1 Application Overview 3 1.1 Snippets................................................. 3 1.2 Contact Form............................................... 3 1.3 Extensibility............................................... 4 1.4 Testing.................................................. 4 1.5 Bootstrap................................................. 4 2 Reusable Components 5 2.1 Encrypted Model Fields......................................... 5 2.2 FancyDateWidget............................................ 5 2.3 Custom Decorators............................................ 5 2.4 Functions................................................. 6 2.5 Template Tags.............................................. 6 3 Models 7 4 Functions 9 5 Indices and tables 11 Python Module Index 13 i
ii
spaste Documentation, Release 1.0 spaste is a simple Django application that allows users to send snippets of information over the web. Users first set a snippet expiration and then they can protect it with an optional password and/or a self-destruct view limit. Snippet data is encrypted in the database layer using PyCrypto to achieve at rest data protection for additional security. Contents 1
spaste Documentation, Release 1.0 2 Contents
CHAPTER 1 Application Overview Here you will find a high level overview of the components of the spaste application. 1.1 Snippets Snippets are the heart of the application. The snippet.snippet model is the central basic building block of sharing content on the site. There is also a logging model snippet.snippetlog hooked for future auditing support. 1.1.1 Encryption To better secure sensitive data, the content of the snippet is encrypted in the database using a helper class Encrypted Model Fields. This at rest data encryption provides some protection against data theft, however, any user with shell access to the deployed application can potentially view ALL the secured data. 1.1.2 Ownership The standard Django session django.contrib.sessions.middleware.sessionmiddleware is used to keep inventory of the snippets (primary key list) a user has created as a simple ownership check. Ownership of a snippet means the user has access to view this snippet content and bypass all security checks (expiration date, view limit, and password protection if applicable). The owner is given the share link on this page and both the view limit increment feature is disabled along with any logging. Session Expiration By default, spaste is configured to store sessions in the database via django.contrib.sessions.models.session. It is also persistent by default and will not be cleared on browser close. This was done since there is no user authentication framework for spaste; we want the share list to last indefinitely for an end user as long as they do not clear their cookies. A future version may expand this to am optional full user authentication system. 1.2 Contact Form A simple form to allow end users to contact the site manager(s) (defined in spaste/settings.py). 3
spaste Documentation, Release 1.0 1.3 Extensibility Even though the application could have been written as direct methods throughout, a number of features were instead encapsulated into reusable components. Future versions of spaste should be able to leverage these objects and by abstracting certain classes, decorators, and widgets we can keep close to the DRY Principle. Encrypted Model Fields - Contains Model field Classes to store encrypted data FancyDateWidget - A jquery UI Datepicker form widget Custom Decorators - View decorators for rendering content Functions - A collection of useful functions Template Tags - Custom Django template tags 1.4 Testing Unit tests have been created for Snippets. Before any codebase changes are committed to the repository a full test execution should be run:./manage.py test Unit tests should be created / updated as necessary as the codebase is modified as well. It may be advisable to follow the principles of test-driven development, that is writing your tests before writing your code. 1.5 Bootstrap The front-end uses Twitter Bootstrap v3 as a design framework. A base template base.html is used as the global layout for all pages (fixed navbar, main, sidebar, footer) and a number of blocks have been created for inheritance purposes. 1.5.1 Compressor All CSS and JS in the templates can be combined and compressed through the Django Compressor package. For development this is probably best left off but for production simply edit the local settings spaste/local_settings.py and enable the compressor: COMPRESS_ENABLED = True 4 Chapter 1. Application Overview
CHAPTER 2 Reusable Components 2.1 Encrypted Model Fields This code is based on the Django Snippet #1095. There are 2 base subfields models (EncryptedTextField, EncryptedCharField) which are themselves derived from the core BaseEncryptedField class. All encryption and decryption is done transparently and defaults to use AES using pycrypto. Encryption is performed by using the site s SECRET_KEY as a cipher. The field size is padded for encrypted content (so we could have up to block_size + 1) as a maximum field length and the overridden call to get_db_prep_value ensures that we do not exceed the database s own constraints on it s field lengths. 2.2 FancyDateWidget An extension of Django s DateTimeInput widget with a jquery UI DatePicker hook. The date_widget class will be added (or appended) to the field s input tag and the datepicker() widget will be instantiated by the base object s ID. At this time no additional arguments can be passed to the UI widget; this should probably be enchanced in a future version. 2.3 Custom Decorators Used as a convenient shortcut for rendering content in the view. 2.3.1 render_to Decorator that sends returned dict to render_to_response function with given template and RequestContext as context instance. 2.3.2 ajax_request If view returns a dictionary it is converted into a JsonResponse. The view must be a POST request. If these conditions are not met a JSON error is returned instead. 5
spaste Documentation, Release 1.0 2.4 Functions A bunch of helpful functions called throughout the application. See Functions for methods. 2.5 Template Tags Custom Django templatetags. 2.5.1 navactive CSS selector for highlighting active navigation elements on the page. Detects the URL in the current request object and compares it to the given named URL pattern. 6 Chapter 2. Reusable Components
CHAPTER 3 Models class helpers.encryptedfield.baseencryptedfield(*args, **kwargs) This code is based on the djangosnippet #1095 You can find the original at http://www.djangosnippets.org/snippets/1095/ 7
spaste Documentation, Release 1.0 8 Chapter 3. Models
CHAPTER 4 Functions helpers.functions.get_hashkey(content, expires= ) helpers.functions.get_ip(request) Retrieves the remote IP address from the request data. If the user is behind a proxy, they may have a commaseparated list of IP addresses, so we need to account for that. In such a case, only the first IP in the list will be retrieved. Also, some hosts that use a proxy will put the REMOTE_ADDR into HTTP_X_FORWARDED_FOR. This will handle pulling back the IP from the proper place. helpers.functions.get_timeout() Gets any specified timeout from the settings file, or use 10 minutes by default helpers.functions.get_cleanup_timeout() Gets any specified visitor clean-up timeout from the settings file, or use 24 hours by default helpers.functions.u_clean(s) A strange attempt at cleaning up unicode 9
spaste Documentation, Release 1.0 10 Chapter 4. Functions
CHAPTER 5 Indices and tables genindex modindex search 11
spaste Documentation, Release 1.0 12 Chapter 5. Indices and tables
Python Module Index h helpers.encryptedfield, 7 13
spaste Documentation, Release 1.0 14 Python Module Index
Index B BaseEncryptedField (class in helpers.encryptedfield), 7 G get_cleanup_timeout() (in module helpers.functions), 9 get_hashkey() (in module helpers.functions), 9 get_ip() (in module helpers.functions), 9 get_timeout() (in module helpers.functions), 9 H helpers.encryptedfield (module), 7 U u_clean() (in module helpers.functions), 9 15