adds shake256()

DESCRIPTION

@@ -6,11 +6,12 @@ Description: Fast and memory-efficient streaming hash functions. Performs direct
     hashing of strings, raw bytes, and files potentially larger than memory, as
     well as hashing in-memory objects through R's serialization mechanism,
     without requiring allocation of the serialized object. Implementations
-    include the SHA-256 and SHA-3 cryptographic hash functions, SHAKE256
-    extendable-output function (XOF), and 'SipHash' pseudo-random function. The
-    SHA-3 Secure Hash Standard was published by the National Institute of
-    Standards and Technology (NIST) in 2015 at <doi:10.6028/NIST.FIPS.202>. The
-    SHA-256 Secure Hash Standard was published by NIST in 2002 at
+    include the SHA-256, SHA-3 and 'Keccak' cryptographic hash functions,
+    SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random
+    function. The SHA-3 Secure Hash Standard was published by the National
+    Institute of Standards and Technology (NIST) in 2015 at
+    <doi:10.6028/NIST.FIPS.202>. The SHA-256 Secure Hash Standard was published
+    by NIST in 2002 at
     <https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf>.
 Authors@R: 
     c(person(given = "Charlie",

NAMESPACE

@@ -3,5 +3,6 @@
 export(keccak)
 export(sha256)
 export(sha3)
+export(shake256)
 export(siphash13)
 useDynLib(secretbase, .registration = TRUE)

NEWS.md

@@ -1,6 +1,8 @@
 # secretbase 0.4.0.9000 (development)
 
 * Adds Keccak cryptographic hash algorithm.
+* Adds `shake256()` to delineate from `sha3()`.
+* Use of `sha3()` supplying 'bit' argument other than 224, 256, 384 or 512 is deprecated.
 
 # secretbase 0.4.0
 

R/base.R

@@ -35,20 +35,19 @@
 
 # secretbase - Main Functions --------------------------------------------------
 
-#' SHA-3 Cryptographic Hash Algorithms and SHAKE256 XOF
+#' SHA-3 Cryptographic Hash Algorithms
 #'
-#' Returns a SHA-3 or SHAKE256 hash of the supplied object or file.
+#' Returns a SHA-3 hash of the supplied object or file.
 #'
 #' @param x object to hash. A character string or raw vector (without
 #'     attributes) is hashed 'as is'. All other objects are stream hashed using
 #'     R serialization, but without requiring allocation of the serialized
 #'     object. To ensure portability, serialization version 3 big-endian
 #'     represenation is always used with headers skipped (as these contain R
 #'     version and native encoding information).
-#' @param bits [default 256L] output size of the returned hash. If one of 224,
-#'     256, 384 or 512, uses the respective SHA-3 cryptographic hash function.
-#'     For all other values, uses the SHAKE256 extendable-output function (XOF).
-#'     Must be between 8 and 2^24 and coercible to integer.
+#' @param bits [default 256L] output size of the returned hash. Must be one of
+#'     224, 256, 384 or 512. For legacy reasons (usage is deprecated), all other
+#'     values return the value of \code{\link{shake256}}.
 #' @param convert [default TRUE] if TRUE, the hash is converted to its hex
 #'     representation as a character string, if FALSE, output directly as a raw
 #'     vector, or if NA, a vector of (32-bit) integer values.
@@ -57,12 +56,8 @@
 #'
 #' @return A character string, raw or integer vector depending on 'convert'.
 #'
-#' @details To produce single integer values suitable for use as random seeds
-#'     for R's pseudo random number generators (RNGs), set 'bits' to 32 and
-#'     'convert' to NA.
-#'     
-#'     The SHA-3 Secure Hash Standard was published by the National Institute of
-#'     Standards and Technology (NIST) in 2015 at
+#' @details The SHA-3 Secure Hash Standard was published by the National
+#'     Institute of Standards and Technology (NIST) in 2015 at
 #'     \doi{doi:10.6028/NIST.FIPS.202}.
 #'     
 #'     This implementation is based on one by 'The Mbed TLS Contributors' under
@@ -84,9 +79,6 @@
 #' 
 #' # SHA3-512 hash as character string:
 #' sha3("secret base", bits = 512)
-#' 
-#' # SHAKE256 hash to integer:
-#' sha3("secret base", bits = 32L, convert = NA)
 #'
 #' # SHA3-256 hash a file:
 #' file <- tempfile(); cat("secret base", file = file)
@@ -99,6 +91,55 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file)
   if (missing(file)) .Call(secretbase_sha3, x, bits, convert) else
     .Call(secretbase_sha3_file, file, bits, convert)
 
+#' SHAKE256 Extendable Output Function (XOF)
+#'
+#' Returns a SHAKE256 hash of the supplied object or file.
+#'
+#' @param x object to hash. A character string or raw vector (without
+#'     attributes) is hashed 'as is'. All other objects are stream hashed using
+#'     R serialization, but without requiring allocation of the serialized
+#'     object. To ensure portability, serialization version 3 big-endian
+#'     represenation is always used with headers skipped (as these contain R
+#'     version and native encoding information).
+#' @param bits [default 256L] output size of the returned hash. Must be between
+#'     8 and 2^24 and coercible to integer.
+#' @param convert [default TRUE] if TRUE, the hash is converted to its hex
+#'     representation as a character string, if FALSE, output directly as a raw
+#'     vector, or if NA, a vector of (32-bit) integer values.
+#' @param file character file name / path. If specified, 'x' is ignored. The
+#'     file is stream hashed, thus capable of handling files larger than memory.
+#'
+#' @return A character string, raw or integer vector depending on 'convert'.
+#'
+#' @details To produce single integer values suitable for use as random seeds
+#'     for R's pseudo random number generators (RNGs), set 'bits' to 32 and
+#'     'convert' to NA.
+#'     
+#'     This implementation is based on one by 'The Mbed TLS Contributors' under
+#'     the 'Mbed TLS' Trusted Firmware Project at
+#'     \url{https://www.trustedfirmware.org/projects/mbed-tls}.
+#'
+#' @examples
+#' # SHAKE256 hash as character string:
+#' shake256("secret base")
+#'
+#' # SHAKE256 hash as raw vector:
+#' shake256("secret base", convert = FALSE)
+#' 
+#' # SHAKE256 hash to integer:
+#' sha3("secret base", bits = 32L, convert = NA)
+#'
+#' # SHAKE256 hash a file:
+#' file <- tempfile(); cat("secret base", file = file)
+#' shake256(file = file)
+#' unlink(file)
+#'
+#' @export
+#'
+shake256 <- function(x, bits = 256L, convert = TRUE, file)
+  if (missing(file)) .Call(secretbase_shake256, x, bits, convert) else
+    .Call(secretbase_shake256_file, file, bits, convert)
+
 #' Keccak Cryptographic Hash Algorithms
 #'
 #' Returns a Keccak hash of the supplied object or file.

README.Rmd

@@ -25,7 +25,7 @@ knitr::opts_chunk$set(
 
 Fast and memory-efficient streaming hash functions. Performs direct hashing of strings, raw bytes, and files potentially larger than memory, as well as hashing in-memory objects through R's serialization mechanism, without requiring allocation of the serialized object.
 
-Implementations include the SHA-256 and SHA-3 cryptographic hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random function.
+Implementations include the SHA-256, SHA-3 and Keccak cryptographic hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random function.
 
 The SHA-3 Secure Hash Standard was published by the National Institute of Standards and Technology (NIST) in 2015 at [doi:10.6028/NIST.FIPS.202](https://dx.doi.org/10.6028/NIST.FIPS.202). The SHA-256 Secure Hash Standard was published by NIST in 2002 at <https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf>. The SipHash family of pseudo-random functions by Jean-Philippe Aumasson and Daniel J. Bernstein was published in 2012 at <https://ia.cr/2012/351>.<sup>[1]</sup>
 
@@ -54,7 +54,6 @@ library(secretbase)
 #### SHA-3
 
  - For the SHA-3 cryptographic hash algorithm, specify 'bits' as `224`, `256`, `384` or `512`
- - For the SHAKE256 extendable-output function (XOF), specify any other bit length
 
 ```{r sha3}
 sha3("secret base")
@@ -72,7 +71,7 @@ sha3("秘密の基地の中", bits = 512)
  - Portable as always uses R serialization version 3 big-endian representation, skipping headers (which contain R version and native encoding information)
 
 ```{r streaming}
-sha3(data.frame(a = 1, b = 2), bits = 160)
+sha3(data.frame(a = 1, b = 2), bits = 224)
 
 sha3(NULL)
 ```
@@ -89,19 +88,23 @@ sha3(file = file)
 unlink(file)
 ```
 
-#### Hash to integer
+#### Hash to integer / SHAKE256 XOF
 
  - Specify 'convert' as `NA` (and 'bits' as `32` for a single integer value)
  - May be supplied as deterministic random seeds for R's pseudo random number generators (RNGs)
 
 ```{r integer}
-sha3("秘密の基地の中", bits = 384, convert = NA)
-
-sha3("秘密の基地の中", bits = 32, convert = NA)
+shake256("秘密の基地の中", bits = 32, convert = NA)
 ```
 
 For use in parallel computing, this is a valid method for reducing to a negligible probability that RNGs in each process may overlap. This may be especially suitable when first-best alternatives such as using recursive streams are too expensive or unable to preserve reproducibility. <sup>[2]</sup>
 
+#### Keccak
+
+```{r keccak}
+keccak("secret base", bits = 384)
+```
+
 #### SHA-256
 
 ```{r sha256}

README.md

@@ -19,7 +19,7 @@ hashing of strings, raw bytes, and files potentially larger than memory,
 as well as hashing in-memory objects through R’s serialization
 mechanism, without requiring allocation of the serialized object.
 
-Implementations include the SHA-256 and SHA-3 cryptographic hash
+Implementations include the SHA-256, SHA-3 and Keccak cryptographic hash
 functions, SHAKE256 extendable-output function (XOF), and ‘SipHash’
 pseudo-random function.
 
@@ -65,8 +65,6 @@ library(secretbase)
 
 - For the SHA-3 cryptographic hash algorithm, specify ‘bits’ as `224`,
   `256`, `384` or `512`
-- For the SHAKE256 extendable-output function (XOF), specify any other
-  bit length
 
 ``` r
 sha3("secret base")
@@ -91,8 +89,8 @@ sha3("秘密の基地の中", bits = 512)
   encoding information)
 
 ``` r
-sha3(data.frame(a = 1, b = 2), bits = 160)
-#> [1] "bc5a411f87ef083296c60d6557f189b62ff9e7e6"
+sha3(data.frame(a = 1, b = 2), bits = 224)
+#> [1] "03778aad53bff7dd68caab94374bba6f07cea235fb97b3c52cf612e9"
 
 sha3(NULL)
 #> [1] "b3e37e4c5def1bfb2841b79ef8503b83d1fed46836b5b913d7c16de92966dcee"
@@ -108,19 +106,15 @@ sha3(file = file)
 #> [1] "a721d57570e7ce366adee2fccbe9770723c6e3622549c31c7cab9dbb4a795520"
 ```
 
-#### Hash to integer
+#### Hash to integer / SHAKE256 XOF
 
 - Specify ‘convert’ as `NA` (and ‘bits’ as `32` for a single integer
   value)
 - May be supplied as deterministic random seeds for R’s pseudo random
   number generators (RNGs)
 
 ``` r
-sha3("秘密の基地の中", bits = 384, convert = NA)
-#>  [1]  1421990570   338241144  1760362273 -1213241427  1313032644 -1154474231
-#>  [7]  1041052480   697347630 -1488396834  -917712316  1835427495  2044829552
-
-sha3("秘密の基地の中", bits = 32, convert = NA)
+shake256("秘密の基地の中", bits = 32, convert = NA)
 #> [1] 2000208511
 ```
 
@@ -130,6 +124,13 @@ be especially suitable when first-best alternatives such as using
 recursive streams are too expensive or unable to preserve
 reproducibility. <sup>\[2\]</sup>
 
+#### Keccak
+
+``` r
+keccak("secret base", bits = 384)
+#> [1] "c82bae24175676028e44aa08b9e2424311847adb0b071c68c7ea47edf049b0e935ddd2fc7c499333bccc08c7eb7b1203"
+```
+
 #### SHA-256
 
 ``` r

src/init.c

@@ -21,6 +21,8 @@
 static const R_CallMethodDef callMethods[] = {
   {"secretbase_sha3", (DL_FUNC) &secretbase_sha3, 3},
   {"secretbase_sha3_file", (DL_FUNC) &secretbase_sha3_file, 3},
+  {"secretbase_shake256", (DL_FUNC) &secretbase_shake256, 3},
+  {"secretbase_shake256_file", (DL_FUNC) &secretbase_shake256_file, 3},
   {"secretbase_keccak", (DL_FUNC) &secretbase_keccak, 3},
   {"secretbase_keccak_file", (DL_FUNC) &secretbase_keccak_file, 3},
   {"secretbase_sha256", (DL_FUNC) &secretbase_sha256, 3},