[src/trunk]: src/lib/libc/hash/sha3 Add riastradh's man pages for sha3 and fr...

To: source-changes-hg%NetBSD.org@localhost
Subject: [src/trunk]: src/lib/libc/hash/sha3 Add riastradh's man pages for sha3 and fr...
From: wiz <wiz%NetBSD.org@localhost>
Date: Tue, 07 Apr 2020 09:04:46 +0000
details:   https://anonhg.NetBSD.org/src/rev/ae7559461767
branches:  trunk
changeset: 828163:ae7559461767
user:      wiz <wiz%NetBSD.org@localhost>
date:      Thu Nov 30 16:00:48 2017 +0000

description:
Add riastradh's man pages for sha3 and friends.

Commented out since the symbols themselves are not yet public.

diffstat:

 lib/libc/hash/sha3/Makefile.inc    |    5 +-
 lib/libc/hash/sha3/SHA3_Selftest.3 |   73 ++++++++++++++++++++
 lib/libc/hash/sha3/SHAKE.3         |  114 ++++++++++++++++++++++++++++++++
 lib/libc/hash/sha3/keccak.3        |   74 +++++++++++++++++++++
 lib/libc/hash/sha3/sha3.3          |  129 +++++++++++++++++++++++++++++++++++++
 5 files changed, 392 insertions(+), 3 deletions(-)

diffs (truncated from 428 to 300 lines):

diff -r 8711fa5ca4f1 -r ae7559461767 lib/libc/hash/sha3/Makefile.inc
--- a/lib/libc/hash/sha3/Makefile.inc   Thu Nov 30 15:42:18 2017 +0000
+++ b/lib/libc/hash/sha3/Makefile.inc   Thu Nov 30 16:00:48 2017 +0000
@@ -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 @@
 #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
diff -r 8711fa5ca4f1 -r ae7559461767 lib/libc/hash/sha3/SHA3_Selftest.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/hash/sha3/SHA3_Selftest.3        Thu Nov 30 16:00:48 2017 +0000
@@ -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+sha3%mumble.net@localhost
diff -r 8711fa5ca4f1 -r ae7559461767 lib/libc/hash/sha3/SHAKE.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/hash/sha3/SHAKE.3        Thu Nov 30 16:00:48 2017 +0000
@@ -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+sha3%mumble.net@localhost
diff -r 8711fa5ca4f1 -r ae7559461767 lib/libc/hash/sha3/keccak.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/hash/sha3/keccak.3       Thu Nov 30 16:00:48 2017 +0000
@@ -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+sha3%mumble.net@localhost
diff -r 8711fa5ca4f1 -r ae7559461767 lib/libc/hash/sha3/sha3.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/hash/sha3/sha3.3 Thu Nov 30 16:00:48 2017 +0000
@@ -0,0 +1,129 @@
+.\" $NetBSD: sha3.3,v 1.1 2017/11/30 16:00:48 wiz Exp $
Prev by Date: [src/trunk]: src/sys/arch/arm/sunxi report VLAN MTU capability
Next by Date: [src/trunk]: src/sys/kern If no auxv is present, don't kmem_alloc(0). Easy to...
Previous by Thread: [src/trunk]: src/sys/arch/arm/sunxi report VLAN MTU capability
Next by Thread: [src/trunk]: src/sys/kern If no auxv is present, don't kmem_alloc(0). Easy to...
Indexes:
Home | Main Index | Thread Index | Old Index