105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
Static Hashing
|
|
==============
|
|
|
|
{{#include ../links.md}}
|
|
|
|
To counter [DOS] attacks, the _hasher_ used by Rhai, [`ahash`], automatically generates a different
|
|
_seed_ for hashing during each compilation and execution run.
|
|
|
|
This means that hash values generated by the hasher will not be _stable_ – they change
|
|
during each compile, and during each run.
|
|
|
|
For certain niche scenarios, however, dynamic hashes are undesirable.
|
|
|
|
So, when _static hashing_ is employed, all hashing uses a fixed, predictable seed all the time.
|
|
|
|
```admonish abstract.small "Hashing seed"
|
|
|
|
A hashing seed requires four 64-bit numbers (i.e. `u64`).
|
|
```
|
|
|
|
```admonish tip.small "Tip: Static hashes are consistent and predictable"
|
|
|
|
Under static hashing, the same function signature _always_ generate the same hash value,
|
|
given the same seed.
|
|
```
|
|
|
|
```admonish warning.small "Warning: Safety considerations"
|
|
|
|
A fixed hashing seed enlarges the attack surface of Rhai to malicious intent
|
|
(e.g. [DOS] attacks).
|
|
```
|
|
|
|
|
|
Set at Run-Time
|
|
---------------
|
|
|
|
Call the static function `rhai::config::hashing::set_ahash_seed` with four `u64` numbers that make
|
|
up the hashing seed.
|
|
|
|
The seed specified is always used to initialize the hasher.
|
|
|
|
```rust
|
|
// Set specific hashing seed - do this BEFORE anything else!
|
|
rhai::config::hashing::set_ahash_seed(Some([123, 456, 789, 42]))?;
|
|
|
|
// ... from now on, all hashing will be predictable
|
|
let engine = Engine::new();
|
|
```
|
|
|
|
```admonish danger.small "Warning: Only call once"
|
|
|
|
`rhai::config::hashing::set_ahash_seed` can only ever be called _once_,
|
|
and must be called _BEFORE_ performing any operation on Rhai (e.g. creating
|
|
an [`Engine`]).
|
|
|
|
Calling it a second time simply returns an error.
|
|
```
|
|
|
|
|
|
Set at Compile Time
|
|
-------------------
|
|
|
|
The hashing seed can also be provided, at _compile time_, via the environment variable
|
|
`RHAI_AHASH_SEED`, with four `u64` numbers that must be specified in Rust array literal format.
|
|
|
|
```admonish warning.small "Warning"
|
|
|
|
If a hashing seed is also set via `rhai::config::hashing::set_ahash_seed`,
|
|
this environment variable has no effect.
|
|
```
|
|
|
|
```sh
|
|
RHAI_AHASH_SEED="[123, 456, 789, 42]" cargo build ...
|
|
```
|
|
|
|
The seed specified in `RHAI_AHASH_SEED` is always used to initialize the hasher.
|
|
|
|
If the environment variable is missing, or it contains all zeros (i.e. `[0, 0, 0, 0]`),
|
|
then static hashing is disabled.
|
|
|
|
|
|
TL;DR
|
|
-----
|
|
|
|
~~~admonish question "Why can't we tell `ahash` to use a static (fixed) seed?"
|
|
|
|
For static hashing seed, [`ahash`] requires:
|
|
|
|
* `default-features = false`
|
|
* `runtime-rng` feature is _not_ set (default on)
|
|
* `compile-time-rng` feature is _not_ set
|
|
|
|
#### The bane of additive Cargo features
|
|
|
|
However, [`ahash`] is also extremely popular, used by many many other crates,
|
|
most notably [`hashbrown`](https://crates.io/crates/hashbrown).
|
|
|
|
Chances are that there are dependency crates that in turn depend on [`ahash`] with
|
|
default features. Since cargo features are _additive_, it is almost certain that [`ahash`]
|
|
will use a runtime-generated seed for large projects.
|
|
|
|
Hence, there exists a need to tell [`ahash`] to use a fixed seed, even when its feature flags
|
|
say otherwise.
|
|
~~~
|