CRM/Utils/Signer.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.5                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2014
  32  * $Id$
  33  *
  34  */
  35
  36 /**
  37  * A utility which signs and verifies a list of key-value pairs
  38  *
  39  * FIXME: Add TTL support?
  40  *
  41  * @code
  42  * $signer = new CRM_Utils_Signer('myprivatekey', array('param1','param2'));
  43  * $params = array(
  44  *   'param1' => 'hello',
  45  *   'param2' => 'world',
  46  * );
  47  * $token = $signer->sign($params);
  48  * ...
  49  * assertTrue($signer->validate($token, $params));
  50  * @endcode
  51  */
  52 class CRM_Utils_Signer {
  53   /**
  54    * Expected length of the salt
  55    *
  56    * @var int
  57    */
  58   const SALT_LEN = 4;
  59
  60   /**
  61    * Instantiate a signature-processor
  62    *
  63    * @param $secret string, private
  64    * @param $paramNames array, fields which should be part of the signature
  65    */
  66   function __construct($secret, $paramNames) {
  67     sort($paramNames); // ensure consistent serialization of payloads
  68     $this->secret = $secret;
  69     $this->paramNames = $paramNames;
  70     $this->signDelim = "_"; // chosen to be valid in URLs but not in salt or md5
  71     $this->defaultSalt = CRM_Utils_String::createRandom(self::SALT_LEN, CRM_Utils_String::ALPHANUMERIC);
  72   }
  73
  74   /**
  75    * Generate a signature for a set of key-value pairs
  76    *
  77    * @param $params array, key-value pairs
  78    * @param $salt string, the salt (if known) or NULL (for auto-generated)
  79    * @return string, the full public token representing the signature
  80    */
  81   function sign($params, $salt = NULL) {
  82     $message = array();
  83     $message['secret'] = $this->secret;
  84     $message['payload'] = array();
  85     if (empty($salt)) {
  86       $message['salt'] = $this->createSalt();
  87     } else {
  88       $message['salt'] =  $salt;
  89     }
  90     // recall: paramNames is pre-sorted for stability
  91     foreach ($this->paramNames as $paramName) {
  92       if (isset($params[$paramName])) {
  93         if (is_numeric($params[$paramName])) {
  94           $params[$paramName] = (string) $params[$paramName];
  95         }
  96       } else { // $paramName is not included or ===NULL
  97         $params[$paramName] = '';
  98       }
  99         $message['payload'][$paramName] = $params[$paramName];
 100       }
 101     $token = $message['salt'] . $this->signDelim . md5(serialize($message));
 102     return $token;
 103   }
 104
 105   /**
 106    * Determine whether a token represents a proper signature for $params
 107    *
 108    * @param $token string, the full public token representing the signature
 109    * @param $params array, key-value pairs
 110    *
 111    * @throws Exception
 112    * @return bool, TRUE iff all $paramNames for the submitted validate($params) and the original sign($params)
 113    */
 114   function validate($token, $params) {
 115     list ($salt, $signature) = explode($this->signDelim, $token);
 116     if (strlen($salt) != self::SALT_LEN) {
 117       throw new Exception("Invalid salt [$token]=[$salt][$signature]");
 118     }
 119     $newToken = $this->sign($params, $salt);
 120     return ($token == $newToken);
 121   }
 122
 123   /**
 124    * @return string
 125    */
 126   function createSalt() {
 127     // It would be more secure to generate a new value but liable to run this
 128     // many times on certain admin pages; so instead we'll re-use the hash.
 129     return $this->defaultSalt;
 130   }
 131 }