lib/libcrypto/man/SHA1.3

   1 .\"     $OpenBSD: SHA1.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $
   2 .\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
   3 .\"
   4 .\" This file was written by Ulf Moeller <ulf@openssl.org> and
   5 .\" Matt Caswell <matt@openssl.org>.
   6 .\" Copyright (c) 2000, 2006, 2015 The OpenSSL Project.  All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in
  17 .\"    the documentation and/or other materials provided with the
  18 .\"    distribution.
  19 .\"
  20 .\" 3. All advertising materials mentioning features or use of this
  21 .\"    software must display the following acknowledgment:
  22 .\"    "This product includes software developed by the OpenSSL Project
  23 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  24 .\"
  25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  26 .\"    endorse or promote products derived from this software without
  27 .\"    prior written permission. For written permission, please contact
  28 .\"    openssl-core@openssl.org.
  29 .\"
  30 .\" 5. Products derived from this software may not be called "OpenSSL"
  31 .\"    nor may "OpenSSL" appear in their names without prior written
  32 .\"    permission of the OpenSSL Project.
  33 .\"
  34 .\" 6. Redistributions of any form whatsoever must retain the following
  35 .\"    acknowledgment:
  36 .\"    "This product includes software developed by the OpenSSL Project
  37 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  38 .\"
  39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  42 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  51 .\"
  52 .Dd $Mdocdate: March 27 2018 $
  53 .Dt SHA1 3
  54 .Os
  55 .Sh NAME
  56 .Nm SHA1 ,
  57 .Nm SHA1_Init ,
  58 .Nm SHA1_Update ,
  59 .Nm SHA1_Final ,
  60 .Nm SHA224 ,
  61 .Nm SHA224_Init ,
  62 .Nm SHA224_Update ,
  63 .Nm SHA224_Final ,
  64 .Nm SHA256 ,
  65 .Nm SHA256_Init ,
  66 .Nm SHA256_Update ,
  67 .Nm SHA256_Final ,
  68 .Nm SHA384 ,
  69 .Nm SHA384_Init ,
  70 .Nm SHA384_Update ,
  71 .Nm SHA384_Final ,
  72 .Nm SHA512 ,
  73 .Nm SHA512_Init ,
  74 .Nm SHA512_Update ,
  75 .Nm SHA512_Final
  76 .Nd Secure Hash Algorithm
  77 .Sh SYNOPSIS
  78 .In openssl/sha.h
  79 .Ft unsigned char *
  80 .Fo SHA1
  81 .Fa "const unsigned char *d"
  82 .Fa "size_t n"
  83 .Fa "unsigned char *md"
  84 .Fc
  85 .Ft int
  86 .Fo SHA1_Init
  87 .Fa "SHA_CTX *c"
  88 .Fc
  89 .Ft int
  90 .Fo SHA1_Update
  91 .Fa "SHA_CTX *c"
  92 .Fa "const void *data"
  93 .Fa "size_t len"
  94 .Fc
  95 .Ft int
  96 .Fo SHA1_Final
  97 .Fa "unsigned char *md"
  98 .Fa "SHA_CTX *c"
  99 .Fc
 100 .Ft unsigned char *
 101 .Fo SHA224
 102 .Fa "const unsigned char *d"
 103 .Fa "size_t n"
 104 .Fa "unsigned char *md"
 105 .Fc
 106 .Ft int
 107 .Fo SHA224_Init
 108 .Fa "SHA256_CTX *c"
 109 .Fc
 110 .Ft int
 111 .Fo SHA224_Update
 112 .Fa "SHA256_CTX *c"
 113 .Fa "const void *data"
 114 .Fa "size_t len"
 115 .Fc
 116 .Ft int
 117 .Fo SHA224_Final
 118 .Fa "unsigned char *md"
 119 .Fa "SHA256_CTX *c"
 120 .Fc
 121 .Ft unsigned char *
 122 .Fo SHA256
 123 .Fa "const unsigned char *d"
 124 .Fa "size_t n"
 125 .Fa "unsigned char *md"
 126 .Fc
 127 .Ft int
 128 .Fo SHA256_Init
 129 .Fa "SHA256_CTX *c"
 130 .Fc
 131 .Ft int
 132 .Fo SHA256_Update
 133 .Fa "SHA256_CTX *c"
 134 .Fa "const void *data"
 135 .Fa "size_t len"
 136 .Fc
 137 .Ft int
 138 .Fo SHA256_Final
 139 .Fa "unsigned char *md"
 140 .Fa "SHA256_CTX *c"
 141 .Fc
 142 .Ft unsigned char *
 143 .Fo SHA384
 144 .Fa "const unsigned char *d"
 145 .Fa "size_t n"
 146 .Fa "unsigned char *md"
 147 .Fc
 148 .Ft int
 149 .Fo SHA384_Init
 150 .Fa "SHA512_CTX *c"
 151 .Fc
 152 .Ft int
 153 .Fo SHA384_Update
 154 .Fa "SHA512_CTX *c"
 155 .Fa "const void *data"
 156 .Fa "size_t len"
 157 .Fc
 158 .Ft int
 159 .Fo SHA384_Final
 160 .Fa "unsigned char *md"
 161 .Fa "SHA512_CTX *c"
 162 .Fc
 163 .Ft unsigned char *
 164 .Fo SHA512
 165 .Fa "const unsigned char *d"
 166 .Fa "size_t n"
 167 .Fa "unsigned char *md"
 168 .Fc
 169 .Ft int
 170 .Fo SHA512_Init
 171 .Fa "SHA512_CTX *c"
 172 .Fc
 173 .Ft int
 174 .Fo SHA512_Update
 175 .Fa "SHA512_CTX *c"
 176 .Fa "const void *data"
 177 .Fa "size_t len"
 178 .Fc
 179 .Ft int
 180 .Fo SHA512_Final
 181 .Fa "unsigned char *md"
 182 .Fa "SHA512_CTX *c"
 183 .Fc
 184 .Sh DESCRIPTION
 185 SHA-1 (Secure Hash Algorithm) is a cryptographic hash function with a
 186 160-bit output.
 187 .Pp
 188 .Fn SHA1
 189 computes the SHA-1 message digest of the
 190 .Fa n
 191 bytes at
 192 .Fa d
 193 and places it in
 194 .Fa md ,
 195 which must have space for
 196 .Dv SHA_DIGEST_LENGTH
 197 == 20 bytes of output.
 198 If
 199 .Fa md
 200 is
 201 .Dv NULL ,
 202 the digest is placed in a static array, which is not thread safe.
 203 .Pp
 204 The following functions may be used if the message is not completely
 205 stored in memory:
 206 .Pp
 207 .Fn SHA1_Init
 208 initializes a
 209 .Vt SHA_CTX
 210 structure.
 211 .Pp
 212 .Fn SHA1_Update
 213 can be called repeatedly with chunks of the message to be hashed
 214 .Pq Fa len No bytes at Fa data .
 215 .Pp
 216 .Fn SHA1_Final
 217 places the message digest in
 218 .Fa md ,
 219 which must have space for
 220 .Dv SHA_DIGEST_LENGTH
 221 == 20 bytes of output, and erases the
 222 .Vt SHA_CTX .
 223 .Pp
 224 The SHA224, SHA256, SHA384, and SHA512 families of functions operate
 225 in the same way as the SHA1 functions.
 226 Note that SHA224 and SHA256 use a
 227 .Vt SHA256_CTX
 228 object instead of
 229 .Vt SHA_CTX ,
 230 and SHA384 and SHA512 use
 231 .Vt SHA512_CTX .
 232 The buffer
 233 .Fa md
 234 must have space for the output from the SHA variant being used:
 235 .Dv SHA224_DIGEST_LENGTH ,
 236 .Dv SHA256_DIGEST_LENGTH ,
 237 .Dv SHA384_DIGEST_LENGTH ,
 238 or
 239 .Dv SHA512_DIGEST_LENGTH
 240 bytes.
 241 .Pp
 242 Applications should use the higher level functions
 243 .Xr EVP_DigestInit 3
 244 etc.  instead of calling the hash functions directly.
 245 .Pp
 246 The predecessor of SHA-1, SHA, is also implemented, but it should be
 247 used only when backward compatibility is required.
 248 .Sh RETURN VALUES
 249 .Fn SHA1 ,
 250 .Fn SHA224 ,
 251 .Fn SHA256 ,
 252 .Fn SHA384 ,
 253 and
 254 .Fn SHA512
 255 return a pointer to the hash value.
 256 The other functions return 1 for success or 0 otherwise.
 257 .Sh SEE ALSO
 258 .Xr EVP_DigestInit 3 ,
 259 .Xr HMAC 3 ,
 260 .Xr RIPEMD160 3
 261 .Sh STANDARDS
 262 SHA: US Federal Information Processing Standard FIPS PUB 180 (Secure
 263 Hash Standard), SHA-1: US Federal Information Processing Standard FIPS
 264 PUB 180-1 (Secure Hash Standard), ANSI X9.30
 265 .Sh HISTORY
 266 .Fn SHA1 ,
 267 .Fn SHA1_Init ,
 268 .Fn SHA1_Update ,
 269 and
 270 .Fn SHA1_Final
 271 first appeared in SSLeay 0.5.1 and have been available since
 272 .Ox 2.4 .
 273 .Pp
 274 The other functions first appeared in OpenSSL 0.9.8
 275 and have been available since
 276 .Ox 4.5 .