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.Dd March 8, 2022 27.Dt SKEIN 3 28.Os 29.Sh NAME 30.Nm SKEIN256_Init , 31.Nm SKEIN256_Update , 32.Nm SKEIN256_Final , 33.Nm SKEIN256_End , 34.Nm SKEIN256_Fd , 35.Nm SKEIN256_FdChunk , 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_Fd , 44.Nm SKEIN512_FdChunk , 45.Nm SKEIN512_File , 46.Nm SKEIN512_FileChunk , 47.Nm SKEIN512_Data , 48.Nm SKEIN1024_Init , 49.Nm SKEIN1024_Update , 50.Nm SKEIN1024_Final , 51.Nm SKEIN1024_End , 52.Nm SKEIN1024_Fd , 53.Nm SKEIN1024_FdChunk , 54.Nm SKEIN1024_File , 55.Nm SKEIN1024_FileChunk , 56.Nm SKEIN1024_Data 57.Nd calculate the ``SKEIN'' family of message digests 58.Sh LIBRARY 59.Lb libmd 60.Sh SYNOPSIS 61.In sys/types.h 62.In skein.h 63.Ft void 64.Fn SKEIN256_Init "SKEIN256_CTX *context" 65.Ft void 66.Fn SKEIN256_Update "SKEIN256_CTX *context" "const unsigned char *data" "size_t len" 67.Ft void 68.Fn SKEIN256_Final "unsigned char digest[32]" "SKEIN256_CTX *context" 69.Ft "char *" 70.Fn SKEIN256_End "SKEIN256_CTX *context" "char *buf" 71.Ft "char *" 72.Fn SKEIN256_Fd "int fd" "char *buf" 73.Ft "char *" 74.Fn SKEIN256_FdChunk "int fd" "char *buf" "off_t offset" "off_t length" 75.Ft "char *" 76.Fn SKEIN256_File "const char *filename" "char *buf" 77.Ft "char *" 78.Fn SKEIN256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 79.Ft "char *" 80.Fn SKEIN256_Data "const unsigned char *data" "unsigned int len" "char *buf" 81.Ft void 82.Fn SKEIN512_Init "SKEIN512_CTX *context" 83.Ft void 84.Fn SKEIN512_Update "SKEIN512_CTX *context" "const unsigned char *data" "size_t len" 85.Ft void 86.Fn SKEIN512_Final "unsigned char digest[64]" "SKEIN512_CTX *context" 87.Ft "char *" 88.Fn SKEIN512_End "SKEIN512_CTX *context" "char *buf" 89.Ft "char *" 90.Fn SKEIN512_Fd "int fd" "char *buf" 91.Ft "char *" 92.Fn SKEIN512_FdChunk "int fd" "char *buf" "off_t offset" "off_t length" 93.Ft "char *" 94.Fn SKEIN512_File "const char *filename" "char *buf" 95.Ft "char *" 96.Fn SKEIN512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 97.Ft "char *" 98.Fn SKEIN512_Data "const unsigned char *data" "unsigned int len" "char *buf" 99.Ft void 100.Fn SKEIN1024_Init "SKEIN1024_CTX *context" 101.Ft void 102.Fn SKEIN1024_Update "SKEIN1024_CTX *context" "const unsigned char *data" "size_t len" 103.Ft void 104.Fn SKEIN1024_Final "unsigned char digest[128]" "SKEIN1024_CTX *context" 105.Ft "char *" 106.Fn SKEIN1024_End "SKEIN1024_CTX *context" "char *buf" 107.Ft "char *" 108.Fn SKEIN1024_Fd "int fd" "char *buf" 109.Ft "char *" 110.Fn SKEIN1024_FdChunk "int fd" "char *buf" "off_t offset" "off_t length" 111.Ft "char *" 112.Fn SKEIN1024_File "const char *filename" "char *buf" 113.Ft "char *" 114.Fn SKEIN1024_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length" 115.Ft "char *" 116.Fn SKEIN1024_Data "const unsigned char *data" "unsigned int len" "char *buf" 117.Sh DESCRIPTION 118.Li Skein 119is a new family of cryptographic hash functions based on the 120.Li Threefish 121large-block cipher. 122Its design combines speed, security, simplicity, and a great deal of 123flexibility in a modular package that is easy to analyze. 124.Li Skein 125is defined for three different internal state sizes\(em256 bits, 512 bits, and 1261024 bits\(emand any output size. 127This allows Skein to be a drop-in replacement for the entire SHA family 128of hash functions. 129.Pp 130The 131.Fn SKEIN256_Init , 132.Fn SKEIN256_Update , 133and 134.Fn SKEIN256_Final 135functions are the core functions. 136Allocate an 137.Vt SKEIN256_CTX , 138initialize it with 139.Fn SKEIN256_Init , 140run over the data with 141.Fn SKEIN256_Update , 142and finally extract the result using 143.Fn SKEIN256_Final , 144which will also erase the 145.Vt SKEIN256_CTX . 146.Pp 147.Fn SKEIN256_End 148is a wrapper for 149.Fn SKEIN256_Final 150which converts the return value to a 33-character 151(including the terminating '\e0') 152ASCII string which represents the 256 bits in hexadecimal. 153.Pp 154.Fn SKEIN256_File 155calculates the digest of a file, and uses 156.Fn SKEIN256_End 157to return the result. 158If the file cannot be opened, a null pointer is returned. 159.Fn SKEIN256_FileChunk 160is similar to 161.Fn SKEIN256_File , 162but it only calculates the digest over a byte-range of the file specified, 163starting at 164.Fa offset 165and spanning 166.Fa length 167bytes. 168If the 169.Fa length 170parameter is specified as 0, or more than the length of the remaining part 171of the file, 172.Fn SKEIN256_FileChunk 173calculates the digest from 174.Fa offset 175to the end of file. 176.Fn SKEIN256_Data 177calculates the digest of a chunk of data in memory, and uses 178.Fn SKEIN256_End 179to return the result. 180.Pp 181The 182.Fn SKEIN256_Fd 183and 184.Fn SKEIN256_FdChunk 185functions are identical to their 186.Fn SKEIN256_File 187and 188.Fn SKEIN256_FileChunk 189counterparts, with the exception that the first argument is an 190.Fa fd 191instead of a 192.Fa filename . 193.Pp 194When using 195.Fn SKEIN256_End , 196.Fn SKEIN256_File , 197or 198.Fn SKEIN256_Data , 199the 200.Fa buf 201argument can be a null pointer, in which case the returned string 202is allocated with 203.Xr malloc 3 204and subsequently must be explicitly deallocated using 205.Xr free 3 206after use. 207If the 208.Fa buf 209argument is non-null it must point to at least 33 characters of buffer space. 210.Pp 211The 212.Li SKEIN512_ 213and 214.Li SKEIN1024_ 215functions are similar to the 216.Li SKEIN256_ 217functions except they produce a 512-bit, 65 character, 218or 1024-bit, 129 character, output. 219.Sh ERRORS 220The 221.Fn SKEIN256_End 222function called with a null buf argument may fail and return NULL if: 223.Bl -tag -width Er 224.It Bq Er ENOMEM 225Insufficient storage space is available. 226.El 227.Pp 228The 229.Fn SKEIN256_File 230and 231.Fn SKEIN256_FileChunk 232may return NULL when underlying 233.Xr open 2 , 234.Xr fstat 2 , 235.Xr lseek 2 , 236or 237.Xr SKEIN256_End 3 238fail. 239.Sh SEE ALSO 240.Xr md4 3 , 241.Xr md5 3 , 242.Xr ripemd 3 , 243.Xr sha 3 , 244.Xr sha256 3 , 245.Xr sha512 3 246.Sh HISTORY 247These functions appeared in 248.Fx 11.0 . 249.Sh AUTHORS 250.An -nosplit 251The core hash routines were imported from version 1.3 of the optimized 252Skein reference implementation written by 253.An Doug Whiting 254as submitted to the NSA SHA-3 contest. 255The algorithms were developed by 256.An Niels Ferguson , 257.An Stefan Lucks , 258.An Bruce Schneier , 259.An Doug Whiting , 260.An Mihir Bellare , 261.An Tadayoshi Kohno , 262.An Jon Callas, 263and 264.An Jesse Walker . 265