lib/libmd/ripemd.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 .\"
  11 .Dd July 20, 2018
  12 .Dt RIPEMD 3
  13 .Os
  14 .Sh NAME
  15 .Nm RIPEMD160_Init ,
  16 .Nm RIPEMD160_Update ,
  17 .Nm RIPEMD160_Final ,
  18 .Nm RIPEMD160_End ,
  19 .Nm RIPEMD160_File ,
  20 .Nm RIPEMD160_FileChunk ,
  21 .Nm RIPEMD160_Data
  22 .Nd calculate the RIPEMD160 message digest
  23 .Sh LIBRARY
  24 .Lb libmd
  25 .Sh SYNOPSIS
  26 .In sys/types.h
  27 .In ripemd.h
  28 .Ft void
  29 .Fn RIPEMD160_Init "RIPEMD160_CTX *context"
  30 .Ft void
  31 .Fn RIPEMD160_Update "RIPEMD160_CTX *context" "const unsigned char *data" "unsigned int len"
  32 .Ft void
  33 .Fn RIPEMD160_Final "unsigned char digest[20]" "RIPEMD160_CTX *context"
  34 .Ft "char *"
  35 .Fn RIPEMD160_End "RIPEMD160_CTX *context" "char *buf"
  36 .Ft "char *"
  37 .Fn RIPEMD160_File "const char *filename" "char *buf"
  38 .Ft "char *"
  39 .Fn RIPEMD160_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
  40 .Ft "char *"
  41 .Fn RIPEMD160_Data "const unsigned char *data" "unsigned int len" "char *buf"
  42 .Sh DESCRIPTION
  43 The
  44 .Li RIPEMD160_
  45 functions calculate a 160-bit cryptographic checksum (digest)
  46 for any number of input bytes.
  47 A cryptographic checksum is a one-way
  48 hash function; that is, it is computationally impractical to find
  49 the input corresponding to a particular output.
  50 This net result is a
  51 .Dq fingerprint
  52 of the input-data, which does not disclose the actual input.
  53 .Pp
  54 The
  55 .Fn RIPEMD160_Init ,
  56 .Fn RIPEMD160_Update ,
  57 and
  58 .Fn RIPEMD160_Final
  59 functions are the core functions.
  60 Allocate an
  61 .Vt RIPEMD160_CTX ,
  62 initialize it with
  63 .Fn RIPEMD160_Init ,
  64 run over the data with
  65 .Fn RIPEMD160_Update ,
  66 and finally extract the result using
  67 .Fn RIPEMD160_Final ,
  68 which will also erase the
  69 .Vt RIPEMD160_CTX .
  70 .Pp
  71 The
  72 .Fn RIPEMD160_End
  73 function is a wrapper for
  74 .Fn RIPEMD160_Final
  75 which converts the return value to a 41-character
  76 (including the terminating '\e0')
  77 ASCII string which represents the 160 bits in hexadecimal.
  78 .Pp
  79 The
  80 .Fn RIPEMD160_File
  81 function calculates the digest of a file, and uses
  82 .Fn RIPEMD160_End
  83 to return the result.
  84 If the file cannot be opened, a null pointer is returned.
  85 The
  86 .Fn RIPEMD160_FileChunk
  87 function is similar to
  88 .Fn RIPEMD160_File ,
  89 but it only calculates the digest over a byte-range of the file specified,
  90 starting at
  91 .Fa offset
  92 and spanning
  93 .Fa length
  94 bytes.
  95 If the
  96 .Fa length
  97 parameter is specified as 0, or more than the length of the remaining part
  98 of the file,
  99 .Fn RIPEMD160_FileChunk
 100 calculates the digest from
 101 .Fa offset
 102 to the end of file.
 103 The
 104 .Fn RIPEMD160_Data
 105 function calculates the digest of a chunk of data in memory, and uses
 106 .Fn RIPEMD160_End
 107 to return the result.
 108 .Pp
 109 When using
 110 .Fn RIPEMD160_End ,
 111 .Fn RIPEMD160_File ,
 112 or
 113 .Fn RIPEMD160_Data ,
 114 the
 115 .Fa buf
 116 argument can be a null pointer, in which case the returned string
 117 is allocated with
 118 .Xr malloc 3
 119 and subsequently must be explicitly deallocated using
 120 .Xr free 3
 121 after use.
 122 If the
 123 .Fa buf
 124 argument is non-null it must point to at least 41 characters of buffer space.
 125 .Sh ERRORS
 126 The
 127 .Fn RIPEMD160_End
 128 function called with a null buf argument may fail and return NULL if:
 129 .Bl -tag -width Er
 130 .It Bq Er ENOMEM
 131 Insufficient storage space is available.
 132 .El
 133 .Pp
 134 The
 135 .Fn RIPEMD160_File
 136 and
 137 .Fn RIPEMD160_FileChunk
 138 may return NULL when underlying
 139 .Xr open 2 ,
 140 .Xr fstat 2 ,
 141 .Xr lseek 2 ,
 142 or
 143 .Xr RIPEMD160_End 3
 144 fail.
 145 .Sh SEE ALSO
 146 .Xr md4 3 ,
 147 .Xr md5 3 ,
 148 .Xr sha 3 ,
 149 .Xr sha256 3 ,
 150 .Xr sha512 3 ,
 151 .Xr skein 3
 152 .Sh HISTORY
 153 These functions appeared in
 154 .Fx 4.0 .
 155 .Sh AUTHORS
 156 The core hash routines were implemented by Eric Young based on the
 157 published RIPEMD160 specification.
 158 .Sh BUGS
 159 No method is known to exist which finds two files having the same hash value,
 160 nor to find a file with a specific hash value.
 161 There is on the other hand no guarantee that such a method does not exist.