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 28, 2016 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 . 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') 134.Tn ASCII 135string which represents the 256 bits in hexadecimal. 136.Pp 137.Fn SKEIN256_File 138calculates the digest of a file, and uses 139.Fn SKEIN256_End 140to return the result. 141If the file cannot be opened, a null pointer is returned. 142.Fn SKEIN256_FileChunk 143is similar to 144.Fn SKEIN256_File , 145but it only calculates the digest over a byte-range of the file specified, 146starting at 147.Fa offset 148and spanning 149.Fa length 150bytes. 151If the 152.Fa length 153parameter is specified as 0, or more than the length of the remaining part 154of the file, 155.Fn SKEIN256_FileChunk 156calculates the digest from 157.Fa offset 158to the end of file. 159.Fn SKEIN256_Data 160calculates the digest of a chunk of data in memory, and uses 161.Fn SKEIN256_End 162to return the result. 163.Pp 164When using 165.Fn SKEIN256_End , 166.Fn SKEIN256_File , 167or 168.Fn SKEIN256_Data , 169the 170.Fa buf 171argument can be a null pointer, in which case the returned string 172is allocated with 173.Xr malloc 3 174and subsequently must be explicitly deallocated using 175.Xr free 3 176after use. 177If the 178.Fa buf 179argument is non-null it must point to at least 33 characters of buffer space. 180.Pp 181The 182.Li SKEIN512_ 183and 184.Li SKEIN1024_ 185functions are similar to the 186.Li SKEIN256_ 187functions except they produce a 512-bit, 65 character, 188or 1024-bit, 129 character, output. 189.Sh SEE ALSO 190.Xr md4 3 , 191.Xr md5 3 , 192.Xr ripemd 3 , 193.Xr sha 3 , 194.Xr sha256 3 , 195.Xr sha512 3 196.Sh HISTORY 197These functions appeared in 198.Fx 11.0 . 199.Sh AUTHORS 200.An -nosplit 201The core hash routines were imported from version 1.3 of the optimized 202Skein reference implementation written by 203.An Doug Whiting 204as submitted to the NSA SHA-3 contest. 205The algorithms were developed by 206.An Niels Ferguson , 207.An Stefan Lucks , 208.An Bruce Schneier , 209.An Doug Whiting , 210.An Mihir Bellare , 211.An Tadayoshi Kohno , 212.An Jon Callas, 213and 214.An Jesse Walker . 215