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 .\" $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 .