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