README.txt in Secure Cookie Data 7

Secure Data Cookie
==================

Introduction
------------

**Secure Data Cookie** is a module that implements the [Secure Cookie
Protocol](http://www.cs.utexas.edu/~gouda/papers/conference/cookie.pdf).
This protocol garantuees that cookies cannot be tampered.

Tamper resistance is achieved through the use of an HMAC that validates
the data stored in the cookie each time the data is retrieved. If the
validation fails an empty object is returned.

Design goals
------------

The goals we aim for are two:

1.  Have a way to store data in a cookie so that this data cannot be
    tampered with.

2.  Have data confidentiality. Note that at the moment that's not yet
    implemented.

Target Audience
---------------

This is a module aimed at **developers** or to site builders that
*dabble* in development to put it bluntly.

Use Cases
---------

Use cases for the module are whenever **security** and/or
**performance** are at play.

It's common for module developers to use session variables to store some
particular settings that are specific to a given user. This practices
raises two issues:

1.  As soon as you store anything in a session, i.e., *write* to
    `$_SESSION`, Drupal starts a session, sending a cookie with a
    session token. This invalidates the vast majority of caching
    strategies.

2.  When setting a session variable you hit the persistence layer.
    Meaning the database in most cases. Therefore hurting performance.

This module addresses these issues by maintaining whatever it is you
need to store between the client and the server. The overhead in terms
of HTTP payload size is negligable relative to the common Drupal size
page.

Howto Use
---------

The module provides two functions to be used in your module to store and
retrieve data from the cookie.

### Setting/modifying a cookie

Invoke `secure_data_cookie_put()` where `` is the data you
want to store in the cookie. By default the cookie is called
`SecureCookieData`. The name can be altered through the
`SecureCookieBasic` class `$__cookie_name` attribute.

Usually you have the data in a serialized format. JSON is particularly
useful. Here's a complete example:

    secure_cookie_data_put(json_encode(array('arg' => 'property_one')));

this creates a cookie (named `SecureDataCookie` by default)with the
given name containing a base64 encoding of the data:

    eyJhcmciOiJ0ZXN0WVVZZ2hnaFVtZTM0NTUiLCJobWFjIjoiZThhNmVmNmNmNjFiMTMxZGZmMDcxMzhiZDcyYTdmNTkwM2I1YzY5NiJ9

Now to recover the value you do:

    secure_cookie_data_get();

that prints the initial array.

You can modify the default secret used for computing the HMAC. You set
the attribute `secureCookieBasic::$__secret`.

That's it.

Final Remarks
-------------

Note that the secret generation could be done automatically upon
install. Nevertheless that would void one of the design goals which is
to avoid hitting the database at all. Since setting the value in install
would envolve using a variable, hence the database.

Even if it's a little less convenient, the gains in terms of simplicity
and performance justify it largely.

TODO
----

-   Implement cookie data confidentiality using crypto.

Acknowledgements
----------------

The development and maintenance of this module is sponsored by [Commerce
Guys](http://commerceguys.com).