The application salt in Salon Booking OS

Salon Booking OS by OsDot™ keeps one secret of its own: the application salt (Security.salt in config/app_local.php). The installer writes it once, at random, when it creates the configuration file. Nothing in the administration area shows or changes it.

What it protects #

The salt is the key of the installation’s keyed hashes and signatures. Among them are the one-time codes with which clients book or sign in, and the booking grants a verified code opens. (Codes are sent by e-mail once the site can send e-mail; this version sends none, so no code is ever pending in it.)

• A code is kept only as a keyed hash of the code itself, never in plain text.
• The grant’s address is kept only as a keyed hash of that address.

The salt is also the key of the per-address limits on code requests. It also signs the “next page” cursors of lists and the browser’s protection against cross-site requests (the CSRF cookie).

It also signs:

• the short-lived links that open a private file, such as a picture or a document in the media library;
• the form of the booking widget on another website, once online booking is switched on;
• in the public demo, the names under which visitors are signed in.

Changing the salt #

Changing the application salt invalidates every pending one-time code and booking grant.

• A code sent before the change can no longer be verified. The client asks for a new one.
• A grant opened before the change no longer matches its address. A client in the middle of booking starts the code step again.
• The limits on code requests start again from zero.
• A form left open in a browser is refused once: reload the page and send it again. A list’s “next page” link starts again from the first page.
• A link to a private file opened before the change stops working: open the file again from its page. The same goes for a booking widget left open on another website: reload it.

Appointments, accounts, passwords and signed-in sessions are not affected. Neither are the stored keys of payment, e-mail and other providers: their encryption key is a separate file (storage/keys/integration.key), which belongs in the backup too.

Change the salt only to rotate it after a suspected leak of config/app_local.php, and preferably at a quiet time. Back up config/app_local.php first. To rotate it:

1. Put the site into maintenance: create an empty file named maintenance.flag in the site’s storage/ folder. While it exists, every page answers with the maintenance page.
2. Make a new value: at least 32 random characters. From the site’s folder, php -r "echo bin2hex(random_bytes(32)), PHP_EOL;" prints one (64 characters).
3. Replace it: in config/app_local.php, find the line 'Security' => ['salt' => env('SECURITY_SALT', '…')], and replace the value between the last pair of quotes with the new one, keeping the quotes. Change nothing else. (If your hosting sets the environment variable SECURITY_SALT, that value is used instead: change it there.)
4. Take the site out of maintenance: delete storage/maintenance.flag.

Keep it with your backups #

Back up config/app_local.php together with the database, as part of the full backup set: the database, config/app_local.php, config/installed.php, the storage/ folder and the webroot/media/ folder (the website’s pictures). A restored database with a different salt behaves as if the salt had been changed.