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