adds SHA-256 HMAC

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: secretbase
 Type: Package
 Title: Cryptographic Hash and Extendable-Output Functions
-Version: 0.3.0.9003
+Version: 0.3.0.9004
 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,

NEWS.md

@@ -1,6 +1,7 @@
-# secretbase 0.3.0.9003 (development)
+# secretbase 0.3.0.9004 (development)
 
-* Adds SipHash-1-3 pseudorandom function (PRF).
+* Adds HMAC generation to `sha256()`.
+* Adds SipHash-1-3 pseudo-random function (PRF) as a fast, cryptographically-strong keyed hash.
 
 # secretbase 0.3.0.1
 

R/base.R

@@ -101,9 +101,14 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file)
 
 #' Cryptographic Hashing Using the SHA-256 Algorithm
 #'
-#' Returns a SHA-256 hash of the supplied object or file.
+#' Returns a SHA-256 hash of the supplied object or file, or an HMAC if a secret
+#'     key is supplied.
 #'
 #' @inheritParams sha3
+#' @param key [default NULL] If NULL, the SHA-256 hash of 'x' is returned.
+#'     Alternatively, supply a secret key as a character string or raw vector to
+#'     generate an HMAC. Note: for character vectors only the first element is
+#'     used.
 #'
 #' @return A character string, raw or integer vector depending on 'convert'.
 #' 
@@ -126,23 +131,30 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file)
 #' file <- tempfile(); cat("secret base", file = file)
 #' sha256(file = file)
 #' unlink(file)
+#' 
+#' # SHA-256 HMAC using a character string secret key:
+#' sha256("secret", key = "base")
+#' 
+#' # SHA-256 HMAC using a raw vector secret key:
+#' sha256("secret", key = charToRaw("base"))
 #'
 #' @export
 #'
-sha256 <- function(x, convert = TRUE, file)
-  if (missing(file)) .Call(secretbase_sha256, x, convert) else
-    .Call(secretbase_sha256_file, file, convert)
+sha256 <- function(x, key = NULL, convert = TRUE, file)
+  if (missing(file)) .Call(secretbase_sha256, x, key, convert) else
+    .Call(secretbase_sha256_file, file, key, convert)
 
 #' Hashing Using the SipHash-1-3 Pseudorandom Function
 #'
-#' Returns a fast, cryptographically-strong SipHash-1-3 hash of the supplied
-#'     object or file.
+#' Returns a fast, cryptographically-strong SipHash-1-3 keyed hash of the
+#'     supplied object or file.
 #'
 #' @inheritParams sha3
-#' @param key [default NULL] an atomic vector comprising the 16 byte (128 bit)
-#'     key data, or else NULL which is equivalent to '0'. If a longer vector is
-#'     supplied, only the first 16 bytes are used, and if shorter, padded with
-#'     trailing '0'. Note: for character vectors only the first element is used.
+#' @param key [default NULL] a character string or raw vector comprising the 16
+#'     byte (128 bit) key data, or else NULL which is equivalent to '0'. If a
+#'     longer vector is supplied, only the first 16 bytes are used, and if
+#'     shorter, padded with trailing '0'. Note: for character vectors only the
+#'     first element is used.
 #'
 #' @return A character string, raw or integer vector depending on 'convert'.
 #' 
@@ -161,16 +173,16 @@ sha256 <- function(x, convert = TRUE, file)
 #' @examples
 #' # SipHash-1-3 hash as character string:
 #' siphash13("secret base")
-#' 
-#' # SipHash-1-3 hash using a complex number (16 byte) key:
-#' siphash13("secret base", key = 1.2 + 3.4i)
-#' 
-#' # SipHash-1-3 hash using a character string key:
-#' siphash13("secret", key = "base")
 #'
 #' # SipHash-1-3 hash as raw vector:
 #' siphash13("secret base", convert = FALSE)
 #' 
+#' # SipHash-1-3 hash using a character string key:
+#' siphash13("secret", key = "base")
+#' 
+#' # SipHash-1-3 hash using a raw vector key:
+#' siphash13("secret", key = charToRaw("base"))
+#' 
 #' # SipHash-1-3 hash a file:
 #' file <- tempfile(); cat("secret base", file = file)
 #' siphash13(file = file)

README.Rmd

@@ -67,8 +67,8 @@ sha3("秘密の基地の中", bits = 512)
 
 ##### Hash arbitrary R objects:
 
- - uses memory-efficient 'streaming' serialization (no allocation of serialized object)
- - portable as always uses R serialization version 3 big-endian representation, skipping headers (which contain R version and native encoding information)
+ - Uses memory-efficient 'streaming' serialization, without allocation of the serialized object
+ - 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)
@@ -78,7 +78,7 @@ sha3(NULL)
 
 ##### Hash files:
 
- - in a streaming fashion, accepting files larger than memory
+ - Performed in a streaming fashion, accepting files larger than memory
 
 ```{r files}
 file <- tempfile(); cat("secret base", file = file)
@@ -90,8 +90,8 @@ unlink(file)
 
 ##### Hash to integer:
 
- - 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)
+ - 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)
@@ -101,15 +101,21 @@ sha3("秘密の基地の中", 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>
 
-##### Using a keyed hash:
+##### Generating a SHA-256 HMAC:
 
-- Use `siphash13()` passing an atomic vector to 'key'.
-- Up to 16 bytes (128 bits) of the key data is used i.e. the length of 1 complex number, 2 doubles, 4 integers, or 16 individual characters / raw bytes.
+- Use `sha256()` passing a character string or raw vector to 'key'.
 
-```{r siphash}
-siphash13("secret base", key = "秘密の基地の中")
+```{r hmac}
+sha256("secret base", key = "秘密の基地の中")
+```
+
+##### Using SipHash:
 
