From 838c9b0e7cccb5b5a9128ddd4bad9c06e4f06ff2 Mon Sep 17 00:00:00 2001 From: shikokuchuo <53399081+shikokuchuo@users.noreply.github.com> Date: Sun, 17 Mar 2024 16:24:09 +0000 Subject: [PATCH] re-organise docs --- DESCRIPTION | 16 +++++------ NEWS.md | 2 +- R/base.R | 57 ++++++++++++++++++++------------------- README.Rmd | 4 ++- README.md | 9 ++++--- man/secretbase-package.Rd | 33 ++++------------------- man/sha256.Rd | 9 +++++++ man/sha3.Rd | 8 ++++++ man/siphash13.Rd | 10 +++++++ 9 files changed, 80 insertions(+), 68 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index e790372..467922d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,16 +1,16 @@ Package: secretbase Type: Package Title: Cryptographic Hash and Extendable-Output Functions -Version: 0.3.0.9002 -Description: SHA-256, SHA-3 cryptographic hash and SHAKE256 extendable-output - functions (XOF). The SHA-3 Secure Hash Standard was published by the - National Institute of Standards and Technology (NIST) in 2015 at +Version: 0.3.0.9003 +Description: Fast and memory-efficient streaming hash functions for strings, raw + bytes, files and in-memory objects using R's serialization mechanism. + 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 . The SHA-256 Secure Hash Standard was published by NIST in 2002 at - . Fast and - memory-efficient implementation using the core algorithms from 'Mbed TLS' - under the Trusted Firmware Project - . + . Authors@R: c(person(given = "Charlie", family = "Gao", diff --git a/NEWS.md b/NEWS.md index 9d08090..c0329b7 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# secretbase 0.3.0.9002 (development) +# secretbase 0.3.0.9003 (development) * Adds SipHash-1-3 pseudorandom function (PRF). diff --git a/R/base.R b/R/base.R index f1eaacc..7e10bb6 100644 --- a/R/base.R +++ b/R/base.R @@ -18,33 +18,11 @@ #' secretbase: Cryptographic Hash and Extendable-Output Functions #' -#' Fast and memory-efficient implementations of the SHA-256, SHA-3 cryptographic -#' hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' -#' pseudo-random function. \cr\cr The SHA-3 cryptographic hash functions are -#' SHA3-224, SHA3-256, SHA3-384 and SHA3-512, each an instance of the Keccak -#' algorithm. SHAKE256 is one of the two XOFs of the SHA-3 family, along -#' with SHAKE128 (not implemented). -#' -#' @references 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}. -#' -#' The SHA-256 Secure Hash Standard was published by NIST in 2002 at -#' \url{https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}. -#' -#' \pkg{secretbase} adapts the SHA-256 and SHA-3 implementations by the -#' 'Mbed TLS Contributors' at \url{https://github.com/Mbed-TLS/mbedtls} -#' under the 'Mbed TLS' Trusted Firmware Project -#' \url{https://www.trustedfirmware.org/projects/mbed-tls/}. -#' -#' The SipHash family of cryptographically-strong pseudorandom functions -#' (PRFs) are described in 'SipHash: a fast short-input PRF', Jean-Philippe -#' Aumasson and Daniel J. Bernstein, Paper 2012/351, 2012, Cryptology ePrint -#' Archive at \url{https://ia.cr/2012/351}. -#' -#' \pkg{secretbase} adapts the SipHash streaming implementation by Daniele -#' Nicolodi, David Rheinsberg and Tom Gundersen at -#' \url{https://github.com/c-util/c-siphash}. +#' Fast and memory-efficient streaming hash functions for strings, raw bytes, +#' files and in-memory objects using R's serialization mechanism. +#' Implementations include the SHA-256 and SHA-3 cryptographic hash +#' functions, SHAKE256 extendable-output function (XOF), and 'SipHash' +#' pseudo-random function. #' #' @encoding UTF-8 #' @author Charlie Gao \email{charlie.gao@@shikokuchuo.net} @@ -81,6 +59,14 @@ #' @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 +#' \doi{doi:10.6028/NIST.FIPS.202}. +#' +#' This implementation is based on that of 'The Mbed TLS Contributors' under +#' the 'Mbed TLS' Trusted Firmware Project at +#' \url{https://www.trustedfirmware.org/projects/mbed-tls/}. #' #' @examples #' # SHA3-256 hash as character string: @@ -119,6 +105,14 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file) #' @inheritParams sha3 #' #' @return A character string, raw or integer vector depending on 'convert'. +#' +#' @details The SHA-256 Secure Hash Standard was published by the National +#' Institute of Standards and Technology (NIST) in 2002 at +#' \url{https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}. +#' +#' This implementation is based on that of 'The Mbed TLS Contributors' under +#' the 'Mbed TLS' Trusted Firmware Project at +#' \url{https://www.trustedfirmware.org/projects/mbed-tls/}. #' #' @examples #' # SHA-256 hash as character string: @@ -150,6 +144,15 @@ sha256 <- function(x, convert = TRUE, file) #' trailing '0'. Note: for character vectors only the first element is used. #' #' @return A character string, raw or integer vector depending on 'convert'. +#' +#' @details The SipHash family of cryptographically-strong pseudorandom +#' functions (PRFs) are described in 'SipHash: a fast short-input PRF', +#' Jean-Philippe Aumasson and Daniel J. Bernstein, Paper 2012/351, 2012, +#' Cryptology ePrint Archive at \url{https://ia.cr/2012/351}. +#' +#' This implementation is based on the SipHash streaming implementation by +#' Daniele Nicolodi, David Rheinsberg and Tom Gundersen at +#' \url{https://github.com/c-util/c-siphash}. #' #' @examples #' # SipHash-1-3 hash as character string: diff --git a/README.Rmd b/README.Rmd index e70c081..18f7a5f 100644 --- a/README.Rmd +++ b/README.Rmd @@ -23,7 +23,9 @@ knitr::opts_chunk$set( [![DOI](https://zenodo.org/badge/745691432.svg)](https://zenodo.org/doi/10.5281/zenodo.10553139) -Fast and memory-efficient implementations of the SHA-256, SHA-3 cryptographic hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random function. +Fast and memory-efficient streaming hash functions for strings, raw bytes, files and in-memory objects using R's serialization mechanism. + +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](https://dx.doi.org/10.6028/NIST.FIPS.202). The SHA-256 Secure Hash Standard was published by NIST in 2002 at . The SipHash family of pseudo-random functions by Jean-Philippe Aumasson and Daniel J. Bernstein was published in 2012 at .[1] diff --git a/README.md b/README.md index 6ea31fc..bb509ab 100644 --- a/README.md +++ b/README.md @@ -14,9 +14,12 @@ badge](https://shikokuchuo.r-universe.dev/badges/secretbase?color=e4723a)](https [![DOI](https://zenodo.org/badge/745691432.svg)](https://zenodo.org/doi/10.5281/zenodo.10553139) -Fast and memory-efficient implementations of the SHA-256, SHA-3 -cryptographic hash functions, SHAKE256 extendable-output function (XOF), -and ‘SipHash’ pseudo-random function. +Fast and memory-efficient streaming hash functions for strings, raw +bytes, files and in-memory objects using R’s serialization mechanism. + +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 diff --git a/man/secretbase-package.Rd b/man/secretbase-package.Rd index b779d9c..89b0d48 100644 --- a/man/secretbase-package.Rd +++ b/man/secretbase-package.Rd @@ -7,34 +7,11 @@ \alias{secretbase-package} \title{secretbase: Cryptographic Hash and Extendable-Output Functions} \description{ -Fast and memory-efficient implementations of the SHA-256, SHA-3 cryptographic - hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' - pseudo-random function. \cr\cr The SHA-3 cryptographic hash functions are - SHA3-224, SHA3-256, SHA3-384 and SHA3-512, each an instance of the Keccak - algorithm. SHAKE256 is one of the two XOFs of the SHA-3 family, along - with SHAKE128 (not implemented). -} -\references{ -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}. - - The SHA-256 Secure Hash Standard was published by NIST in 2002 at - \url{https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}. - - \pkg{secretbase} adapts the SHA-256 and SHA-3 implementations by the - 'Mbed TLS Contributors' at \url{https://github.com/Mbed-TLS/mbedtls} - under the 'Mbed TLS' Trusted Firmware Project - \url{https://www.trustedfirmware.org/projects/mbed-tls/}. - - The SipHash family of cryptographically-strong pseudorandom functions - (PRFs) are described in 'SipHash: a fast short-input PRF', Jean-Philippe - Aumasson and Daniel J. Bernstein, Paper 2012/351, 2012, Cryptology ePrint - Archive at \url{https://ia.cr/2012/351}. - - \pkg{secretbase} adapts the SipHash streaming implementation by Daniele - Nicolodi, David Rheinsberg and Tom Gundersen at - \url{https://github.com/c-util/c-siphash}. +Fast and memory-efficient streaming hash functions for strings, raw bytes, + files and in-memory objects using R's serialization mechanism. + Implementations include the SHA-256 and SHA-3 cryptographic hash + functions, SHAKE256 extendable-output function (XOF), and 'SipHash' + pseudo-random function. } \seealso{ Useful links: diff --git a/man/sha256.Rd b/man/sha256.Rd index 32b2728..af65da6 100644 --- a/man/sha256.Rd +++ b/man/sha256.Rd @@ -27,6 +27,15 @@ A character string, raw or integer vector depending on 'convert'. \description{ Returns a SHA-256 hash of the supplied R object or file. } +\details{ +The SHA-256 Secure Hash Standard was published by the National + Institute of Standards and Technology (NIST) in 2002 at + \url{https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf}. + + This implementation is based on that of 'The Mbed TLS Contributors' under + the 'Mbed TLS' Trusted Firmware Project at + \url{https://www.trustedfirmware.org/projects/mbed-tls/}. +} \examples{ # SHA-256 hash as character string: sha256("secret base") diff --git a/man/sha3.Rd b/man/sha3.Rd index 7d59b5a..656f2d0 100644 --- a/man/sha3.Rd +++ b/man/sha3.Rd @@ -36,6 +36,14 @@ Returns a SHA-3 hash of the supplied R object or file. 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 + \doi{doi:10.6028/NIST.FIPS.202}. + + This implementation is based on that of 'The Mbed TLS Contributors' under + the 'Mbed TLS' Trusted Firmware Project at + \url{https://www.trustedfirmware.org/projects/mbed-tls/}. } \examples{ # SHA3-256 hash as character string: diff --git a/man/siphash13.Rd b/man/siphash13.Rd index 2838d19..d2b8417 100644 --- a/man/siphash13.Rd +++ b/man/siphash13.Rd @@ -33,6 +33,16 @@ A character string, raw or integer vector depending on 'convert'. Returns a cryptographically-strong SipHash-1-3 hash of the supplied R object or file. } +\details{ +The SipHash family of cryptographically-strong pseudorandom + functions (PRFs) are described in 'SipHash: a fast short-input PRF', + Jean-Philippe Aumasson and Daniel J. Bernstein, Paper 2012/351, 2012, + Cryptology ePrint Archive at \url{https://ia.cr/2012/351}. + + This implementation is based on the SipHash streaming implementation by + Daniele Nicolodi, David Rheinsberg and Tom Gundersen at + \url{https://github.com/c-util/c-siphash}. +} \examples{ # SipHash-1-3 hash as character string: siphash13("secret base")