Permalink
Browse files

Cookie Encryption: adding documentation.

  • Loading branch information...
1 parent 3b7a4b1 commit c41ac9cb614df2fe439abbce4baa5ea4fcb52e88 @daschl daschl committed Sep 12, 2011
Showing with 38 additions and 23 deletions.
  1. +38 −23 storage/session/strategy/Encrypt.php
@@ -12,7 +12,10 @@
/**
* This strategy allows you to encrypt your `Session` and / or `Cookie` data so that it
- * is not stored in cleartext on the client side.
+ * is not stored in cleartext on the client side. You must provide a secret key, otherwise
+ * an exception is raised.
+ *
+ * To use this class, you need to have the `mcrypt` extension enabled.
*
* Example configuration:
*
@@ -23,20 +26,28 @@
* )));
* }}}
*
- * By default, this strategy uses the AES algorithm in the CBC mode. You can override this
+ * By default, this strategy uses the AES algorithm in the CBC mode. This means that an
+ * initialization vector has to be generated and transported with the payload data. This
+ * is done transparently, but you may want to keep this in mind (the ECB mode doesn't require
+ * an itialization vector but is not recommended to use as it's insecure). You can override this
* defaults by passing a different `cipher` and/or `mode` to the config like this:
*
* {{{
* Session::config(array('default' => array(
* 'adapter' => 'Cookie',
* 'strategies' => array('Encrypt' => array(
* 'cipher' => MCRYPT_RIJNDAEL_128,
- * 'mode' => MCRYPT_MODE_ECB,
+ * 'mode' => MCRYPT_MODE_ECB, // Don't use ECB when you don't have to!
* 'secret' => 'foobar'
* ))
* )));
* }}}
+ *
+ * Please keep in mind that it is generally not a good idea to store sensitive information in
+ * cookies (or generally on the client side) and this class is no exception to the rule. It allows
+ * you to store client side data in a more secure way, but 100% security can't be achieved.
*
+ * @link http://php.net/manual/en/book.mcrypt.php The mcrypt extension.
* @link http://www.php.net/manual/en/mcrypt.ciphers.php List of supported ciphers.
* @link http://www.php.net/manual/en/mcrypt.constants.php List of supported modes.
*/
@@ -53,6 +64,9 @@ class Encrypt extends \lithium\core\Object {
* @param array $config Configuration array. You can override the default cipher and mode.
*/
public function __construct(array $config = array()) {
+ if(!static::enabled()) {
+ throw new ConfigException("The Mcrypt extension is not installed or enabled.");
+ }
if (!isset($config['secret'])) {
throw new ConfigException("Encrypt strategy requires a secret key.");
}
@@ -62,16 +76,17 @@ public function __construct(array $config = array()) {
);
parent::__construct($config + $defaults);
- extract($this->_config);
+ $cipher = $this->_config['cipher'];
+ $mode = $this->_config['mode'];
$this->_config['vector'] = static::_vector($cipher, $mode);
}
/**
* Read encryption method.
- *
- * @param
- * @param
- * @return
+ *
+ * @param array $data the Data being read.
+ * @param array $options Options for this method.
+ * @return mixed Returns the decrypted key or the dataset.
*/
public function read($data, array $options = array()) {
$class = $options['class'];
@@ -95,9 +110,9 @@ public function read($data, array $options = array()) {
/**
* Write encryption method.
*
- * @param
- * @param
- * @return
+ * @param mixed $data The data to be encrypted.
+ * @param array $options Options for this method.
+ * @return string Returns the written data in cleartext.
*/
public function write($data, array $options = array()) {
$class = $options['class'];
@@ -114,9 +129,9 @@ public function write($data, array $options = array()) {
/**
* Delete encryption method.
*
- * @param
- * @param
- * @return
+ * @param mixed $data The data to be encrypted.
+ * @param array $options Options for this method.
+ * @return string Returns the deleted data in cleartext.
*/
public function delete($data, array $options = array()) {
$class = $options['class'];
@@ -142,8 +157,8 @@ public static function enabled() {
/**
* Serialize and encrypt a given data array.
*
- * @param
- * @return
+ * @param array The cleartext data to be encrypted.
+ * @return string A Base64 encoded and encrypted string.
*/
protected function _encrypt($decrypted = array()) {
extract($this->_config);
@@ -157,8 +172,8 @@ protected function _encrypt($decrypted = array()) {
/**
* Decrypt and unserialize a previously encrypted string.
*
- * @param
- * @return
+ * @param string a Base64 encoded and encrypted string.
+ * @return array The cleartext data.
*/
protected function _decrypt($encrypted) {
extract($this->_config);
@@ -176,8 +191,8 @@ protected function _decrypt($encrypted) {
/**
* Generates an initialization vector.
*
- * @param
- * @param
+ * @param string The cipher for the initialization vector.
+ * @param string The mode for the initialization vector.
* @return string Returns an initialization vector.
* @link http://www.php.net/manual/en/function.mcrypt-create-iv.php
*/
@@ -193,9 +208,9 @@ protected static function _vector($cipher, $mode) {
/**
* Returns the vector size vor a given cipher and mode.
*
- * @param
- * @param
- * @return
+ * @param string The cipher for the initialization vector.
+ * @param string The mode for the initialization vector.
+ * @return number The vector size.
*/
protected static function _vectorSize($cipher, $mode) {
return mcrypt_get_iv_size($cipher, $mode);

0 comments on commit c41ac9c

Please sign in to comment.