svn commit: r362191 - head/sbin/md5

Mon Jun 15 11:02:02 UTC 2020

Fernando Apesteguía wrote:
> Author: fernape (ports committer)
> Date: Mon Jun 15 10:08:02 2020
> New Revision: 362191
> URL: https://svnweb.freebsd.org/changeset/base/362191
> 
> Log:
>    md5(1): fix style in man page
>    
>    Fix a bunch of style problems reported by mandoc(1) and igor:
>    
>    mandoc: ./md5.1:19:71: STYLE: no blank before trailing delimiter: Nm ... rmd160,
>    mandoc: ./md5.1:20:23: STYLE: no blank before trailing delimiter: Nm ...  skein512,
>    mandoc: ./md5.1:33:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:33:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:33:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:33:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:35:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:42:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:45:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:47:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:56:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:58:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:61:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:66:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:68:2: STYLE: useless macro: Tn
>    mandoc: ./md5.1:104:24: STYLE: no blank before trailing delimiter: Nm skein512,
>    mandoc: ./md5.1:117:6: STYLE: referenced manual not found: Xr sha224 3
>    
>    igor:
>    md5.1:46:no comma after "i.e.":either algorithm, [i.e.] to find an input that produces a specific
>    
>    Approved by:	bcr@
>    Differential Revision: https://reviews.freebsd.org/D25277
> 
> Modified:
>    head/sbin/md5/md5.1
> 
> Modified: head/sbin/md5/md5.1
> ==============================================================================
> --- head/sbin/md5/md5.1	Mon Jun 15 03:10:53 2020	(r362190)
> +++ head/sbin/md5/md5.1	Mon Jun 15 10:08:02 2020	(r362191)
> @@ -1,5 +1,5 @@
>   .\" $FreeBSD$
> -.Dd July 9, 2018
> +.Dd June 15, 2020
>   .Dt MD5 1
>   .Os
>   .Sh NAME
> @@ -16,8 +16,8 @@
>   (All other hashes have the same options and usage.)
>   .Sh DESCRIPTION
>   The
> -.Nm md5 , sha1 , sha224 , sha256 , sha384 , sha512, sha512t256, rmd160,
> -.Nm skein256, skein512,
> +.Nm md5 , sha1 , sha224 , sha256 , sha384 , sha512 , sha512t256 , rmd160 ,
> +.Nm skein256 , skein512 ,
>   and
>   .Nm skein1024
>   utilities take as input a message of arbitrary length and produce as
> @@ -29,43 +29,29 @@ of the input.
>   It is conjectured that it is computationally infeasible to
>   produce two messages having the same message digest, or to produce any
>   message having a given prespecified target message digest.
> -The
> -.Tn SHA-224 , SHA-256 , SHA-384 , SHA-512, RIPEMD-160,
> -and
> -.Tn SKEIN
> +The SHA-224 , SHA-256 , SHA-384 , SHA-512, RIPEMD-160,
> +and SKEIN
>   algorithms are intended for digital signature applications, where a
>   large file must be
>   .Dq compressed
>   in a secure manner before being encrypted with a private
>   (secret)
> -key under a public-key cryptosystem such as
> -.Tn RSA .
> +key under a public-key cryptosystem such as RSA.
>   .Pp
> -The
> -.Tn MD5
> -and
> -.Tn SHA-1
> -algorithms have been proven to be vulnerable to practical collision
> -attacks and should not be relied upon to produce unique outputs,
> +The MD5 and SHA-1 algorithms have been proven to be vulnerable to practical
> +collision attacks and should not be relied upon to produce unique outputs,
>   .Em nor should they be used as part of a cryptographic signature scheme.
>   As of 2017-03-02, there is no publicly known method to
>   .Em reverse
> -either algorithm, i.e. to find an input that produces a specific
> +either algorithm, i.e., to find an input that produces a specific
>   output.
>   .Pp
> -.Tn SHA-512t256
> -is a version of
> -.Tn SHA-512
> -truncated to only 256 bits.
> -On 64-bit hardware, this algorithm is approximately 50% faster than
> -.Tn SHA-256
> -but with the same level of security.
> +SHA-512t256 is a version of SHA-512 truncated to only 256 bits.
> +On 64-bit hardware, this algorithm is approximately 50% faster than SHA-256 but
> +with the same level of security.
>   The hashes are not interchangeable.
>   .Pp
> -It is recommended that all new applications use
> -.Tn SHA-512
> -or
> -.Tn SKEIN-512
> +It is recommended that all new applications use SHA-512 or SKEIN-512
>   instead of one of the other hash functions.
>   .Pp
>   The following options may be used in any combination and must
> @@ -101,7 +87,7 @@ Run a built-in test script.
>   .Sh EXIT STATUS
>   The
>   .Nm md5 , sha1 , sha224 , sha256 , sha512 , sha512t256 , rmd160 ,
> -.Nm skein256 , skein512,
> +.Nm skein256 , skein512 ,
>   and
>   .Nm skein1024
>   utilities exit 0 on success,
> @@ -114,7 +100,6 @@ option.
>   .Xr md5 3 ,
>   .Xr ripemd 3 ,
>   .Xr sha 3 ,
> -.Xr sha224 3 ,
>   .Xr sha256 3 ,
>   .Xr sha384 3 ,
>   .Xr sha512 3 ,

I think we should create sha256.3 -> sha224.3 instead of removing the 
reference, as done for sha512.3 -> sha384.3 -- if you look at the 
sha256.3 man page, it documents all of the SHA224_* functions; i.e.,:

Index: Makefile
===================================================================

--- Makefile    (revision 362145)
+++ Makefile    (working copy)
@@ -40,7 +40,7 @@
  MLINKS+=sha256.3 SHA224_Init.3  sha256.3 SHA224_Update.3
  MLINKS+=sha256.3 SHA224_Final.3 sha256.3 SHA224_End.3
  MLINKS+=sha256.3 SHA224_File.3  sha256.3 SHA224_FileChunk.3
-MLINKS+=sha256.3 SHA224_Data.3
+MLINKS+=sha256.3 SHA224_Data.3 sha256.3 sha224.3
  MLINKS+=sha256.3 SHA256_Init.3  sha256.3 SHA256_Update.3
  MLINKS+=sha256.3 SHA256_Final.3 sha256.3 SHA256_End.3
  MLINKS+=sha256.3 SHA256_File.3  sha256.3 SHA256_FileChunk.3
