CRM/Utils/Signer.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | Copyright CiviCRM LLC. All rights reserved.                        |
   5  |                                                                    |
   6  | This work is published under the GNU AGPLv3 license with some      |
   7  | permitted exceptions and without any warranty. For full license    |
   8  | and copyright information, see https://civicrm.org/licensing       |
   9  +--------------------------------------------------------------------+
  10  */
  11
  12 /**
  13  *
  14  * @package CRM
  15  * @copyright CiviCRM LLC https://civicrm.org/licensing
  16  */
  17
  18 /**
  19  * A utility which signs and verifies a list of key-value pairs
  20  *
  21  * FIXME: Add TTL support?
  22  *
  23  * @code
  24  * $signer = new CRM_Utils_Signer('myprivatekey', array('param1','param2'));
  25  * $params = array(
  26  *   'param1' => 'hello',
  27  *   'param2' => 'world',
  28  * );
  29  * $token = $signer->sign($params);
  30  * ...
  31  * assertTrue($signer->validate($token, $params));
  32  * @endcode
  33  */
  34 class CRM_Utils_Signer {
  35   /**
  36    * Expected length of the salt
  37    *
  38    * @var int
  39    */
  40   const SALT_LEN = 4;
  41
  42   /**
  43    * Instantiate a signature-processor
  44    *
  45    * @param string $secret
  46    *   private.
  47    * @param array $paramNames
  48    *   Array, fields which should be part of the signature.
  49    */
  50   public function __construct($secret, $paramNames) {
  51     // ensure consistent serialization of payloads
  52     sort($paramNames);
  53     $this->secret = $secret;
  54     $this->paramNames = $paramNames;
  55     // chosen to be valid in URLs but not in salt or md5
  56     $this->signDelim = "_";
  57     $this->defaultSalt = CRM_Utils_String::createRandom(self::SALT_LEN, CRM_Utils_String::ALPHANUMERIC);
  58   }
  59
  60   /**
  61    * Generate a signature for a set of key-value pairs
  62    *
  63    * @param array $params
  64    *   Array, key-value pairs.
  65    * @param string $salt
  66    *   the salt (if known) or NULL (for auto-generated).
  67    * @return string, the full public token representing the signature
  68    */
  69   public function sign($params, $salt = NULL) {
  70     $message = [];
  71     $message['secret'] = $this->secret;
  72     $message['payload'] = [];
  73     if (empty($salt)) {
  74       $message['salt'] = $this->createSalt();
  75     }
  76     else {
  77       $message['salt'] = $salt;
  78     }
  79     // recall: paramNames is pre-sorted for stability
  80     foreach ($this->paramNames as $paramName) {
  81       if (isset($params[$paramName])) {
  82         if (is_numeric($params[$paramName])) {
  83           $params[$paramName] = (string) $params[$paramName];
  84         }
  85       }
  86       else {
  87         // $paramName is not included or ===NULL
  88         $params[$paramName] = '';
  89       }
  90       $message['payload'][$paramName] = $params[$paramName];
  91     }
  92     $token = $message['salt'] . $this->signDelim . md5(serialize($message));
  93     return $token;
  94   }
  95
  96   /**
  97    * Determine whether a token represents a proper signature for $params
  98    *
  99    * @param string $token
 100    *   the full public token representing the signature.
 101    * @param array $params
 102    *   Array, key-value pairs.
 103    *
 104    * @throws Exception
 105    * @return bool, TRUE iff all $paramNames for the submitted validate($params) and the original sign($params)
 106    */
 107   public function validate($token, $params) {
 108     list ($salt, $signature) = explode($this->signDelim, $token);
 109     if (strlen($salt) != self::SALT_LEN) {
 110       throw new Exception("Token contains invalid salt [" . urlencode($token) . "]");
 111     }
 112     $newToken = $this->sign($params, $salt);
 113     return ($token == $newToken);
 114   }
 115
 116   /**
 117    * @return string
 118    */
 119   public function createSalt() {
 120     // It would be more secure to generate a new value but liable to run this
 121     // many times on certain admin pages; so instead we'll re-use the hash.
 122     return $this->defaultSalt;
 123   }
 124
 125 }