xref: /freebsd/lib/libmd/sha512.3 (revision 22cf89c938886d14f5796fc49f9f020c23ea8eaf)
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.\"
11.Dd February 3, 2023
12.Dt SHA512 3
13.Os
14.Sh NAME
15.Nm SHA512_Init ,
16.Nm SHA512_Update ,
17.Nm SHA512_Final ,
18.Nm SHA512_End ,
19.Nm SHA512_File ,
20.Nm SHA512_FileChunk ,
21.Nm SHA512_Data ,
22.Nm SHA384_Init ,
23.Nm SHA384_Update ,
24.Nm SHA384_Final ,
25.Nm SHA384_End ,
26.Nm SHA384_File ,
27.Nm SHA384_FileChunk ,
28.Nm SHA384_Data ,
29.Nm SHA512_224_Init ,
30.Nm SHA512_224_Update ,
31.Nm SHA512_224_Final ,
32.Nm SHA512_224_End ,
33.Nm SHA512_224_File ,
34.Nm SHA512_224_FileChunk ,
35.Nm SHA512_224_Data
36.Nm SHA512_256_Init ,
37.Nm SHA512_256_Update ,
38.Nm SHA512_256_Final ,
39.Nm SHA512_256_End ,
40.Nm SHA512_256_File ,
41.Nm SHA512_256_FileChunk ,
42.Nm SHA512_256_Data
43.Nd calculate the FIPS 180-4 ``SHA-512'' family of message digests
44.Sh LIBRARY
45.Lb libmd
46.Sh SYNOPSIS
47.In sys/types.h
48.In sha512.h
49.Ft void
50.Fn SHA512_Init "SHA512_CTX *context"
51.Ft void
52.Fn SHA512_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
53.Ft void
54.Fn SHA512_Final "unsigned char digest[64]" "SHA512_CTX *context"
55.Ft "char *"
56.Fn SHA512_End "SHA512_CTX *context" "char *buf"
57.Ft "char *"
58.Fn SHA512_File "const char *filename" "char *buf"
59.Ft "char *"
60.Fn SHA512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
61.Ft "char *"
62.Fn SHA512_Data "const unsigned char *data" "unsigned int len" "char *buf"
63.In sha384.h
64.Ft void
65.Fn SHA384_Init "SHA384_CTX *context"
66.Ft void
67.Fn SHA384_Update "SHA384_CTX *context" "const unsigned char *data" "size_t len"
68.Ft void
69.Fn SHA384_Final "unsigned char digest[48]" "SHA384_CTX *context"
70.Ft "char *"
71.Fn SHA384_End "SHA384_CTX *context" "char *buf"
72.Ft "char *"
73.Fn SHA384_File "const char *filename" "char *buf"
74.Ft "char *"
75.Fn SHA384_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
76.Ft "char *"
77.Fn SHA384_Data "const unsigned char *data" "unsigned int len" "char *buf"
78.In sha512t.h
79.Ft void
80.Fn SHA512_224_Init "SHA512_CTX *context"
81.Ft void
82.Fn SHA512_224_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
83.Ft void
84.Fn SHA512_224_Final "unsigned char digest[32]" "SHA512_CTX *context"
85.Ft "char *"
86.Fn SHA512_224_End "SHA512_CTX *context" "char *buf"
87.Ft "char *"
88.Fn SHA512_224_File "const char *filename" "char *buf"
89.Ft "char *"
90.Fn SHA512_224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
91.Ft "char *"
92.Fn SHA512_224_Data "const unsigned char *data" "unsigned int len" "char *buf"
93.Ft void
94.Fn SHA512_256_Init "SHA512_CTX *context"
95.Ft void
96.Fn SHA512_256_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
97.Ft void
98.Fn SHA512_256_Final "unsigned char digest[32]" "SHA512_CTX *context"
99.Ft "char *"
100.Fn SHA512_256_End "SHA512_CTX *context" "char *buf"
101.Ft "char *"
102.Fn SHA512_256_File "const char *filename" "char *buf"
103.Ft "char *"
104.Fn SHA512_256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
105.Ft "char *"
106.Fn SHA512_256_Data "const unsigned char *data" "unsigned int len" "char *buf"
107.Sh DESCRIPTION
108The
109.Li SHA512_
110functions calculate a 512-bit cryptographic checksum (digest)
111for any number of input bytes.
112A cryptographic checksum is a one-way
113hash function; that is, it is computationally impractical to find
114the input corresponding to a particular output.
115This net result is
116a
117.Dq fingerprint
118of the input-data, which does not disclose the actual input.
119.Pp
120The
121.Fn SHA512_Init ,
122.Fn SHA512_Update ,
123and
124.Fn SHA512_Final
125functions are the core functions.
126Allocate an
127.Vt SHA512_CTX ,
128initialize it with
129.Fn SHA512_Init ,
130run over the data with
131.Fn SHA512_Update ,
132and finally extract the result using
133.Fn SHA512_Final ,
134which will also erase the
135.Vt SHA512_CTX .
136.Pp
137.Fn SHA512_End
138is a wrapper for
139.Fn SHA512_Final
140which converts the return value to a 129-character
141(including the terminating '\e0')
142ASCII string which represents the 512 bits in hexadecimal.
143.Pp
144.Fn SHA512_File
145calculates the digest of a file, and uses
146.Fn SHA512_End
147to return the result.
148If the file cannot be opened, a null pointer is returned.
149.Fn SHA512_FileChunk
150is similar to
151.Fn SHA512_File ,
152but it only calculates the digest over a byte-range of the file specified,
153starting at
154.Fa offset
155and spanning
156.Fa length
157bytes.
158If the
159.Fa length
160parameter is specified as 0, or more than the length of the remaining part
161of the file,
162.Fn SHA512_FileChunk
163calculates the digest from
164.Fa offset
165to the end of file.
166.Fn SHA512_Data
167calculates the digest of a chunk of data in memory, and uses
168.Fn SHA512_End
169to return the result.
170.Pp
171When using
172.Fn SHA512_End ,
173.Fn SHA512_File ,
174or
175.Fn SHA512_Data ,
176the
177.Fa buf
178argument can be a null pointer, in which case the returned string
179is allocated with
180.Xr malloc 3
181and subsequently must be explicitly deallocated using
182.Xr free 3
183after use.
184If the
185.Fa buf
186argument is non-null it must point to at least 129 characters of buffer space.
187.Pp
188The
189.Li SHA384_ ,
190.Li SHA512_224 ,
191and
192.Li SHA512_256_
193functions are identical to the
194.Li SHA512_
195functions except they use a different initial hash value and the output is
196truncated to 384, 224, and 256 bits respectively.
197.Pp
198.Fn SHA384_End
199is a wrapper for
200.Fn SHA384_Final
201which converts the return value to a 97-character
202(including the terminating '\e0')
203ASCII string which represents the 384 bits in hexadecimal.
204.Pp
205.Fn SHA512_224_End
206is a wrapper for
207.Fn SHA512_Final
208which converts the return value to a 57-character
209(including the terminating '\e0')
210ASCII string which represents the 224 bits in hexadecimal.
211.Pp
212.Fn SHA512_224_End
213is a wrapper for
214.Fn SHA512_Final
215which converts the return value to a 57-character
216(including the terminating '\e0')
217.Tn ASCII
218string which represents the 224 bits in hexadecimal.
219.Pp
220.Fn SHA512_256_End
221is a wrapper for
222.Fn SHA512_Final
223which converts the return value to a 65-character
224(including the terminating '\e0')
225ASCII string which represents the 256 bits in hexadecimal.
226.Sh ERRORS
227The
228.Fn SHA512_End
229function called with a null buf argument may fail and return NULL if:
230.Bl -tag -width Er
231.It Bq Er ENOMEM
232Insufficient storage space is available.
233.El
234.Pp
235The
236.Fn SHA512_File
237and
238.Fn SHA512_FileChunk
239may return NULL when underlying
240.Xr open 2 ,
241.Xr fstat 2 ,
242.Xr lseek 2 ,
243or
244.Xr SHA512_End 3
245fail.
246.Sh SEE ALSO
247.Xr md4 3 ,
248.Xr md5 3 ,
249.Xr ripemd 3 ,
250.Xr sha 3 ,
251.Xr sha256 3 ,
252.Xr sha512 3 ,
253.Xr skein 3
254.Sh HISTORY
255These functions appeared in
256.Fx 9.0 .
257.Sh AUTHORS
258The core hash routines were implemented by Colin Percival based on
259the published FIPS 180-2 standard.
260.Sh BUGS
261No method is known to exist which finds two files having the same hash value,
262nor to find a file with a specific hash value.
263There is on the other hand no guarantee that such a method does not exist.
264