[PATCH 0/4] crypt.3: documented "rounds" parameter for SHA-* algorithms

[PATCH 0/4] crypt.3: documented "rounds" parameter for SHA-* algorithms

[Konstantin Shemyak]

SHA-256 and SHA-512 based encryption algorithms support passing number of hashing rounds in the salt string, like:

crypt("password", "$5$rounds=100000$saltsaltsalt")

This was present since introduction of SHA-*-based algorithms in the glibc commit c3266dc0d85ed519ff40d1738aadf7b1280af3ba.

The parameter is explained. Minor wording and formatting fixes done.

Konstantin Shemyak (4):
  crypt.3: wfix: encryption is not done with SHA-xxx, but with a
    function based on SHA-xxx.
  crypt.3: ffix: added missing formatting
  crypt.3: wfix: clarified that ending of the salt string with '$' is
    optional
  crypt.3: Added description of previously undocumented 'rounds'
    parameter

 man3/crypt.3 | 30 +++++++++++++++++++++++-------
 1 file changed, 23 insertions(+), 7 deletions(-)

-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 1/4] crypt.3: wfix: encryption is not done with SHA-xxx, but with a function based on SHA-xxx.

[Konstantin Shemyak]

Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>
---
 man3/crypt.3 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man3/crypt.3 b/man3/crypt.3
index 9edd63a..749a636 100644
--- a/man3/crypt.3
+++ b/man3/crypt.3
@@ -227,9 +227,9 @@ _
 .TE
 .RE
 .PP
-So $5$\fIsalt\fP$\fIencrypted\fP is an SHA-256 encoded
-password and $6$\fIsalt\fP$\fIencrypted\fP is an
-SHA-512 encoded one.
+So $5$\fIsalt\fP$\fIencrypted\fP and $6$\fIsalt\fP$\fIencrypted\fP
+contain the password encrypted correspondingly with a function
+based on SHA-256 and SHA-512.
 .PP
 "\fIsalt\fP" stands for the up to 16 characters
 following "$\fIid\fP$" in the salt.
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 2/4] crypt.3: ffix: added missing formatting

[Konstantin Shemyak]

Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>
---
 man3/crypt.3 | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/man3/crypt.3 b/man3/crypt.3
index 749a636..1bd8509 100644
--- a/man3/crypt.3
+++ b/man3/crypt.3
@@ -233,7 +233,8 @@ based on SHA-256 and SHA-512.
 .PP
 "\fIsalt\fP" stands for the up to 16 characters
 following "$\fIid\fP$" in the salt.
-The encrypted part of the password string is the actual computed password.
+The "\fIencrypted\fP"
+part of the password string is the actual computed password.
 The size of this string is fixed:
 .TS
 l l.
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 3/4] crypt.3: wfix: clarified that ending of the salt string with '$' is optional

[Konstantin Shemyak]

Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>
---
 man3/crypt.3 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man3/crypt.3 b/man3/crypt.3
index 1bd8509..375ef93 100644
--- a/man3/crypt.3
+++ b/man3/crypt.3
@@ -195,15 +195,15 @@ encryption algorithms.
 If
 .I salt
 is a character string starting with the characters "$\fIid\fP$"
-followed by a string terminated by "$":
+followed by a string optionally terminated by "$",
+then the result has the form:
 .RS
 .PP
 $\fIid\fP$\fIsalt\fP$\fIencrypted\fP
 .PP
 .RE
-then instead of using the DES machine,
 .I id
-identifies the encryption method used and this then determines how the rest
+identifies the encryption method used instead of DES and this then determines how the rest
 of the password string is interpreted.
 The following values of
 .I id
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 4/4] crypt.3: Added description of previously undocumented 'rounds' parameter

[Konstantin Shemyak]

Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>
---
 man3/crypt.3 | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/man3/crypt.3 b/man3/crypt.3
index 375ef93..b9cf973 100644
--- a/man3/crypt.3
+++ b/man3/crypt.3
@@ -249,6 +249,21 @@ In the MD5 and SHA implementations the entire
 .I key
 is significant (instead of only the first
 8 bytes in DES).
