lib/libmd/ripemd.3

   1 .\"
   2 .\" ----------------------------------------------------------------------------
   3 .\" "THE BEER-WARE LICENSE" (Revision 42):
   4 .\" <phk@login.dkuug.dk> 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 February 26, 1999
  13 .Dt RIPEMD 3
  14 .Os FreeBSD 4.0
  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_Data
  22 .Nd calculate the RIPEMD160 message digest
  23 .Sh SYNOPSIS
  24 .Fd #include <sys/types.h>
  25 .Fd #include <ripemd.h>
  26 .Ft void
  27 .Fn RIPEMD160_Init "RIPEMD160_CTX *context"
  28 .Ft void
  29 .Fn RIPEMD160_Update "RIPEMD160_CTX *context" "const unsigned char *data" "unsigned int len"
  30 .Ft void
  31 .Fn RIPEMD160_Final "unsigned char digest[20]" "RIPEMD160_CTX *context"
  32 .Ft "char *"
  33 .Fn RIPEMD160_End "RIPEMD160_CTX *context" "char *buf"
  34 .Ft "char *"
  35 .Fn RIPEMD160_File "const char *filename" "char *buf"
  36 .Ft "char *"
  37 .Fn RIPEMD160_Data "const unsigned char *data" "unsigned int len" "char *buf"
  38 .Sh DESCRIPTION
  39 The
  40 .Li RIPEMD160_
  41 functions calculate a 160-bit cryptographic checksum (digest)
  42 for any number of input bytes.  A cryptographic checksum is a one-way
  43 hash function; that is, it is computationally impractical to find
  44 the input corresponding to a particular output.  This net result is
  45 a ``fingerprint'' of the input-data, which doesn't disclose the actual
  46 input.
  47 .Pp
  48 The
  49 .Fn RIPEMD160_Init  ,
  50 .Fn RIPEMD160_Update ,
  51 and
  52 .Fn RIPEMD160_Final
  53 functions are the core functions.  Allocate an RIPEMD160_CTX, initialize it with
  54 .Fn RIPEMD160_Init ,
  55 run over the data with
  56 .Fn RIPEMD160_Update ,
  57 and finally extract the result using
  58 .Fn RIPEMD160_Final .
  59 .Pp
  60 .Fn RIPEMD160_End
  61 is a wrapper for
  62 .Fn RIPEMD160_Final
  63 which converts the return value to a 41-character
  64 (including the terminating '\e0')
  65 .Tn ASCII
  66 string which represents the 160 bits in hexadecimal.
  67 .Pp
  68 .Fn RIPEMD160_File
  69 calculates the digest of a file, and uses
  70 .Fn RIPEMD160_End
  71 to return the result.
  72 If the file cannot be opened, a null pointer is returned.
  73 .Fn RIPEMD160_Data
  74 calculates the digest of a chunk of data in memory, and uses
  75 .Fn RIPEMD160_End
  76 to return the result.
  77 .Pp
  78 When using
  79 .Fn RIPEMD160_End ,
  80 .Fn RIPEMD160_File ,
  81 or
  82 .Fn RIPEMD160_Data ,
  83 the
  84 .Ar buf
  85 argument can be a null pointer, in which case the returned string
  86 is allocated with
  87 .Xr malloc 3
  88 and subsequently must be explicitly deallocated using
  89 .Xr free 3
  90 after use.
  91 If the
  92 .Ar buf
  93 argument is non-null it must point to at least 41 characters of buffer space.
  94 .Sh SEE ALSO
  95 .Xr md2 3 ,
  96 .Xr md4 3 ,
  97 .Xr md5 3 ,
  98 .Xr sha 3
  99 .Sh AUTHORS
 100 The core hash routines were implemented by Eric Young based on the
 101 published
 102 .Tn RIPEMD160
 103 specification.
 104 .Sh HISTORY
 105 These functions appeared in
 106 .Fx 4.0 .
 107 .Sh BUGS
 108 No method is known to exist which finds two files having the same hash value,
 109 nor to find a file with a specific hash value.
 110 There is on the other hand no guarantee that such a method doesn't exist.