CRM/Utils/Signer.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 5                                                  |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2019                                |
   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-2019
  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     // ensure consistent serialization of payloads
  68     sort($paramNames);
  69     $this->secret = $secret;
  70     $this->paramNames = $paramNames;
  71     // chosen to be valid in URLs but not in salt or md5
  72     $this->signDelim = "_";
  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 = [];
  87     $message['secret'] = $this->secret;
  88     $message['payload'] = [];
  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 {
 103         // $paramName is not included or ===NULL
 104         $params[$paramName] = '';
 105       }
 106       $message['payload'][$paramName] = $params[$paramName];
 107     }
 108     $token = $message['salt'] . $this->signDelim . md5(serialize($message));
 109     return $token;
 110   }
 111
 112   /**
 113    * Determine whether a token represents a proper signature for $params
 114    *
 115    * @param string $token
 116    *   the full public token representing the signature.
 117    * @param array $params
 118    *   Array, key-value pairs.
 119    *
 120    * @throws Exception
 121    * @return bool, TRUE iff all $paramNames for the submitted validate($params) and the original sign($params)
 122    */
 123   public function validate($token, $params) {
 124     list ($salt, $signature) = explode($this->signDelim, $token);
 125     if (strlen($salt) != self::SALT_LEN) {
 126       throw new Exception("Token contains invalid salt [" . urlencode($token) . "]");
 127     }
 128     $newToken = $this->sign($params, $salt);
 129     return ($token == $newToken);
 130   }
 131
 132   /**
 133    * @return string
 134    */
 135   public function createSalt() {
 136     // It would be more secure to generate a new value but liable to run this
 137     // many times on certain admin pages; so instead we'll re-use the hash.
 138     return $this->defaultSalt;
 139   }
 140
 141 }