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