Click here for the french version
&cHash revealed
Weeding out the misunderstandings
A hash string is a short string with a fixed length which uniquely represents a larger string of unknown length. In TYPO3 – and PHP – such a string is often generated by md5() which creates a 32 character hex-string. TYPO3 will sometimes shorten such hash strings down to 10 characters which is considered accurate enough for some purposes.
Hash strings are nice because they are impossible to reverse engineer back to the original value. Additionally there is a very small probability that two different source strings will generate the same hash string. This means they are great for comparison and validation of data. This is exactly how we use them in TYPO3!
The term “hash” apparently comes by way of analogy with its standard meaning in the physical world, to "chop and mix." (according to http://en.wikipedia.org/wiki/Hash_function) – which is of course a very boring explanation, but I wasn't the author of that.
Generating the cHash string
The “&cHash” string is a hash of the – to TYPO3 unknown - additional parameters in a URL in the frontend. By creating and sending the cHash string along with the URL we can verify on the server that the additional parameters received in the URL are indeed created by TYPO3 when generating the page. In that case we should be safe by caching the page based on these extra parameters!
This is the flow:
Page being generated by TYPO3:
A plugin (running as a USER cObject) wants to create the link “?id=566&tx_myext[uid]=44&type=1&tx_myext[details]=yes” and want it cached. The link is sent to an internal API function, ->typolink()
The ->typolink() function sees that the URL must be cachable and begins to generate the cHash value of the parameters. In this process the variables “?id=566” and “&type=1” are filtered out because they are already known by the core system. So now “&tx_myext[uid]=44” and “&tx_myext[details]=yes” are left and after ordering them alphabetically the hash string “13b5d6efa7” is generated. (t3lib_div::makeCacheHash())
The URL is returned to the plugin as “?id=566&tx_myext[uid]=44&type=1&tx_myext[details]=yes&cHash=13b5d6efa7”
Page is requested by the URL “?id=566&tx_myext[uid]=44&type=1&tx_myext[details]=yes&cHash=13b5d6efa7”:
The server immediately reacts on the known parameters which are “?id=566” and “&type=1” by validating the page id and type-number in relation to the Template.
The server discovers that a “cHash” value is set; this means one thing: additional parameters in the URL not known to TYPO3 must match this value when a hash is created upon them. After filtering away the &id, &type and &cHash parameters TYPO3 is left with “&tx_myext[uid]=44” and “&tx_myext[details]=yes” which turns out to generate the hash string “13b5d6efa7” which is exactly the same as “&cHash”! This is proof that no parameters has been forged from the evil darkside. The page can safely be cached based on this custom parameter combination!
In case the enemy had changed “&tx_myext[uid]=9876554321” in order to spam our cache table the resulting hash string generated will with all probability not match “13b5d6efa7”: Page caching will be disabled immediately, but the page will still be generated trying to display news item 9876554321 (which probably does not exist, but so what? The cache table is not loaded with that...)
So the cHash is like a signature that ensures us the parameters are OK!
Forging &cHash?
Now, could the enemy calculate that cHash value himself? Well, only if he can guess the value of the $TYPO3_CONF_VARS[SYS][encryptionKey] since that is included both in the generation of the cHash in the URL and during verification. This value is supposed to be secret and since the cHash cannot be reverse engineered the only way to find that value is to hack the server or guess it.
