How to change the Key Hashing Algorithm used by the Tyk Gateway

When key hashing is enabled there are a number of options for the hashing algorithm that the gateway can use. The active hashing algorithm is specified with TYK_GW_HASHKEYFUNCTION and can be one of murmur64, murmur128 and sha256.

Sometimes an organisation finds it necessary to switch from one to another but wants to preserve the existing keys which have already been hashed and stored.

To achieve this set the value of TYK_GW_HASHKEYFUNCTIONFALLBACK to the old hashing algorithm and set TYK_GW_HASHKEYFUNCTION to the new value. This will instruct the gateway to try the old algorithm if a key does not decode with the new one. 

There will be a slight performance hit for some key types as a result of this although Tyk issued authorisation keys will not be affected.

This is because Tyk authorisation keys contain the hashing algorithm used to create them in their value.

Take this Tyk authorisation key for example:

eyJvcmciOiI2N2ZlNTYyYTQ0YWU4ZDAwOGJlODQzMTIiLCJpZCI6IjQ3NWZlZWZmM2Y3MDRkZWQ4MTJhOTlhYWVlYWFkYzU4IiwiaCI6Im11cm11cjEyOCJ9

It is a base64 encoded string that decodes to this:

{"org":"67fe562a44ae8d008be84312","id":"475feeff3f704ded812a99aaeeaadc58","h":"murmur128"}

This key was encoded using murmur128 so Tyk does not need to work out what algorithm to use. It will hash the key using murmur128 and lookup the result in redis.

However custom keys, keys based on certificates used in dynamic mTLS and keys based on the sub of a JWT will not contain this hint so TYK_GW_HASHKEYFUNCTIONFALLBACK is needed to find these keys in redis. There will be an associated performance implication for these types of keys

As and example if TYK_GW_HASHKEYFUNCTION was changed from murmur128 to sha256 then it would be necessary to set TYK_GW_HASHKEYFUNCTIONFALLBACK=murmur128