+.PP
+SHA-256 and SHA-512 implementations support user-supplied number of
+hashing rounds, defaulting to 5000.
+If the "$\fIid\fP$" characters in the salt are
+followed by "rounds=\fIxxx\fP$" and \fIxxx\fP is an integer, then the
+result has the form
+.RS
+.PP
+$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIencrypted\fP
+.PP
+.RE
+where \fIyyy\fP is the actual number of hashing rounds used.
+This actual number is 1000 if the supplied number is less than 1000,
+999999999 if the supplied number is greater than 999999999, and
+equal to the supplied number otherwise.
 .SH SEE ALSO
 .BR login (1),
 .BR passwd (1),
-- 
2.7.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/4] crypt.3: ffix: added missing formatting

[Michael Kerrisk (man-pages)]

On 09/03/2017 06:16 PM, Konstantin Shemyak wrote:
> Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>

Applied. Thanks, Konstantin.

Cheers,

Michael

> ---
>  man3/crypt.3 | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/man3/crypt.3 b/man3/crypt.3
> index 749a636..1bd8509 100644
> --- a/man3/crypt.3
> +++ b/man3/crypt.3
> @@ -233,7 +233,8 @@ based on SHA-256 and SHA-512.
>  .PP
>  "\fIsalt\fP" stands for the up to 16 characters
>  following "$\fIid\fP$" in the salt.
> -The encrypted part of the password string is the actual computed password.
> +The "\fIencrypted\fP"
> +part of the password string is the actual computed password.
>  The size of this string is fixed:
>  .TS
>  l l.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 3/4] crypt.3: wfix: clarified that ending of the salt string with '$' is optional

[Michael Kerrisk (man-pages)]

Hello Konstantin,

On 09/03/2017 06:16 PM, Konstantin Shemyak wrote:
> Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>

Some details about how this was verified would be useful for the commit
message. Am I correct to assume that the relevant code is the following
in crypt/sha512-crypt.c::__sha512_crypt_r()

      if (*endp == '$')
        {
          salt = endp + 1;
          rounds = MAX (ROUNDS_MIN, MIN (srounds, ROUNDS_MAX));
          rounds_custom = true;
        }

and similar in crypt/sha256-crypt.c?

Thanks,

Michael

> ---
>  man3/crypt.3 | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/man3/crypt.3 b/man3/crypt.3
> index 1bd8509..375ef93 100644
> --- a/man3/crypt.3
> +++ b/man3/crypt.3
> @@ -195,15 +195,15 @@ encryption algorithms.
>  If
>  .I salt
>  is a character string starting with the characters "$\fIid\fP$"
> -followed by a string terminated by "$":
> +followed by a string optionally terminated by "$",
> +then the result has the form:
>  .RS
>  .PP
>  $\fIid\fP$\fIsalt\fP$\fIencrypted\fP
>  .PP
>  .RE
> -then instead of using the DES machine,
>  .I id
> -identifies the encryption method used and this then determines how the rest
> +identifies the encryption method used instead of DES and this then determines how the rest
>  of the password string is interpreted.
>  The following values of
>  .I id
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 0/4] crypt.3: documented "rounds" parameter for SHA-* algorithms

[Michael Kerrisk (man-pages)]

Hello Konstantin,

On 09/03/2017 06:16 PM, Konstantin Shemyak wrote:
> SHA-256 and SHA-512 based encryption algorithms support passing
> number of hashing rounds in the salt string, like:
> 
> crypt("password", "$5$rounds=100000$saltsaltsalt")
> 
> This was present since introduction of SHA-*-based algorithms in the
> glibc commit c3266dc0d85ed519ff40d1738aadf7b1280af3ba.
> 
> The parameter is explained. Minor wording and formatting fixes done.
> 
> Konstantin Shemyak (4):
>   crypt.3: wfix: encryption is not done with SHA-xxx, but with a
>     function based on SHA-xxx.
>   crypt.3: ffix: added missing formatting
>   crypt.3: wfix: clarified that ending of the salt string with '$' is
>     optional
>   crypt.3: Added description of previously undocumented 'rounds'
>     parameter
> 
>  man3/crypt.3 | 30 +++++++++++++++++++++++-------
>  1 file changed, 23 insertions(+), 7 deletions(-)

