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 April 22, 2016
  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 .Pp
 115 .Fn SHA512_End
 116 is a wrapper for
 117 .Fn SHA512_Final
 118 which converts the return value to a 129-character
 119 (including the terminating '\e0')
 120 .Tn ASCII
 121 string which represents the 512 bits in hexadecimal.
 122 .Pp
 123 .Fn SHA512_File
 124 calculates the digest of a file, and uses
 125 .Fn SHA512_End
 126 to return the result.
 127 If the file cannot be opened, a null pointer is returned.
 128 .Fn SHA512_FileChunk
 129 is similar to
 130 .Fn SHA512_File ,
 131 but it only calculates the digest over a byte-range of the file specified,
 132 starting at
 133 .Fa offset
 134 and spanning
 135 .Fa length
 136 bytes.
 137 If the
 138 .Fa length
 139 parameter is specified as 0, or more than the length of the remaining part
 140 of the file,
 141 .Fn SHA512_FileChunk
 142 calculates the digest from
 143 .Fa offset
 144 to the end of file.
 145 .Fn SHA512_Data
 146 calculates the digest of a chunk of data in memory, and uses
 147 .Fn SHA512_End
 148 to return the result.
 149 .Pp
 150 When using
 151 .Fn SHA512_End ,
 152 .Fn SHA512_File ,
 153 or
 154 .Fn SHA512_Data ,
 155 the
 156 .Fa buf
 157 argument can be a null pointer, in which case the returned string
 158 is allocated with
 159 .Xr malloc 3
 160 and subsequently must be explicitly deallocated using
 161 .Xr free 3
 162 after use.
 163 If the
 164 .Fa buf
 165 argument is non-null it must point to at least 129 characters of buffer space.
 166 .Pp
 167 The
 168 .Li SHA384_
 169 and
 170 .Li SHA512_256_
 171 functions are identical to the
 172 .Li SHA512_
 173 functions except they use a different initial hash value and the output is
 174 truncated to 384 bits and 256 bits respectively.
 175 .Pp
 176 .Fn SHA384_End
 177 is a wrapper for
 178 .Fn SHA384_Final
 179 which converts the return value to a 97-character
 180 (including the terminating '\e0')
 181 .Tn ASCII
 182 string which represents the 384 bits in hexadecimal.
 183 .Pp
 184 .Fn SHA512_256_End
 185 is a wrapper for
 186 .Fn SHA512_Final
 187 which converts the return value to a 65-character
 188 (including the terminating '\e0')
 189 .Tn ASCII
 190 string which represents the 256 bits in hexadecimal.
 191 .Sh SEE ALSO
 192 .Xr md4 3 ,
 193 .Xr md5 3 ,
 194 .Xr ripemd 3 ,
 195 .Xr sha 3
 196 .Sh HISTORY
 197 These functions appeared in
 198 .Fx 9.0 .
 199 .Sh AUTHORS
 200 The core hash routines were implemented by Colin Percival based on
 201 the published
 202 .Tn FIPS 180-2
 203 standard.
 204 .Sh BUGS
 205 No method is known to exist which finds two files having the same hash value,
 206 nor to find a file with a specific hash value.
 207 There is on the other hand no guarantee that such a method does not exist.