3 +--------------------------------------------------------------------+
5 +--------------------------------------------------------------------+
6 | Copyright CiviCRM LLC (c) 2004-2018 |
7 +--------------------------------------------------------------------+
8 | This file is a part of CiviCRM. |
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. |
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. |
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 +--------------------------------------------------------------------+
31 * @copyright CiviCRM LLC (c) 2004-2018
35 * A utility which signs and verifies a list of key-value pairs
37 * FIXME: Add TTL support?
40 * $signer = new CRM_Utils_Signer('myprivatekey', array('param1','param2'));
42 * 'param1' => 'hello',
43 * 'param2' => 'world',
45 * $token = $signer->sign($params);
47 * assertTrue($signer->validate($token, $params));
50 class CRM_Utils_Signer
{
52 * Expected length of the salt
59 * Instantiate a signature-processor
61 * @param string $secret
63 * @param array $paramNames
64 * Array, fields which should be part of the signature.
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
);
75 * Generate a signature for a set of key-value pairs
77 * @param array $params
78 * Array, key-value pairs.
80 * the salt (if known) or NULL (for auto-generated).
81 * @return string, the full public token representing the signature
83 public function sign($params, $salt = NULL) {
85 $message['secret'] = $this->secret
;
86 $message['payload'] = array();
88 $message['salt'] = $this->createSalt();
91 $message['salt'] = $salt;
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];
101 // $paramName is not included or ===NULL
102 $params[$paramName] = '';
104 $message['payload'][$paramName] = $params[$paramName];
106 $token = $message['salt'] . $this->signDelim
. md5(serialize($message));
111 * Determine whether a token represents a proper signature for $params
113 * @param string $token
114 * the full public token representing the signature.
115 * @param array $params
116 * Array, key-value pairs.
119 * @return bool, TRUE iff all $paramNames for the submitted validate($params) and the original sign($params)
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) . "]");
126 $newToken = $this->sign($params, $salt);
127 return ($token == $newToken);
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
;