From 6a5a2178d65c149848db14b08d797166e750b248 Mon Sep 17 00:00:00 2001 From: shikokuchuo <53399081+shikokuchuo@users.noreply.github.com> Date: Wed, 15 Jan 2025 23:58:32 +0000 Subject: [PATCH] use roxygen2 md --- DESCRIPTION | 1 + R/base.R | 26 ++++++++++---------- R/secret.R | 51 ++++++++++++++++++--------------------- README.md | 2 +- man/base64dec.Rd | 12 ++++----- man/base64enc.Rd | 14 +++++------ man/keccak.Rd | 15 ++++++------ man/secretbase-package.Rd | 2 +- man/sha256.Rd | 18 ++++++-------- man/sha3.Rd | 15 ++++++------ man/shake256.Rd | 15 ++++++------ man/siphash13.Rd | 20 +++++++-------- 12 files changed, 91 insertions(+), 100 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index dd7790a..f0a6700 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -24,4 +24,5 @@ Encoding: UTF-8 Depends: R (>= 3.5) RoxygenNote: 7.3.2 +Roxygen: list(markdown = TRUE) Config/build/compilation-database: true diff --git a/R/base.R b/R/base.R index 7732ec6..2c9a736 100644 --- a/R/base.R +++ b/R/base.R @@ -1,4 +1,4 @@ -# Copyright (C) 2024 Hibiki AI Limited +# Copyright (C) 2024-2025 Hibiki AI Limited # # This file is part of secretbase. # @@ -20,13 +20,13 @@ #' #' Encodes a character string, raw vector or other object to base64 encoding. #' -#' A character string or raw vector (with no attributes) is encoded -#' \emph{as is}, whilst all other objects are first serialized (using R -#' serialisation version 3, big-endian representation). +#' A character string or raw vector (with no attributes) is encoded *as is*, +#' whilst all other objects are first serialized (using R serialisation version +#' 3, big-endian representation). #' #' @param x an object. -#' @param convert [default TRUE] 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}. @@ -34,9 +34,9 @@ #' @references #' This implementation is based that by 'The Mbed TLS Contributors' under the #' 'Mbed TLS' Trusted Firmware Project at -#' \url{https://www.trustedfirmware.org/projects/mbed-tls}. +#' . #' -#' @seealso \code{\link{base64dec}} +#' @seealso [base64dec()] #' #' @examples #' base64enc("secret base") @@ -56,9 +56,9 @@ base64enc <- function(x, convert = TRUE) .Call(secretbase_base64enc, x, convert) #' objects), in order to return the original object. #' #' @param x an object. -#' @param convert [default TRUE] 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 @@ -67,9 +67,9 @@ base64enc <- function(x, convert = TRUE) .Call(secretbase_base64enc, x, convert) #' @references #' This implementation is based that by 'The Mbed TLS Contributors' under the #' 'Mbed TLS' Trusted Firmware Project at -#' \url{https://www.trustedfirmware.org/projects/mbed-tls}. +#' . #' -#' @seealso \code{\link{base64enc}} +#' @seealso [base64enc()] #' #' @examples #' base64dec(base64enc("secret base")) diff --git a/R/secret.R b/R/secret.R index 148d78d..84619cb 100644 --- a/R/secret.R +++ b/R/secret.R @@ -27,7 +27,7 @@ #' #' @encoding UTF-8 #' @author Charlie Gao \email{charlie.gao@@shikokuchuo.net} -#' (\href{https://orcid.org/0000-0002-0750-061X}{ORCID}) +#' ([ORCID](https://orcid.org/0000-0002-0750-061X)) #' #' @useDynLib secretbase, .registration = TRUE #' @@ -42,14 +42,13 @@ #' @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). -#' @param bits [default 256L] output size of the returned hash. Must be one of -#' 224, 256, 384 or 512. -#' @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 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, thus capable of handling files larger than -#' memory. +#' The file is stream hashed, hence files larger than memory are permitted. #' #' @return A character string, raw or integer vector depending on #' \sQuote{convert}. @@ -66,7 +65,7 @@ #' #' 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 #' # SHA3-256 hash as character string: @@ -104,8 +103,8 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file) #' \sQuote{convert} to NA. #' #' @inheritParams sha3 -#' @param bits [default 256L] output size of the returned hash. Must be between -#' 8 and 2^24 and coercible to integer. +#' @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}. @@ -115,7 +114,7 @@ sha3 <- function(x, bits = 256L, convert = TRUE, file) #' @references #' 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: @@ -158,7 +157,7 @@ shake256 <- function(x, bits = 256L, convert = TRUE, file) #' #' 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 #' # Keccak-256 hash as character string: @@ -193,10 +192,9 @@ keccak <- function(x, bits = 256L, convert = TRUE, file) #' key is supplied. #' #' @inheritParams sha3 -#' @param key [default NULL] If NULL, the SHA-256 hash of \sQuote{x} is -#' returned. Alternatively, supply a character string or raw vector 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 \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. #' #' @return A character string, raw or integer vector depending on #' \sQuote{convert}. @@ -206,11 +204,11 @@ keccak <- function(x, bits = 256L, convert = TRUE, file) #' @references #' 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 one by '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: @@ -243,11 +241,10 @@ sha256 <- function(x, key = NULL, convert = TRUE, file) #' not a cryptographic hash algorithm. #' #' @inheritParams sha3 -#' @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. +#' @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 +#' 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}. @@ -258,14 +255,14 @@ sha256 <- function(x, key = NULL, convert = TRUE, file) #' 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}. This is in turn based on the +#' . This is in turn based on the #' SipHash reference implementation by Jean-Philippe Aumasson and Daniel J. #' Bernstein released to the public domain at -#' \url{https://github.com/veorq/SipHash}. +#' . #' #' @examples #' # SipHash-1-3 hash as character string: diff --git a/README.md b/README.md index f838b6f..80143c3 100644 --- a/README.md +++ b/README.md @@ -158,7 +158,7 @@ Serialized objects: ``` r base64enc(data.frame()) -#> [1] "WAoAAAADAAQEAQADBQAAAAAFVVRGLTgAAAMTAAAAAAAABAIAAAABAAQACQAAAAVuYW1lcwAAABAAAAAAAAAEAgAAAAEABAAJAAAACXJvdy5uYW1lcwAAAA0AAAAAAAAEAgAAAAEABAAJAAAABWNsYXNzAAAAEAAAAAEABAAJAAAACmRhdGEuZnJhbWUAAAD+" +#> [1] "WAoAAAADAAQEAgADBQAAAAAFVVRGLTgAAAMTAAAAAAAABAIAAAABAAQACQAAAAVuYW1lcwAAABAAAAAAAAAEAgAAAAEABAAJAAAACXJvdy5uYW1lcwAAAA0AAAAAAAAEAgAAAAEABAAJAAAABWNsYXNzAAAAEAAAAAEABAAJAAAACmRhdGEuZnJhbWUAAAD+" base64dec(base64enc(data.frame()), convert = NA) #> data frame with 0 columns and 0 rows ``` diff --git a/man/base64dec.Rd b/man/base64dec.Rd index 4e19b0c..6b4d940 100644 --- a/man/base64dec.Rd +++ b/man/base64dec.Rd @@ -9,14 +9,14 @@ base64dec(x, convert = TRUE) \arguments{ \item{x}{an object.} -\item{convert}{[default TRUE] 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 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.} } \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 \sQuote{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. @@ -38,5 +38,5 @@ This implementation is based that by 'The Mbed TLS Contributors' under the \url{https://www.trustedfirmware.org/projects/mbed-tls}. } \seealso{ -\code{\link{base64enc}} +\code{\link[=base64enc]{base64enc()}} } diff --git a/man/base64enc.Rd b/man/base64enc.Rd index d655e70..73d5531 100644 --- a/man/base64enc.Rd +++ b/man/base64enc.Rd @@ -9,20 +9,20 @@ base64enc(x, convert = TRUE) \arguments{ \item{x}{an object.} -\item{convert}{[default TRUE] logical TRUE to encode to a character string or -FALSE to a raw vector.} +\item{convert}{logical TRUE to encode to a character string or FALSE to a raw +vector.} } \value{ A character string or raw vector depending on the value of - \sQuote{convert}. +\sQuote{convert}. } \description{ Encodes a character string, raw vector or other object to base64 encoding. } \details{ -A character string or raw vector (with no attributes) is encoded -\emph{as is}, whilst all other objects are first serialized (using R -serialisation version 3, big-endian representation). +A character string or raw vector (with no attributes) is encoded \emph{as is}, +whilst all other objects are first serialized (using R serialisation version +3, big-endian representation). } \examples{ base64enc("secret base") @@ -36,5 +36,5 @@ This implementation is based that by 'The Mbed TLS Contributors' under the \url{https://www.trustedfirmware.org/projects/mbed-tls}. } \seealso{ -\code{\link{base64dec}} +\code{\link[=base64dec]{base64dec()}} } diff --git a/man/keccak.Rd b/man/keccak.Rd index 5eedcfd..3dbfac9 100644 --- a/man/keccak.Rd +++ b/man/keccak.Rd @@ -11,20 +11,19 @@ keccak(x, bits = 256L, convert = TRUE, file) attributes) is hashed \sQuote{as is}. All other objects are stream hashed using R serialization (but without allocation of the serialized object).} -\item{bits}{[default 256L] output size of the returned hash. Must be one of -224, 256, 384 or 512.} +\item{bits}{integer output size of the returned hash. Must be one of 224, +256, 384 or 512.} -\item{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.} +\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{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, thus capable of handling files larger than -memory.} +The file is stream hashed, hence files larger than memory are permitted.} } \value{ A character string, raw or integer vector depending on - \sQuote{convert}. +\sQuote{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 be6ff20..00f5fce 100644 --- a/man/secretbase-package.Rd +++ b/man/secretbase-package.Rd @@ -25,5 +25,5 @@ Useful links: } \author{ Charlie Gao \email{charlie.gao@shikokuchuo.net} - (\href{https://orcid.org/0000-0002-0750-061X}{ORCID}) +(\href{https://orcid.org/0000-0002-0750-061X}{ORCID}) } diff --git a/man/sha256.Rd b/man/sha256.Rd index 5beab90..b9a23ea 100644 --- a/man/sha256.Rd +++ b/man/sha256.Rd @@ -11,22 +11,20 @@ sha256(x, key = NULL, convert = TRUE, file) attributes) is hashed \sQuote{as is}. All other objects are stream hashed using R serialization (but without allocation of the serialized object).} -\item{key}{[default NULL] If NULL, the SHA-256 hash of \sQuote{x} is -returned. Alternatively, supply a character string or raw vector as a -secret key to generate an HMAC. Note: for character vectors, only the first -element is used.} +\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{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.} +\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{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, thus capable of handling files larger than -memory.} +The file is stream hashed, hence files larger than memory are permitted.} } \value{ A character string, raw or integer vector depending on - \sQuote{convert}. +\sQuote{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 591dea2..358c1ee 100644 --- a/man/sha3.Rd +++ b/man/sha3.Rd @@ -11,20 +11,19 @@ sha3(x, bits = 256L, convert = TRUE, file) attributes) is hashed \sQuote{as is}. All other objects are stream hashed using R serialization (but without allocation of the serialized object).} -\item{bits}{[default 256L] output size of the returned hash. Must be one of -224, 256, 384 or 512.} +\item{bits}{integer output size of the returned hash. Must be one of 224, +256, 384 or 512.} -\item{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.} +\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{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, thus capable of handling files larger than -memory.} +The file is stream hashed, hence files larger than memory are permitted.} } \value{ A character string, raw or integer vector depending on - \sQuote{convert}. +\sQuote{convert}. } \description{ Returns a SHA-3 hash of the supplied object or file. diff --git a/man/shake256.Rd b/man/shake256.Rd index a048e97..585b1eb 100644 --- a/man/shake256.Rd +++ b/man/shake256.Rd @@ -11,20 +11,19 @@ shake256(x, bits = 256L, convert = TRUE, file) attributes) is hashed \sQuote{as is}. All other objects are stream hashed using R serialization (but without allocation of the serialized object).} -\item{bits}{[default 256L] output size of the returned hash. Must be between -8 and 2^24 and coercible to integer.} +\item{bits}{integer output size of the returned hash. Value must be between 8 +and 2^24.} -\item{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.} +\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{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, thus capable of handling files larger than -memory.} +The file is stream hashed, hence files larger than memory are permitted.} } \value{ A character string, raw or integer vector depending on - \sQuote{convert}. +\sQuote{convert}. } \description{ Returns a SHAKE256 hash of the supplied object or file. diff --git a/man/siphash13.Rd b/man/siphash13.Rd index a1001d9..15c70f3 100644 --- a/man/siphash13.Rd +++ b/man/siphash13.Rd @@ -11,23 +11,21 @@ siphash13(x, key = NULL, convert = TRUE, file) attributes) is hashed \sQuote{as is}. All other objects are stream hashed using R serialization (but without allocation of the serialized object).} -\item{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.} +\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 +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}{[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.} +\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{file}{character file name / path. If specified, \sQuote{x} is ignored. -The file is stream hashed, thus capable of handling files larger than -memory.} +The file is stream hashed, hence files larger than memory are permitted.} } \value{ A character string, raw or integer vector depending on - \sQuote{convert}. +\sQuote{convert}. } \description{ Returns a fast, cryptographically-strong SipHash keyed hash of the supplied