sbin/md5/md5.1

   1 .\" $FreeBSD$
   2 .Dd April 12, 2023
   3 .Dt MD5 1
   4 .Os
   5 .Sh NAME
   6 .Nm md5 , sha1 , sha224 , sha256 , sha384 ,
   7 .Nm sha512 , sha512t224 , sha512t256 ,
   8 .Nm rmd160 , skein256 , skein512 , skein1024 ,
   9 .Nm md5sum , sha1sum , sha224sum , sha256sum , sha384sum ,
  10 .Nm sha512sum , sha512t224sum , sha512t256sum ,
  11 .Nm rmd160sum , skein256sum , skein512sum , skein1024sum ,
  12 .Nm shasum
  13 .Nd calculate a message-digest fingerprint (checksum) for a file
  14 .Sh SYNOPSIS
  15 .Nm
  16 .Op Fl pqrtx
  17 .Op Fl c Ar string
  18 .Op Fl s Ar string
  19 .Op Ar
  20 .Pp
  21 .Nm md5sum
  22 .Op Fl bctwz
  23 .Op Fl -binary
  24 .Op Fl -check
  25 .Op Fl -help
  26 .Op Fl -ignore-missing
  27 .Op Fl -quiet
  28 .Op Fl -status
  29 .Op Fl -strict
  30 .Op Fl -tag
  31 .Op Fl -text
  32 .Op Fl -version
  33 .Op Fl -warn
  34 .Op Fl -zero
  35 .Op Ar
  36 .Pp
  37 (All other hashes have the same options and usage.)
  38 .Pp
  39 .Nm shasum
  40 .Op Fl 0bchqstUvw
  41 .Op Fl -01
  42 .Op Fl a | -algorithm Ar alg
  43 .Op Fl -binary
  44 .Op Fl -check
  45 .Op Fl -help
  46 .Op Fl -ignore-missing
  47 .Op Fl -quiet
  48 .Op Fl -status
  49 .Op Fl -strict
  50 .Op Fl -tag
  51 .Op Fl -text
  52 .Op Fl -UNIVERSAL
  53 .Op Fl -version
  54 .Op Fl -warn
  55 .Op Ar
  56 .Sh DESCRIPTION
  57 The
  58 .Nm md5 , sha1 , sha224 , sha256 , sha384 , sha512 , sha512t224 , sha512t256 ,
  59 .Nm rmd160 , skein256 , skein512 ,
  60 and
  61 .Nm skein1024
  62 utilities take as input a message of arbitrary length and produce as
  63 output a
  64 .Dq fingerprint
  65 or
  66 .Dq message digest
  67 of the input.
  68 .Pp
  69 The
  70 .Nm md5sum , sha1sum , sha224sum , sha256sum , sha384sum , sha512sum ,
  71 .Nm sha512t224sum , sha512t256sum , rmd160sum , skein256sum , skein512sum ,
  72 and
  73 .Nm skein1024sum
  74 utilities do the same, but with command-line options and an output
  75 format that match those of their similary named GNU utilities.
  76 .Pp
  77 The
  78 .Nm shasum
  79 utility does the same, but with command-line options and an output
  80 format that match those of the similarly named utility that ships with
  81 Perl.
  82 .Pp
  83 It is conjectured that it is computationally infeasible to
  84 produce two messages having the same message digest, or to produce any
  85 message having a given prespecified target message digest.
  86 The SHA-224 , SHA-256 , SHA-384 , SHA-512, RIPEMD-160,
  87 and SKEIN
  88 algorithms are intended for digital signature applications, where a
  89 large file must be
  90 .Dq compressed
  91 in a secure manner before being encrypted with a private
  92 (secret)
  93 key under a public-key cryptosystem such as RSA.
  94 .Pp
  95 The MD5 and SHA-1 algorithms have been proven to be vulnerable to practical
  96 collision attacks and should not be relied upon to produce unique outputs,
  97 .Em nor should they be used as part of a cryptographic signature scheme.
  98 As of 2017-03-02, there is no publicly known method to
  99 .Em reverse
 100 either algorithm, i.e., to find an input that produces a specific
 101 output.
 102 .Pp
 103 SHA-512t256 is a version of SHA-512 truncated to only 256 bits.
 104 On 64-bit hardware, this algorithm is approximately 50% faster than SHA-256 but
 105 with the same level of security.
 106 The hashes are not interchangeable.
 107 .Pp
 108 SHA-512t224 is identical to SHA-512t256, but with the digest truncated
 109 to 224 bits.
 110 .Pp
 111 It is recommended that all new applications use SHA-512 or SKEIN-512
 112 instead of one of the other hash functions.
 113 .Ss BSD OPTIONS
 114 The following options are available in BSD mode, i.e. when the program
 115 is invoked with a name that does not end in
 116 .Dq sum :
 117 .Bl -tag -width indent
 118 .It Fl c Ar string , Fl -check= Ns Ar string
 119 Compare the digest of the file against this string.
 120 If combined with the
 121 .Fl q
 122 or
 123 .Fl -quiet
 124 option, the calculated digest is printed in addition to the exit status being set.
 125 .Pq Note that this option is not yet useful if multiple files are specified.
 126 .It Fl p , -passthrough
 127 Echo stdin to stdout and append the checksum to stdout.
 128 .It Fl q , -quiet
 129 Quiet mode \(em only the checksum is printed out.
 130 Overrides the
 131 .Fl r
 132 or
 133 .Fl -reverse
 134 option.
 135 .It Fl r , -reverse
 136 Reverses the format of the output.
 137 This helps with visual diffs.
 138 Does nothing
 139 when combined with the
 140 .Fl ptx
 141 options.
 142 .It Fl s Ar string , Fl -string= Ns Ar string
 143 Print a checksum of the given
 144 .Ar string .
 145 .It Fl t , Fl -time-trial
 146 Run a built-in time trial.
 147 For the
 148 .Nm -sum
 149 versions, this is a nop for compatibility with coreutils.
 150 .It Fl x , Fl -self-test
 151 Run a built-in test script.
 152 .El
 153 .Ss GNU OPTIONS
 154 The following options are available in GNU mode, i.e. when the program
 155 is invoked with a name that ends in
 156 .Dq sum :
 157 .Bl -tag -width indent
 158 .It Fl b , Fl -binary
 159 Read files in binary mode.
 160 .It Fl c , Fl -check
 161 The file passed as arguments must contain digest lines generated by the same
 162 digest algorithm in either classical BSD format or in GNU coreutils format.
 163 A line with the file name followed by a colon
 164 .Dq ":"
 165 and either OK or FAILED is written for each well-formed line in the digest file.
 166 If applicable, the number of failed comparisons and the number of lines that were
 167 skipped since they were not well-formed are printed at the end.
 168 The
 169 .Fl -quiet
 170 option can be used to quiesce the output unless there are mismatched entries in
 171 the digest.
 172 .It Fl -help
 173 Print a usage message and exit.
 174 .It Fl -ignore-missing
 175 When verifying checksums, ignore files for which checksums are given
 176 but which aren't found on disk.
 177 .It Fl -quiet
 178 When verifying checksums, do not print anything unless the
 179 verification fails.
 180 .It Fl -status
 181 When verifying checksums, do not print anything at all.
 182 The exit code will reflect whether verification succeeded.
 183 .It Fl -strict
 184 When verifying checksums, fail if the input is malformed.
 185 .It Fl -tag
 186 Produce BSD-style output.
 187 .It Fl t , Fl -text
 188 Read files in text mode.
 189 This is the default.
 190 Note that this implementation does not differentiate between binary
 191 and text mode.
 192 .It Fl -version
 193 Print version information and exit.
 194 .It Fl w , Fl -warn
 195 When verifying checksums, warn about malformed input.
 196 .It Fl z , Fl -zero
 197 Terminate output lines with NUL rather than with newline.
 198 .El
 199 .Ss PERL OPTIONS
 200 The following options are available in Perl mode, i.e. when the program
 201 is invoked with the name
 202 .Dq shasum :
 203 .Bl -tag -width indent
 204 .It Fl 0 , Fl -01
 205 Read files in bits mode: ASCII
 206 .Sq 0
 207 and
 208 .Sq 1
 209 characters correspond to 0 and 1 bits, respectively, and all other
 210 characters are ignored.
 211 See
 212 .Sx BUGS .
 213 .It Fl a Ar alg , Fl -algorithm Ar alg
 214 Use the specified algorithm:
 215 .Dq 1
 216 for SHA-1 (default),
 217 .Dq xxx
 218 for
 219 .Va xxx Ns -bit
 220 SHA-2 (e.g.
 221 .Dq 256
 222 for SHA-256)
 223 or
 224 .Dq xxxyyy
 225 for
 226 .Va xxx Ns -bit
 227 SHA-2 truncated to
 228 .Va yyy
 229 bits (e.g.
 230 .Dq 512224
 231 for SHA-512/224).
 232 .It Fl b , Fl -binary
 233 Read files in binary mode.
 234 .It Fl c , Fl -check
 235 The file passed as arguments must contain digest lines generated by the same
 236 digest algorithm in either classical BSD format or in GNU coreutils format.
 237 A line with the file name followed by a colon
 238 .Dq ":"
 239 and either OK or FAILED is written for each well-formed line in the digest file.
 240 If applicable, the number of failed comparisons and the number of lines that were
 241 skipped since they were not well-formed are printed at the end.
 242 The
 243 .Fl -quiet
 244 option can be used to quiesce the output unless there are mismatched entries in
 245 the digest.
 246 .It Fl -help
 247 Print a usage message and exit.
 248 .It Fl -ignore-missing
 249 When verifying checksums, ignore files for which checksums are given
 250 but which aren't found on disk.
 251 .It Fl -quiet
 252 When verifying checksums, do not print anything unless the
 253 verification fails.
 254 .It Fl -status
 255 When verifying checksums, do not print anything at all.
 256 The exit code will reflect whether verification succeeded.
 257 .It Fl -strict
 258 When verifying checksums, fail if the input is malformed.
 259 .It Fl -tag
 260 Produce BSD-style output.
 261 .It Fl t , Fl -text
 262 Read files in text mode.
 263 This is the default.
 264 Note that this implementation does not differentiate between binary
 265 and text mode.
 266 .It Fl U , Fl -UNIVERSAL
 267 Read files in universal mode: any CR-LF pair, as well as any CR not
 268 followed by LF, is translated to LF before the digest is computed.
 269 .It Fl -version
 270 Print version information and exit.
 271 .It Fl w , Fl -warn
 272 When verifying checksums, warn about malformed input.
 273 .El
 274 .Sh EXIT STATUS
 275 The
 276 .Nm md5 , sha1 , sha224 , sha256 , sha512 , 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 , 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.