From: Tobias Stoeckmann Date: Tue, 19 Dec 2023 16:39:54 +0000 (+0100) Subject: man/: add BCRYPT and YESCRYPT information X-Git-Tag: 4.15.0-rc1~63 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=11091949be0ad717bc7259b230cf81bac5f1e52d;p=thirdparty%2Fshadow.git man/: add BCRYPT and YESCRYPT information The BCRYPT and YESCRYPT relevant items should be described in manual pages. Signed-off-by: Tobias Stoeckmann --- diff --git a/man/Makefile.am b/man/Makefile.am index 89d97937b..cffef699a 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -125,6 +125,7 @@ man_XMANS += lastlog.8.xml endif login_defs_v = \ + BCRYPT_MIN_ROUNDS.xml \ CHFN_AUTH.xml \ CHFN_RESTRICT.xml \ CHSH_AUTH.xml \ @@ -191,7 +192,8 @@ login_defs_v = \ SUB_GID_COUNT.xml \ SUB_UID_COUNT.xml \ SYS_GID_MAX.xml \ - SYS_UID_MAX.xml + SYS_UID_MAX.xml \ + YESCRYPT_COST_FACTOR.xml EXTRA_DIST = \ $(man_MANS) \ diff --git a/man/chgpasswd.8.xml b/man/chgpasswd.8.xml index bd2d11796..f4a83c244 100644 --- a/man/chgpasswd.8.xml +++ b/man/chgpasswd.8.xml @@ -6,10 +6,12 @@ --> + ]> @@ -88,12 +90,16 @@ , Use the specified method to encrypt the passwords. - - The available methods are DES, MD5, and NONE. - - - The available methods are DES, MD5, NONE, and SHA256 or SHA512 - if your libc support these methods. + + The available methods are + BCRYPT, + DES, + MD5, + SHA256, + SHA512, + YESCRYPT and + NONE + if your libc supports these methods. @@ -131,29 +137,49 @@ - + , Use the specified number of rounds to encrypt the passwords. - The value 0 means that the system will choose the default - number of rounds for the crypt method (5000). + You can only use this option with crypt method: + + BCRYPT + + SHA256 + SHA512 + + YESCRYPT - - A minimal value of 1000 and a maximal value of 999,999,999 - will be enforced. + + By default, the number of rounds for BCRYPT is defined by the + BCRYPT_MIN_ROUNDS and BCRYPT_MAX_ROUNDS variables in + /etc/login.defs. - - You can only use this option with the SHA256 or SHA512 - crypt method. + + A minimal value of 4 and a maximal value of 31 + will be enforced for BCRYPT. The default number of rounds is 13. - - By default, the number of rounds is defined by the - SHA_CRYPT_MIN_ROUNDS and SHA_CRYPT_MAX_ROUNDS variables in + + By default, the number of rounds for SHA256 or SHA512 is defined by + the SHA_CRYPT_MIN_ROUNDS and SHA_CRYPT_MAX_ROUNDS variables in /etc/login.defs. + + A minimal value of 1000 and a maximal value of 999,999,999 + will be enforced for SHA256 and SHA512. The default number of rounds + is 5000. + + + By default, the number of rounds for YESCRYPT is defined by the + YESCRYPT_COST_FACTOR in /etc/login.defs. + + + A minimal value of 1 and a maximal value of 11 + will be enforced for YESCRYPT. The default number of rounds is 5. + @@ -179,10 +205,12 @@ tool: + &BCRYPT_MIN_ROUNDS; &ENCRYPT_METHOD; &MAX_MEMBERS_PER_GROUP; &MD5_CRYPT_ENAB; &SHA_CRYPT_MIN_ROUNDS; + &YESCRYPT_COST_FACTOR; diff --git a/man/chpasswd.8.xml b/man/chpasswd.8.xml index 1984573ab..cffd9df14 100644 --- a/man/chpasswd.8.xml +++ b/man/chpasswd.8.xml @@ -6,9 +6,11 @@ --> + ]> @@ -115,12 +117,16 @@ Use the specified method to encrypt the passwords. - - The available methods are DES, MD5, and NONE. - - - The available methods are DES, MD5, NONE, and SHA256 or SHA512 - if your libc support these methods. + + The available methods are + BCRYPT, + DES, + MD5, + SHA256, + SHA512, + YESCRYPT and + NONE + if your libc supports these methods. By default, PAM is used to encrypt the passwords. @@ -188,7 +194,7 @@ - + ,  ROUNDS @@ -197,23 +203,42 @@ Use the specified number of rounds to encrypt the passwords. - The value 0 means that the system will choose the default - number of rounds for the crypt method (5000). + You can only use this option with crypt method: + + BCRYPT + + SHA256 + SHA512 + + YESCRYPT - - A minimal value of 1000 and a maximal value of 999,999,999 - will be enforced. + + By default, the number of rounds for BCRYPT is defined by the + BCRYPT_MIN_ROUNDS and BCRYPT_MAX_ROUNDS variables in + /etc/login.defs. - - You can only use this option with the SHA256 or SHA512 - crypt method. + + A minimal value of 4 and a maximal value of 31 + will be enforced for BCRYPT. The default number of rounds is 13. - - By default, the number of rounds is defined by the - and - variables in + + By default, the number of rounds for SHA256 or SHA512 is defined by + the SHA_CRYPT_MIN_ROUNDS and SHA_CRYPT_MAX_ROUNDS variables in /etc/login.defs. + + A minimal value of 1000 and a maximal value of 999,999,999 + will be enforced for SHA256 and SHA512. The default number of rounds + is 5000. + + + By default, the number of rounds for YESCRYPT is defined by the + YESCRYPT_COST_FACTOR in /etc/login.defs. + + + A minimal value of 1 and a maximal value of 11 + will be enforced for YESCRYPT. The default number of rounds is 5. + @@ -239,7 +264,9 @@ &MD5_CRYPT_ENAB; + &BCRYPT_MIN_ROUNDS; &SHA_CRYPT_MIN_ROUNDS; + &YESCRYPT_COST_FACTOR; diff --git a/man/generate_mans.mak b/man/generate_mans.mak index 4d0d268eb..47f906fea 100644 --- a/man/generate_mans.mak +++ b/man/generate_mans.mak @@ -25,6 +25,18 @@ else SHA_CRYPT_COND=no_sha_crypt endif +if USE_BCRYPT +BCRYPT_COND=bcrypt +else +BCRYPT_COND=no_bcrypt +endif + +if USE_YESCRYPT +YESCRYPT_COND=yescrypt +else +YESCRYPT_COND=no_yescrypt +endif + if ENABLE_SUBIDS SUBIDS_COND=subids else @@ -50,7 +62,7 @@ if ENABLE_REGENERATE_MAN fi man1/% man3/% man5/% man8/%: %.xml-config Makefile config.xml - $(XSLTPROC) --stringparam profile.condition "$(PAM_COND);$(SHADOWGRP_COND);$(TCB_COND);$(SHA_CRYPT_COND);$(SUBIDS_COND);$(VENDORDIR_COND);$(LASTLOG_COND)" \ + $(XSLTPROC) --stringparam profile.condition "$(PAM_COND);$(SHADOWGRP_COND);$(TCB_COND);$(SHA_CRYPT_COND);$(BCRYPT_COND);$(YESCRYPT_COND);$(SUBIDS_COND);$(VENDORDIR_COND);$(LASTLOG_COND)" \ --param "man.authors.section.enabled" "0" \ --stringparam "man.output.base.dir" "" \ --stringparam vendordir "$(VENDORDIR)" \ diff --git a/man/gpasswd.1.xml b/man/gpasswd.1.xml index e0d9c0db0..9b89d9156 100644 --- a/man/gpasswd.1.xml +++ b/man/gpasswd.1.xml @@ -6,10 +6,12 @@ --> + ]> diff --git a/man/login.defs.5.xml b/man/login.defs.5.xml index dc64cfc2e..05ef5125e 100644 --- a/man/login.defs.5.xml +++ b/man/login.defs.5.xml @@ -7,6 +7,7 @@ --> @@ -74,6 +75,7 @@ + ]> @@ -145,6 +147,7 @@ The following configuration items are provided: + &BCRYPT_MIN_ROUNDS; &CHFN_AUTH; &CHFN_RESTRICT; &CHSH_AUTH; @@ -218,6 +221,7 @@ &USERDEL_CMD; &USERGROUPS_ENAB; &USE_TCB; + &YESCRYPT_COST_FACTOR; @@ -249,9 +253,12 @@ chgpasswd + BCRYPT_MAX_ROUNDS + BCRYPT_MIN_ROUNDS ENCRYPT_METHOD MAX_MEMBERS_PER_GROUP MD5_CRYPT_ENAB SHA_CRYPT_MAX_ROUNDS SHA_CRYPT_MIN_ROUNDS + YESCRYPT_COST_FACTOR @@ -259,10 +266,13 @@ chpasswd + BCRYPT_MAX_ROUNDS + BCRYPT_MIN_ROUNDS ENCRYPT_METHOD MD5_CRYPT_ENAB SHA_CRYPT_MAX_ROUNDS SHA_CRYPT_MIN_ROUNDS + YESCRYPT_COST_FACTOR @@ -280,9 +290,12 @@ gpasswd + BCRYPT_MAX_ROUNDS + BCRYPT_MIN_ROUNDS ENCRYPT_METHOD MAX_MEMBERS_PER_GROUP MD5_CRYPT_ENAB SHA_CRYPT_MAX_ROUNDS SHA_CRYPT_MIN_ROUNDS + YESCRYPT_COST_FACTOR @@ -380,6 +393,8 @@ newusers + BCRYPT_MAX_ROUNDS + BCRYPT_MIN_ROUNDS ENCRYPT_METHOD GID_MAX GID_MIN MAX_MEMBERS_PER_GROUP MD5_CRYPT_ENAB @@ -391,6 +406,7 @@ SUB_UID_COUNT SUB_UID_MAX SUB_UID_MIN SYS_GID_MAX SYS_GID_MIN SYS_UID_MAX SYS_UID_MIN UID_MAX UID_MIN UMASK + YESCRYPT_COST_FACTOR @@ -399,10 +415,13 @@ passwd + BCRYPT_MAX_ROUNDS + BCRYPT_MIN_ROUNDS ENCRYPT_METHOD MD5_CRYPT_ENAB OBSCURE_CHECKS_ENAB PASS_ALWAYS_WARN PASS_CHANGE_TRIES PASS_MAX_LEN PASS_MIN_LEN SHA_CRYPT_MAX_ROUNDS SHA_CRYPT_MIN_ROUNDS + YESCRYPT_COST_FACTOR diff --git a/man/login.defs.d/BCRYPT_MIN_ROUNDS.xml b/man/login.defs.d/BCRYPT_MIN_ROUNDS.xml new file mode 100644 index 000000000..81ee5c9af --- /dev/null +++ b/man/login.defs.d/BCRYPT_MIN_ROUNDS.xml @@ -0,0 +1,40 @@ + + + (number) + (number) + + + When is set to + BCRYPT, this defines the number of + BCRYPT rounds used by the encryption algorithm by default (when the + number of rounds is not specified on the command line). + + + With a lot of rounds, it is more difficult to brute force the + password. But note also that more CPU resources will be needed to + authenticate users. + + + The values must be inside the 4-31 range. + + + If only one of the or + values is set, then this value + will be used. + + + If > + , the highest value will be + used. + + + Note: This only affect the generation of group passwords. + The generation of user passwords is done by PAM and subject to the + PAM configuration. It is recommended to set this variable + consistently with the PAM configuration. + + + diff --git a/man/login.defs.d/ENCRYPT_METHOD.xml b/man/login.defs.d/ENCRYPT_METHOD.xml index 85dd79b0a..531ce04a8 100644 --- a/man/login.defs.d/ENCRYPT_METHOD.xml +++ b/man/login.defs.d/ENCRYPT_METHOD.xml @@ -10,11 +10,13 @@ passwords (if no algorithm are specified on the command line). - It can take one of these values: + It can take one of these values: + BCRYPT, DES (default), MD5, SHA256, - SHA512. + SHA512, + YESCRYPT. MD5 and DES should not be used for new hashes, see crypt5 for recommendations. diff --git a/man/login.defs.d/SHA_CRYPT_MIN_ROUNDS.xml b/man/login.defs.d/SHA_CRYPT_MIN_ROUNDS.xml index 43972d76c..a22c324c4 100644 --- a/man/login.defs.d/SHA_CRYPT_MIN_ROUNDS.xml +++ b/man/login.defs.d/SHA_CRYPT_MIN_ROUNDS.xml @@ -14,7 +14,7 @@ of rounds is not specified on the command line). - With a lot of rounds, it is more difficult to brute forcing the + With a lot of rounds, it is more difficult to brute force the password. But note also that more CPU resources will be needed to authenticate users. diff --git a/man/login.defs.d/YESCRYPT_COST_FACTOR.xml b/man/login.defs.d/YESCRYPT_COST_FACTOR.xml new file mode 100644 index 000000000..b9c531406 --- /dev/null +++ b/man/login.defs.d/YESCRYPT_COST_FACTOR.xml @@ -0,0 +1,29 @@ + + + (number) + + + When is set to + YESCRYPT, this defines the cost factor + used by the encryption algorithm by default (when the cost factor + is not specified on the command line). + + + With a high cost factor, it is more difficult to brute force the + password. But note also that more CPU resources will be needed to + authenticate users. + + + The value must be inside the 1-11 range. + + + Note: This only affect the generation of group passwords. + The generation of user passwords is done by PAM and subject to the + PAM configuration. It is recommended to set this variable + consistently with the PAM configuration. + + + diff --git a/man/newusers.8.xml b/man/newusers.8.xml index 4ff005244..6812c7509 100644 --- a/man/newusers.8.xml +++ b/man/newusers.8.xml @@ -6,6 +6,7 @@ --> @@ -21,6 +22,7 @@ + ]> @@ -316,29 +318,48 @@ - + , Use the specified number of rounds to encrypt the passwords. - The value 0 means that the system will choose the default - number of rounds for the crypt method (5000). + You can only use this option with crypt method: + + BCRYPT + + SHA256 + SHA512 + + YESCRYPT - - A minimal value of 1000 and a maximal value of 999,999,999 - will be enforced. + + By default, the number of rounds for BCRYPT is defined by the + BCRYPT_MIN_ROUNDS and BCRYPT_MAX_ROUNDS variables in + /etc/login.defs. - - You can only use this option with the SHA256 or SHA512 - crypt method. + + A minimal value of 4 and a maximal value of 31 + will be enforced for BCRYPT. The default is 13. - - By default, the number of rounds is defined by the + + By default, the number of rounds for SHA256 or SHA512 is defined by the SHA_CRYPT_MIN_ROUNDS and SHA_CRYPT_MAX_ROUNDS variables in /etc/login.defs. + + A minimal value of 1000 and a maximal value of 999,999,999 + will be enforced for SHA256 and SHA512. The default is 5000. + + + By default, the number of rounds for YESCRYPT is defined by the + YESCRYPT_COST_FACTOR in /etc/login.defs. + + + A minimal value of 1 and a maximal value of 11 + will be enforced for YESCRYPT. The default is 5. + diff --git a/man/passwd.1.xml b/man/passwd.1.xml index 5fbfa6d17..312f7ded1 100644 --- a/man/passwd.1.xml +++ b/man/passwd.1.xml @@ -6,6 +6,7 @@ --> @@ -13,6 +14,7 @@ + ]>