lib/libc/hash/rmd160/rmd160.3

   1 .\"     $NetBSD: rmd160.3,v 1.1 2005/09/24 19:07:00 elad Exp $
   2 .\"     $OpenBSD: rmd160.3,v 1.12 2000/04/18 03:01:29 aaron Exp $
   3 .\"
   4 .\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. The name of the author may not be used to endorse or promote products
  16 .\"    derived from this software without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  19 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  20 .\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
  21 .\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  22 .\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  23 .\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  24 .\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  25 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  26 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  27 .\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" See http://www.esat.kuleuven.ac.be/~bosselae/ripemd160.html
  30 .\"     for detailed information about RIPEMD-160.
  31 .\"
  32 .Dd July 16, 1997
  33 .Dt RMD160 3
  34 .Os
  35 .Sh NAME
  36 .Nm RMD160Init ,
  37 .Nm RMD160Update ,
  38 .Nm RMD160Final ,
  39 .Nm RMD160Transform ,
  40 .Nm RMD160End ,
  41 .Nm RMD160File ,
  42 .Nm RMD160Data
  43 .Nd calculate the ``RIPEMD-160'' message digest
  44 .Sh SYNOPSIS
  45 .In sys/types.h
  46 .In rmd160.h
  47 .Ft void
  48 .Fn RMD160Init "RMD160_CTX *context"
  49 .Ft void
  50 .Fn RMD160Update "RMD160_CTX *context" "const u_char *data" "u_int nbytes"
  51 .Ft void
  52 .Fn RMD160Final "u_char digest[20]" "RMD160_CTX *context"
  53 .Ft void
  54 .Fn RMD160Transform "uint32_t state[5]" "const uint32_t block[16]"
  55 .Ft "char *"
  56 .Fn RMD160End "RMD160_CTX *context" "char *buf"
  57 .Ft "char *"
  58 .Fn RMD160File "char *filename" "char *buf"
  59 .Ft "char *"
  60 .Fn RMD160Data "u_char *data" "size_t len" "char *buf"
  61 .Sh DESCRIPTION
  62 The RMD160 functions implement the 160-bit RIPE message digest hash algorithm
  63 (RMD-160).
  64 RMD-160 is used to generate a condensed representation
  65 of a message called a message digest.
  66 The algorithm takes a
  67 message less than 2^64 bits as input and produces a 160-bit digest
  68 suitable for use as a digital signature.
  69 .Pp
  70 The RMD160 functions are considered to be more secure than the
  71 .Xr md4 3
  72 and
  73 .Xr md5 3
  74 functions and at least as secure as the
  75 .Xr sha1 3
  76 function.
  77 All share a similar interface.
  78 .Pp
  79 The
  80 .Fn RMD160Init
  81 function initializes a RMD160_CTX
  82 .Ar context
  83 for use with
  84 .Fn RMD160Update ,
  85 and
  86 .Fn RMD160Final .
  87 The
  88 .Fn RMD160Update
  89 function adds
  90 .Ar data
  91 of length
  92 .Ar nbytes
  93 to the RMD160_CTX specified by
  94 .Ar context .
  95 .Fn RMD160Final
  96 is called when all data has been added via
  97 .Fn RMD160Update
  98 and stores a message digest in the
  99 .Ar digest
 100 parameter.
 101 When a null pointer is passed to
 102 .Fn RMD160Final
 103 as first argument only the final padding will be applied and the
 104 current context can still be used with
 105 .Fn RMD160Update .
 106 .Pp
 107 The
 108 .Fn RMD160Transform
 109 function is used by
 110 .Fn RMD160Update
 111 to hash 512-bit blocks and forms the core of the algorithm.
 112 Most programs should use the interface provided by
 113 .Fn RMD160Init ,
 114 .Fn RMD160Update
 115 and
 116 .Fn RMD160Final
 117 instead of calling
 118 .Fn RMD160Transform
 119 directly.
 120 .Pp
 121 The
 122 .Fn RMD160End
 123 function is a front end for
 124 .Fn RMD160Final
 125 which converts the digest into an
 126 .Tn ASCII
 127 representation of the 160 bit digest in hexadecimal.
 128 .Pp
 129 The
 130 .Fn RMD160File
 131 function calculates the digest for a file and returns the result via
 132 .Fn RMD160End .
 133 If
 134 .Fn RMD160File
 135 is unable to open the file a NULL pointer is returned.
 136 .Pp
 137 The
 138 .Fn RMD160Data
 139 function
 140 calculates the digest of an arbitrary string and returns the result via
 141 .Fn RMD160End .
 142 .Pp
 143 For each of the
 144 .Fn RMD160End ,
 145 .Fn RMD160File ,
 146 and
 147 .Fn RMD160Data
 148 functions the
 149 .Ar buf
 150 parameter should either be a string of at least 41 characters in
 151 size or a NULL pointer.
 152 In the latter case, space will be dynamically allocated via
 153 .Xr malloc 3
 154 and should be freed using
 155 .Xr free 3
 156 when it is no longer needed.
 157 .Sh EXAMPLES
 158 The follow code fragment will calculate the digest for
 159 the string "abc" which is ``0x8eb208f7e05d987a9b044a8e98c6b087f15a0bfc''.
 160 .Bd -literal -offset indent
 161 RMD160_CTX rmd;
 162 u_char results[20];
 163 char *buf;
 164 int n;
 165
 166 buf = "abc";
 167 n = strlen(buf);
 168 RMD160Init(\*[Am]rmd);
 169 RMD160Update(\*[Am]rmd, (u_char *)buf, n);
 170 RMD160Final(results, \*[Am]rmd);
 171
 172 /* Print the digest as one long hex value */
 173 printf("0x");
 174 for (n = 0; n \*[Lt] 20; n++)
 175         printf("%02x", results[n]);
 176 putchar('\\n');
 177 .Ed
 178 .Pp
 179 Alternately, the helper functions could be used in the following way:
 180 .Bd -literal -offset indent
 181 RMD160_CTX rmd;
 182 u_char output[41];
 183 char *buf = "abc";
 184
 185 printf("0x%s\en", RMD160Data(buf, strlen(buf), output));
 186 .Ed
 187 .Sh SEE ALSO
 188 .Xr rmd160 1 ,
 189 .Xr md4 3 ,
 190 .Xr md5 3 ,
 191 .Xr sha1 3
 192 .Pp
 193 .Rs
 194 .%A H. Dobbertin, A. Bosselaers, B. Preneel
 195 .%T RIPEMD-160, a strengthened version of RIPEMD
 196 .Re
 197 .Rs
 198 .%T Information technology - Security techniques - Hash-functions - Part 3: Dedicated hash-functions
 199 .%O ISO/IEC 10118-3
 200 .Re
 201 .Rs
 202 .%A H. Dobbertin, A. Bosselaers, B. Preneel
 203 .%T The RIPEMD-160 cryptographic hash function
 204 .%J Dr. Dobb's Journal
 205 .%V Vol. 22, No. 1
 206 .%D January 1997
 207 .%P pp. 24-28
 208 .Re
 209 .Sh HISTORY
 210 The RMD-160 functions appeared in
 211 .Ox 2.1 .
 212 .Sh AUTHORS
 213 This implementation of RMD-160 was written by Antoon Bosselaers.
 214 .Pp
 215 The
 216 .Fn RMD160End ,
 217 .Fn RMD160File ,
 218 and
 219 .Fn RMD160Data
 220 helper functions are derived from code written by Poul-Henning Kamp.
 221 .Sh BUGS
 222 If a message digest is to be copied to a multi-byte type (ie:
 223 an array of five 32-bit integers) it will be necessary to
 224 perform byte swapping on little endian machines such as the i386, alpha,
 225 and VAX.