sbin/md5/md5.1

   1 .Dd May 10, 2023
   2 .Dt MD5 1
   3 .Os
   4 .Sh NAME
   5 .Nm md5 , sha1 , sha224 , sha256 , sha384 ,
   6 .Nm sha512 , sha512t224 , sha512t256 ,
   7 .Nm rmd160 , skein256 , skein512 , skein1024 ,
   8 .Nm md5sum , sha1sum , sha224sum , sha256sum , sha384sum ,
   9 .Nm sha512sum , sha512t224sum , sha512t256sum ,
  10 .Nm rmd160sum , skein256sum , skein512sum , skein1024sum ,
  11 .Nm shasum
  12 .Nd calculate a message-digest fingerprint (checksum) for a file
  13 .Sh SYNOPSIS
  14 .Nm
  15 .Op Fl pqrtx
  16 .Op Fl c Ar string
  17 .Op Fl s Ar string
  18 .Op Ar
  19 .Pp
  20 .Nm md5sum
  21 .Op Fl bctwz
  22 .Op Fl -binary
  23 .Op Fl -check
  24 .Op Fl -help
  25 .Op Fl -ignore-missing
  26 .Op Fl -quiet
  27 .Op Fl -status
  28 .Op Fl -strict
  29 .Op Fl -tag
  30 .Op Fl -text
  31 .Op Fl -version
  32 .Op Fl -warn
  33 .Op Fl -zero
  34 .Op Ar
  35 .Pp
  36 (All other hashes have the same options and usage.)
  37 .Pp
  38 .Nm shasum
  39 .Op Fl 0bchqstUvw
  40 .Op Fl -01
  41 .Op Fl a | -algorithm Ar alg
  42 .Op Fl -binary
  43 .Op Fl -check
  44 .Op Fl -help
  45 .Op Fl -ignore-missing
  46 .Op Fl -quiet
  47 .Op Fl -status
  48 .Op Fl -strict
  49 .Op Fl -tag
  50 .Op Fl -text
  51 .Op Fl -UNIVERSAL
  52 .Op Fl -version
  53 .Op Fl -warn
  54 .Op Ar
  55 .Sh DESCRIPTION
  56 The
  57 .Nm md5 , sha1 , sha224 , sha256 , sha384 , sha512 , sha512t224 , sha512t256 ,
  58 .Nm rmd160 , skein256 , skein512 ,
  59 and
  60 .Nm skein1024
  61 utilities take as input a message of arbitrary length and produce as
  62 output a
  63 .Dq fingerprint
  64 or
  65 .Dq message digest
  66 of the input.
  67 .Pp
  68 The
  69 .Nm md5sum , sha1sum , sha224sum , sha256sum , sha384sum , sha512sum ,
  70 .Nm sha512t224sum , sha512t256sum , rmd160sum , skein256sum , skein512sum ,
  71 and
  72 .Nm skein1024sum
  73 utilities do the same, but with command-line options and an output
  74 format that match those of their similary named GNU utilities.
  75 .Pp
  76 The
  77 .Nm shasum
  78 utility does the same, but with command-line options and an output
  79 format that match those of the similarly named utility that ships with
  80 Perl.
  81 .Pp
  82 It is conjectured that it is computationally infeasible to
  83 produce two messages having the same message digest, or to produce any
  84 message having a given prespecified target message digest.
  85 The SHA-224 , SHA-256 , SHA-384 , SHA-512, RIPEMD-160,
  86 and SKEIN
  87 algorithms are intended for digital signature applications, where a
  88 large file must be
  89 .Dq compressed
  90 in a secure manner before being encrypted with a private
  91 (secret)
  92 key under a public-key cryptosystem such as RSA.
  93 .Pp
  94 The MD5 and SHA-1 algorithms have been proven to be vulnerable to practical
  95 collision attacks and should not be relied upon to produce unique outputs,
  96 .Em nor should they be used as part of a cryptographic signature scheme.
  97 As of 2017-03-02, there is no publicly known method to
  98 .Em reverse
  99 either algorithm, i.e., to find an input that produces a specific
 100 output.
 101 .Pp
 102 SHA-512t256 is a version of SHA-512 truncated to only 256 bits.
 103 On 64-bit hardware, this algorithm is approximately 50% faster than SHA-256 but
 104 with the same level of security.
 105 The hashes are not interchangeable.
 106 .Pp
 107 SHA-512t224 is identical to SHA-512t256, but with the digest truncated
 108 to 224 bits.
 109 .Pp
 110 It is recommended that all new applications use SHA-512 or SKEIN-512
 111 instead of one of the other hash functions.
 112 .Ss BSD OPTIONS
 113 The following options are available in BSD mode, i.e. when the program
 114 is invoked with a name that does not end in
 115 .Dq sum :
 116 .Bl -tag -width indent
 117 .It Fl c Ar string , Fl -check= Ns Ar string
 118 Compare the digest of the file against this string.
 119 If combined with the
 120 .Fl q
 121 or
 122 .Fl -quiet
 123 option, the calculated digest is printed in addition to the exit status being set.
 124 .Pq Note that this option is not yet useful if multiple files are specified.
 125 .It Fl p , -passthrough
 126 Echo stdin to stdout and append the checksum to stdout.
 127 .It Fl q , -quiet
 128 Quiet mode \(em only the checksum is printed out.
 129 Overrides the
 130 .Fl r
 131 or
 132 .Fl -reverse
 133 option.
 134 .It Fl r , -reverse
 135 Reverses the format of the output.
 136 This helps with visual diffs.
 137 Does nothing
 138 when combined with the
 139 .Fl ptx
 140 options.
 141 .It Fl s Ar string , Fl -string= Ns Ar string
 142 Print a checksum of the given
 143 .Ar string .
 144 .It Fl t , Fl -time-trial
 145 Run a built-in time trial.
 146 For the
 147 .Nm -sum
 148 versions, this is a nop for compatibility with coreutils.
 149 .It Fl x , Fl -self-test
 150 Run a built-in test script.
 151 .El
 152 .Ss GNU OPTIONS
 153 The following options are available in GNU mode, i.e. when the program
 154 is invoked with a name that ends in
 155 .Dq sum :
 156 .Bl -tag -width indent
 157 .It Fl b , Fl -binary
 158 Read files in binary mode.
 159 .It Fl c , Fl -check
 160 The file passed as arguments must contain digest lines generated by the same
 161 digest algorithm in either classical BSD format or in GNU coreutils format.
 162 A line with the file name followed by a colon
 163 .Dq ":"
 164 and either OK or FAILED is written for each well-formed line in the digest file.
 165 If applicable, the number of failed comparisons and the number of lines that were
 166 skipped since they were not well-formed are printed at the end.
 167 The
 168 .Fl -quiet
 169 option can be used to quiesce the output unless there are mismatched entries in
 170 the digest.
 171 .It Fl -help
 172 Print a usage message and exit.
 173 .It Fl -ignore-missing
 174 When verifying checksums, ignore files for which checksums are given
 175 but which aren't found on disk.
 176 .It Fl -quiet
 177 When verifying checksums, do not print anything unless the
 178 verification fails.
 179 .It Fl -status
 180 When verifying checksums, do not print anything at all.
 181 The exit code will reflect whether verification succeeded.
 182 .It Fl -strict
 183 When verifying checksums, fail if the input is malformed.
 184 .It Fl -tag
 185 Produce BSD-style output.
 186 .It Fl t , Fl -text
 187 Read files in text mode.
 188 This is the default.
 189 Note that this implementation does not differentiate between binary
 190 and text mode.
 191 .It Fl -version
 192 Print version information and exit.
 193 .It Fl w , Fl -warn
 194 When verifying checksums, warn about malformed input.
 195 .It Fl z , Fl -zero
 196 Terminate output lines with NUL rather than with newline.
 197 .El
 198 .Ss PERL OPTIONS
 199 The following options are available in Perl mode, i.e. when the program
 200 is invoked with the name
 201 .Dq shasum :
 202 .Bl -tag -width indent
 203 .It Fl 0 , Fl -01
 204 Read files in bits mode: ASCII
 205 .Sq 0
 206 and
 207 .Sq 1
 208 characters correspond to 0 and 1 bits, respectively, and all other
 209 characters are ignored.
 210 See
 211 .Sx BUGS .
 212 .It Fl a Ar alg , Fl -algorithm Ar alg
 213 Use the specified algorithm:
 214 .Dq 1
 215 for SHA-1 (default),
 216 .Dq xxx
 217 for
 218 .Va xxx Ns -bit
 219 SHA-2 (e.g.
 220 .Dq 256
 221 for SHA-256)
 222 or
 223 .Dq xxxyyy
 224 for
 225 .Va xxx Ns -bit
 226 SHA-2 truncated to
 227 .Va yyy
 228 bits (e.g.
 229 .Dq 512224
 230 for SHA-512/224).
 231 .It Fl b , Fl -binary
 232 Read files in binary mode.
 233 .It Fl c , Fl -check
 234 The file passed as arguments must contain digest lines generated by the same
 235 digest algorithm in either classical BSD format or in GNU coreutils format.
 236 A line with the file name followed by a colon
 237 .Dq ":"
 238 and either OK or FAILED is written for each well-formed line in the digest file.
 239 If applicable, the number of failed comparisons and the number of lines that were
 240 skipped since they were not well-formed are printed at the end.
 241 The
 242 .Fl -quiet
 243 option can be used to quiesce the output unless there are mismatched entries in
 244 the digest.
 245 .It Fl -help
 246 Print a usage message and exit.
 247 .It Fl -ignore-missing
 248 When verifying checksums, ignore files for which checksums are given
 249 but which aren't found on disk.
 250 .It Fl -quiet
 251 When verifying checksums, do not print anything unless the
 252 verification fails.
 253 .It Fl -status
 254 When verifying checksums, do not print anything at all.
 255 The exit code will reflect whether verification succeeded.
 256 .It Fl -strict
 257 When verifying checksums, fail if the input is malformed.
 258 .It Fl -tag
 259 Produce BSD-style output.
 260 .It Fl t , Fl -text
 261 Read files in text mode.
 262 This is the default.
 263 Note that this implementation does not differentiate between binary
 264 and text mode.
 265 .It Fl U , Fl -UNIVERSAL
 266 Read files in universal mode: any CR-LF pair, as well as any CR not
 267 followed by LF, is translated to LF before the digest is computed.
 268 .It Fl -version
 269 Print version information and exit.
 270 .It Fl w , Fl -warn
 271 When verifying checksums, warn about malformed input.
 272 .El
 273 .Sh EXIT STATUS
 274 The
 275 .Nm md5 , sha1 , sha224 , sha256 , sha384 , sha512 ,
 276 .Nm sha512t224 , sha512t256 ,
 277 .Nm rmd160 , skein256 , skein512 ,
 278 and
 279 .Nm skein1024
 280 utilities exit 0 on success,
 281 1 if at least one of the input files could not be read,
 282 and 2 if at least one file does not have the same hash as the
 283 .Fl c
 284 option.
 285 .Pp
 286 The
 287 .Nm md5sum , sha1sum , sha224sum , sha256sum , sha384sum , sha512sum ,
 288 .Nm sha512t224sum , sha512t256sum ,
 289 .Nm rmd160 , skein256 , skein512 , skein1024
 290 and
 291 .Nm shasum
 292 utilities exit 0 on success and 1 if at least one of the input files
 293 could not be read or, when verifying checksums, does not have the
 294 expected checksum.
 295 .Sh EXAMPLES
 296 Calculate the MD5 checksum of the string
 297 .Dq Hello .
 298 .Bd -literal -offset indent
 299 $ md5 -s Hello
 300 MD5 ("Hello") = 8b1a9953c4611296a827abf8c47804d7
 301 .Ed
 302 .Pp
 303 Same as above, but note the absence of the newline character in the input
 304 string:
 305 .Bd -literal -offset indent
 306 $ echo -n Hello | md5
 307 8b1a9953c4611296a827abf8c47804d7
 308 .Ed
 309 .Pp
 310 Calculate the checksum of multiple files reversing the output:
 311 .Bd -literal -offset indent
 312 $ md5 -r /boot/loader.conf /etc/rc.conf
 313 ada5f60f23af88ff95b8091d6d67bef6 /boot/loader.conf
 314 d80bf36c332dc0fdc479366ec3fa44cd /etc/rc.conf
 315 .Ed
 316 .Pp
 317 This is almost but not quite identical to the output from GNU mode:
 318 .Bd -literal -offset indent
 319 $ md5sum /boot/loader.conf /etc/rc.conf
 320 ada5f60f23af88ff95b8091d6d67bef6  /boot/loader.conf
 321 d80bf36c332dc0fdc479366ec3fa44cd  /etc/rc.conf
 322 .Ed
 323 .Pp
 324 Note the two spaces between hash and file name.
 325 If binary mode is requested, they are instead separated by a space and
 326 an asterisk:
 327 .Bd -literal -offset indent
 328 $ md5sum -b /boot/loader.conf /etc/rc.conf
 329 ada5f60f23af88ff95b8091d6d67bef6 */boot/loader.conf
 330 d80bf36c332dc0fdc479366ec3fa44cd */etc/rc.conf
 331 .Ed
 332 .Pp
 333 Write the digest for
 334 .Pa /boot/loader.conf
 335 in a file named
 336 .Pa digest .
 337 Then calculate the checksum again and validate it against the checksum string
 338 extracted from the
 339 .Pa digest
 340 file:
 341 .Bd -literal -offset indent
 342 $ md5 /boot/loader.conf > digest && md5 -c $(cut -f2 -d= digest) /boot/loader.conf
 343 MD5 (/boot/loader.conf) = ada5f60f23af88ff95b8091d6d67bef6
 344 .Ed
 345 .Pp
 346 Same as above but comparing the digest against an invalid string
 347 .Pq Dq randomstring ,
 348 which results in a failure.
 349 .Bd -literal -offset indent
 350 $ md5 -c randomstring /boot/loader.conf
 351 MD5 (/boot/loader.conf) = ada5f60f23af88ff95b8091d6d67bef6 [ Failed ]
 352 .Ed
 353 .Pp
 354 In GNU mode, the
 355 .Fl c
 356 option does not compare against a hash string passed as parameter.
 357 Instead, it expects a digest file, as created under the name
 358 .Pa digest
 359 for
 360 .Pa /boot/loader.conf
 361 in the example above.
 362 .Bd -literal -offset indent
 363 $ md5 -c digest /boot/loader.conf
 364 /boot/loader.conf: OK
 365 .Ed
 366 .Pp
 367 The digest file may contain any number of lines in the format
 368 generated in either BSD or GNU mode.
 369 If a hash value does not match the file,
 370 .Dq FAILED
 371 is printed instead of
 372 .Dq OK .
 373 .Sh SEE ALSO
 374 .Xr cksum 1 ,
 375 .Xr md5 3 ,
 376 .Xr ripemd 3 ,
 377 .Xr sha 3 ,
 378 .Xr sha256 3 ,
 379 .Xr sha384 3 ,
 380 .Xr sha512 3 ,
 381 .Xr skein 3
 382 .Rs
 383 .%A R. Rivest
 384 .%T The MD5 Message-Digest Algorithm
 385 .%O RFC1321
 386 .Re
 387 .Rs
 388 .%A J. Burrows
 389 .%T The Secure Hash Standard
 390 .%O FIPS PUB 180-2
 391 .Re
 392 .Rs
 393 .%A D. Eastlake and P. Jones
 394 .%T US Secure Hash Algorithm 1
 395 .%O RFC 3174
 396 .Re
 397 .Pp
 398 RIPEMD-160 is part of the ISO draft standard
 399 .Qq ISO/IEC DIS 10118-3
 400 on dedicated hash functions.
 401 .Pp
 402 Secure Hash Standard (SHS):
 403 .Pa https://www.nist.gov/publications/secure-hash-standard-shs
 404 .Pp
 405 The RIPEMD-160 page:
 406 .Pa https://homes.esat.kuleuven.be/~bosselae/ripemd160.html
 407 .Sh BUGS
 408 In bits mode, the original
 409 .Nm shasum
 410 script is capable of processing inputs of arbitrary length.
 411 This implementation is not, and will issue an error if the input
 412 length is not a multiple of eight bits.
 413 .Sh ACKNOWLEDGMENTS
 414 .An -nosplit
 415 This utility was originally derived from a program which was placed in
 416 the public domain for free general use by RSA Data Security.
 417 .Pp
 418 Support for SHA-1 and RIPEMD-160 was added by
 419 .An Oliver Eikemeier Aq Mt eik@FreeBSD.org .
 420 .Pp
 421 Support for SHA-2 was added by
 422 .An Colin Percival Aq Mt cperciva@FreeBSD.org
 423 and
 424 .An Allan Jude Aq Mt allanjude@FreeBSD.org .
 425 .Pp
 426 Support for SKEIN was added by
 427 .An Allan Jude Aq Mt allanjude@FreeBSD.org .
 428 .Pp
 429 Compatibility with GNU coreutils was added by
 430 .An Warner Losh Aq Mt imp@FreeBSD.org
 431 and much expanded by
 432 .An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org ,
 433 who also added Perl compatibility.