In general the patch series looks good, but I need some more
supporting information for the commit message and for checking details.
See comments on individual patches, in following mails.

Cheers,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/4] crypt.3: wfix: encryption is not done with SHA-xxx, but with a function based on SHA-xxx.

[Michael Kerrisk (man-pages)]

On 09/03/2017 06:16 PM, Konstantin Shemyak wrote:
> Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>

Hi Konstantin,

Could you add some info saying how you checked/discovered
the details changed by this commit message?

Also, a minor nit: this is not a "wfix" commit. It changes the
meaning of the text.

Thanks,

Michael


> ---
>  man3/crypt.3 | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
> 
> diff --git a/man3/crypt.3 b/man3/crypt.3
> index 9edd63a..749a636 100644
> --- a/man3/crypt.3
> +++ b/man3/crypt.3
> @@ -227,9 +227,9 @@ _
>  .TE
>  .RE
>  .PP
> -So $5$\fIsalt\fP$\fIencrypted\fP is an SHA-256 encoded
> -password and $6$\fIsalt\fP$\fIencrypted\fP is an
> -SHA-512 encoded one.
> +So $5$\fIsalt\fP$\fIencrypted\fP and $6$\fIsalt\fP$\fIencrypted\fP
> +contain the password encrypted correspondingly with a function
> +based on SHA-256 and SHA-512.
>  .PP
>  "\fIsalt\fP" stands for the up to 16 characters
>  following "$\fIid\fP$" in the salt.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 4/4] crypt.3: Added description of previously undocumented 'rounds' parameter

[Michael Kerrisk (man-pages)]

Hi Konstantin

On 09/03/2017 06:16 PM, Konstantin Shemyak wrote:
> Signed-off-by: Konstantin Shemyak <konstantin-gSWgoXPz5bhBDgjK7y7TUQ@public.gmane.org>

So, this man page change should mention the glibc version where this
parameter was introduced. It looks like glibc 2.7. Can you confirm
and update the patch?

Also, in the commit message, it would be good to note how the various
details were discovered/can be verified from source code. For example,
mention the following from crypt/sha512-crypt.c:

/* Default number of rounds if not explicitly specified.  */
#define ROUNDS_DEFAULT 5000
/* Minimum number of rounds.  */
#define ROUNDS_MIN 1000
/* Maximum number of rounds.  */
#define ROUNDS_MAX 999999999

> ---
>  man3/crypt.3 | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/man3/crypt.3 b/man3/crypt.3
> index 375ef93..b9cf973 100644
> --- a/man3/crypt.3
> +++ b/man3/crypt.3
> @@ -249,6 +249,21 @@ In the MD5 and SHA implementations the entire
>  .I key
>  is significant (instead of only the first
>  8 bytes in DES).
> +.PP
> +SHA-256 and SHA-512 implementations support user-supplied number of
> +hashing rounds, defaulting to 5000.
> +If the "$\fIid\fP$" characters in the salt are
> +followed by "rounds=\fIxxx\fP$" and \fIxxx\fP is an integer, then the
> +result has the form
> +.RS
> +.PP
> +$\fIid\fP$\fIrounds=yyy\fP$\fIsalt\fP$\fIencrypted\fP
> +.PP
> +.RE
> +where \fIyyy\fP is the actual number of hashing rounds used.
> +This actual number is 1000 if the supplied number is less than 1000,

Change first part to" The number actually used is 1000..."

> +999999999 if the supplied number is greater than 999999999, and
> +equal to the supplied number otherwise.
>  .SH SEE ALSO
>  .BR login (1),
>  .BR passwd (1),

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html