[PATCH 3/3] docs: Document password_argon2 and grub-mkpasswd-argon2

Signed-off-by: Gary Lin <[email protected]>
---
 docs/grub.texi | 86 ++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 73 insertions(+), 13 deletions(-)

diff --git a/docs/grub.texi b/docs/grub.texi
index 7181009b6..827b9defb 100644
--- a/docs/grub.texi
+++ b/docs/grub.texi
@@ -35,6 +35,7 @@ Invariant Sections.
 * GRUB: (grub).                 The GRand Unified Bootloader
 * grub-install: (grub)Invoking grub-install.    Install GRUB on your drive
 * grub-mkconfig: (grub)Invoking grub-mkconfig.  Generate GRUB configuration
+* grub-mkpasswd-argon2: (grub)Invoking grub-mkpasswd-argon2.
 * grub-mkpasswd-pbkdf2: (grub)Invoking grub-mkpasswd-pbkdf2.
 * grub-mkrelpath: (grub)Invoking grub-mkrelpath.
 * grub-mkrescue: (grub)Invoking grub-mkrescue.  Make a GRUB rescue image
@@ -4250,6 +4251,7 @@ Modules can be loaded via the @command{insmod} (@pxref{insmod}) command.
 * part_sunpc_module::
 * parttool_module::
 * password_module::
+* password_argon2_module::
 * password_pbkdf2_module::
 * pata_module::
 * pbkdf2_module::
@@ -5655,8 +5657,13 @@ for more information.
 @section password
 This module provides support for the @command{password} command. Please note
 that this uses the password in plain text, if security is a concern consider
-using @ref{password_pbkdf2_module} instead. @xref{password} for more
-information.
+using @ref{password_argon2_module} or @ref{password_pbkdf2_module} instead.
+@xref{password} for more information.
+
+@node password_argon2_module
+@section password_argon2
+This module provides support for the @command{password_argon2} command.
+@xref{password_argon2} for more information.
 
 @node password_pbkdf2_module
 @section password_pbkdf2
@@ -6717,7 +6724,8 @@ you forget a command, you can run the command @command{help}
 * normal_exit::                 Exit from normal mode
 * parttool::                    Modify partition table entries
 * password::                    Set a clear-text password
-* password_pbkdf2::             Set a hashed password
+* password_argon2::             Set a Argon2 hashed password
+* password_pbkdf2::             Set a PBKDF2 hashed password
 * plainmount::                  Open device encrypted in plain mode
 * play::                        Play a tune
 * probe::                       Retrieve device info
@@ -7975,12 +7983,23 @@ Define a user named @var{user} with password @var{clear-password}.
 @end deffn
 
 
+@node password_argon2
+@subsection password_argon2
+
+@deffn Command password_argon2 user hashed-password
+Define a user named @var{user} with password hash @var{hashed-password}.
+Use @command{grub-mkpasswd-argon2} (@pxref{Invoking grub-mkpasswd-argon2})
+to generate password hashes.  @xref{Security}.
+@end deffn
+
+
 @node password_pbkdf2
 @subsection password_pbkdf2
 
 @deffn Command password_pbkdf2 user hashed-password
 Define a user named @var{user} with password hash @var{hashed-password}.
-Use @command{grub-mkpasswd-pbkdf2} (@pxref{Invoking grub-mkpasswd-pbkdf2})
+Use @command{grub-mkpasswd-argon2} (@pxref{Invoking grub-mkpasswd-argon2})
+or @command{grub-mkpasswd-pbkdf2} (@pxref{Invoking grub-mkpasswd-pbkdf2})
 to generate password hashes.  @xref{Security}.
 @end deffn
 
@@ -9237,12 +9256,17 @@ However, in some environments, such as kiosks, it may be appropriate to lock
 down the boot loader to require authentication before performing certain
 operations.
 
-The @samp{password} (@pxref{password}) and @samp{password_pbkdf2}
+The @samp{password} (@pxref{password}), @samp{password_argon2}
+(@pxref{password_argon2}) and @samp{password_pbkdf2}
 (@pxref{password_pbkdf2}) commands can be used to define users, each of
 which has an associated password.  @samp{password} sets the password in
