b6cbf7203b
This patch imports the unmodified current version of NetBSD libc. The NetBSD includes are in /nbsd_include, while the libc code itself is split between lib/nbsd_libc and common/lib/libc.
305 lines
8.5 KiB
Groff
305 lines
8.5 KiB
Groff
.\" $NetBSD: sha2.3,v 1.5 2009/05/26 08:04:12 joerg Exp $
|
|
.\" $OpenBSD: sha2.3,v 1.11 2004/06/22 01:57:29 jfb Exp $
|
|
.\"
|
|
.\" Copyright (c) 2003, 2004 Todd C. Miller <Todd.Miller@courtesan.com>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" Sponsored in part by the Defense Advanced Research Projects
|
|
.\" Agency (DARPA) and Air Force Research Laboratory, Air Force
|
|
.\" Materiel Command, USAF, under agreement number F39502-99-1-0512.
|
|
.\"
|
|
.\" See http://www.nist.gov/sha/ for the detailed standard
|
|
.\"
|
|
.Dd May 20, 2009
|
|
.Dt SHA2 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm SHA256_Init ,
|
|
.Nm SHA256_Update ,
|
|
.Nm SHA256_Pad ,
|
|
.Nm SHA256_Final ,
|
|
.Nm SHA256_Transform ,
|
|
.Nm SHA256_End ,
|
|
.Nm SHA256_File ,
|
|
.Nm SHA256_FileChunk ,
|
|
.Nm SHA256_Data
|
|
.Nd calculate the NIST Secure Hash Standard (version 2)
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sha2.h
|
|
.Ft void
|
|
.Fn SHA224_Init "SHA224_CTX *context"
|
|
.Ft void
|
|
.Fn SHA224_Update "SHA224_CTX *context" "const uint8_t *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA224_Pad "SHA224_CTX *context"
|
|
.Ft void
|
|
.Fn SHA224_Final "uint8_t digest[SHA224_DIGEST_LENGTH]" "SHA224_CTX *context"
|
|
.Ft void
|
|
.Fn SHA224_Transform "uint32_t state[8]" "const uint8_t buffer[SHA224_BLOCK_LENGTH]"
|
|
.Ft "char *"
|
|
.Fn SHA224_End "SHA224_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA224_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA224_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA224_Data "uint8_t *data" "size_t len" "char *buf"
|
|
.Ft void
|
|
.Fn SHA256_Init "SHA256_CTX *context"
|
|
.Ft void
|
|
.Fn SHA256_Update "SHA256_CTX *context" "const uint8_t *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA256_Pad "SHA256_CTX *context"
|
|
.Ft void
|
|
.Fn SHA256_Final "uint8_t digest[SHA256_DIGEST_LENGTH]" "SHA256_CTX *context"
|
|
.Ft void
|
|
.Fn SHA256_Transform "uint32_t state[8]" "const uint8_t buffer[SHA256_BLOCK_LENGTH]"
|
|
.Ft "char *"
|
|
.Fn SHA256_End "SHA256_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA256_File "const char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA256_FileChunk "const char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA256_Data "uint8_t *data" "size_t len" "char *buf"
|
|
.Ft void
|
|
.Fn SHA384_Init "SHA384_CTX *context"
|
|
.Ft void
|
|
.Fn SHA384_Update "SHA384_CTX *context" "const uint8_t *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA384_Pad "SHA384_CTX *context"
|
|
.Ft void
|
|
.Fn SHA384_Final "uint8_t digest[SHA384_DIGEST_LENGTH]" "SHA384_CTX *context"
|
|
.Ft void
|
|
.Fn SHA384_Transform "uint64_t state[8]" "const uint8_t buffer[SHA384_BLOCK_LENGTH]"
|
|
.Ft "char *"
|
|
.Fn SHA384_End "SHA384_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA384_File "char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA384_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA384_Data "uint8_t *data" "size_t len" "char *buf"
|
|
.Ft void
|
|
.Fn SHA512_Init "SHA512_CTX *context"
|
|
.Ft void
|
|
.Fn SHA512_Update "SHA512_CTX *context" "const uint8_t *data" "size_t len"
|
|
.Ft void
|
|
.Fn SHA512_Pad "SHA512_CTX *context"
|
|
.Ft void
|
|
.Fn SHA512_Final "uint8_t digest[SHA512_DIGEST_LENGTH]" "SHA512_CTX *context"
|
|
.Ft void
|
|
.Fn SHA512_Transform "uint64_t state[8]" "const uint8_t buffer[SHA512_BLOCK_LENGTH]"
|
|
.Ft "char *"
|
|
.Fn SHA512_End "SHA512_CTX *context" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_File "char *filename" "char *buf"
|
|
.Ft "char *"
|
|
.Fn SHA512_FileChunk "char *filename" "char *buf" "off_t offset" "off_t length"
|
|
.Ft "char *"
|
|
.Fn SHA512_Data "uint8_t *data" "size_t len" "char *buf"
|
|
.Sh DESCRIPTION
|
|
The SHA2 functions implement the NIST Secure Hash Standard,
|
|
FIPS PUB 180-2.
|
|
The SHA2 functions are used to generate a condensed representation of a
|
|
message called a message digest, suitable for use as a digital signature.
|
|
There are four families of functions, with names corresponding to
|
|
the number of bits in the resulting message digest.
|
|
The SHA-224 and SHA-256 functions are limited to processing a message of less
|
|
than 2^64 bits as input.
|
|
The SHA-384 and SHA-512 functions can process a message of at most 2^128 - 1
|
|
bits as input.
|
|
.Pp
|
|
The SHA2 functions are considered to be more secure than the
|
|
.Xr sha1 3
|
|
functions with which they share a similar interface.
|
|
The 224, 256, 384, and 512-bit versions of SHA2 share the same interface.
|
|
For brevity, only the 256-bit variants are described below.
|
|
.Pp
|
|
The
|
|
.Fn SHA256_Init
|
|
function initializes a SHA256_CTX
|
|
.Ar context
|
|
for use with
|
|
.Fn SHA256_Update ,
|
|
and
|
|
.Fn SHA256_Final .
|
|
The
|
|
.Fn SHA256_Update
|
|
function adds
|
|
.Ar data
|
|
of length
|
|
.Ar len
|
|
to the SHA256_CTX specified by
|
|
.Ar context .
|
|
.Fn SHA256_Final
|
|
is called when all data has been added via
|
|
.Fn SHA256_Update
|
|
and stores a message digest in the
|
|
.Ar digest
|
|
parameter.
|
|
.Pp
|
|
The
|
|
.Fn SHA256_Pad
|
|
function can be used to apply padding to the message digest as in
|
|
.Fn SHA256_Final ,
|
|
but the current context can still be used with
|
|
.Fn SHA256_Update .
|
|
.Pp
|
|
The
|
|
.Fn SHA256_Transform
|
|
function is used by
|
|
.Fn SHA256_Update
|
|
to hash 512-bit blocks and forms the core of the algorithm.
|
|
Most programs should use the interface provided by
|
|
.Fn SHA256_Init ,
|
|
.Fn SHA256_Update ,
|
|
and
|
|
.Fn SHA256_Final
|
|
instead of calling
|
|
.Fn SHA256_Transform
|
|
directly.
|
|
.Pp
|
|
The
|
|
.Fn SHA256_End
|
|
function is a front end for
|
|
.Fn SHA256_Final
|
|
which converts the digest into an
|
|
.Tn ASCII
|
|
representation of the digest in hexadecimal.
|
|
.Pp
|
|
The
|
|
.Fn SHA256_File
|
|
function calculates the digest for a file and returns the result via
|
|
.Fn SHA256_End .
|
|
If
|
|
.Fn SHA256_File
|
|
is unable to open the file, a
|
|
.Dv NULL
|
|
pointer is returned.
|
|
.Pp
|
|
.Fn SHA256_FileChunk
|
|
behaves like
|
|
.Fn SHA256_File
|
|
but calculates the digest only for that portion of the file starting at
|
|
.Fa offset
|
|
and continuing for
|
|
.Fa length
|
|
bytes or until end of file is reached, whichever comes first.
|
|
A zero
|
|
.Fa length
|
|
can be specified to read until end of file.
|
|
A negative
|
|
.Fa length
|
|
or
|
|
.Fa offset
|
|
will be ignored.
|
|
.Pp
|
|
The
|
|
.Fn SHA256_Data
|
|
function
|
|
calculates the digest of an arbitrary string and returns the result via
|
|
.Fn SHA256_End .
|
|
.Pp
|
|
For each of the
|
|
.Fn SHA256_End ,
|
|
.Fn SHA256_File ,
|
|
.Fn SHA256_FileChunk ,
|
|
and
|
|
.Fn SHA256_Data
|
|
functions the
|
|
.Ar buf
|
|
parameter should either be a string large enough to hold the resulting digest
|
|
(e.g.,
|
|
.Ev SHA224_DIGEST_STRING_LENGTH ,
|
|
.Ev SHA256_DIGEST_STRING_LENGTH ,
|
|
.Ev SHA384_DIGEST_STRING_LENGTH ,
|
|
or
|
|
.Ev SHA512_DIGEST_STRING_LENGTH ,
|
|
depending on the function being used)
|
|
or a
|
|
.Dv 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 following code fragment will calculate the SHA-256 digest for the string
|
|
.Qq abc ,
|
|
which is
|
|
.Dq 0xba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad .
|
|
.Bd -literal -offset indent
|
|
SHA256_CTX ctx;
|
|
uint8_t results[SHA256_DIGEST_LENGTH];
|
|
char *buf;
|
|
int n;
|
|
|
|
buf = "abc";
|
|
n = strlen(buf);
|
|
SHA256_Init(\*[Am]ctx);
|
|
SHA256_Update(\*[Am]ctx, (uint8_t *)buf, n);
|
|
SHA256_Final(results, \*[Am]ctx);
|
|
|
|
/* Print the digest as one long hex value */
|
|
printf("0x");
|
|
for (n = 0; n \*[Lt] SHA256_DIGEST_LENGTH; n++)
|
|
printf("%02x", results[n]);
|
|
putchar('\en');
|
|
.Ed
|
|
.Pp
|
|
Alternately, the helper functions could be used in the following way:
|
|
.Bd -literal -offset indent
|
|
SHA256_CTX ctx;
|
|
uint8_t output[SHA256_DIGEST_STRING_LENGTH];
|
|
char *buf = "abc";
|
|
|
|
printf("0x%s\en", SHA256_Data(buf, strlen(buf), output));
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr cksum 1 ,
|
|
.Xr md4 3 ,
|
|
.Xr md5 3 ,
|
|
.Xr rmd160 3 ,
|
|
.Xr sha1 3
|
|
.Rs
|
|
.%T Secure Hash Standard
|
|
.%O FIPS PUB 180-2
|
|
.Re
|
|
.Sh HISTORY
|
|
The SHA2 functions appeared in
|
|
.Ox 3.4
|
|
and
|
|
.Nx 3.0 .
|
|
.Sh AUTHORS
|
|
This implementation of the SHA functions was written by Aaron D. Gifford.
|
|
.Pp
|
|
The
|
|
.Fn SHA256_End ,
|
|
.Fn SHA256_File ,
|
|
.Fn SHA256_FileChunk ,
|
|
and
|
|
.Fn SHA256_Data
|
|
helper functions are derived from code written by Poul-Henning Kamp.
|
|
.Sh CAVEATS
|
|
This implementation of the Secure Hash Standard has not been validated by
|
|
NIST and as such is not in official compliance with the standard.
|
|
.Pp
|
|
If a message digest is to be copied to a multi-byte type (i.e.:
|
|
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.
|