CRM/Utils/Signer.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2018                                |
   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-2018
  32  */
  33
  34 /**
  35  * A utility which signs and verifies a list of key-value pairs
  36  *
  37  * FIXME: Add TTL support?
  38  *
  39  * @code
  40  * $signer = new CRM_Utils_Signer('myprivatekey', array('param1','param2'));
  41  * $params = array(
  42  *   'param1' => 'hello',
  43  *   'param2' => 'world',
  44  * );
  45  * $token = $signer->sign($params);
  46  * ...
  47  * assertTrue($signer->validate($token, $params));
  48  * @endcode
  49  */
  50 class CRM_Utils_Signer {
  51   /**
  52    * Expected length of the salt
  53    *
  54    * @var int
  55    */
  56   const SALT_LEN = 4;
  57
  58   /**
  59    * Instantiate a signature-processor
  60    *
  61    * @param string $secret
  62    *   private.
  63    * @param array $paramNames
  64    *   Array, fields which should be part of the signature.
  65    */
  66   public 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 array $params
  78    *   Array, key-value pairs.
  79    * @param string $salt
  80    *   the salt (if known) or NULL (for auto-generated).
  81    * @return string, the full public token representing the signature
  82    */
  83   public function sign($params, $salt = NULL) {
  84     $message = array();
  85     $message['secret'] = $this->secret;
  86     $message['payload'] = array();
  87     if (empty($salt)) {
  88       $message['salt'] = $this->createSalt();
  89     }
  90     else {
  91       $message['salt'] = $salt;
  92     }
  93     // recall: paramNames is pre-sorted for stability
  94     foreach ($this->paramNames as $paramName) {
  95       if (isset($params[$paramName])) {
  96         if (is_numeric($params[$paramName])) {
  97           $params[$paramName] = (string) $params[$paramName];
  98         }
  99       }
 100       else {
 101         // $paramName is not included or ===NULL
 102         $params[$paramName] = '';
 103       }
 104       $message['payload'][$paramName] = $params[$paramName];
 105     }
 106     $token = $message['salt'] . $this->signDelim . md5(serialize($message));
 107     return $token;
 108   }
 109
 110   /**
 111    * Determine whether a token represents a proper signature for $params
 112    *
 113    * @param string $token
 114    *   the full public token representing the signature.
 115    * @param array $params
 116    *   Array, key-value pairs.
 117    *
 118    * @throws Exception
 119    * @return bool, TRUE iff all $paramNames for the submitted validate($params) and the original sign($params)
 120    */
 121   public function validate($token, $params) {
 122     list ($salt, $signature) = explode($this->signDelim, $token);
 123     if (strlen($salt) != self::SALT_LEN) {
 124       throw new Exception("Token contains invalid salt [" . urlencode($token) . "]");
 125     }
 126     $newToken = $this->sign($params, $salt);
 127     return ($token == $newToken);
 128   }
 129
 130   /**
 131    * @return string
 132    */
 133   public function createSalt() {
 134     // It would be more secure to generate a new value but liable to run this
 135     // many times on certain admin pages; so instead we'll re-use the hash.
 136     return $this->defaultSalt;
 137   }
 138
 139 }