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 * CryptoToken constructor.
61 public function __construct() {
62 $this->delim
= chr(2);
66 * Determine if a string looks like plain-text.
68 * @param string $plainText
71 public function isPlainText($plainText) {
72 return is_string($plainText) && ($plainText === '' ||
$plainText{0} !== $this->delim
);
76 * Create an encrypted token (given the plaintext).
78 * @param string $plainText
79 * The secret value to encode (e.g. plain-text password).
80 * @param string|string[] $keyIdOrTag
81 * List of key IDs or key tags to check. First available match wins.
84 * @throws \Civi\Crypto\Exception\CryptoException
86 public function encrypt($plainText, $keyIdOrTag) {
87 /** @var CryptoRegistry $registry */
88 $registry = \Civi
::service('crypto.registry');
90 $key = $registry->findKey($keyIdOrTag);
91 if ($key['suite'] === 'plain') {
92 if (!$this->isPlainText($plainText)) {
93 throw new CryptoException("Cannot use plaintext encoding for data with reserved delimiter.");
98 /** @var \Civi\Crypto\CipherSuiteInterface $cipherSuite */
99 $cipherSuite = $registry->findSuite($key['suite']);
100 $cipherText = $cipherSuite->encrypt($plainText, $key);
102 return $this->delim
. self
::FMT_QUERY
. \
http_build_query([
104 't' => \CRM_Utils_String
::base64UrlEncode($cipherText),
109 * Get the plaintext (given an encrypted token).
111 * @param string $token
112 * @param string|string[] $keyIdOrTag
113 * Whitelist of acceptable keys. Wildcard '*' will allow it to use
114 * any/all available means to decode the token.
116 * @throws \Civi\Crypto\Exception\CryptoException
118 public function decrypt($token, $keyIdOrTag = '*') {
119 $keyIdOrTag = (array) $keyIdOrTag;
121 if ($this->isPlainText($token)) {
122 if (in_array('*', $keyIdOrTag) ||
in_array('plain', $keyIdOrTag)) {
126 throw new CryptoException("Cannot decrypt token. Unexpected key: plain");
130 /** @var CryptoRegistry $registry */
131 $registry = \Civi
::service('crypto.registry');
133 $tokenData = $this->parse($token);
135 $key = $registry->findKey($tokenData['k']);
136 if (!in_array('*', $keyIdOrTag) && !in_array($tokenData['k'], $keyIdOrTag) && empty(array_intersect($keyIdOrTag, $key['tags']))) {
137 throw new CryptoException("Cannot decrypt token. Unexpected key: {$tokenData['k']}");
140 /** @var \Civi\Crypto\CipherSuiteInterface $cipherSuite */
141 $cipherSuite = $registry->findSuite($key['suite']);
142 $plainText = $cipherSuite->decrypt($tokenData['t'], $key);
147 * Re-encrypt an existing token with a newer version of the key.
149 * @param string $oldToken
150 * @param string $keyTag
153 * @return string|null
154 * A re-encrypted version of $oldToken, or NULL if there should be no change.
155 * @throws \Civi\Crypto\Exception\CryptoException
157 public function rekey($oldToken, $keyTag) {
158 /** @var \Civi\Crypto\CryptoRegistry $registry */
159 $registry = \Civi
::service('crypto.registry');
161 $sourceKeys = $registry->findKeysByTag($keyTag);
162 $targetKey = array_shift($sourceKeys);
164 if ($this->isPlainText($oldToken)) {
165 if ($targetKey['suite'] === 'plain') {
170 $tokenData = $this->parse($oldToken);
171 if ($tokenData['k'] === $targetKey['id'] ||
!isset($sourceKeys[$tokenData['k']])) {
176 $decrypted = $this->decrypt($oldToken);
177 return $this->encrypt($decrypted, $targetKey['id']);
181 * Parse the content of a token (without decrypting it).
183 * @param string $token
186 * @throws \Civi\Crypto\Exception\CryptoException
188 public function parse($token): array {
189 $fmt = substr($token, 1, 4);
191 case self
::FMT_QUERY
:
193 parse_str(substr($token, 5), $tokenData);
194 $tokenData['t'] = \CRM_Utils_String
::base64UrlDecode($tokenData['t']);
198 throw new CryptoException("Cannot decrypt token. Invalid format.");