Skip to content
This repository has been archived by the owner on Mar 21, 2024. It is now read-only.

Reject master keys shorter than 16 bytes in production #209

Merged
merged 10 commits into from
Feb 6, 2023
12 changes: 8 additions & 4 deletions text/0085-api-keys.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,15 +41,19 @@ At the first launch of Meilisearch with a master key, Meilisearch automatically

If the master key is removed at Meilisearch launch, the previously generated API keys no longer secure the Meilisearch instance.

If Meilisearch is launched with the `production` value for the `MEILI_ENV` environment variable or the `--env` CLI option, a master key is mandatory. If the master key is omitted in that particular case, Meilisearch launch is aborted and displays an error:
If Meilisearch is launched with the `production` value for the `MEILI_ENV` environment variable or the `--env` CLI option, a master key of at least 16 bytes is mandatory.

`Error: In production mode, the environment variable MEILI_MASTER_KEY is mandatory`
If the master key is omitted in that particular case, or is too short, Meilisearch launch is aborted and displays an error.

If Meilisearch is launched with the `development` value for the `MEILI_ENV` environment variable or the `--env` CLI option, Meilisearch displays warning messages given different cases.

See [`MEILI_MASTER_KEY`/`--master-key` launch option](0119-instance-options#334-master-key).

The master key must be composed of valid utf-8 characters. It is advisable to enclose it in `'` when specified via the `--master-key` option.

> 🚨 The master key should never be exposed to the public as it may compromise a Meilisearch instance.

> 🚨 If the value of the master key changes, all the previously generated `API Keys` changes, thus allows to invalidate the set of API keys previously generated by regenerating a different value for their `key` field. This is particularly useful in the case where the master key might have been leaked and the user need to re-generate the whole set of keys at once to re-secure the instance.
> 🚨 If the value of the master key changes, all the previously generated `API Keys` changes, thus allowing to invalidate the set of API keys previously generated by regenerating a different value for their `key` field. This is particularly useful in the case where the master key might have been leaked and the user needs to re-generate the whole set of keys at once to re-secure the instance.

> The master key does not appear on the `/keys` endpoints and can't be used to authorize requests other than on the `/keys` endpoint.

Expand Down Expand Up @@ -316,7 +320,7 @@ Create an API key.
| indexes.swap | Provides access to `POST` `/swap-indexes`. See [Swap Indexes API](0191-swap-indexes-api.md) specification. |
| tasks.get | Provides access to `GET` `/tasks`. **⚠️Non-authorized `indexes` are omitted from the response on `/tasks`**. Also add access to `GET` `/indexes/:authorizedIndexes/tasks` routes. |
| tasks.cancel | Provides access to `POST` `/tasks/cancel`. route. |
| tasks.delete | Provides access to `DELETE` `/tasks` route. |
| tasks.delete | Provides access to `DELETE` `/tasks` route. |
| settings.get | Provides access to `GET` `/indexes/:authorizedIndexes/settings` and `/indexes/:authorizedIndexes/settings/*` routes. |
| settings.update | Provides access to `POST / DELETE` `/indexes/:authorizedIndexes/settings` and `/indexes/:authorizedIndexes/settings/*` routes. |
| stats.get | Provides access to `GET` `/stats/`. **⚠️Non-authorized `indexes` are omitted from the response on `/stats`**. Also add access to `GET` `/indexes/:authorizedIndexes/stats`. |
Expand Down
57 changes: 53 additions & 4 deletions text/0119-instance-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,12 +142,13 @@ Configures the instance's environment. Value must be either `production` or `dev

`production`:

- Setting a master key is **mandatory**
- Setting a master key of at least 16 bytes is **mandatory**
- The search preview interface is disabled

`development`:

- Setting a master key is **optional**
- Setting a master key of at least 16 bytes is **optional**
- Search preview is enabled

#### 3.3.3. HTTP address & port binding
Expand All @@ -170,10 +171,59 @@ Sets the instance's master key, automatically protecting all routes except [`GET

You must supply an alphanumeric string when using this option.

Providing a master key is mandatory when `--env` is set to `production`; if none is given, then Meilisearch will throw an error and refuse to launch.

If no master key is provided in a `development` environment, all routes will be unprotected and publicly accessible.

##### 3.3.4.1. Error and Warning messages

Providing a master key of at least 16 bytes is mandatory when `--env` is set to `production`; if none is given, Meilisearch will throw an error and refuse to launch.

```
Error: You must provide a master key to secure your instance in a production environment. It can be specified via the MEILI_MASTER_KEY environment variable or the --master-key launch option.

We generated a secure master key for you (you can safely use this token):

>> --master-key `:suggestedMasterKey` <<
```

Providing a master key of at least 16 bytes is mandatory when `--env` is set to `production`; if it is given but too short then, Meilisearch will throw an error and refuse to launch.

```
Error: The master key must be at least 16 bytes in a production environment. The provided key is only `:numBytes` bytes.

We generated a secure master key for you (you can safely use this token):

>> --master-key `:suggestedMasterKey` <<
```

Providing a master key of less than 16 bytes when `--env` is set to `development` displays a warning message.

```
Meilisearch started with a master key considered unsafe for use in a production environment.

A master key of at least 16 bytes will be required when switching to a production environment.

We generated a new secure master key for you (you can safely use this token):

>> --master-key `:suggestedMasterKey` <<

Restart Meilisearch after executing the command above to use this new and secure master key.
gmourier marked this conversation as resolved.
Show resolved Hide resolved
```

Not providing a master key when `--env` is set to `development` displays a warning message.

```
No master key was found. The server will accept unidentified requests.

A master key of at least 16 bytes will be required when switching to a production environment.

If you need protection in a development environment, we generated a secure master key for you (you can safely use this token):

>> --master-key `:suggestedMasterKey` <<

Restart Meilisearch after executing the command above to use this new and secure master key.
gmourier marked this conversation as resolved.
Show resolved Hide resolved
```


#### 3.3.5. Disable analytics

**Environment variable**: `MEILI_NO_ANALYTICS`
Expand Down Expand Up @@ -476,4 +526,3 @@ N/A

- Redo the command-line to create a more interactive CLI
- Autocomplete for the options when using the Meilisearch CLI
- Minimal requirement when setting the master key, for example, a minimal number of characters