-plain text, requiring @file{grub.cfg} to be secure; @samp{password_pbkdf2}
-sets the password hashed using the Password-Based Key Derivation Function
-(RFC 2898), requiring the use of @command{grub-mkpasswd-pbkdf2}
+plain text, requiring @file{grub.cfg} to be secure; @samp{password_argon2}
+sets the password hashed using the Argon2 key derivation function (RFC 9106),
+requiring the use of @command{grub-mkpasswd-argon2}
+(@pxref{Invoking grub-mkpasswd-argon2}) to generate password hashes.
+@samp{password_pbkdf2} sets the password hashed using the Password-Based Key
+Derivation Function (RFC 2898), requiring the use of @command{grub-mkpasswd-argon2}
+(@pxref{Invoking grub-mkpasswd-argon2}) or @command{grub-mkpasswd-pbkdf2}
 (@pxref{Invoking grub-mkpasswd-pbkdf2}) to generate password hashes.
 
 In order to enable authentication support, the @samp{superusers} environment
@@ -9293,8 +9317,8 @@ menuentry "May be run by user1 or a superuser" --users user1 @{
 The @command{grub-mkconfig} program does not yet have built-in support for
 generating configuration files with authentication.  You can use
 @file{/etc/grub.d/40_custom} to add simple superuser authentication, by
-adding @kbd{set superusers=} and @kbd{password} or @kbd{password_pbkdf2}
-commands.
+adding @kbd{set superusers=} and @kbd{password}, @kbd{password_argon2}
+or @kbd{password_pbkdf2} commands.
 
 @node Using GPG-style digital signatures
 @section Using GPG-style digital signatures in GRUB
@@ -10648,8 +10672,10 @@ bootability on other machines.
 @menu
 * Invoking grub-install::       How to use the GRUB installer
 * Invoking grub-mkconfig::      Generate a GRUB configuration file
+* Invoking grub-mkpasswd-argon2::
+                                Generate GRUB password hashes (Argon2)
 * Invoking grub-mkpasswd-pbkdf2::
-                                Generate GRUB password hashes
+                                Generate GRUB password hashes (PBKDF2)
 * Invoking grub-mkrelpath::     Make system path relative to its root
 * Invoking grub-mkrescue::      Make a GRUB rescue image
 * Invoking grub-mount::         Mount a file system using GRUB
@@ -10750,12 +10776,46 @@ Send the generated configuration file to @var{file}.  The default is to send
 it to standard output.
 @end table
 
+@node Invoking grub-mkpasswd-argon2
+@section Invoking grub-mkpasswd-argon2
+
+The program @command{grub-mkpasswd-pbkdf2} generates password hashes (Argon2)
+for GRUB (@pxref{Security}).
+
+@example
+grub-mkpasswd-argon2
+@end example
+
+@command{grub-mkpasswd-argon2} accepts the following options:
+
+@table @option
+@item -i @var{number}
+@itemx --iterations=@var{number}
+Number of iterations to perform. Defaults to 5.
+
+@item -m @var{number}
+@itemx --memory=@var{number}
+Amount of memory (in kibibytes) to use. Defaults to 131072.
+
+@item -p @var{number}
+@itemx --parallelism=@var{number}
+Degree of parallelism (i.e. number of threads). Defaults to 1.
+
+@item -l @var{number}
+@itemx --buflen=@var{number}
+Length of the generated hash. Defaults to 32.
+
+@item -s @var{number}
+@itemx --salt=@var{number}
+Length of the salt. Defaults to 16.
+@end table
+
 
 @node Invoking grub-mkpasswd-pbkdf2
 @section Invoking grub-mkpasswd-pbkdf2
 
-The program @command{grub-mkpasswd-pbkdf2} generates password hashes for
-GRUB (@pxref{Security}).
+The program @command{grub-mkpasswd-pbkdf2} generates password hashes (PBKDF)
+for GRUB (@pxref{Security}).
 
 @example
 grub-mkpasswd-pbkdf2
-- 
2.51.0


_______________________________________________
Grub-devel mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/grub-devel