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: src/lib/libmd/ripemd.3,v 1.2.2.5 2001/12/17 10:08:31 ru Exp $
  11 .\"
  12 .Dd February 26, 1999
  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_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_Data "const unsigned char *data" "unsigned int len" "char *buf"
  40 .Sh DESCRIPTION
  41 The
  42 .Li RIPEMD160_
  43 functions calculate a 160-bit cryptographic checksum (digest)
  44 for any number of input bytes.  A cryptographic checksum is a one-way
  45 hash function; that is, it is computationally impractical to find
  46 the input corresponding to a particular output.  This net result is
  47 a ``fingerprint'' of the input-data, which doesn't disclose the actual
  48 input.
  49 .Pp
  50 The
  51 .Fn RIPEMD160_Init  ,
  52 .Fn RIPEMD160_Update ,
  53 and
  54 .Fn RIPEMD160_Final
  55 functions are the core functions.  Allocate an RIPEMD160_CTX, initialize it with
  56 .Fn RIPEMD160_Init ,
  57 run over the data with
  58 .Fn RIPEMD160_Update ,
  59 and finally extract the result using
  60 .Fn RIPEMD160_Final .
  61 .Pp
  62 .Fn RIPEMD160_End
  63 is a wrapper for
  64 .Fn RIPEMD160_Final
  65 which converts the return value to a 41-character
  66 (including the terminating '\e0')
  67 .Tn ASCII
  68 string which represents the 160 bits in hexadecimal.
  69 .Pp
  70 .Fn RIPEMD160_File
  71 calculates the digest of a file, and uses
  72 .Fn RIPEMD160_End
  73 to return the result.
  74 If the file cannot be opened, a null pointer is returned.
  75 .Fn RIPEMD160_Data
  76 calculates the digest of a chunk of data in memory, and uses
  77 .Fn RIPEMD160_End
  78 to return the result.
  79 .Pp
  80 When using
  81 .Fn RIPEMD160_End ,
  82 .Fn RIPEMD160_File ,
  83 or
  84 .Fn RIPEMD160_Data ,
  85 the
  86 .Fa buf
  87 argument can be a null pointer, in which case the returned string
  88 is allocated with
  89 .Xr malloc 3
  90 and subsequently must be explicitly deallocated using
  91 .Xr free 3
  92 after use.
  93 If the
  94 .Fa buf
  95 argument is non-null it must point to at least 41 characters of buffer space.
  96 .Sh SEE ALSO
  97 .Xr md2 3 ,
  98 .Xr md4 3 ,
  99 .Xr md5 3 ,
 100 .Xr sha 3
 101 .Sh AUTHORS
 102 The core hash routines were implemented by Eric Young based on the
 103 published
 104 .Tn RIPEMD160
 105 specification.
 106 .Sh HISTORY
 107 These functions appeared in
 108 .Fx 4.0 .
 109 .Sh BUGS
 110 No method is known to exist which finds two files having the same hash value,
 111 nor to find a file with a specific hash value.
 112 There is on the other hand no guarantee that such a method doesn't exist.