xref: /freebsd/sbin/md5/md5.1 (revision 031beb4e239bfce798af17f5fe8dba8bcaf13d99)
1.\" $FreeBSD$
2.Dd May 10, 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 , sha384 , sha512 ,
277.Nm sha512t224 , sha512t256 ,
278.Nm rmd160 , skein256 , skein512 ,
279and
280.Nm skein1024
281utilities exit 0 on success,
2821 if at least one of the input files could not be read,
283and 2 if at least one file does not have the same hash as the
284.Fl c
285option.
286.Pp
287The
288.Nm md5sum , sha1sum , sha224sum , sha256sum , sha384sum , sha512sum ,
289.Nm sha512t224sum , sha512t256sum ,
290.Nm rmd160 , skein256 , skein512 , skein1024
291and
292.Nm shasum
293utilities exit 0 on success and 1 if at least one of the input files
294could not be read or, when verifying checksums, does not have the
295expected checksum.
296.Sh EXAMPLES
297Calculate the MD5 checksum of the string
298.Dq Hello .
299.Bd -literal -offset indent
300$ md5 -s Hello
301MD5 ("Hello") = 8b1a9953c4611296a827abf8c47804d7
302.Ed
303.Pp
304Same as above, but note the absence of the newline character in the input
305string:
306.Bd -literal -offset indent
307$ echo -n Hello | md5
3088b1a9953c4611296a827abf8c47804d7
309.Ed
310.Pp
311Calculate the checksum of multiple files reversing the output:
312.Bd -literal -offset indent
313$ md5 -r /boot/loader.conf /etc/rc.conf
314ada5f60f23af88ff95b8091d6d67bef6 /boot/loader.conf
315d80bf36c332dc0fdc479366ec3fa44cd /etc/rc.conf
316.Ed
317.Pp
318This is almost but not quite identical to the output from GNU mode:
319.Bd -literal -offset indent
320$ md5sum /boot/loader.conf /etc/rc.conf
321ada5f60f23af88ff95b8091d6d67bef6  /boot/loader.conf
322d80bf36c332dc0fdc479366ec3fa44cd  /etc/rc.conf
323.Ed
324.Pp
325Note the two spaces between hash and file name.
326If binary mode is requested, they are instead separated by a space and
327an asterisk:
328.Bd -literal -offset indent
329$ md5sum -b /boot/loader.conf /etc/rc.conf
330ada5f60f23af88ff95b8091d6d67bef6 */boot/loader.conf
331d80bf36c332dc0fdc479366ec3fa44cd */etc/rc.conf
332.Ed
333.Pp
334Write the digest for
335.Pa /boot/loader.conf
336in a file named
337.Pa digest .
338Then calculate the checksum again and validate it against the checksum string
339extracted from the
340.Pa digest
341file:
342.Bd -literal -offset indent
343$ md5 /boot/loader.conf > digest && md5 -c $(cut -f2 -d= digest) /boot/loader.conf
344MD5 (/boot/loader.conf) = ada5f60f23af88ff95b8091d6d67bef6
345.Ed
346.Pp
347Same as above but comparing the digest against an invalid string
348.Pq Dq randomstring ,
349which results in a failure.
350.Bd -literal -offset indent
351$ md5 -c randomstring /boot/loader.conf
352MD5 (/boot/loader.conf) = ada5f60f23af88ff95b8091d6d67bef6 [ Failed ]
353.Ed
354.Pp
355In GNU mode, the
356.Fl c
357option does not compare against a hash string passed as parameter.
358Instead, it expects a digest file, as created under the name
359.Pa digest
360for
361.Pa /boot/loader.conf
362in the example above.
363.Bd -literal -offset indent
364$ md5 -c digest /boot/loader.conf
365/boot/loader.conf: OK
366.Ed
367.Pp
368The digest file may contain any number of lines in the format
369generated in either BSD or GNU mode.
370If a hash value does not match the file,
371.Dq FAILED
372is printed instead of
373.Dq OK .
374.Sh SEE ALSO
375.Xr cksum 1 ,
376.Xr md5 3 ,
377.Xr ripemd 3 ,
378.Xr sha 3 ,
379.Xr sha256 3 ,
380.Xr sha384 3 ,
381.Xr sha512 3 ,
382.Xr skein 3
383.Rs
384.%A R. Rivest
385.%T The MD5 Message-Digest Algorithm
386.%O RFC1321
387.Re
388.Rs
389.%A J. Burrows
390.%T The Secure Hash Standard
391.%O FIPS PUB 180-2
392.Re
393.Rs
394.%A D. Eastlake and P. Jones
395.%T US Secure Hash Algorithm 1
396.%O RFC 3174
397.Re
398.Pp
399RIPEMD-160 is part of the ISO draft standard
400.Qq ISO/IEC DIS 10118-3
401on dedicated hash functions.
402.Pp
403Secure Hash Standard (SHS):
404.Pa https://www.nist.gov/publications/secure-hash-standard-shs
405.Pp
406The RIPEMD-160 page:
407.Pa https://homes.esat.kuleuven.be/~bosselae/ripemd160.html
408.Sh BUGS
409In bits mode, the original
410.Nm shasum
411script is capable of processing inputs of arbitrary length.
412This implementation is not, and will issue an error if the input
413length is not a multiple of eight bits.
414.Sh ACKNOWLEDGMENTS
415.An -nosplit
416This utility was originally derived from a program which was placed in
417the public domain for free general use by RSA Data Security.
418.Pp
419Support for SHA-1 and RIPEMD-160 was added by
420.An Oliver Eikemeier Aq Mt eik@FreeBSD.org .
421.Pp
422Support for SHA-2 was added by
423.An Colin Percival Aq Mt cperciva@FreeBSD.org
424and
425.An Allan Jude Aq Mt allanjude@FreeBSD.org .
426.Pp
427Support for SKEIN was added by
428.An Allan Jude Aq Mt allanjude@FreeBSD.org .
429.Pp
430Compatibility with GNU coreutils was added by
431.An Warner Losh Aq Mt imp@FreeBSD.org
432and much expanded by
433.An Dag-Erling Sm\(/orgrav Aq Mt des@FreeBSD.org ,
434who also added Perl compatibility.
435