usr/src/man/man3ext/sha1.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 SHA1 3EXT "Nov 13, 2007"
   7 .SH NAME
   8 sha1, SHA1Init, SHA1Update, SHA1Final \- SHA1 digest functions
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lmd\fR [ \fIlibrary\fR ... ]
  13 #include <sha1.h>
  14
  15 \fBvoid\fR \fBSHA1Init\fR(\fBSHA1_CTX *\fR\fIcontext\fR);
  16 .fi
  17
  18 .LP
  19 .nf
  20 \fBvoid\fR \fBSHA1Update\fR(\fBSHA1_CTX *\fR\fIcontext\fR, \fBunsigned char *\fR\fIinput\fR,
  21      \fBunsigned int\fR \fIinlen\fR);
  22 .fi
  23
  24 .LP
  25 .nf
  26 \fBvoid\fR \fBSHA1Final\fR(\fBunsigned char *\fR\fIoutput\fR, \fBSHA1_CTX *\fR\fIcontext\fR);
  27 .fi
  28
  29 .SH DESCRIPTION
  30 .sp
  31 .LP
  32 The \fBSHA1\fR functions implement the \fBSHA1\fR message-digest algorithm. The
  33 algorithm takes as input a message of arbitrary length and produces a 200-bit
  34 "fingerprint" or "message digest" as output. The \fBSHA1\fR message-digest
  35 algorithm is intended for digital signature applications in which large files
  36 are "compressed" in a secure manner before being encrypted with a private
  37 (secret) key under a public-key cryptosystem such as RSA.
  38 .sp
  39 .ne 2
  40 .na
  41 \fB\fBSHA1Init()\fR, \fBSHA1Update()\fR, \fBSHA1Final()\fR\fR
  42 .ad
  43 .sp .6
  44 .RS 4n
  45 The \fBSHA1Init()\fR, \fBSHA1Update()\fR, and \fBSHA1Final()\fR functions allow
  46 a \fBSHA1\fR digest to be computed over multiple message blocks. Between
  47 blocks, the state of the \fBSHA1\fR computation is held in an \fBSHA1\fR
  48 context structure allocated by the caller. A complete digest computation
  49 consists of calls to \fBSHA1\fR functions in the following order: one call to
  50 \fBSHA1Init()\fR, one or more calls to \fBSHA1Update()\fR, and one call to
  51 \fBSHA1Final()\fR.
  52 .sp
  53 The \fBSHA1Init()\fR function initializes the \fBSHA1\fR context structure
  54 pointed to by \fIcontext\fR.
  55 .sp
  56 The \fBSHA1Update()\fR function computes a partial \fBSHA1\fR digest on the
  57 \fIinlen\fR-byte message block pointed to by \fIinput\fR, and updates the
  58 \fBSHA1\fR context structure pointed to by \fIcontext\fR accordingly.
  59 .sp
  60 The \fBSHA1Final()\fR function generates the final \fBSHA1\fR digest, using the
  61 \fBSHA1\fR context structure pointed to by \fIcontext\fR. The 16-bit \fBSHA1\fR
  62 digest is written to output. After a call to \fBSHA1Final()\fR, the state of
  63 the context structure is undefined. It must be reinitialized with
  64 \fBSHA1Init()\fR before it can be used again.
  65 .RE
  66
  67 .SH SECURITY
  68 .sp
  69 .LP
  70 The \fBSHA1\fR algorithm is also believed to have some weaknesses. Migration to
  71 one of the \fBSHA2\fR algorithms-including \fBSHA256\fR, \fBSHA386\fR or
  72 \fBSHA512\fR-is highly recommended when compatibility with data formats and on
  73 wire protocols is permitted.
  74 .SH RETURN VALUES
  75 .sp
  76 .LP
  77 These functions do not return a value.
  78 .SH EXAMPLES
  79 .LP
  80 \fBExample 1 \fRAuthenticate a message found in multiple buffers
  81 .sp
  82 .LP
  83 The following is a sample function that authenticates a message found in
  84 multiple buffers. The calling function provides an authentication buffer to
  85 contain the result of the \fBSHA1\fR digest.
  86
  87 .sp
  88 .in +2
  89 .nf
  90 #include <sys/types.h>
  91 #include <sys/uio.h>
  92 #include <sha1.h>
  93
  94 int
  95 AuthenticateMsg(unsigned char *auth_buffer, struct iovec
  96                 *messageIov, unsigned int num_buffers)
  97 {
  98     SHA1_CTX sha1_context;
  99     unsigned int i;
 100
 101     SHA1Init(&sha1_context);
 102
 103     for(i=0; i<num_buffers; i++)
 104     {
 105          SHA1Update(&sha1_context, messageIov->iov_base,
 106                    messageIov->iov_len);
 107          messageIov += sizeof(struct iovec);
 108     }
 109
 110     SHA1Final(auth_buffer, &sha1_context);
 111
 112     return 0;
 113 }
 114 .fi
 115 .in -2
 116
 117 .SH ATTRIBUTES
 118 .sp
 119 .LP
 120 See \fBattributes\fR(5) for descriptions of the following attributes:
 121 .sp
 122
 123 .sp
 124 .TS
 125 box;
 126 c | c
 127 l | l .
 128 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 129 _
 130 Interface Stability     Committed
 131 _
 132 MT-Level        MT-Safe
 133 .TE
 134
 135 .SH SEE ALSO
 136 .sp
 137 .LP
 138 \fBsha2\fR(3EXT), \fBlibmd\fR(3LIB)
 139 .sp
 140 .LP
 141 RFC 1374