lib/libmd/sha512.3

   1 .\"
   2 .\" ----------------------------------------------------------------------------
   3 .\" "THE BEER-WARE LICENSE" (Revision 42):
   4 .\" <phk@FreeBSD.org> wrote this file.  As long as you retain this notice you
   5 .\" can do whatever you want with this stuff. If we meet some day, and you think
   6 .\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
   7 .\" ----------------------------------------------------------------------------
   8 .\"
   9 .\"     From: Id: mdX.3,v 1.14 1999/02/11 20:31:49 wollman Exp
  10 .\" $FreeBSD$
  11 .\"
  12 .Dd May 21, 2019
  13 .Dt SHA512 3
  14 .Os
  15 .Sh NAME
  16 .Nm SHA512_Init ,
  17 .Nm SHA512_Update ,
  18 .Nm SHA512_Final ,
  19 .Nm SHA512_End ,
  20 .Nm SHA512_File ,
  21 .Nm SHA512_FileChunk ,
  22 .Nm SHA512_Data ,
  23 .Nm SHA384_Init ,
  24 .Nm SHA384_Update ,
  25 .Nm SHA384_Final ,
  26 .Nm SHA384_End ,
  27 .Nm SHA384_File ,
  28 .Nm SHA384_FileChunk ,
  29 .Nm SHA384_Data ,
  30 .Nm SHA512_256_Init ,
  31 .Nm SHA512_256_Update ,
  32 .Nm SHA512_256_Final ,
  33 .Nm SHA512_256_End ,
  34 .Nm SHA512_256_File ,
  35 .Nm SHA512_256_FileChunk ,
  36 .Nm SHA512_256_Data
  37 .Nd calculate the FIPS 180-4 ``SHA-512'' family of message digests
  38 .Sh LIBRARY
  39 .Lb libmd
  40 .Sh SYNOPSIS
  41 .In sys/types.h
  42 .In sha512.h
  43 .Ft void
  44 .Fn SHA512_Init "SHA512_CTX *context"
  45 .Ft void
  46 .Fn SHA512_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
  47 .Ft void
  48 .Fn SHA512_Final "unsigned char digest[64]" "SHA512_CTX *context"
  49 .Ft "char *"
  50 .Fn SHA512_End "SHA512_CTX *context" "char *buf"
  51 .Ft "char *"
  52 .Fn SHA512_File "const char *filename" "char *buf"
  53 .Ft "char *"
  54 .Fn SHA512_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  55 .Ft "char *"
  56 .Fn SHA512_Data "const unsigned char *data" "unsigned int len" "char *buf"
  57 .In sha384.h
  58 .Ft void
  59 .Fn SHA384_Init "SHA384_CTX *context"
  60 .Ft void
  61 .Fn SHA384_Update "SHA384_CTX *context" "const unsigned char *data" "size_t len"
  62 .Ft void
  63 .Fn SHA384_Final "unsigned char digest[48]" "SHA384_CTX *context"
  64 .Ft "char *"
  65 .Fn SHA384_End "SHA384_CTX *context" "char *buf"
  66 .Ft "char *"
  67 .Fn SHA384_File "const char *filename" "char *buf"
  68 .Ft "char *"
  69 .Fn SHA384_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  70 .Ft "char *"
  71 .Fn SHA384_Data "const unsigned char *data" "unsigned int len" "char *buf"
  72 .In sha512t.h
  73 .Ft void
  74 .Fn SHA512_256_Init "SHA512_CTX *context"
  75 .Ft void
  76 .Fn SHA512_256_Update "SHA512_CTX *context" "const unsigned char *data" "size_t len"
  77 .Ft void
  78 .Fn SHA512_256_Final "unsigned char digest[32]" "SHA512_CTX *context"
  79 .Ft "char *"
  80 .Fn SHA512_256_End "SHA512_CTX *context" "char *buf"
  81 .Ft "char *"
  82 .Fn SHA512_256_File "const char *filename" "char *buf"
  83 .Ft "char *"
  84 .Fn SHA512_256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  85 .Ft "char *"
  86 .Fn SHA512_256_Data "const unsigned char *data" "unsigned int len" "char *buf"
  87 .Sh DESCRIPTION
  88 The
  89 .Li SHA512_
  90 functions calculate a 512-bit cryptographic checksum (digest)
  91 for any number of input bytes.
  92 A cryptographic checksum is a one-way
  93 hash function; that is, it is computationally impractical to find
  94 the input corresponding to a particular output.
  95 This net result is
  96 a
  97 .Dq fingerprint
  98 of the input-data, which does not disclose the actual input.
  99 .Pp
 100 The
 101 .Fn SHA512_Init ,
 102 .Fn SHA512_Update ,
 103 and
 104 .Fn SHA512_Final
 105 functions are the core functions.
 106 Allocate an
 107 .Vt SHA512_CTX ,
 108 initialize it with
 109 .Fn SHA512_Init ,
 110 run over the data with
 111 .Fn SHA512_Update ,
 112 and finally extract the result using
 113 .Fn SHA512_Final ,
 114 which will also erase the
 115 .Vt SHA512_CTX .
 116 .Pp
 117 .Fn SHA512_End
 118 is a wrapper for
 119 .Fn SHA512_Final
 120 which converts the return value to a 129-character
 121 (including the terminating '\e0')
 122 .Tn ASCII
 123 string which represents the 512 bits in hexadecimal.
 124 .Pp
 125 .Fn SHA512_File
 126 calculates the digest of a file, and uses
 127 .Fn SHA512_End
 128 to return the result.
 129 If the file cannot be opened, a null pointer is returned.
 130 .Fn SHA512_FileChunk
 131 is similar to
 132 .Fn SHA512_File ,
 133 but it only calculates the digest over a byte-range of the file specified,
 134 starting at
 135 .Fa offset
 136 and spanning
 137 .Fa length
 138 bytes.
 139 If the
 140 .Fa length
 141 parameter is specified as 0, or more than the length of the remaining part
 142 of the file,
 143 .Fn SHA512_FileChunk
 144 calculates the digest from
 145 .Fa offset
 146 to the end of file.
 147 .Fn SHA512_Data
 148 calculates the digest of a chunk of data in memory, and uses
 149 .Fn SHA512_End
 150 to return the result.
 151 .Pp
 152 When using
 153 .Fn SHA512_End ,
 154 .Fn SHA512_File ,
 155 or
 156 .Fn SHA512_Data ,
 157 the
 158 .Fa buf
 159 argument can be a null pointer, in which case the returned string
 160 is allocated with
 161 .Xr malloc 3
 162 and subsequently must be explicitly deallocated using
 163 .Xr free 3
 164 after use.
 165 If the
 166 .Fa buf
 167 argument is non-null it must point to at least 129 characters of buffer space.
 168 .Pp
 169 The
 170 .Li SHA384_
 171 and
 172 .Li SHA512_256_
 173 functions are identical to the
 174 .Li SHA512_
 175 functions except they use a different initial hash value and the output is
 176 truncated to 384 bits and 256 bits respectively.
 177 .Pp
 178 .Fn SHA384_End
 179 is a wrapper for
 180 .Fn SHA384_Final
 181 which converts the return value to a 97-character
 182 (including the terminating '\e0')
 183 .Tn ASCII
 184 string which represents the 384 bits in hexadecimal.
 185 .Pp
 186 .Fn SHA512_256_End
 187 is a wrapper for
 188 .Fn SHA512_Final
 189 which converts the return value to a 65-character
 190 (including the terminating '\e0')
 191 .Tn ASCII
 192 string which represents the 256 bits in hexadecimal.
 193 .Sh ERRORS
 194 The
 195 .Fn SHA512_End
 196 function called with a null buf argument may fail and return NULL if:
 197 .Bl -tag -width Er
 198 .It Bq Er ENOMEM
 199 Insufficient storage space is available.
 200 .El
 201 .Pp
 202 The
 203 .Fn SHA512_File
 204 and
 205 .Fn SHA512_FileChunk
 206 may return NULL when underlying
 207 .Xr open 2 ,
 208 .Xr fstat 2 ,
 209 .Xr lseek 2 ,
 210 or
 211 .Xr SHA512_End 2
 212 fail.
 213 .Sh SEE ALSO
 214 .Xr md4 3 ,
 215 .Xr md5 3 ,
 216 .Xr ripemd 3 ,
 217 .Xr sha 3 ,
 218 .Xr sha256 3 ,
 219 .Xr sha512 3 ,
 220 .Xr skein 3
 221 .Sh HISTORY
 222 These functions appeared in
 223 .Fx 9.0 .
 224 .Sh AUTHORS
 225 The core hash routines were implemented by Colin Percival based on
 226 the published
 227 .Tn FIPS 180-2
 228 standard.
 229 .Sh BUGS
 230 No method is known to exist which finds two files having the same hash value,
 231 nor to find a file with a specific hash value.
 232 There is on the other hand no guarantee that such a method does not exist.