lib/libmd/sha256.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: src/lib/libmd/sha256.3,v 1.4 2005/11/17 13:00:00 ru Exp $
  11 .\"
  12 .Dd April 29, 2006
  13 .Dt SHA256 3
  14 .Os
  15 .Sh NAME
  16 .Nm SHA256_Init ,
  17 .Nm SHA256_Update ,
  18 .Nm SHA256_Final ,
  19 .Nm SHA256_End ,
  20 .Nm SHA256_File ,
  21 .Nm SHA256_FileChunk ,
  22 .Nm SHA256_Data
  23 .Nd calculate the FIPS 180-2 ``SHA-256'' message digest
  24 .Sh LIBRARY
  25 .Lb libmd
  26 .Sh SYNOPSIS
  27 .In sys/types.h
  28 .In sha256.h
  29 .Ft void
  30 .Fn SHA256_Init "SHA256_CTX *context"
  31 .Ft void
  32 .Fn SHA256_Update "SHA256_CTX *context" "const void *data" "size_t len"
  33 .Ft void
  34 .Fn SHA256_Final "unsigned char digest[32]" "SHA256_CTX *context"
  35 .Ft "char *"
  36 .Fn SHA256_End "SHA256_CTX *context" "char *buf"
  37 .Ft "char *"
  38 .Fn SHA256_File "const char *filename" "char *buf"
  39 .Ft "char *"
  40 .Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  41 .Ft "char *"
  42 .Fn SHA256_Data "const void *data" "unsigned int len" "char *buf"
  43 .Sh DESCRIPTION
  44 The
  45 .Li SHA256_
  46 functions calculate a 256-bit cryptographic checksum (digest)
  47 for any number of input bytes.
  48 A cryptographic checksum is a one-way
  49 hash function; that is, it is computationally impractical to find
  50 the input corresponding to a particular output.
  51 This net result is
  52 a
  53 .Dq fingerprint
  54 of the input-data, which does not disclose the actual input.
  55 .Pp
  56 The
  57 .Fn SHA256_Init ,
  58 .Fn SHA256_Update ,
  59 and
  60 .Fn SHA256_Final
  61 functions are the core functions.
  62 Allocate an
  63 .Vt SHA256_CTX ,
  64 initialize it with
  65 .Fn SHA256_Init ,
  66 run over the data with
  67 .Fn SHA256_Update ,
  68 and finally extract the result using
  69 .Fn SHA256_Final .
  70 .Pp
  71 .Fn SHA256_End
  72 is a wrapper for
  73 .Fn SHA256_Final
  74 which converts the return value to a 65-character
  75 (including the terminating '\e0')
  76 .Tn ASCII
  77 string which represents the 256 bits in hexadecimal.
  78 .Pp
  79 .Fn SHA256_File
  80 calculates the digest of a file, and uses
  81 .Fn SHA256_End
  82 to return the result.
  83 If the file cannot be opened, a null pointer is returned.
  84 .Fn SHA256_FileChunk
  85 is similar to
  86 .Fn SHA256_File ,
  87 but it only calculates the digest over a byte-range of the file specified,
  88 starting at
  89 .Fa offset
  90 and spanning
  91 .Fa length
  92 bytes.
  93 If the
  94 .Fa length
  95 parameter is specified as 0, or more than the length of the remaining part
  96 of the file,
  97 .Fn SHA256_FileChunk
  98 calculates the digest from
  99 .Fa offset
 100 to the end of file.
 101 .Fn SHA256_Data
 102 calculates the digest of a chunk of data in memory, and uses
 103 .Fn SHA256_End
 104 to return the result.
 105 .Pp
 106 When using
 107 .Fn SHA256_End ,
 108 .Fn SHA256_File ,
 109 or
 110 .Fn SHA256_Data ,
 111 the
 112 .Fa buf
 113 argument can be a null pointer, in which case the returned string
 114 is allocated with
 115 .Xr malloc 3
 116 and subsequently must be explicitly deallocated using
 117 .Xr free 3
 118 after use.
 119 If the
 120 .Fa buf
 121 argument is non-null it must point to at least 65 characters of buffer space.
 122 .Sh SEE ALSO
 123 .Xr md2 3 ,
 124 .Xr md4 3 ,
 125 .Xr md5 3 ,
 126 .Xr ripemd 3 ,
 127 .Xr sha 3
 128 .Sh HISTORY
 129 These functions appeared in
 130 .Fx 4.0 .
 131 .Sh AUTHORS
 132 The core hash routines were implemented by Colin Percival based on
 133 the published
 134 .Tn FIPS 180-2
 135 standard.
 136 .Sh BUGS
 137 No method is known to exist which finds two files having the same hash value,
 138 nor to find a file with a specific hash value.
 139 There is on the other hand no guarantee that such a method does not exist.