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