lib/libc/hash/sha2/sha2.3

   1 .\" $NetBSD: sha2.3,v 1.5 2009/05/26 08:04:12 joerg Exp $
   2 .\"     $OpenBSD: sha2.3,v 1.11 2004/06/22 01:57:29 jfb Exp $
   3 .\"
   4 .\" Copyright (c) 2003, 2004 Todd C. Miller <Todd.Miller@courtesan.com>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .\" Sponsored in part by the Defense Advanced Research Projects
  19 .\" Agency (DARPA) and Air Force Research Laboratory, Air Force
  20 .\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
  21 .\"
  22 .\" See http://www.nist.gov/sha/ for the detailed standard
  23 .\"
  24 .Dd May 20, 2009
  25 .Dt SHA2 3
  26 .Os
  27 .Sh NAME
  28 .Nm SHA256_Init ,
  29 .Nm SHA256_Update ,
  30 .Nm SHA256_Pad ,
  31 .Nm SHA256_Final ,
  32 .Nm SHA256_Transform ,
  33 .Nm SHA256_End ,
  34 .Nm SHA256_File ,
  35 .Nm SHA256_FileChunk ,
  36 .Nm SHA256_Data
  37 .Nd calculate the NIST Secure Hash Standard (version 2)
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sha2.h
  41 .Ft void
  42 .Fn SHA224_Init "SHA224_CTX *context"
  43 .Ft void
  44 .Fn SHA224_Update "SHA224_CTX *context" "const uint8_t *data" "size_t len"
  45 .Ft void
  46 .Fn SHA224_Pad "SHA224_CTX *context"
  47 .Ft void
  48 .Fn SHA224_Final "uint8_t digest[SHA224_DIGEST_LENGTH]" "SHA224_CTX *context"
  49 .Ft void
  50 .Fn SHA224_Transform "uint32_t state[8]" "const uint8_t buffer[SHA224_BLOCK_LENGTH]"
  51 .Ft "char *"
  52 .Fn SHA224_End "SHA224_CTX *context" "char *buf"
  53 .Ft "char *"
  54 .Fn SHA224_File "const char *filename" "char *buf"
  55 .Ft "char *"
  56 .Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  57 .Ft "char *"
  58 .Fn SHA224_Data "uint8_t *data" "size_t len" "char *buf"
  59 .Ft void
  60 .Fn SHA256_Init "SHA256_CTX *context"
  61 .Ft void
  62 .Fn SHA256_Update "SHA256_CTX *context" "const uint8_t *data" "size_t len"
  63 .Ft void
  64 .Fn SHA256_Pad "SHA256_CTX *context"
  65 .Ft void
  66 .Fn SHA256_Final "uint8_t digest[SHA256_DIGEST_LENGTH]" "SHA256_CTX *context"
  67 .Ft void
  68 .Fn SHA256_Transform "uint32_t state[8]" "const uint8_t buffer[SHA256_BLOCK_LENGTH]"
  69 .Ft "char *"
  70 .Fn SHA256_End "SHA256_CTX *context" "char *buf"
  71 .Ft "char *"
  72 .Fn SHA256_File "const char *filename" "char *buf"
  73 .Ft "char *"
  74 .Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  75 .Ft "char *"
  76 .Fn SHA256_Data "uint8_t *data" "size_t len" "char *buf"
  77 .Ft void
  78 .Fn SHA384_Init "SHA384_CTX *context"
  79 .Ft void
  80 .Fn SHA384_Update "SHA384_CTX *context" "const uint8_t *data" "size_t len"
  81 .Ft void
  82 .Fn SHA384_Pad "SHA384_CTX *context"
  83 .Ft void
  84 .Fn SHA384_Final "uint8_t digest[SHA384_DIGEST_LENGTH]" "SHA384_CTX *context"
  85 .Ft void
  86 .Fn SHA384_Transform "uint64_t state[8]" "const uint8_t buffer[SHA384_BLOCK_LENGTH]"
  87 .Ft "char *"
  88 .Fn SHA384_End "SHA384_CTX *context" "char *buf"
  89 .Ft "char *"
  90 .Fn SHA384_File "char *filename" "char *buf"
  91 .Ft "char *"
  92 .Fn SHA384_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length"
  93 .Ft "char *"
  94 .Fn SHA384_Data "uint8_t *data" "size_t len" "char *buf"
  95 .Ft void
  96 .Fn SHA512_Init "SHA512_CTX *context"
  97 .Ft void
  98 .Fn SHA512_Update "SHA512_CTX *context" "const uint8_t *data" "size_t len"
  99 .Ft void
 100 .Fn SHA512_Pad "SHA512_CTX *context"
 101 .Ft void
 102 .Fn SHA512_Final "uint8_t digest[SHA512_DIGEST_LENGTH]" "SHA512_CTX *context"
 103 .Ft void
 104 .Fn SHA512_Transform "uint64_t state[8]" "const uint8_t buffer[SHA512_BLOCK_LENGTH]"
 105 .Ft "char *"
 106 .Fn SHA512_End "SHA512_CTX *context" "char *buf"
 107 .Ft "char *"
 108 .Fn SHA512_File "char *filename" "char *buf"
 109 .Ft "char *"
 110 .Fn SHA512_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length"
 111 .Ft "char *"
 112 .Fn SHA512_Data "uint8_t *data" "size_t len" "char *buf"
 113 .Sh DESCRIPTION
 114 The SHA2 functions implement the NIST Secure Hash Standard,
 115 FIPS PUB 180-2.
 116 The SHA2 functions are used to generate a condensed representation of a
 117 message called a message digest, suitable for use as a digital signature.
 118 There are four families of functions, with names corresponding to
 119 the number of bits in the resulting message digest.
 120 The SHA-224 and SHA-256 functions are limited to processing a message of less
 121 than 2^64 bits as input.
 122 The SHA-384 and SHA-512 functions can process a message of at most 2^128 - 1
 123 bits as input.
 124 .Pp
 125 The SHA2 functions are considered to be more secure than the
 126 .Xr sha1 3
 127 functions with which they share a similar interface.
 128 The 224, 256, 384, and 512-bit versions of SHA2 share the same interface.
 129 For brevity, only the 256-bit variants are described below.
 130 .Pp
 131 The
 132 .Fn SHA256_Init
 133 function initializes a SHA256_CTX
 134 .Ar context
 135 for use with
 136 .Fn SHA256_Update ,
 137 and
 138 .Fn SHA256_Final .
 139 The
 140 .Fn SHA256_Update
 141 function adds
 142 .Ar data
 143 of length
 144 .Ar len
 145 to the SHA256_CTX specified by
 146 .Ar context .
 147 .Fn SHA256_Final
 148 is called when all data has been added via
 149 .Fn SHA256_Update
 150 and stores a message digest in the
 151 .Ar digest
 152 parameter.
 153 .Pp
 154 The
 155 .Fn SHA256_Pad
 156 function can be used to apply padding to the message digest as in
 157 .Fn SHA256_Final ,
 158 but the current context can still be used with
 159 .Fn SHA256_Update .
 160 .Pp
 161 The
 162 .Fn SHA256_Transform
 163 function is used by
 164 .Fn SHA256_Update
 165 to hash 512-bit blocks and forms the core of the algorithm.
 166 Most programs should use the interface provided by
 167 .Fn SHA256_Init ,
 168 .Fn SHA256_Update ,
 169 and
 170 .Fn SHA256_Final
 171 instead of calling
 172 .Fn SHA256_Transform
 173 directly.
 174 .Pp
 175 The
 176 .Fn SHA256_End
 177 function is a front end for
 178 .Fn SHA256_Final
 179 which converts the digest into an
 180 .Tn ASCII
 181 representation of the digest in hexadecimal.
 182 .Pp
 183 The
 184 .Fn SHA256_File
 185 function calculates the digest for a file and returns the result via
 186 .Fn SHA256_End .
 187 If
 188 .Fn SHA256_File
 189 is unable to open the file, a
 190 .Dv NULL
 191 pointer is returned.
 192 .Pp
 193 .Fn SHA256_FileChunk
 194 behaves like
 195 .Fn SHA256_File
 196 but calculates the digest only for that portion of the file starting at
 197 .Fa offset
 198 and continuing for
 199 .Fa length
 200 bytes or until end of file is reached, whichever comes first.
 201 A zero
 202 .Fa length
 203 can be specified to read until end of file.
 204 A negative
 205 .Fa length
 206 or
 207 .Fa offset
 208 will be ignored.
 209 .Pp
 210 The
 211 .Fn SHA256_Data
 212 function
 213 calculates the digest of an arbitrary string and returns the result via
 214 .Fn SHA256_End .
 215 .Pp
 216 For each of the
 217 .Fn SHA256_End ,
 218 .Fn SHA256_File ,
 219 .Fn SHA256_FileChunk ,
 220 and
 221 .Fn SHA256_Data
 222 functions the
 223 .Ar buf
 224 parameter should either be a string large enough to hold the resulting digest
 225 (e.g.,
 226 .Ev SHA224_DIGEST_STRING_LENGTH ,
 227 .Ev SHA256_DIGEST_STRING_LENGTH ,
 228 .Ev SHA384_DIGEST_STRING_LENGTH ,
 229 or
 230 .Ev SHA512_DIGEST_STRING_LENGTH ,
 231 depending on the function being used)
 232 or a
 233 .Dv NULL
 234 pointer.
 235 In the latter case, space will be dynamically allocated via
 236 .Xr malloc 3
 237 and should be freed using
 238 .Xr free 3
 239 when it is no longer needed.
 240 .Sh EXAMPLES
 241 The following code fragment will calculate the SHA-256 digest for the string
 242 .Qq abc ,
 243 which is
 244 .Dq 0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad .
 245 .Bd -literal -offset indent
 246 SHA256_CTX ctx;
 247 uint8_t results[SHA256_DIGEST_LENGTH];
 248 char *buf;
 249 int n;
 250
 251 buf = "abc";
 252 n = strlen(buf);
 253 SHA256_Init(\*[Am]ctx);
 254 SHA256_Update(\*[Am]ctx, (uint8_t *)buf, n);
 255 SHA256_Final(results, \*[Am]ctx);
 256
 257 /* Print the digest as one long hex value */
 258 printf("0x");
 259 for (n = 0; n \*[Lt] SHA256_DIGEST_LENGTH; n++)
 260         printf("%02x", results[n]);
 261 putchar('\en');
 262 .Ed
 263 .Pp
 264 Alternately, the helper functions could be used in the following way:
 265 .Bd -literal -offset indent
 266 SHA256_CTX ctx;
 267 uint8_t output[SHA256_DIGEST_STRING_LENGTH];
 268 char *buf = "abc";
 269
 270 printf("0x%s\en", SHA256_Data(buf, strlen(buf), output));
 271 .Ed
 272 .Sh SEE ALSO
 273 .Xr cksum 1 ,
 274 .Xr md4 3 ,
 275 .Xr md5 3 ,
 276 .Xr rmd160 3 ,
 277 .Xr sha1 3
 278 .Rs
 279 .%T Secure Hash Standard
 280 .%O FIPS PUB 180-2
 281 .Re
 282 .Sh HISTORY
 283 The SHA2 functions appeared in
 284 .Ox 3.4
 285 and
 286 .Nx 3.0 .
 287 .Sh AUTHORS
 288 This implementation of the SHA functions was written by Aaron D. Gifford.
 289 .Pp
 290 The
 291 .Fn SHA256_End ,
 292 .Fn SHA256_File ,
 293 .Fn SHA256_FileChunk ,
 294 and
 295 .Fn SHA256_Data
 296 helper functions are derived from code written by Poul-Henning Kamp.
 297 .Sh CAVEATS
 298 This implementation of the Secure Hash Standard has not been validated by
 299 NIST and as such is not in official compliance with the standard.
 300 .Pp
 301 If a message digest is to be copied to a multi-byte type (i.e.:
 302 an array of five 32-bit integers) it will be necessary to
 303 perform byte swapping on little endian machines such as the i386, alpha,
 304 and vax.