3 +--------------------------------------------------------------------+
4 | Copyright CiviCRM LLC. All rights reserved. |
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 +--------------------------------------------------------------------+
12 namespace Civi\Crypto
;
14 use Civi\Crypto\Exception\CryptoException
;
17 * The "Crypto Token" service supports a token format suitable for
18 * storing specific values in the database with encryption. Characteristics:
20 * - Primarily designed to defend confidentiality in case of data-leaks
21 * (SQL injections, lost backups, etc).
22 * - NOT appropriate for securing data-transmission. Data-transmission
23 * requires more protections (eg mandatory TTLs + signatures). If you need
24 * that, consider adding a JWT/JWS/JWE implementation.
25 * - Data-format allows phase-in/phase-out. If you have a datum that was written
26 * with an old key or with no key, it will still be readable.
28 * USAGE: The "encrypt()" and "decrypt()" methods are the primary interfaces.
30 * $encrypted = Civi::service('crypto.token')->encrypt('my-mail-password, 'KEY_ID_OR_TAG');
31 * $decrypted = Civi::service('crypto.token')->decrypt($encrypted, '*');
33 * FORMAT: An encoded token may be in either of these formats:
35 * - Plain text: Any string which does not begin with chr(2)
36 * - Encrypted text: A string in the format:
37 * TOKEN := DLM + FMT + QUERY
38 * DLM := ASCII char #2
39 * FMT := String, 4-digit, alphanumeric (as in "CTK?")
40 * QUERY := String, URL-encoded key-value pairs,
41 * "k", the key ID (alphanumeric and symbols "_-.,:;=+/\")
42 * "t", the text (base64-encoded ciphertext)
44 * @package Civi\Crypto
49 * Format identification code
51 const FMT_QUERY
= 'CTK?';
59 * @var \Civi\Crypto\CryptoRegistry|null
64 * CryptoToken constructor.
66 * @param CryptoRegistry $registry
68 public function __construct($registry = NULL) {
69 $this->delim
= chr(2);
70 $this->registry
= $registry;
74 * Determine if a string looks like plain-text.
76 * @param string $plainText
79 public function isPlainText($plainText) {
80 return is_string($plainText) && ($plainText === '' ||
$plainText[0] !== $this->delim
);
84 * Create an encrypted token (given the plaintext).
86 * @param string $plainText
87 * The secret value to encode (e.g. plain-text password).
88 * @param string|string[] $keyIdOrTag
89 * List of key IDs or key tags to check. First available match wins.
92 * @throws \Civi\Crypto\Exception\CryptoException
94 public function encrypt($plainText, $keyIdOrTag) {
95 /** @var CryptoRegistry $registry */
96 $registry = $this->getRegistry();
98 $key = $registry->findKey($keyIdOrTag);
99 if ($key['suite'] === 'plain') {
100 if (!$this->isPlainText($plainText)) {
101 throw new CryptoException("Cannot use plaintext encoding for data with reserved delimiter.");
106 /** @var \Civi\Crypto\CipherSuiteInterface $cipherSuite */
107 $cipherSuite = $registry->findSuite($key['suite']);
108 $cipherText = $cipherSuite->encrypt($plainText, $key);
110 return $this->delim
. self
::FMT_QUERY
. \
http_build_query([
112 't' => \CRM_Utils_String
::base64UrlEncode($cipherText),
117 * Get the plaintext (given an encrypted token).
119 * @param string $token
120 * @param string|string[] $keyIdOrTag
121 * Whitelist of acceptable keys. Wildcard '*' will allow it to use
122 * any/all available means to decode the token.
124 * @throws \Civi\Crypto\Exception\CryptoException
126 public function decrypt($token, $keyIdOrTag = '*') {
127 $keyIdOrTag = (array) $keyIdOrTag;
129 if ($this->isPlainText($token)) {
130 if (in_array('*', $keyIdOrTag) ||
in_array('plain', $keyIdOrTag)) {
134 throw new CryptoException("Cannot decrypt token. Unexpected key: plain");
138 /** @var CryptoRegistry $registry */
139 $registry = $this->getRegistry();
141 $tokenData = $this->parse($token);
143 $key = $registry->findKey($tokenData['k']);
144 if (!in_array('*', $keyIdOrTag) && !in_array($tokenData['k'], $keyIdOrTag) && empty(array_intersect($keyIdOrTag, $key['tags']))) {
145 throw new CryptoException("Cannot decrypt token. Unexpected key: {$tokenData['k']}");
148 /** @var \Civi\Crypto\CipherSuiteInterface $cipherSuite */
149 $cipherSuite = $registry->findSuite($key['suite']);
150 $plainText = $cipherSuite->decrypt($tokenData['t'], $key);
155 * Re-encrypt an existing token with a newer version of the key.
157 * @param string $oldToken
158 * @param string $keyTag
161 * @return string|null
162 * A re-encrypted version of $oldToken, or NULL if there should be no change.
163 * @throws \Civi\Crypto\Exception\CryptoException
165 public function rekey($oldToken, $keyTag) {
166 /** @var \Civi\Crypto\CryptoRegistry $registry */
167 $registry = $this->getRegistry();
169 $sourceKeys = $registry->findKeysByTag($keyTag);
170 $targetKey = array_shift($sourceKeys);
172 if ($this->isPlainText($oldToken)) {
173 if ($targetKey['suite'] === 'plain') {
178 $tokenData = $this->parse($oldToken);
179 if ($tokenData['k'] === $targetKey['id'] ||
!isset($sourceKeys[$tokenData['k']])) {
184 $decrypted = $this->decrypt($oldToken);
185 return $this->encrypt($decrypted, $targetKey['id']);
189 * Parse the content of a token (without decrypting it).
191 * @param string $token
194 * @throws \Civi\Crypto\Exception\CryptoException
196 public function parse($token): array {
197 $fmt = substr($token, 1, 4);
199 case self
::FMT_QUERY
:
201 parse_str(substr($token, 5), $tokenData);
202 $tokenData['t'] = \CRM_Utils_String
::base64UrlDecode($tokenData['t']);
206 throw new CryptoException("Cannot decrypt token. Invalid format.");
212 * @return CryptoRegistry
214 protected function getRegistry(): CryptoRegistry
{
215 if ($this->registry
=== NULL) {
216 $this->registry
= \Civi
::service('crypto.registry');
218 return $this->registry
;