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