diff --git a/DESCRIPTION b/DESCRIPTION index f0a6700..7f80c48 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -4,7 +4,7 @@ Title: Cryptographic Hash, Extendable-Output and Base64 Functions Version: 1.0.3.9000 Description: Fast and memory-efficient streaming hash functions and base64 encoding / decoding. Hashes strings and raw vectors directly. Stream hashes - files potentially larger than memory, as well as in-memory objects through + files which can be larger than memory, as well as in-memory objects through R's serialization mechanism. Implementations include the SHA-256, SHA-3 and 'Keccak' cryptographic hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random function. diff --git a/R/base.R b/R/base.R index 2c9a736..747732b 100644 --- a/R/base.R +++ b/R/base.R @@ -25,11 +25,10 @@ #' 3, big-endian representation). #' #' @param x an object. -#' @param convert logical TRUE to encode to a character string or FALSE to a raw -#' vector. +#' @param convert logical `TRUE` to encode to a character string or `FALSE` to a +#' raw vector. #' -#' @return A character string or raw vector depending on the value of -#' \sQuote{convert}. +#' @return A character string or raw vector depending on the value of `convert`. #' #' @references #' This implementation is based that by 'The Mbed TLS Contributors' under the @@ -51,18 +50,18 @@ base64enc <- function(x, convert = TRUE) .Call(secretbase_base64enc, x, convert) #' #' Decodes a character string, raw vector or other object from base64 encoding. #' -#' The value of \sQuote{convert} should be set to TRUE, FALSE or NA to be the +#' The value of `convert` should be set to `TRUE`, `FALSE` or `NA` to be the #' reverse of the 3 encoding operations (for strings, raw vectors and arbitrary #' objects), in order to return the original object. #' #' @param x an object. -#' @param convert logical TRUE to convert back to a character string, FALSE to -#' convert back to a raw vector or NA to decode and then unserialize back to -#' the original object. +#' @param convert logical `TRUE` to convert back to a character string, `FALSE` +#' to convert back to a raw vector or `NA` to decode and then unserialize back +#' to the original object. #' #' @return A character string, raw vector, or other object depending on the -#' value of \sQuote{convert}. If conversion to a character string fails, a raw -#' vector will be returned instead (accompanied by a warning). +#' value of `convert`. If conversion to a character string fails, a raw vector +#' will be returned instead (accompanied by a warning). #' #' @references #' This implementation is based that by 'The Mbed TLS Contributors' under the diff --git a/R/secret.R b/R/secret.R index 84619cb..4671868 100644 --- a/R/secret.R +++ b/R/secret.R @@ -19,8 +19,8 @@ #' secretbase: Cryptographic Hash, Extendable-Output and Base64 Functions #' #' Fast and memory-efficient streaming hash functions and base64 encoding / -#' decoding. Hashes strings and raw vectors directly. Stream hashes files -#' potentially larger than memory, as well as in-memory objects through R's +#' decoding. Hashes strings and raw vectors directly. Stream hashes files which +#' can be larger than memory, as well as in-memory objects through R's #' serialization mechanism. Implementations include the SHA-256, SHA-3 and #' 'Keccak' cryptographic hash functions, SHAKE256 extendable-output function #' (XOF), and 'SipHash' pseudo-random function. @@ -40,18 +40,17 @@ #' 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 \sQuote{as is}. All other objects are stream hashed -#' using R serialization (but without allocation of the serialized object). +#' attributes) is hashed *as is*. All other objects are stream hashed +#' using R serialization (without allocation of the serialized object). #' @param bits integer output size of the returned hash. Must be one of 224, #' 256, 384 or 512. -#' @param convert logical TRUE to convert the hash to its hex representation as -#' a character string, FALSE to return directly as a raw vector, or NA to -#' return as a vector of (32-bit) integers. -#' @param file character file name / path. If specified, \sQuote{x} is ignored. -#' The file is stream hashed, hence files larger than memory are permitted. -#' -#' @return A character string, raw or integer vector depending on -#' \sQuote{convert}. +#' @param convert logical `TRUE` to convert the hash to its hex representation +#' as a character string, `FALSE` to return directly as a raw vector, or `NA` +#' to return as a vector of (32-bit) integers. +#' @param file character file name / path. If specified, `x` is ignored. The +#' file is stream hashed, and the file can be larger than memory. +#' +#' @return A character string, raw or integer vector depending on `convert`. #' #' @section R Serialization Stream Hashing: #' @@ -106,8 +105,7 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file) #' @param bits integer output size of the returned hash. Value must be between 8 #' and 2^24. #' -#' @return A character string, raw or integer vector depending on -#' \sQuote{convert}. +#' @return A character string, raw or integer vector depending on `convert`. #' #' @inheritSection sha3 R Serialization Stream Hashing #' @@ -143,8 +141,7 @@ shake256 <- function(x, bits = 256L, convert = TRUE, file) #' #' @inheritParams sha3 #' -#' @return A character string, raw or integer vector depending on -#' \sQuote{convert}. +#' @return A character string, raw or integer vector depending on `convert`. #' #' @inheritSection sha3 R Serialization Stream Hashing #' @@ -192,12 +189,11 @@ keccak <- function(x, bits = 256L, convert = TRUE, file) #' key is supplied. #' #' @inheritParams sha3 -#' @param key if NULL, the SHA-256 hash of \sQuote{x} is returned. If a -#' character string or raw vector, this is used as a secret key to generate an -#' HMAC. Note: for character vectors, only the first element is used. +#' @param key if `NULL`, the SHA-256 hash of `x` is returned. If a character +#' string or raw vector, this is used as a secret key to generate an HMAC. +#' Note: for character vectors, only the first element is used. #' -#' @return A character string, raw or integer vector depending on -#' \sQuote{convert}. +#' @return A character string, raw or integer vector depending on `convert`. #' #' @inheritSection sha3 R Serialization Stream Hashing #' @@ -242,12 +238,11 @@ sha256 <- function(x, key = NULL, convert = TRUE, file) #' #' @inheritParams sha3 #' @param key 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 +#' 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 -#' \sQuote{convert}. +#' @return A character string, raw or integer vector depending on `convert`. #' #' @inheritSection sha3 R Serialization Stream Hashing #' diff --git a/README.Rmd b/README.Rmd index 1289457..7b8fec7 100644 --- a/README.Rmd +++ b/README.Rmd @@ -33,7 +33,7 @@ knitr::opts_chunk$set( Fast and memory-efficient streaming hash functions and base64 encoding / decoding. -Hashes strings and raw vectors directly. Stream hashes files potentially larger than memory, as well as in-memory objects through R's serialization mechanism. +Hashes strings and raw vectors directly. Stream hashes files which can be larger than memory, as well as in-memory objects through R's serialization mechanism. Implementations include the SHA-256, SHA-3 and 'Keccak' cryptographic hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random function. @@ -112,7 +112,7 @@ sha256("secret base", key = "秘密の基地の中") SipHash-1-3 is optimized for performance.
Pass to `key` a character string or raw vector of up to 16 bytes (128 bits): ```{r siphash} -siphash13("secret base", key = charToRaw("秘密の基地の中")) +siphash13("secret base", key = "秘密の基地の中") ``` #### Base64 Encoding / Decoding diff --git a/README.md b/README.md index 80143c3..fc5457d 100644 --- a/README.md +++ b/README.md @@ -25,8 +25,8 @@ badge](https://shikokuchuo.r-universe.dev/badges/secretbase?color=ff803d)](https Fast and memory-efficient streaming hash functions and base64 encoding / decoding. -Hashes strings and raw vectors directly. Stream hashes files potentially -larger than memory, as well as in-memory objects through R’s +Hashes strings and raw vectors directly. Stream hashes files which can +be larger than memory, as well as in-memory objects through R’s serialization mechanism. Implementations include the SHA-256, SHA-3 and ‘Keccak’ cryptographic @@ -130,7 +130,7 @@ SipHash-1-3 is optimized for performance.
Pass to `key` a character string or raw vector of up to 16 bytes (128 bits): ``` r -siphash13("secret base", key = charToRaw("秘密の基地の中")) +siphash13("secret base", key = "秘密の基地の中") #> [1] "a1f0a751892cc7dd" ``` diff --git a/man/base64dec.Rd b/man/base64dec.Rd index 6b4d940..d4ca5c8 100644 --- a/man/base64dec.Rd +++ b/man/base64dec.Rd @@ -9,20 +9,20 @@ base64dec(x, convert = TRUE) \arguments{ \item{x}{an object.} -\item{convert}{logical TRUE to convert back to a character string, FALSE to -convert back to a raw vector or NA to decode and then unserialize back to -the original object.} +\item{convert}{logical \code{TRUE} to convert back to a character string, \code{FALSE} +to convert back to a raw vector or \code{NA} to decode and then unserialize back +to the original object.} } \value{ A character string, raw vector, or other object depending on the -value of \sQuote{convert}. If conversion to a character string fails, a raw -vector will be returned instead (accompanied by a warning). +value of \code{convert}. If conversion to a character string fails, a raw vector +will be returned instead (accompanied by a warning). } \description{ Decodes a character string, raw vector or other object from base64 encoding. } \details{ -The value of \sQuote{convert} should be set to TRUE, FALSE or NA to be the +The value of \code{convert} should be set to \code{TRUE}, \code{FALSE} or \code{NA} to be the reverse of the 3 encoding operations (for strings, raw vectors and arbitrary objects), in order to return the original object. } diff --git a/man/base64enc.Rd b/man/base64enc.Rd index 73d5531..3e2daa1 100644 --- a/man/base64enc.Rd +++ b/man/base64enc.Rd @@ -9,12 +9,11 @@ base64enc(x, convert = TRUE) \arguments{ \item{x}{an object.} -\item{convert}{logical TRUE to encode to a character string or FALSE to a raw -vector.} +\item{convert}{logical \code{TRUE} to encode to a character string or \code{FALSE} to a +raw vector.} } \value{ -A character string or raw vector depending on the value of -\sQuote{convert}. +A character string or raw vector depending on the value of \code{convert}. } \description{ Encodes a character string, raw vector or other object to base64 encoding. diff --git a/man/keccak.Rd b/man/keccak.Rd index 3dbfac9..c0a76e0 100644 --- a/man/keccak.Rd +++ b/man/keccak.Rd @@ -8,22 +8,21 @@ keccak(x, bits = 256L, convert = TRUE, file) } \arguments{ \item{x}{object to hash. A character string or raw vector (without -attributes) is hashed \sQuote{as is}. All other objects are stream hashed -using R serialization (but without allocation of the serialized object).} +attributes) is hashed \emph{as is}. All other objects are stream hashed +using R serialization (without allocation of the serialized object).} \item{bits}{integer output size of the returned hash. Must be one of 224, 256, 384 or 512.} -\item{convert}{logical TRUE to convert the hash to its hex representation as -a character string, FALSE to return directly as a raw vector, or NA to -return as a vector of (32-bit) integers.} +\item{convert}{logical \code{TRUE} to convert the hash to its hex representation +as a character string, \code{FALSE} to return directly as a raw vector, or \code{NA} +to return as a vector of (32-bit) integers.} -\item{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, hence files larger than memory are permitted.} +\item{file}{character file name / path. If specified, \code{x} is ignored. The +file is stream hashed, and the file can be larger than memory.} } \value{ -A character string, raw or integer vector depending on -\sQuote{convert}. +A character string, raw or integer vector depending on \code{convert}. } \description{ Returns a Keccak hash of the supplied object or file. diff --git a/man/secretbase-package.Rd b/man/secretbase-package.Rd index 00f5fce..910b77a 100644 --- a/man/secretbase-package.Rd +++ b/man/secretbase-package.Rd @@ -8,8 +8,8 @@ \title{secretbase: Cryptographic Hash, Extendable-Output and Base64 Functions} \description{ Fast and memory-efficient streaming hash functions and base64 encoding / -decoding. Hashes strings and raw vectors directly. Stream hashes files -potentially larger than memory, as well as in-memory objects through R's +decoding. Hashes strings and raw vectors directly. Stream hashes files which +can be larger than memory, as well as in-memory objects through R's serialization mechanism. Implementations include the SHA-256, SHA-3 and 'Keccak' cryptographic hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random function. diff --git a/man/sha256.Rd b/man/sha256.Rd index b9a23ea..7b45008 100644 --- a/man/sha256.Rd +++ b/man/sha256.Rd @@ -8,23 +8,22 @@ sha256(x, key = NULL, convert = TRUE, file) } \arguments{ \item{x}{object to hash. A character string or raw vector (without -attributes) is hashed \sQuote{as is}. All other objects are stream hashed -using R serialization (but without allocation of the serialized object).} +attributes) is hashed \emph{as is}. All other objects are stream hashed +using R serialization (without allocation of the serialized object).} -\item{key}{if NULL, the SHA-256 hash of \sQuote{x} is returned. If a -character string or raw vector, this is used as a secret key to generate an -HMAC. Note: for character vectors, only the first element is used.} +\item{key}{if \code{NULL}, the SHA-256 hash of \code{x} is returned. If a character +string or raw vector, this is used as a secret key to generate an HMAC. +Note: for character vectors, only the first element is used.} -\item{convert}{logical TRUE to convert the hash to its hex representation as -a character string, FALSE to return directly as a raw vector, or NA to -return as a vector of (32-bit) integers.} +\item{convert}{logical \code{TRUE} to convert the hash to its hex representation +as a character string, \code{FALSE} to return directly as a raw vector, or \code{NA} +to return as a vector of (32-bit) integers.} -\item{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, hence files larger than memory are permitted.} +\item{file}{character file name / path. If specified, \code{x} is ignored. The +file is stream hashed, and the file can be larger than memory.} } \value{ -A character string, raw or integer vector depending on -\sQuote{convert}. +A character string, raw or integer vector depending on \code{convert}. } \description{ Returns a SHA-256 hash of the supplied object or file, or HMAC if a secret diff --git a/man/sha3.Rd b/man/sha3.Rd index 358c1ee..bacfa09 100644 --- a/man/sha3.Rd +++ b/man/sha3.Rd @@ -8,22 +8,21 @@ sha3(x, bits = 256L, convert = TRUE, file) } \arguments{ \item{x}{object to hash. A character string or raw vector (without -attributes) is hashed \sQuote{as is}. All other objects are stream hashed -using R serialization (but without allocation of the serialized object).} +attributes) is hashed \emph{as is}. All other objects are stream hashed +using R serialization (without allocation of the serialized object).} \item{bits}{integer output size of the returned hash. Must be one of 224, 256, 384 or 512.} -\item{convert}{logical TRUE to convert the hash to its hex representation as -a character string, FALSE to return directly as a raw vector, or NA to -return as a vector of (32-bit) integers.} +\item{convert}{logical \code{TRUE} to convert the hash to its hex representation +as a character string, \code{FALSE} to return directly as a raw vector, or \code{NA} +to return as a vector of (32-bit) integers.} -\item{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, hence files larger than memory are permitted.} +\item{file}{character file name / path. If specified, \code{x} is ignored. The +file is stream hashed, and the file can be larger than memory.} } \value{ -A character string, raw or integer vector depending on -\sQuote{convert}. +A character string, raw or integer vector depending on \code{convert}. } \description{ Returns a SHA-3 hash of the supplied object or file. diff --git a/man/shake256.Rd b/man/shake256.Rd index 585b1eb..eb10102 100644 --- a/man/shake256.Rd +++ b/man/shake256.Rd @@ -8,22 +8,21 @@ shake256(x, bits = 256L, convert = TRUE, file) } \arguments{ \item{x}{object to hash. A character string or raw vector (without -attributes) is hashed \sQuote{as is}. All other objects are stream hashed -using R serialization (but without allocation of the serialized object).} +attributes) is hashed \emph{as is}. All other objects are stream hashed +using R serialization (without allocation of the serialized object).} \item{bits}{integer output size of the returned hash. Value must be between 8 and 2^24.} -\item{convert}{logical TRUE to convert the hash to its hex representation as -a character string, FALSE to return directly as a raw vector, or NA to -return as a vector of (32-bit) integers.} +\item{convert}{logical \code{TRUE} to convert the hash to its hex representation +as a character string, \code{FALSE} to return directly as a raw vector, or \code{NA} +to return as a vector of (32-bit) integers.} -\item{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, hence files larger than memory are permitted.} +\item{file}{character file name / path. If specified, \code{x} is ignored. The +file is stream hashed, and the file can be larger than memory.} } \value{ -A character string, raw or integer vector depending on -\sQuote{convert}. +A character string, raw or integer vector depending on \code{convert}. } \description{ Returns a SHAKE256 hash of the supplied object or file. diff --git a/man/siphash13.Rd b/man/siphash13.Rd index 15c70f3..f972c29 100644 --- a/man/siphash13.Rd +++ b/man/siphash13.Rd @@ -8,24 +8,23 @@ siphash13(x, key = NULL, convert = TRUE, file) } \arguments{ \item{x}{object to hash. A character string or raw vector (without -attributes) is hashed \sQuote{as is}. All other objects are stream hashed -using R serialization (but without allocation of the serialized object).} +attributes) is hashed \emph{as is}. All other objects are stream hashed +using R serialization (without allocation of the serialized object).} \item{key}{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 +key data, or else \code{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.} -\item{convert}{logical TRUE to convert the hash to its hex representation as -a character string, FALSE to return directly as a raw vector, or NA to -return as a vector of (32-bit) integers.} +\item{convert}{logical \code{TRUE} to convert the hash to its hex representation +as a character string, \code{FALSE} to return directly as a raw vector, or \code{NA} +to return as a vector of (32-bit) integers.} -\item{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, hence files larger than memory are permitted.} +\item{file}{character file name / path. If specified, \code{x} is ignored. The +file is stream hashed, and the file can be larger than memory.} } \value{ -A character string, raw or integer vector depending on -\sQuote{convert}. +A character string, raw or integer vector depending on \code{convert}. } \description{ Returns a fast, cryptographically-strong SipHash keyed hash of the supplied