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