usr/src/man/man3ext/md5.3ext

   1 '\" te
   2 .\"  Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH MD5 3EXT "Nov 13, 2007"
   7 .SH NAME
   8 md5, md5_calc, MD5Init, MD5Update, MD5Final \- MD5 digest functions
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lmd5\fR [ \fIlibrary\fR ... ]
  13 #include <md5.h>
  14
  15 \fBvoid\fR \fBmd5_calc\fR(\fBunsigned char *\fR\fIoutput\fR, \fBunsigned char *\fR\fIinput\fR,
  16      \fBunsigned int\fR \fIinlen\fR);
  17 .fi
  18
  19 .LP
  20 .nf
  21 \fBvoid\fR \fBMD5Init\fR(\fBMD5_CTX *\fR\fIcontext\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBvoid\fR \fBMD5Update\fR(\fBMD5_CTX *\fR\fIcontext\fR, \fBunsigned char *\fR\fIinput\fR,
  27      \fBunsigned int\fR \fIinlen\fR);
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBvoid\fR \fBMD5Final\fR(\fBunsigned char *\fR\fIoutput\fR, \fBMD5_CTX *\fR\fIcontext\fR);
  33 .fi
  34
  35 .SH DESCRIPTION
  36 .sp
  37 .LP
  38 These functions implement the MD5 message-digest algorithm, which takes as
  39 input a message of arbitrary length and produces as output a 128-bit
  40 "fingerprint" or "message digest" of the input. It is intended for digital
  41 signature applications, where large file must be "compressed" in a secure
  42 manner before being encrypted with a private (secret) key under a public-key
  43 cryptosystem such as RSA.
  44 .SS "\fBmd5_calc()\fR"
  45 .sp
  46 .LP
  47 The \fBmd5_calc()\fR function computes an MD5 digest on a single message block.
  48 The \fIinlen\fR-byte block is pointed to by \fIinput\fR, and the 16-byte MD5
  49 digest is written to \fIoutput\fR.
  50 .SS "\fBMD5Init()\fR, \fBMD5Update()\fR, \fBMD5Final()\fR"
  51 .sp
  52 .LP
  53 The \fBMD5Init()\fR, \fBMD5Update()\fR, and \fBMD5Final()\fR functions allow an
  54 MD5 digest to be computed over multiple message blocks; between blocks, the
  55 state of the MD5 computation is held in an MD5 context structure, allocated by
  56 the caller. A complete digest computation consists of one call to
  57 \fBMD5Init()\fR, one or more calls to \fBMD5Update()\fR, and one call to
  58 \fBMD5Final()\fR, in that order.
  59 .sp
  60 .LP
  61 The \fBMD5Init()\fR function initializes the MD5 context structure pointed to
  62 by \fIcontext\fR.
  63 .sp
  64 .LP
  65 The \fBMD5Update()\fR function computes a partial MD5 digest on the
  66 \fIinlen\fR-byte message block pointed to by \fIinput\fR, and updates the MD5
  67 context structure pointed to by \fIcontext\fR accordingly.
  68 .sp
  69 .LP
  70 The \fBMD5Final()\fR function generates the final MD5 digest, using the MD5
  71 context structure pointed to by \fIcontext\fR; the 16-byte MD5 digest is
  72 written to \fIoutput\fR. After calling \fBMD5Final()\fR, the state of the
  73 context structure is undefined; it must be reinitialized with \fBMD5Init()\fR
  74 before being used again.
  75 .SH RETURN VALUES
  76 .sp
  77 .LP
  78 These functions do not return a value.
  79 .SH EXAMPLES
  80 .LP
  81 \fBExample 1 \fRAuthenticate a message found in multiple buffers
  82 .sp
  83 .LP
  84 The following is a sample function that must authenticate a message that is
  85 found in multiple buffers. The calling function provides an authentication
  86 buffer that will contain the result of the MD5 digest.
  87
  88 .sp
  89 .in +2
  90 .nf
  91 #include <sys/types.h>
  92 #include <sys/uio.h>
  93 #include <md5.h>
  94
  95 int
  96 AuthenticateMsg(unsigned char *auth_buffer, struct iovec
  97                 *messageIov, unsigned int num_buffers)
  98 {
  99     MD5_CTX md5_context;
 100     unsigned int i;
 101
 102     MD5Init(&md5_context);
 103
 104     for(i=0; i<num_buffers; i++)
 105     {
 106          MD5Update(&md5_context, messageIov->iov_base,
 107                    messageIov->iov_len);
 108          messageIov += sizeof(struct iovec);
 109     }
 110
 111     MD5Final(auth_buffer, &md5_context);
 112
 113     return 0;
 114 }
 115 .fi
 116 .in -2
 117
 118 .LP
 119 \fBExample 2 \fRUse \fBmd5_calc()\fR to generate the MD5 digest
 120 .sp
 121 .LP
 122 Since the buffer to be computed is contiguous, the \fBmd5_calc()\fR function
 123 can be used to generate the MD5 digest.
 124
 125 .sp
 126 .in +2
 127 .nf
 128 int AuthenticateMsg(unsigned char *auth_buffer, unsigned
 129                     char *buffer, unsigned int length)
 130 {
 131     md5_calc(buffer, auth_buffer, length);
 132
 133     return (0);
 134 }
 135 .fi
 136 .in -2
 137
 138 .SH ATTRIBUTES
 139 .sp
 140 .LP
 141 See \fBattributes\fR(5) for descriptions of the following attributes:
 142 .sp
 143
 144 .sp
 145 .TS
 146 box;
 147 c | c
 148 l | l .
 149 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 150 _
 151 Interface Stability     Committed
 152 _
 153 MT-Level        MT-Safe
 154 .TE
 155
 156 .SH SEE ALSO
 157 .sp
 158 .LP
 159 \fBlibmd5\fR(3LIB)
 160 .sp
 161 .LP
 162 Rivest, R., The MD5 Message-Digest Algorithm, RFC 1321, April 1992.