1.\" $NetBSD: sha3.3,v 1.1 2017/11/30 16:00:48 wiz Exp $ 2.\" 3.\" Copyright (c) 2015 Taylor R. Campbell 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd October 14, 2015 28.Dt SHA3 3 29.Os 30.Sh NAME 31.Nm SHA3 32.Nd NIST FIPS PUB 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions 33.Sh SYNOPSIS 34.In sha3.h 35.Ft void 36.Fn SHA3_224_Init "SHA3_224_CTX *ctx" 37.Ft void 38.Fn SHA3_224_Update "SHA3_224_CTX *ctx" "const uint8_t *buf" "size_t len" 39.Ft void 40.Fn SHA3_224_Final "uint8_t digest[SHA3_224_DIGEST_LENGTH]" "SHA3_224_CTX *ctx" 41.Ft void 42.Fn SHA3_256_Init "SHA3_256_CTX *ctx" 43.Ft void 44.Fn SHA3_256_Update "SHA3_256_CTX *ctx" "const uint8_t *buf" "size_t len" 45.Ft void 46.Fn SHA3_256_Final "uint8_t digest[SHA3_256_DIGEST_LENGTH]" "SHA3_256_CTX *ctx" 47.Ft void 48.Fn SHA3_384_Init "SHA3_384_CTX *ctx" 49.Ft void 50.Fn SHA3_384_Update "SHA3_384_CTX *ctx" "const uint8_t *buf" "size_t len" 51.Ft void 52.Fn SHA3_384_Final "uint8_t digest[SHA3_384_DIGEST_LENGTH]" "SHA3_384_CTX *ctx" 53.Ft void 54.Fn SHA3_512_Init "SHA3_512_CTX *ctx" 55.Ft void 56.Fn SHA3_512_Update "SHA3_512_CTX *ctx" "const uint8_t *buf" "size_t len" 57.Ft void 58.Fn SHA3_512_Final "uint8_t digest[SHA3_512_DIGEST_LENGTH]" "SHA3_512_CTX *ctx" 59.Sh DESCRIPTION 60The 61.Nm 62functions implement the cryptographic hash functions of the NIST SHA-3 63standard, FIPS PUB 202. 64The 65.Nm 66functions compress an arbitrary-length message m into short 67fixed-length octet strings SHA3-224(m), SHA3-256(m), etc., called a 68cryptographic digest or hash. 69.Pp 70Before using the 71.Nm 72functions, applications should first call 73.Xr SHA3_Selftest 3 74and confirm that it succeeded. 75.Pp 76Only the 77.Nm SHA3_256 78functions are specified in detail; the 79.Nm SHA3_224 , 80.Nm SHA3_384 , 81and 82.Nm SHA3_512 83functions are exactly analogous. 84.Pp 85The caller must allocate memory for a 86.Vt SHA3_256_CTX 87object to hold the state of a SHA3-256 hash computation over a 88message. 89.Vt SHA3_256_CTX 90objects are slightly over 200 bytes, and may be copied or relocated in 91memory. 92.Bl -tag -width abcd 93.It Fn SHA3_256_Init "ctx" 94Initialize a SHA3-256 context. 95Must be done before any other operations on 96.Fa ctx . 97.It Fn SHA3_256_Update "ctx" "data" "len" 98Append 99.Fa len 100octets at 101.Fa data 102to the message. 103.It Fn SHA3_256_Final "digest" "ctx" 104Store at 105.Fa digest 106the 32-octet SHA3-256 hash of the message obtained by concatenating 107all prior inputs to 108.Fn SHA3_256_Update 109on 110.Fa ctx . 111.Pp 112Subsequent use of 113.Fa ctx 114is not allowed, unless it is reinitialized with 115.Fn SHA3_256_Init . 116.El 117.Sh SEE ALSO 118.Xr keccak 3 , 119.Xr SHA3_Selftest 3 , 120.Xr SHAKE 3 121.Sh STANDARDS 122.Rs 123.%A National Institute of Standards and Technology 124.%T SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions 125.%O FIPS PUB 202 126.%D August 2015 127.Re 128.Sh AUTHORS 129.An Taylor R Campbell Aq campbell+sha3@mumble.net 130