Sync libmd with FreeBSD:
[dragonfly.git] / lib / libmd / sha256.3
CommitLineData
39b242ad
MD
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
3cd01911
SW
10.\" $FreeBSD: src/lib/libmd/sha256.3,v 1.4 2005/11/17 13:00:00 ru Exp $
11.\" $DragonFly: src/lib/libmd/sha256.3,v 1.2 2008/09/11 20:25:34 swildner Exp $
39b242ad 12.\"
3cd01911 13.Dd April 29, 2006
39b242ad
MD
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
45The
46.Li SHA256_
47functions calculate a 256-bit cryptographic checksum (digest)
48for any number of input bytes.
49A cryptographic checksum is a one-way
50hash function; that is, it is computationally impractical to find
51the input corresponding to a particular output.
52This net result is
53a
54.Dq fingerprint
55of the input-data, which does not disclose the actual input.
56.Pp
57The
58.Fn SHA256_Init ,
59.Fn SHA256_Update ,
60and
61.Fn SHA256_Final
62functions are the core functions.
63Allocate an
64.Vt SHA256_CTX ,
65initialize it with
66.Fn SHA256_Init ,
67run over the data with
68.Fn SHA256_Update ,
69and finally extract the result using
70.Fn SHA256_Final .
71.Pp
72.Fn SHA256_End
73is a wrapper for
74.Fn SHA256_Final
75which converts the return value to a 65-character
76(including the terminating '\e0')
77.Tn ASCII
78string which represents the 256 bits in hexadecimal.
79.Pp
80.Fn SHA256_File
81calculates the digest of a file, and uses
82.Fn SHA256_End
83to return the result.
84If the file cannot be opened, a null pointer is returned.
85.Fn SHA256_FileChunk
86is similar to
87.Fn SHA256_File ,
88but it only calculates the digest over a byte-range of the file specified,
89starting at
90.Fa offset
91and spanning
92.Fa length
93bytes.
94If the
95.Fa length
96parameter is specified as 0, or more than the length of the remaining part
97of the file,
98.Fn SHA256_FileChunk
99calculates the digest from
100.Fa offset
101to the end of file.
102.Fn SHA256_Data
103calculates the digest of a chunk of data in memory, and uses
104.Fn SHA256_End
105to return the result.
106.Pp
107When using
108.Fn SHA256_End ,
109.Fn SHA256_File ,
110or
111.Fn SHA256_Data ,
112the
113.Fa buf
114argument can be a null pointer, in which case the returned string
115is allocated with
116.Xr malloc 3
117and subsequently must be explicitly deallocated using
118.Xr free 3
119after use.
120If the
121.Fa buf
122argument 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
130These functions appeared in
131.Fx 4.0 .
132.Sh AUTHORS
133The core hash routines were implemented by Colin Percival based on
134the published
135.Tn FIPS 180-2
136standard.
137.Sh BUGS
138No method is known to exist which finds two files having the same hash value,
139nor to find a file with a specific hash value.
140There is on the other hand no guarantee that such a method does not exist.