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