Bring in SHA256 support from FreeBSD.
[dragonfly.git] / lib / libmd / sha256.3
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: src/lib/libmd/sha256.3,v 1.2.4.1 2005/10/08 21:46:23 pjd Exp $
11 .\" $DragonFly: src/lib/libmd/sha256.3,v 1.1 2006/04/29 22:19:26 dillon Exp $
12 .\"
13 .Dd March 9, 2005
14 .Dt SHA256 3
15 .Os
16 .Sh NAME
17 .Nm SHA256_Init ,
18 .Nm SHA256_Update ,
19 .Nm SHA256_Final ,
20 .Nm SHA256_End ,
21 .Nm SHA256_File ,
22 .Nm SHA256_FileChunk ,
23 .Nm SHA256_Data
24 .Nd calculate the FIPS 180-2 ``SHA-256'' message digest
25 .Sh LIBRARY
26 .Lb libmd
27 .Sh SYNOPSIS
28 .In sys/types.h
29 .In sha256.h
30 .Ft void
31 .Fn SHA256_Init "SHA256_CTX *context"
32 .Ft void
33 .Fn SHA256_Update "SHA256_CTX *context" "const unsigned char *data" "size_t len"
34 .Ft void
35 .Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context"
36 .Ft "char *"
37 .Fn SHA256_End "SHA256_CTX *context" "char *buf"
38 .Ft "char *"
39 .Fn SHA256_File "const char *filename" "char *buf"
40 .Ft "char *"
41 .Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
42 .Ft "char *"
43 .Fn SHA256_Data "const unsigned char *data" "unsigned int len" "char *buf"
44 .Sh DESCRIPTION
45 The
46 .Li SHA256_
47 functions calculate a 256-bit cryptographic checksum (digest)
48 for any number of input bytes.
49 A cryptographic checksum is a one-way
50 hash function; that is, it is computationally impractical to find
51 the input corresponding to a particular output.
52 This net result is
53 a
54 .Dq fingerprint
55 of the input-data, which does not disclose the actual input.
56 .Pp
57 The
58 .Fn SHA256_Init ,
59 .Fn SHA256_Update ,
60 and
61 .Fn SHA256_Final
62 functions are the core functions.
63 Allocate an
64 .Vt SHA256_CTX ,
65 initialize it with
66 .Fn SHA256_Init ,
67 run over the data with
68 .Fn SHA256_Update ,
69 and finally extract the result using
70 .Fn SHA256_Final .
71 .Pp
72 .Fn SHA256_End
73 is a wrapper for
74 .Fn SHA256_Final
75 which converts the return value to a 65-character
76 (including the terminating '\e0')
77 .Tn ASCII
78 string which represents the 256 bits in hexadecimal.
79 .Pp
80 .Fn SHA256_File
81 calculates the digest of a file, and uses
82 .Fn SHA256_End
83 to return the result.
84 If the file cannot be opened, a null pointer is returned.
85 .Fn SHA256_FileChunk
86 is similar to
87 .Fn SHA256_File ,
88 but it only calculates the digest over a byte-range of the file specified,
89 starting at
90 .Fa offset
91 and spanning
92 .Fa length
93 bytes.
94 If the
95 .Fa length
96 parameter is specified as 0, or more than the length of the remaining part
97 of the file,
98 .Fn SHA256_FileChunk
99 calculates the digest from
100 .Fa offset
101 to the end of file.
102 .Fn SHA256_Data
103 calculates the digest of a chunk of data in memory, and uses
104 .Fn SHA256_End
105 to return the result.
106 .Pp
107 When using
108 .Fn SHA256_End ,
109 .Fn SHA256_File ,
110 or
111 .Fn SHA256_Data ,
112 the
113 .Fa buf
114 argument can be a null pointer, in which case the returned string
115 is allocated with
116 .Xr malloc 3
117 and subsequently must be explicitly deallocated using
118 .Xr free 3
119 after use.
120 If the
121 .Fa buf
122 argument is non-null it must point to at least 65 characters of buffer space.
123 .Sh SEE ALSO
124 .Xr md2 3 ,
125 .Xr md4 3 ,
126 .Xr md5 3 ,
127 .Xr ripemd 3 ,
128 .Xr sha 3
129 .Sh HISTORY
130 These functions appeared in
131 .Fx 4.0 .
132 .Sh AUTHORS
133 The core hash routines were implemented by Colin Percival based on
134 the published
135 .Tn FIPS 180-2
136 standard.
137 .Sh BUGS
138 No method is known to exist which finds two files having the same hash value,
139 nor to find a file with a specific hash value.
140 There is on the other hand no guarantee that such a method does not exist.