-siphash13("secret base", key = 1.2 + 3.4i)
+- SipHash is a fast, cryptographically-strong keyed hash. The SipHash-1-3 parameters are optimized for performance.
+- Pass a character string or raw vector to 'key'. Up to 16 bytes (128 bits) of the key data is used.
+
+```{r siphash}
+siphash13("secret base", key = charToRaw("秘密の基地の中"))
 ```
 
 ### References

README.md

@@ -83,9 +83,9 @@ sha3("秘密の基地の中", bits = 512)
 
 ##### Hash arbitrary R objects:
 
-- uses memory-efficient ‘streaming’ serialization (no allocation of
-  serialized object)
-- portable as always uses R serialization version 3 big-endian
+- Uses memory-efficient ‘streaming’ serialization, without allocation of
+  the serialized object
+- Portable as always uses R serialization version 3 big-endian
   representation, skipping headers (which contain R version and native
   encoding information)
 
@@ -99,7 +99,7 @@ sha3(NULL)
 
 ##### Hash files:
 
-- in a streaming fashion, accepting files larger than memory
+- Performed in a streaming fashion, accepting files larger than memory
 
 ``` r
 file <- tempfile(); cat("secret base", file = file)
@@ -109,9 +109,9 @@ sha3(file = file)
 
 ##### Hash to integer:
 
-- specify ‘convert’ as `NA` (and ‘bits’ as `32` for a single integer
+- 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
+- May be supplied as deterministic random seeds for R’s pseudo random
   number generators (RNGs)
 
 ``` r
@@ -129,19 +129,25 @@ be especially suitable when first-best alternatives such as using
 recursive streams are too expensive or unable to preserve
 reproducibility. <sup>\[2\]</sup>
 
-##### Using a keyed hash:
+##### Generating a SHA-256 HMAC:
 
-- Use `siphash13()` passing an atomic vector to ‘key’.
-- Up to 16 bytes (128 bits) of the key data is used i.e. the length of 1
-  complex number, 2 doubles, 4 integers, or 16 individual characters /
-  raw bytes.
+- Use `sha256()` passing a character string or raw vector to ‘key’.
 
 ``` r
-siphash13("secret base", key = "秘密の基地の中")
-#> [1] "a1f0a751892cc7dd"
+sha256("secret base", key = "秘密の基地の中")
+#> [1] "ec58099ab21325e792bef8f1aafc0a70e1a7227463cfc410931112705d753392"
+```
+
+##### Using SipHash:
 
-siphash13("secret base", key = 1.2 + 3.4i)
-#> [1] "931a7b8f07c863a4"
+- SipHash is a fast, cryptographically-strong keyed hash. The
+  SipHash-1-3 parameters are optimized for performance.
+- Pass a character string or raw vector to ‘key’. Up to 16 bytes (128
+  bits) of the key data is used.
+
+``` r
+siphash13("secret base", key = charToRaw("秘密の基地の中"))
+#> [1] "a1f0a751892cc7dd"
 ```
 
 ### References

src/init.c

@@ -21,8 +21,8 @@
 static const R_CallMethodDef callMethods[] = {
   {"secretbase_sha3", (DL_FUNC) &secretbase_sha3, 3},
   {"secretbase_sha3_file", (DL_FUNC) &secretbase_sha3_file, 3},
-  {"secretbase_sha256", (DL_FUNC) &secretbase_sha256, 2},
-  {"secretbase_sha256_file", (DL_FUNC) &secretbase_sha256_file, 2},
+  {"secretbase_sha256", (DL_FUNC) &secretbase_sha256, 3},
+  {"secretbase_sha256_file", (DL_FUNC) &secretbase_sha256_file, 3},
   {"secretbase_siphash13", (DL_FUNC) &secretbase_siphash13, 3},
   {"secretbase_siphash13_file", (DL_FUNC) &secretbase_siphash13_file, 3},
   {NULL, NULL, 0}

src/secret.h

@@ -37,6 +37,7 @@
 #endif
 
 #define SB_SHA256_SIZE 32
+#define SB_SHA256_BLK 64
 #define SB_SIPH_SIZE 8
 #define SB_SKEY_SIZE 16
 
@@ -100,8 +101,8 @@ SEXP hash_to_sexp(unsigned char *, size_t, int);
 
 SEXP secretbase_sha3(SEXP, SEXP, SEXP);
 SEXP secretbase_sha3_file(SEXP, SEXP, SEXP);
-SEXP secretbase_sha256(SEXP, SEXP);
-SEXP secretbase_sha256_file(SEXP, SEXP);
+SEXP secretbase_sha256(SEXP, SEXP, SEXP);
+SEXP secretbase_sha256_file(SEXP, SEXP, SEXP);
 SEXP secretbase_siphash13(SEXP, SEXP, SEXP);
 SEXP secretbase_siphash13_file(SEXP, SEXP, SEXP);