xref: /freebsd/lib/libmd/skein.3 (revision 0bf48626aaa33768078f5872b922b1487b3a9296)
1.\"-
2.\" Copyright (c) 2016 Allan Jude
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd May 21, 2019
29.Dt SKEIN 3
30.Os
31.Sh NAME
32.Nm SKEIN256_Init ,
33.Nm SKEIN256_Update ,
34.Nm SKEIN256_Final ,
35.Nm SKEIN256_End ,
36.Nm SKEIN256_File ,
37.Nm SKEIN256_FileChunk ,
38.Nm SKEIN256_Data ,
39.Nm SKEIN512_Init ,
40.Nm SKEIN512_Update ,
41.Nm SKEIN512_Final ,
42.Nm SKEIN512_End ,
43.Nm SKEIN512_File ,
44.Nm SKEIN512_FileChunk ,
45.Nm SKEIN512_Data ,
46.Nm SKEIN1024_Init ,
47.Nm SKEIN1024_Update ,
48.Nm SKEIN1024_Final ,
49.Nm SKEIN1024_End ,
50.Nm SKEIN1024_File ,
51.Nm SKEIN1024_FileChunk ,
52.Nm SKEIN1024_Data
53.Nd calculate the ``SKEIN'' family of message digests
54.Sh LIBRARY
55.Lb libmd
56.Sh SYNOPSIS
57.In sys/types.h
58.In skein.h
59.Ft void
60.Fn SKEIN256_Init "SKEIN256_CTX *context"
61.Ft void
62.Fn SKEIN256_Update "SKEIN256_CTX *context" "const unsigned char *data" "size_t len"
63.Ft void
64.Fn SKEIN256_Final "unsigned char digest[32]" "SKEIN256_CTX *context"
65.Ft "char *"
66.Fn SKEIN256_End "SKEIN256_CTX *context" "char *buf"
67.Ft "char *"
68.Fn SKEIN256_File "const char *filename" "char *buf"
69.Ft "char *"
70.Fn SKEIN256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
71.Ft "char *"
72.Fn SKEIN256_Data "const unsigned char *data" "unsigned int len" "char *buf"
73.Ft void
74.Fn SKEIN512_Init "SKEIN512_CTX *context"
75.Ft void
76.Fn SKEIN512_Update "SKEIN512_CTX *context" "const unsigned char *data" "size_t len"
77.Ft void
78.Fn SKEIN512_Final "unsigned char digest[64]" "SKEIN512_CTX *context"
79.Ft "char *"
80.Fn SKEIN512_End "SKEIN512_CTX *context" "char *buf"
81.Ft "char *"
82.Fn SKEIN512_File "const char *filename" "char *buf"
83.Ft "char *"
84.Fn SKEIN512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
85.Ft "char *"
86.Fn SKEIN512_Data "const unsigned char *data" "unsigned int len" "char *buf"
87.Ft void
88.Fn SKEIN1024_Init "SKEIN1024_CTX *context"
89.Ft void
90.Fn SKEIN1024_Update "SKEIN1024_CTX *context" "const unsigned char *data" "size_t len"
91.Ft void
92.Fn SKEIN1024_Final "unsigned char digest[128]" "SKEIN1024_CTX *context"
93.Ft "char *"
94.Fn SKEIN1024_End "SKEIN1024_CTX *context" "char *buf"
95.Ft "char *"
96.Fn SKEIN1024_File "const char *filename" "char *buf"
97.Ft "char *"
98.Fn SKEIN1024_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
99.Ft "char *"
100.Fn SKEIN1024_Data "const unsigned char *data" "unsigned int len" "char *buf"
101.Sh DESCRIPTION
102.Li Skein
103is a new family of cryptographic hash functions based on the
104.Li Threefish
105large-block cipher.
106Its design combines speed, security, simplicity, and a great deal of
107flexibility in a modular package that is easy to analyze.
108.Li Skein
109is defined for three different internal state sizes\(em256 bits, 512 bits, and
1101024 bits\(emand any output size.
111This allows Skein to be a drop-in replacement for the entire SHA family
112of hash functions.
113.Pp
114The
115.Fn SKEIN256_Init ,
116.Fn SKEIN256_Update ,
117and
118.Fn SKEIN256_Final
119functions are the core functions.
120Allocate an
121.Vt SKEIN256_CTX ,
122initialize it with
123.Fn SKEIN256_Init ,
124run over the data with
125.Fn SKEIN256_Update ,
126and finally extract the result using
127.Fn SKEIN256_Final ,
128which will also erase the
129.Vt SKEIN256_CTX .
130.Pp
131.Fn SKEIN256_End
132is a wrapper for
133.Fn SKEIN256_Final
134which converts the return value to a 33-character
135(including the terminating '\e0')
136.Tn ASCII
137string which represents the 256 bits in hexadecimal.
138.Pp
139.Fn SKEIN256_File
140calculates the digest of a file, and uses
141.Fn SKEIN256_End
142to return the result.
143If the file cannot be opened, a null pointer is returned.
144.Fn SKEIN256_FileChunk
145is similar to
146.Fn SKEIN256_File ,
147but it only calculates the digest over a byte-range of the file specified,
148starting at
149.Fa offset
150and spanning
151.Fa length
152bytes.
153If the
154.Fa length
155parameter is specified as 0, or more than the length of the remaining part
156of the file,
157.Fn SKEIN256_FileChunk
158calculates the digest from
159.Fa offset
160to the end of file.
161.Fn SKEIN256_Data
162calculates the digest of a chunk of data in memory, and uses
163.Fn SKEIN256_End
164to return the result.
165.Pp
166When using
167.Fn SKEIN256_End ,
168.Fn SKEIN256_File ,
169or
170.Fn SKEIN256_Data ,
171the
172.Fa buf
173argument can be a null pointer, in which case the returned string
174is allocated with
175.Xr malloc 3
176and subsequently must be explicitly deallocated using
177.Xr free 3
178after use.
179If the
180.Fa buf
181argument is non-null it must point to at least 33 characters of buffer space.
182.Pp
183The
184.Li SKEIN512_
185and
186.Li SKEIN1024_
187functions are similar to the
188.Li SKEIN256_
189functions except they produce a 512-bit, 65 character,
190or 1024-bit, 129 character, output.
191.Sh ERRORS
192The
193.Fn SKEIN256_End
194function called with a null buf argument may fail and return NULL if:
195.Bl -tag -width Er
196.It Bq Er ENOMEM
197Insufficient storage space is available.
198.El
199.Pp
200The
201.Fn SKEIN256_File
202and
203.Fn SKEIN256_FileChunk
204may return NULL when underlying
205.Xr open 2 ,
206.Xr fstat 2 ,
207.Xr lseek 2 ,
208or
209.Xr SKEIN256_End 2
210fail.
211.Sh SEE ALSO
212.Xr md4 3 ,
213.Xr md5 3 ,
214.Xr ripemd 3 ,
215.Xr sha 3 ,
216.Xr sha256 3 ,
217.Xr sha512 3
218.Sh HISTORY
219These functions appeared in
220.Fx 11.0 .
221.Sh AUTHORS
222.An -nosplit
223The core hash routines were imported from version 1.3 of the optimized
224Skein reference implementation written by
225.An Doug Whiting
226as submitted to the NSA SHA-3 contest.
227The algorithms were developed by
228.An Niels Ferguson ,
229.An Stefan Lucks ,
230.An Bruce Schneier ,
231.An Doug Whiting ,
232.An Mihir Bellare ,
233.An Tadayoshi Kohno ,
234.An Jon Callas,
235and
236.An Jesse Walker .
237