xref: /freebsd/lib/libmd/sha256.3 (revision 9f23cbd6cae82fd77edfad7173432fa8dccd0a95)
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 July 20, 2018
13.Dt SHA256 3
14.Os
15.Sh NAME
16.Nm SHA224_Init ,
17.Nm SHA224_Update ,
18.Nm SHA224_Final ,
19.Nm SHA224_End ,
20.Nm SHA224_File ,
21.Nm SHA224_FileChunk ,
22.Nm SHA224_Data ,
23.Nm SHA256_Init ,
24.Nm SHA256_Update ,
25.Nm SHA256_Final ,
26.Nm SHA256_End ,
27.Nm SHA256_File ,
28.Nm SHA256_FileChunk ,
29.Nm SHA256_Data
30.Nd calculate the FIPS 180-2 ``SHA-256'' (or SHA-224) message digest
31.Sh LIBRARY
32.Lb libmd
33.Sh SYNOPSIS
34.In sys/types.h
35.In sha224.h
36.Ft void
37.Fn SHA224_Init "SHA224_CTX *context"
38.Ft void
39.Fn SHA224_Update "SHA224_CTX *context" "const unsigned char *data" "size_t len"
40.Ft void
41.Fn SHA224_Final "unsigned char digest[32]" "SHA224_CTX *context"
42.Ft "char *"
43.Fn SHA224_End "SHA224_CTX *context" "char *buf"
44.Ft "char *"
45.Fn SHA224_File "const char *filename" "char *buf"
46.Ft "char *"
47.Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
48.Ft "char *"
49.Fn SHA224_Data "const unsigned char *data" "unsigned int len" "char *buf"
50.In sha256.h
51.Ft void
52.Fn SHA256_Init "SHA256_CTX *context"
53.Ft void
54.Fn SHA256_Update "SHA256_CTX *context" "const unsigned char *data" "size_t len"
55.Ft void
56.Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context"
57.Ft "char *"
58.Fn SHA256_End "SHA256_CTX *context" "char *buf"
59.Ft "char *"
60.Fn SHA256_File "const char *filename" "char *buf"
61.Ft "char *"
62.Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
63.Ft "char *"
64.Fn SHA256_Data "const unsigned char *data" "unsigned int len" "char *buf"
65.Sh DESCRIPTION
66The
67.Li SHA256_
68functions calculate a 256-bit cryptographic checksum (digest)
69for any number of input bytes.
70A cryptographic checksum is a one-way
71hash function; that is, it is computationally impractical to find
72the input corresponding to a particular output.
73This net result is
74a
75.Dq fingerprint
76of the input-data, which does not disclose the actual input.
77.Pp
78The
79.Fn SHA256_Init ,
80.Fn SHA256_Update ,
81and
82.Fn SHA256_Final
83functions are the core functions.
84Allocate an
85.Vt SHA256_CTX ,
86initialize it with
87.Fn SHA256_Init ,
88run over the data with
89.Fn SHA256_Update ,
90and finally extract the result using
91.Fn SHA256_Final ,
92which will also erase the
93.Vt SHA256_CTX .
94.Pp
95.Fn SHA256_End
96is a wrapper for
97.Fn SHA256_Final
98which converts the return value to a 65-character
99(including the terminating '\e0')
100ASCII string which represents the 256 bits in hexadecimal.
101.Pp
102.Fn SHA256_File
103calculates the digest of a file, and uses
104.Fn SHA256_End
105to return the result.
106If the file cannot be opened, a null pointer is returned.
107.Fn SHA256_FileChunk
108is similar to
109.Fn SHA256_File ,
110but it only calculates the digest over a byte-range of the file specified,
111starting at
112.Fa offset
113and spanning
114.Fa length
115bytes.
116If the
117.Fa length
118parameter is specified as 0, or more than the length of the remaining part
119of the file,
120.Fn SHA256_FileChunk
121calculates the digest from
122.Fa offset
123to the end of file.
124.Fn SHA256_Data
125calculates the digest of a chunk of data in memory, and uses
126.Fn SHA256_End
127to return the result.
128.Pp
129When using
130.Fn SHA256_End ,
131.Fn SHA256_File ,
132or
133.Fn SHA256_Data ,
134the
135.Fa buf
136argument can be a null pointer, in which case the returned string
137is allocated with
138.Xr malloc 3
139and subsequently must be explicitly deallocated using
140.Xr free 3
141after use.
142If the
143.Fa buf
144argument is non-null it must point to at least 65 characters of buffer space.
145.Pp
146SHA224 is identical SHA256, except it has slightly different initialization
147vectors, and is truncated to a shorter digest.
148.Sh ERRORS
149The
150.Fn SHA256_End
151function called with a null buf argument may fail and return NULL if:
152.Bl -tag -width Er
153.It Bq Er ENOMEM
154Insufficient storage space is available.
155.El
156.Pp
157The
158.Fn SHA256_File
159and
160.Fn SHA256_FileChunk
161may return NULL when underlying
162.Xr open 2 ,
163.Xr fstat 2 ,
164.Xr lseek 2 ,
165or
166.Xr SHA256_End 3
167fail.
168.Sh SEE ALSO
169.Xr md4 3 ,
170.Xr md5 3 ,
171.Xr ripemd 3 ,
172.Xr sha 3 ,
173.Xr sha512 3 ,
174.Xr skein 3
175.Sh HISTORY
176These functions appeared in
177.Fx 6.0 .
178.Sh AUTHORS
179The core hash routines were implemented by Colin Percival based on
180the published FIPS 180-2 standard.
181.Sh BUGS
182No method is known to exist which finds two files having the same hash value,
183nor to find a file with a specific hash value.
184There is on the other hand no guarantee that such a method does not exist.
185