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 103 is a new family of cryptographic hash functions based on the 104 .Li Threefish 105 large-block cipher. 106 Its design combines speed, security, simplicity, and a great deal of 107 flexibility in a modular package that is easy to analyze. 108 .Li Skein 109 is defined for three different internal state sizes\(em256 bits, 512 bits, and 110 1024 bits\(emand any output size. 111 This allows Skein to be a drop-in replacement for the entire SHA family 112 of hash functions. 113 .Pp 114 The 115 .Fn SKEIN256_Init , 116 .Fn SKEIN256_Update , 117 and 118 .Fn SKEIN256_Final 119 functions are the core functions. 120 Allocate an 121 .Vt SKEIN256_CTX , 122 initialize it with 123 .Fn SKEIN256_Init , 124 run over the data with 125 .Fn SKEIN256_Update , 126 and finally extract the result using 127 .Fn SKEIN256_Final , 128 which will also erase the 129 .Vt SKEIN256_CTX . 130 .Pp 131 .Fn SKEIN256_End 132 is a wrapper for 133 .Fn SKEIN256_Final 134 which converts the return value to a 33-character 135 (including the terminating '\e0') 136 .Tn ASCII 137 string which represents the 256 bits in hexadecimal. 138 .Pp 139 .Fn SKEIN256_File 140 calculates the digest of a file, and uses 141 .Fn SKEIN256_End 142 to return the result. 143 If the file cannot be opened, a null pointer is returned. 144 .Fn SKEIN256_FileChunk 145 is similar to 146 .Fn SKEIN256_File , 147 but it only calculates the digest over a byte-range of the file specified, 148 starting at 149 .Fa offset 150 and spanning 151 .Fa length 152 bytes. 153 If the 154 .Fa length 155 parameter is specified as 0, or more than the length of the remaining part 156 of the file, 157 .Fn SKEIN256_FileChunk 158 calculates the digest from 159 .Fa offset 160 to the end of file. 161 .Fn SKEIN256_Data 162 calculates the digest of a chunk of data in memory, and uses 163 .Fn SKEIN256_End 164 to return the result. 165 .Pp 166 When using 167 .Fn SKEIN256_End , 168 .Fn SKEIN256_File , 169 or 170 .Fn SKEIN256_Data , 171 the 172 .Fa buf 173 argument can be a null pointer, in which case the returned string 174 is allocated with 175 .Xr malloc 3 176 and subsequently must be explicitly deallocated using 177 .Xr free 3 178 after use. 179 If the 180 .Fa buf 181 argument is non-null it must point to at least 33 characters of buffer space. 182 .Pp 183 The 184 .Li SKEIN512_ 185 and 186 .Li SKEIN1024_ 187 functions are similar to the 188 .Li SKEIN256_ 189 functions except they produce a 512-bit, 65 character, 190 or 1024-bit, 129 character, output. 191 .Sh ERRORS 192 The 193 .Fn SKEIN256_End 194 function called with a null buf argument may fail and return NULL if: 195 .Bl -tag -width Er 196 .It Bq Er ENOMEM 197 Insufficient storage space is available. 198 .El 199 .Pp 200 The 201 .Fn SKEIN256_File 202 and 203 .Fn SKEIN256_FileChunk 204 may return NULL when underlying 205 .Xr open 2 , 206 .Xr fstat 2 , 207 .Xr lseek 2 , 208 or 209 .Xr SKEIN256_End 2 210 fail. 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 219 These functions appeared in 220 .Fx 11.0 . 221 .Sh AUTHORS 222 .An -nosplit 223 The core hash routines were imported from version 1.3 of the optimized 224 Skein reference implementation written by 225 .An Doug Whiting 226 as submitted to the NSA SHA-3 contest. 227 The 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, 235 and 236 .An Jesse Walker . 237