Manpage for RMD*(3)

1 files changed, 224 insertions, 0 deletions

diff --git a/lib/libc/hash/rmd160.3 b/lib/libc/hash/rmd160.3
new file mode 100644
index 00000000000..bcec1084a52
--- /dev/null
+++ b/lib/libc/hash/rmd160.3
@@ -0,0 +1,224 @@
+.\"	$OpenBSD: rmd160.3,v 1.1 1997/07/17 06:02:43 millert Exp $
+.\"
+.\" Copyright (c) 1997 Todd C. Miller <Todd.Miller@courtesan.com>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"	This product includes software developed by Todd C. Miller.
+.\" 4. The name of the author may not be used to endorse or promote products
+.\"    derived from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
+.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.\" See http://www.esat.kuleuven.ac.be/~bosselae/ripemd160.html
+.\"	for detailed information about RIPEMD-160.
+.\"
+.Dd July 16, 1997
+.Dt RMD160 3
+.Sh NAME
+.Nm RMD160Init ,
+.Nm RMD160Update ,
+.Nm RMD160Final ,
+.Nm RMD160Transform ,
+.Nm RMD160End ,
+.Nm RMD160File ,
+.Nm RMD160Data ,
+.Nd calculate the ``RIPEMD-160'' message digest
+.Sh SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <rmd160.h>
+.Ft void
+.Fn RMD160Init "RMD160_CTX *context"
+.Ft void
+.Fn RMD160Update "RMD160_CTX *context" "const u_char *data" "u_int nbytes"
+.Ft void
+.Fn RMD160Final "u_char digest[20]" "RMD160_CTX *context"
+.Ft void
+.Fn RMD160Transform "u_int32_t state[5]" "const u_int32_t block[16]"
+.Ft "char *"
+.Fn RMD160End "RMD160_CTX *context" "char *buf"
+.Ft "char *"
+.Fn RMD160File "char *filename" "char *buf"
+.Ft "char *"
+.Fn RMD160Data "u_char *data" "u_int len" "char *buf"
+.Sh DESCRIPTION
+The RMD160 functions implement the 160-bit RIPE message digest hash algorithm
+(RMD-160).  RMD-160 is used to generate a condensed representation
+of a message called a message digest.  The algorithm takes a
+message less than 2^64 bits as input and produces a 160-bit digest
+suitable for use as a digital signature.
+.Pp
+The RMD160 functions are considered to be more secure than the 
+.Xr md4 3
+and
+.Xr md5 3
+functions and at least as secure as the
+.Xr sha1 3
+function.  All share a similar interface.
+.Pp
+The
+.Fn RMD160Init
+function initializes a RMD160_CTX
+.Ar context
+for use with
+.Fn RMD160Update ,
+and
+.Fn RMD160Final .
+The
+.Fn RMD160Update
+function adds
+.Ar data
+of length
+.Ar nbytes
+to the RMD160_CTX specified by
+.Ar context.
+.Fn RMD160Final
+is called when all data has been added via
+.Fn RMD160Update
+and stores a message digest in the
+.Ar digest
+parameter.
+When a null pointer is passed to
+.Fn RMD160Final
+as first argument only the final padding will be applied and the 
+current context can still be used with
+.Fn RMD160Update .
+.Pp
+The
+.Fn RMD160Transform
+function is used by
+.Fn RMD160Update
+to hash 512-bit blocks and forms the core of the algorithm.
+Most programs should use the interface provided by
+.Fn RMD160Init ,
+.Fn RMD160Update
+and
+.Fn RMD160Final
+instead of calling
+.Fn RMD160Transform
+directly.
+.Pp
+The
+.Fn RMD160End
+function is a front end for
+.Fn RMD160Final
+which converts the digest into an
+.Tn ASCII
+representation of the 160 bit digest in hexadecimal.
+.Pp
+The
+.Fn RMD160File
+function calculates the digest for a file and returns the result via
+.Fn RMD160End .
+If
+.Fn RMD160File
+is unable to open the file a NULL pointer is returned.
+.Pp
+The
+.Fn RMD160Data
+function
+calculates the digest of an arbitrary string and returns the result via
+.Fn RMD160End .
+.Pp
+For each of the
+.Fn RMD160End ,
+.Fn RMD160File ,
+and
+.Fn RMD160Data
+functions the
+.Ar buf
+parameter should either be a string of at least 41 characters in
+size or a NULL pointer.  In the latter case, space will be dynamically
+allocated via
+.Xr malloc 3
+and should be freed using
+.Xr free 3
+when it is no longer needed.
+.Sh EXAMPLES
+The follow code fragment will calculate the digest for
+the string "abc" which is ``0x8eb208f7e05d987a9b044a8e98c6b087f15a0bfc''.
+.Bd -literal -offset indent
+RMD160_CTX rmd;
+u_char results[20];
+char *buf;
+int n;
+
+buf = "abc";
+n = strlen(buf);
+RMD160Init(&rmd);
+RMD160Update(&rmd, (u_char *)buf, n);
+RMD160Final(results, &rmd);
+
+/* Print the digest as one long hex value */
+printf("0x");
+for (n = 0; n < 20; n++)
+	printf("%x", results[n]);
+putchar('\\n');
+.Ed
+.Pp
+Alternately, the helper functions could be used in the following way:
+.Bd -literal -offset indent
+RMD160_CTX rmd;
+u_char output[41];
+char *buf = "abc";
+
+printf("0x%s", MD5Data(buf, strlen(buf), output));
+.Ed
+.Sh CAVEATS
+If a message digest is to be copied to a multi-byte type (ie:
+an array of five 32-bit integers) it will be necessary to
+perform byte swapping on little endian machines such as the i386, alpha,
+and vax.
+.Sh AUTHOR
+This implementation of RMD-160 was written by Antoon Bosselaers.
+.br
+The
+.Fn RMD160End ,
+.Fn RMD160File ,
+and
+.Fn RMD160Data
+helper functions are derived from code written by Poul-Henning Kamp.
+.Sh SEE ALSO
+.Xr rmd160 1 ,
+.Xr md4 3 ,
+.Xr md5 3 ,
+.Xr sha1 3
+.Pp
+.Rs
+.%A H. Dobbertin, A. Bosselaers, B. Preneel
+.%T RIPEMD-160, a strengthened version of RIPEMD
+.Re
+.Rs
+.%T Information technology - Security techniques - Hash-functions - Part 3: Dedicated hash-functions
+.%O ISO/IEC 10118-3
+.Re
+.Rs
+.%A H. Dobbertin, A. Bosselaers, B. Preneel
+.%T The RIPEMD-160 cryptographic hash function
+.%J Dr. Dobb's Journal
+.%V Vol. 22, No. 1
+.%D January 1997
+.%P pp. 24-28
+.Re
+.Sh HISTORY
+The RMD-160 functions appeared in
+.Bx Open
+2.1.