lib/libmd/skein.3

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