Module Name: src
Committed By: wiz
Date: Thu Nov 30 16:00:48 UTC 2017
Modified Files:
src/lib/libc/hash/sha3: Makefile.inc
Added Files:
src/lib/libc/hash/sha3: SHA3_Selftest.3 SHAKE.3 keccak.3 sha3.3
Log Message:
Add riastradh's man pages for sha3 and friends.
Commented out since the symbols themselves are not yet public.
To generate a diff of this commit:
cvs rdiff -u -r1.1 -r1.2 src/lib/libc/hash/sha3/Makefile.inc
cvs rdiff -u -r0 -r1.1 src/lib/libc/hash/sha3/SHA3_Selftest.3 \
src/lib/libc/hash/sha3/SHAKE.3 src/lib/libc/hash/sha3/keccak.3 \
src/lib/libc/hash/sha3/sha3.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libc/hash/sha3/Makefile.inc
diff -u src/lib/libc/hash/sha3/Makefile.inc:1.1 src/lib/libc/hash/sha3/Makefile.inc:1.2
--- src/lib/libc/hash/sha3/Makefile.inc:1.1 Thu Nov 30 05:47:24 2017
+++ src/lib/libc/hash/sha3/Makefile.inc Thu Nov 30 16:00:48 2017
@@ -1,11 +1,11 @@
-# $NetBSD: Makefile.inc,v 1.1 2017/11/30 05:47:24 riastradh Exp $
+# $NetBSD: Makefile.inc,v 1.2 2017/11/30 16:00:48 wiz Exp $
.PATH: ${.CURDIR}/hash/sha3
SRCS+= keccak.c sha3.c
# XXX not (yet) public
-#MAN+= sha3.3
+#MAN+= SHA3_Selftest.3 SHAKE.3 keccak.3 sha3.3
#MLINKS+=sha3.3 SHA3_224_Init.3 sha3.3 SHA3_224_Update.3 sha3.3 SHA3_224_Final.3
#MLINKS+=sha3.3 SHA3_256_Init.3 sha3.3 SHA3_256_Update.3 sha3.3 SHA3_256_Final.3
@@ -13,4 +13,3 @@ SRCS+= keccak.c sha3.c
#MLINKS+=sha3.3 SHA3_512_Init.3 sha3.3 SHA3_512_Update.3 sha3.3 SHA3_512_Final.3
#MLINKS+=sha3.3 SHAKE128_Init.3 sha3.3 SHAKE128_Update.3 sha3.3 SHAKE128_Final.3
#MLINKS+=sha3.3 SHAKE256_Init.3 sha3.3 SHAKE256_Update.3 sha3.3 SHAKE256_Final.3
-#MLINKS+=sha3.3 SHA3_Selftest.3
Added files:
Index: src/lib/libc/hash/sha3/SHA3_Selftest.3
diff -u /dev/null src/lib/libc/hash/sha3/SHA3_Selftest.3:1.1
--- /dev/null Thu Nov 30 16:00:48 2017
+++ src/lib/libc/hash/sha3/SHA3_Selftest.3 Thu Nov 30 16:00:48 2017
@@ -0,0 +1,73 @@
+.\" $NetBSD: SHA3_Selftest.3,v 1.1 2017/11/30 16:00:48 wiz Exp $
+.\"
+.\" Copyright (c) 2015 Taylor R. Campbell
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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.
+.\"
+.Dd October 14, 2015
+.Dt SHA3_SELFTEST 3
+.Os
+.Sh NAME
+.Nm SHA3_Selftest
+.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.Sh SYNOPSIS
+.In sha3.h
+.Ft int
+.Fn SHA3_Selftest "void"
+.Sh DESCRIPTION
+The
+.Nm
+function automatically tests a number of SHA-3 computations on fixed
+inputs with with known outputs to make sure the
+.Xr sha3 3
+library is not catastrophically broken.
+Applications should call
+.Fn SHA3_Selftest
+and confirm that it succeeded before using the
+.Xr sha3 3 ,
+.Xr SHAKE 3 ,
+or
+.Xr keccak 3
+functions.
+.Pp
+.Fn SHA3_Selftest
+returns 0 if successful, or -1 if the self-test failed.
+.Pp
+The
+.Fn SHA3_Selftest
+function costs a few hundred thousand cycles on most CPUs, since it
+involves a little over a hundred calls to the Keccak permutation,
+which usually take one or two thousand cycles each.
+.Sh SEE ALSO
+.Xr keccak 3 ,
+.Xr sha3 3 ,
+.Xr SHAKE 3
+.Sh STANDARDS
+.Rs
+.%A National Institute of Standards and Technology
+.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.%O FIPS PUB 202
+.%D August 2015
+.Re
+.Sh AUTHORS
+.An Taylor R Campbell Aq campbell+s...@mumble.net
Index: src/lib/libc/hash/sha3/SHAKE.3
diff -u /dev/null src/lib/libc/hash/sha3/SHAKE.3:1.1
--- /dev/null Thu Nov 30 16:00:48 2017
+++ src/lib/libc/hash/sha3/SHAKE.3 Thu Nov 30 16:00:48 2017
@@ -0,0 +1,114 @@
+.\" $NetBSD: SHAKE.3,v 1.1 2017/11/30 16:00:48 wiz Exp $
+.\"
+.\" Copyright (c) 2015 Taylor R. Campbell
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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.
+.\"
+.Dd October 14, 2015
+.Dt SHAKE 3
+.Os
+.Sh NAME
+.Nm SHAKE
+.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.Sh SYNOPSIS
+.In sha3.h
+.Ft void
+.Fn SHAKE128_Init "SHAKE128_CTX *ctx"
+.Ft void
+.Fn SHAKE128_Update "SHAKE128_CTX *ctx" "const uint8_t *buf" "size_t len"
+.Ft void
+.Fn SHAKE128_Final "uint8_t *output[]" "size_t outlen" "SHAKE128_CTX *ctx"
+.Ft void
+.Fn SHAKE256_Init "SHAKE256_CTX *ctx"
+.Ft void
+.Fn SHAKE256_Update "SHAKE256_CTX *ctx" "const uint8_t *buf" "size_t len"
+.Ft void
+.Fn SHAKE256_Final "uint8_t *output[]" "size_t outlen" "SHAKE256_CTX *ctx"
+.Sh DESCRIPTION
+The
+.Nm
+functions implement the extendable-output functions of the NIST SHA-3
+standard, FIPS PUB 202.
+The
+.Nm
+functions absorb an arbitrary-length message m and yield an
+arbitrary-length output SHAKE128(m) or SHAKE256(m), truncated to a
+specified number of octets.
+.Pp
+Before using the
+.Nm
+functions, applications should first call
+.Xr SHA3_Selftest 3
+and confirm that it succeeded.
+.Pp
+Only the
+.Nm SHAKE128
+functions are specified in detail; the
+.Nm SHAKE256
+functions are analogous.
+.Pp
+The caller must allocate memory for a
+.Vt SHAKE128_CTX
+object to hold the state of a SHAKE128 computation over a message.
+.Vt SHAKE128_CTX
+objects may be copied or relocated in memory.
+.Bl -tag -width abcd
+.It Fn SHAKE128_Init "ctx"
+Initialize a SHAKE128 context.
+Must be done before any other operations on
+.Fa ctx .
+.It Fn SHAKE128_Update "ctx" "data" "len"
+Append
+.Fa len
+octets at
+.Fa data
+to the message.
+.It Fn SHAKE128_Final "output" "outlen" "ctx"
+Store at
+.Fa output
+the first
+.Fa outlen
+octets of the SHAKE128 output for the message obtained by concatenating
+all prior inputs to
+.Fn SHAKE128_Update
+on
+.Fa ctx .
+.Pp
+Subsequent use of
+.Fa ctx
+is not allowed, unless it is reinitialized with
+.Fn SHAKE128_Init .
+.El
+.Sh SEE ALSO
+.Xr keccak 3 ,
+.Xr sha3 3 ,
+.Xr SHA3_Selftest 3
+.Sh STANDARDS
+.Rs
+.%A National Institute of Standards and Technology
+.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.%O FIPS PUB 202
+.%D August 2015
+.Re
+.Sh AUTHORS
+.An Taylor R Campbell Aq campbell+s...@mumble.net
Index: src/lib/libc/hash/sha3/keccak.3
diff -u /dev/null src/lib/libc/hash/sha3/keccak.3:1.1
--- /dev/null Thu Nov 30 16:00:48 2017
+++ src/lib/libc/hash/sha3/keccak.3 Thu Nov 30 16:00:48 2017
@@ -0,0 +1,74 @@
+.\" $NetBSD: keccak.3,v 1.1 2017/11/30 16:00:48 wiz Exp $
+.\"
+.\" Copyright (c) 2015 Taylor R. Campbell
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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.
+.\"
+.Dd October 14, 2015
+.Dt KECCAK 3
+.Os
+.Sh NAME
+.Nm Keccak
+.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.Sh SYNOPSIS
+.In keccak.h
+.Ft void
+.Fn keccakf1600 "uint64_t A[25]"
+.Sh DESCRIPTION
+The
+.Nm
+functions implement the core Keccak permutation of the NIST SHA-3
+standard, FIPS PUB 202.
+.Pp
+Before using the
+.Nm
+functions, applications should first call
+.Xr SHA3_Selftest 3
+and confirm that it succeeded.
+.Pp
+The
+.Fn keccakf1600
+function implements the 24-round Keccak-f[1600] permutation on a state
+of twenty-five 64-bit words, to be loaded from or stored to octets in
+little-endian order.
+.Pp
+This function scrambles a 1600-bit state, and is conjectured to look
+like a random permutation.
+It lies at the core of all the SHA-3 hash and extendable-output
+functions, and can be used for other cryptographic constructions,
+e.g. a sponge duplex.
+.Pp
+The permutation Keccak-f[1600] is also known as Keccak-p[1600, 24].
+.Sh SEE ALSO
+.Xr sha3 3 ,
+.Xr SHA3_Selftest 3 ,
+.Xr SHAKE 3
+.Sh STANDARDS
+.Rs
+.%A National Institute of Standards and Technology
+.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.%O FIPS PUB 202
+.%D August 2015
+.Re
+.Sh AUTHORS
+.An Taylor R Campbell Aq campbell+s...@mumble.net
Index: src/lib/libc/hash/sha3/sha3.3
diff -u /dev/null src/lib/libc/hash/sha3/sha3.3:1.1
--- /dev/null Thu Nov 30 16:00:48 2017
+++ src/lib/libc/hash/sha3/sha3.3 Thu Nov 30 16:00:48 2017
@@ -0,0 +1,129 @@
+.\" $NetBSD: sha3.3,v 1.1 2017/11/30 16:00:48 wiz Exp $
+.\"
+.\" Copyright (c) 2015 Taylor R. Campbell
+.\" 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.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``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 OR CONTRIBUTORS 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.
+.\"
+.Dd October 14, 2015
+.Dt SHA3 3
+.Os
+.Sh NAME
+.Nm SHA3
+.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.Sh SYNOPSIS
+.In sha3.h
+.Ft void
+.Fn SHA3_224_Init "SHA3_224_CTX *ctx"
+.Ft void
+.Fn SHA3_224_Update "SHA3_224_CTX *ctx" "const uint8_t *buf" "size_t len"
+.Ft void
+.Fn SHA3_224_Final "uint8_t digest[SHA3_224_DIGEST_LENGTH]" "SHA3_224_CTX *ctx"
+.Ft void
+.Fn SHA3_256_Init "SHA3_256_CTX *ctx"
+.Ft void
+.Fn SHA3_256_Update "SHA3_256_CTX *ctx" "const uint8_t *buf" "size_t len"
+.Ft void
+.Fn SHA3_256_Final "uint8_t digest[SHA3_256_DIGEST_LENGTH]" "SHA3_256_CTX *ctx"
+.Ft void
+.Fn SHA3_384_Init "SHA3_384_CTX *ctx"
+.Ft void
+.Fn SHA3_384_Update "SHA3_384_CTX *ctx" "const uint8_t *buf" "size_t len"
+.Ft void
+.Fn SHA3_384_Final "uint8_t digest[SHA3_384_DIGEST_LENGTH]" "SHA3_384_CTX *ctx"
+.Ft void
+.Fn SHA3_512_Init "SHA3_512_CTX *ctx"
+.Ft void
+.Fn SHA3_512_Update "SHA3_512_CTX *ctx" "const uint8_t *buf" "size_t len"
+.Ft void
+.Fn SHA3_512_Final "uint8_t digest[SHA3_512_DIGEST_LENGTH]" "SHA3_512_CTX *ctx"
+.Sh DESCRIPTION
+The
+.Nm
+functions implement the cryptographic hash functions of the NIST SHA-3
+standard, FIPS PUB 202.
+The
+.Nm
+functions compress an arbitrary-length message m into short
+fixed-length octet strings SHA3-224(m), SHA3-256(m), etc., called a
+cryptographic digest or hash.
+.Pp
+Before using the
+.Nm
+functions, applications should first call
+.Xr SHA3_Selftest 3
+and confirm that it succeeded.
+.Pp
+Only the
+.Nm SHA3_256
+functions are specified in detail; the
+.Nm SHA3_224 ,
+.Nm SHA3_384 ,
+and
+.Nm SHA3_512
+functions are exactly analogous.
+.Pp
+The caller must allocate memory for a
+.Vt SHA3_256_CTX
+object to hold the state of a SHA3-256 hash computation over a
+message.
+.Vt SHA3_256_CTX
+objects are slightly over 200 bytes, and may be copied or relocated in
+memory.
+.Bl -tag -width abcd
+.It Fn SHA3_256_Init "ctx"
+Initialize a SHA3-256 context.
+Must be done before any other operations on
+.Fa ctx .
+.It Fn SHA3_256_Update "ctx" "data" "len"
+Append
+.Fa len
+octets at
+.Fa data
+to the message.
+.It Fn SHA3_256_Final "digest" "ctx"
+Store at
+.Fa digest
+the 32-octet SHA3-256 hash of the message obtained by concatenating
+all prior inputs to
+.Fn SHA3_256_Update
+on
+.Fa ctx .
+.Pp
+Subsequent use of
+.Fa ctx
+is not allowed, unless it is reinitialized with
+.Fn SHA3_256_Init .
+.El
+.Sh SEE ALSO
+.Xr keccak 3 ,
+.Xr SHA3_Selftest 3 ,
+.Xr SHAKE 3
+.Sh STANDARDS
+.Rs
+.%A National Institute of Standards and Technology
+.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions
+.%O FIPS PUB 202
+.%D August 2015
+.Re
+.Sh AUTHORS
+.An Taylor R Campbell Aq campbell+s...@mumble.net
