CRM/Utils/Signer.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   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 string $secret
  64    *   private.
  65    * @param array $paramNames
  66    *   Array, fields which should be part of the signature.
  67    */
  68   public function __construct($secret, $paramNames) {
  69     sort($paramNames); // ensure consistent serialization of payloads
  70     $this->secret = $secret;
  71     $this->paramNames = $paramNames;
  72     $this->signDelim = "_"; // chosen to be valid in URLs but not in salt or md5
  73     $this->defaultSalt = CRM_Utils_String::createRandom(self::SALT_LEN, CRM_Utils_String::ALPHANUMERIC);
  74   }
  75
  76   /**
  77    * Generate a signature for a set of key-value pairs
  78    *
  79    * @param array $params
  80    *   Array, key-value pairs.
  81    * @param string $salt
  82    *   the salt (if known) or NULL (for auto-generated).
  83    * @return string, the full public token representing the signature
  84    */
  85   public function sign($params, $salt = NULL) {
  86     $message = array();
  87     $message['secret'] = $this->secret;
  88     $message['payload'] = array();
  89     if (empty($salt)) {
  90       $message['salt'] = $this->createSalt();
  91     }
  92     else {
  93       $message['salt'] = $salt;
  94     }
  95     // recall: paramNames is pre-sorted for stability
  96     foreach ($this->paramNames as $paramName) {
  97       if (isset($params[$paramName])) {
  98         if (is_numeric($params[$paramName])) {
  99           $params[$paramName] = (string) $params[$paramName];
 100         }
 101       }
 102       else {// $paramName is not included or ===NULL
 103         $params[$paramName] = '';
 104       }
 105       $message['payload'][$paramName] = $params[$paramName];
 106     }
 107     $token = $message['salt'] . $this->signDelim . md5(serialize($message));
 108     return $token;
 109   }
 110
 111   /**
 112    * Determine whether a token represents a proper signature for $params
 113    *
 114    * @param string $token
 115    *   the full public token representing the signature.
 116    * @param array $params
 117    *   Array, key-value pairs.
 118    *
 119    * @throws Exception
 120    * @return bool, TRUE iff all $paramNames for the submitted validate($params) and the original sign($params)
 121    */
 122   public function validate($token, $params) {
 123     list ($salt, $signature) = explode($this->signDelim, $token);
 124     if (strlen($salt) != self::SALT_LEN) {
 125       throw new Exception("Invalid salt [$token]=[$salt][$signature]");
 126     }
 127     $newToken = $this->sign($params, $salt);
 128     return ($token == $newToken);
 129   }
 130
 131   /**
 132    * @return string
 133    */
 134   public function createSalt() {
 135     // It would be more secure to generate a new value but liable to run this
 136     // many times on certain admin pages; so instead we'll re-use the hash.
 137     return $this->defaultSalt;
 138   }
 139 }