Create and Safely Install a GRUB PBKDF2 Password Hash

An unprotected GRUB menu lets anyone at the console edit boot parameters or reach a rescue shell. grub-mkpasswd-pbkdf2 fixes that without ever typing your password in plain text. This guide generates the hash, then walks it into your GRUB configuration carefully. The examples use GRUB 2.12-1ubuntu7.3 from the grub-common package, as installed on this machine.

• Time: about ten minutes.
• Needs: a local shell and grub-mkpasswd-pbkdf2; sudo or a root shell only for the later configuration step.
• Will not touch: generating the hash makes no change to the boot loader. Editing /boot/grub/grub.cfg later can affect boot access, so keep a second administrative session open and a tested recovery path ready before you get there.

1. Check the installed tool

Two read-only checks, neither needing elevated privileges:

$ grub-mkpasswd-pbkdf2 --version
grub-mkpasswd-pbkdf2 (GRUB) 2.12-1ubuntu7.3
$ dpkg-query -W -f='${Package} ${Version}\n' grub-common
grub-common 2.12-1ubuntu7.3

Your package revision may differ. The checkpoint that matters is that the command exists and you know which GRUB build supplied it.

2. Generate the hash interactively

Run the command with no password anywhere on the command line:

$ grub-mkpasswd-pbkdf2
Enter password:
Reenter password:
PBKDF2 hash of your password is grub.pbkdf2.sha512.10000.SALT.HASH

• Type it twice. Nothing useful is echoed back while you type.
• Copy the whole value. Everything from the word grub through the final character of the hash, not the sentence around it.
• Treat it as sensitive. The salt and hash are freshly generated each run, so they differ every time. The string cannot be reversed to recover your password, but it is what lets GRUB check a guess against it.

3. Understand the tunables before touching them

• --iteration-count=NUM sets the number of PBKDF2 iterations.
• --buflen=NUM sets the length of the generated hash.
• --salt=NUM sets the length of the salt.

For an ordinary workstation, the defaults are the least surprising choice. More iterations raise the cost of a brute-force check but also raise boot-time checking cost; a shorter salt or hash narrows the margin against guessing. Never copy tuning values from another host without knowing why they were chosen and confirming your GRUB build accepts the result.

If you need a deliberately cheap hash purely to check syntax:

$ grub-mkpasswd-pbkdf2 --iteration-count=1000 --salt=8 --buflen=64
Enter password:
Reenter password:
PBKDF2 hash of your password is grub.pbkdf2.sha512.1000.SALT.HASH

That is fine for testing, not for a real boot menu: regenerate with the default settings for production unless your security policy says otherwise. The long options have short forms (-c, -s, -l) but the full names read better in notes and scripts.

4. Put the hash into GRUB configuration carefully

Generating a hash does not turn on GRUB authentication by itself. It has to be referenced from your GRUB configuration, usually a custom fragment or your distribution's own configuration workflow. Do not paste a guessed stanza into a production boot config; the exact syntax depends on how your system manages /etc/grub.d and /etc/default/grub.

Before touching anything privileged, take a recoverable copy:

$ sudo cp --preserve=all /etc/grub.d/40_custom /etc/grub.d/40_custom.bak
$ sudoedit /etc/grub.d/40_custom

Put the hash only where your GRUB syntax expects it, keep the file root-readable, and never write the clear-text password into it. If the result is wrong, restore the backup with sudo cp --preserve=all /etc/grub.d/40_custom.bak /etc/grub.d/40_custom and regenerate.

Do not edit the generated /boot/grub/grub.cfg directly as your first move: a later package update or config rebuild can overwrite it. If your distribution documents a different file for this, follow that instead, with the same backup-first habit.

5. Rebuild and inspect before rebooting

Once the fragment is correct, regenerate GRUB with your distribution's tool. On Ubuntu that is commonly:

$ sudo update-grub

That command sits outside grub-mkpasswd-pbkdf2, so its output depends on your installed scripts. Treat any error as a stop sign, and confirm the hash actually made it into the generated file before rebooting:

$ sudo grep -n 'grub.pbkdf2.sha512' /boot/grub/grub.cfg
123: set superusers="GRUB_ADMIN"
124: password_pbkdf2 GRUB_ADMIN grub.pbkdf2.sha512.10000.SALT.HASH

If that search returns nothing, the hash was not incorporated. Go back to the source fragment and the rebuild output rather than assuming authentication is active.

6. Test the boundary without losing access

Reboot only once you are certain of the new password and have console or provider recovery available. At the GRUB menu, confirm the prompt appears and the password works. If the menu locks you out, use your machine's documented recovery method and restore the backup configuration from a root shell rather than repeatedly guessing at the boot prompt.

A successful grub-mkpasswd-pbkdf2 run only proves a hash was generated. It does not prove GRUB will load it, that the username matches, or that every menu entry is actually protected; those are separate checks.