xref: /freebsd/lib/libmd/sha.3 (revision d6b92ffa) 
1.\"
2.\" ----------------------------------------------------------------------------
3.\" "THE BEER-WARE LICENSE" (Revision 42):
4.\" <phk@FreeBSD.org> wrote this file.  As long as you retain this notice you
5.\" can do whatever you want with this stuff. If we meet some day, and you think
6.\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
7.\" ----------------------------------------------------------------------------
8.\"
9.\" 	From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp
10.\" $FreeBSD$
11.\"
12.Dd April 26, 2016
13.Dt SHA 3
14.Os
15.Sh NAME
16.Nm SHA_Init ,
17.Nm SHA_Update ,
18.Nm SHA_Final ,
19.Nm SHA_End ,
20.Nm SHA_File ,
21.Nm SHA_FileChunk ,
22.Nm SHA_Data ,
23.Nm SHA1_Init ,
24.Nm SHA1_Update ,
25.Nm SHA1_Final ,
26.Nm SHA1_End ,
27.Nm SHA1_File ,
28.Nm SHA1_FileChunk ,
29.Nm SHA1_Data
30.Nd calculate the FIPS 160 and 160-1 ``SHA'' message digests
31.Sh LIBRARY
32.Lb libmd
33.Sh SYNOPSIS
34.In sys/types.h
35.In sha.h
36.Ft void
37.Fn SHA_Init "SHA_CTX *context"
38.Ft void
39.Fn SHA_Update "SHA_CTX *context" "const unsigned char *data" "size_t len"
40.Ft void
41.Fn SHA_Final "unsigned char digest[20]" "SHA_CTX *context"
42.Ft "char *"
43.Fn SHA_End "SHA_CTX *context" "char *buf"
44.Ft "char *"
45.Fn SHA_File "const char *filename" "char *buf"
46.Ft "char *"
47.Fn SHA_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
48.Ft "char *"
49.Fn SHA_Data "const unsigned char *data" "unsigned int len" "char *buf"
50.Ft void
51.Fn SHA1_Init "SHA_CTX *context"
52.Ft void
53.Fn SHA1_Update "SHA_CTX *context" "const unsigned char *data" "size_t len"
54.Ft void
55.Fn SHA1_Final "unsigned char digest[20]" "SHA_CTX *context"
56.Ft "char *"
57.Fn SHA1_End "SHA_CTX *context" "char *buf"
58.Ft "char *"
59.Fn SHA1_File "const char *filename" "char *buf"
60.Ft "char *"
61.Fn SHA1_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
62.Ft "char *"
63.Fn SHA1_Data "const unsigned char *data" "unsigned int len" "char *buf"
64.Sh DESCRIPTION
65The
66.Li SHA_
67and
68.Li SHA1_
69functions calculate a 160-bit cryptographic checksum (digest)
70for any number of input bytes.
71A cryptographic checksum is a one-way
72hash function; that is, it is computationally impractical to find
73the input corresponding to a particular output.
74This net result is
75a
76.Dq fingerprint
77of the input-data, which does not disclose the actual input.
78.Pp
79.Tn SHA
80(or
81.Tn SHA-0 )
82is the original Secure Hash Algorithm specified in
83.Tn FIPS
84160.
85It was quickly proven insecure, and has been superseded by
86.Tn SHA-1 .
87.Tn SHA-0
88is included for compatibility purposes only.
89.Pp
90The
91.Fn SHA1_Init ,
92.Fn SHA1_Update ,
93and
94.Fn SHA1_Final
95functions are the core functions.
96Allocate an
97.Vt SHA_CTX ,
98initialize it with
99.Fn SHA1_Init ,
100run over the data with
101.Fn SHA1_Update ,
102and finally extract the result using
103.Fn SHA1_Final .
104.Pp
105.Fn SHA1_End
106is a wrapper for
107.Fn SHA1_Final
108which converts the return value to a 41-character
109(including the terminating '\e0')
110.Tn ASCII
111string which represents the 160 bits in hexadecimal.
112.Pp
113.Fn SHA1_File
114calculates the digest of a file, and uses
115.Fn SHA1_End
116to return the result.
117If the file cannot be opened, a null pointer is returned.
118.Fn SHA1_FileChunk
119is similar to
120.Fn SHA1_File ,
121but it only calculates the digest over a byte-range of the file specified,
122starting at
123.Fa offset
124and spanning
125.Fa length
126bytes.
127If the
128.Fa length
129parameter is specified as 0, or more than the length of the remaining part
130of the file,
131.Fn SHA1_FileChunk
132calculates the digest from
133.Fa offset
134to the end of file.
135.Fn SHA1_Data
136calculates the digest of a chunk of data in memory, and uses
137.Fn SHA1_End
138to return the result.
139.Pp
140When using
141.Fn SHA1_End ,
142.Fn SHA1_File ,
143or
144.Fn SHA1_Data ,
145the
146.Fa buf
147argument can be a null pointer, in which case the returned string
148is allocated with
149.Xr malloc 3
150and subsequently must be explicitly deallocated using
151.Xr free 3
152after use.
153If the
154.Fa buf
155argument is non-null it must point to at least 41 characters of buffer space.
156.Sh SEE ALSO
157.Xr md4 3 ,
158.Xr md5 3 ,
159.Xr ripemd 3 ,
160.Xr sha256 3 ,
161.Xr sha512 3 ,
162.Xr skein 3
163.Sh HISTORY
164These functions appeared in
165.Fx 4.0 .
166.Sh AUTHORS
167The core hash routines were implemented by Eric Young based on the
168published
169.Tn FIPS
170standards.
171.Sh BUGS
172No method is known to exist which finds two files having the same hash value,
173nor to find a file with a specific hash value.
174There is on the other hand no guarantee that such a method does not exist.
175.Pp
176The
177.Tn IA32
178(Intel) implementation of
179.Tn SHA-1
180makes heavy use of the
181.Ql bswapl
182instruction, which is not present on the original 80386.
183Attempts to use
184.Tn SHA-1
185on those processors will cause an illegal instruction trap.
186(Arguably, the kernel should simply emulate this instruction.)
187