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