https://github.com/shikokuchuo/secretbase
secretbase - Cryptographic Hash and Extendable-Output Functions
https://github.com/shikokuchuo/secretbase
cran cryptographic-hash-functions extendable-output-functions keccak r r-package rstats sha256 sha3 shake256 siphash
Last synced: 7 months ago
JSON representation
secretbase - Cryptographic Hash and Extendable-Output Functions
- Host: GitHub
- URL: https://github.com/shikokuchuo/secretbase
- Owner: shikokuchuo
- License: gpl-3.0
- Created: 2024-01-19T22:08:33.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-15T16:15:34.000Z (about 2 years ago)
- Last Synced: 2024-05-17T03:45:17.001Z (about 2 years ago)
- Topics: cran, cryptographic-hash-functions, extendable-output-functions, keccak, r, r-package, rstats, sha256, sha3, shake256, siphash
- Language: C
- Homepage: https://shikokuchuo.net/secretbase/
- Size: 899 KB
- Stars: 7
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
---
output: github_document
---
```{r}
#| include: false
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
out.width = "100%"
)
```
# secretbase
[](https://CRAN.R-project.org/package=secretbase)
[](https://shikokuchuo.r-universe.dev/secretbase)
[](https://github.com/shikokuchuo/secretbase/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/shikokuchuo/secretbase)
```
________
/\ sec \
/ \ ret \
\ / base /
\/_______/
```
Fast and memory-efficient streaming hash functions, binary encoding and serialization.
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.
Implements the SHA-256, SHA-3 and 'Keccak' cryptographic hash functions, SHAKE256 extendable-output function (XOF), 'SipHash' pseudo-random function, base64 and base58 encoding, and 'CBOR' serialization.
| Function | Purpose |
|----------|---------|
| `sha3()` `sha256()` `keccak()` | Cryptographic hashes |
| `shake256()` | Extendable-output function (XOF) |
| `siphash13()` | Keyed, fast pseudo-random function |
| `base64enc()` `base64dec()` | Base64 encoding |
| `base58enc()` `base58dec()` | Base58 encoding with checksum |
| `cborenc()` `cbordec()` | CBOR serialization |
### Installation
```{r}
#| label: cran
#| eval: false
install.packages("secretbase")
```
### Get Started
```{r}
#| label: secretbase
library(secretbase)
```
### Hash Functions
#### SHA-3
Specify `bits` as `224`, `256`, `384` or `512`:
```{r}
#| label: sha3
sha3("secret base")
sha3("secret base", convert = FALSE)
sha3("秘密の基地の中", bits = 512L)
```
#### SHA-256
```{r}
#| label: sha256
sha256("secret base")
```
For HMAC, pass a character string or raw vector to `key`:
```{r}
#| label: hmac
sha256("secret base", key = "秘密の基地の中")
```
#### Keccak
```{r}
#| label: keccak
keccak("secret base", bits = 384L)
```
#### SHAKE256
An extendable-output function (XOF). Specify arbitrary `bits`. May be used as deterministic random seeds for R's pseudo random number generators (RNGs) - use `convert = NA` for integer output:
```{r}
#| label: shake256
shake256("秘密の基地の中", bits = 32L, 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. [1]
#### SipHash
SipHash-1-3 is a fast, keyed pseudo-random function. Pass to `key` up to 16 bytes (128 bits):
```{r}
#| label: siphash
siphash13("secret base", key = "秘密の基地の中")
```
### Streaming
All hash functions above support streaming of R objects and files.
#### R Objects
Character strings and raw vectors are hashed directly. All other objects are stream hashed using R serialization:
- memory-efficient as performed without allocation of the serialized object
- portable as uses serialization version 3, big-endian representation, skipping headers
```{r}
#| label: streaming
sha3(data.frame(a = 1, b = 2), bits = 224L)
sha3(NULL)
```
#### Files
Files are read and hashed incrementally, accepting files larger than memory:
```{r}
#| label: files
file <- tempfile(); cat("secret base", file = file)
sha3(file = file)
```
```{r}
#| label: unlink
#| echo: false
unlink(file)
```
### Encoding
#### Base64
```{r}
#| label: base64
base64enc("secret base")
base64dec(base64enc("secret base"))
base64enc(as.raw(c(1L, 2L, 4L)), convert = FALSE)
base64dec(base64enc(data.frame()), convert = NA)
```
#### Base58
Includes a 4-byte checksum (double SHA-256), verified on decode:
```{r}
#| label: base58
base58enc("secret base")
base58dec(base58enc("secret base"))
base58enc(as.raw(c(1L, 2L, 4L)), convert = FALSE)
base58dec(base58enc(data.frame()), convert = NA)
```
### Serialization
#### CBOR
Encode R objects to CBOR (RFC 8949) - a compact binary format. Supports integers, doubles, strings, raw vectors, logical, NULL, and lists (named lists become maps):
```{r}
#| label: cbor
cborenc(list(a = 1L, b = "hello", c = TRUE))
cbordec(cborenc(list(a = 1L, b = "hello", c = TRUE)))
```
### Implementation
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). SHA-3 is based on the Keccak algorithm, designed by G. Bertoni, J. Daemen, M. Peeters and G. Van Assche.
The SHA-256 Secure Hash Standard was published by NIST in 2002 at .
The SHA-256, SHA-3, Keccak, and base64 implementations are based on those by the 'Mbed TLS' Trusted Firmware Project at .
The SipHash family of pseudo-random functions by Jean-Philippe Aumasson and Daniel J. Bernstein was published in 2012 at . [2]
The SipHash implementation is based on that of Daniele Nicolodi, David Rheinsberg and Tom Gundersen at , which is in turn based on the reference implementation by Jean-Philippe Aumasson and Daniel J. Bernstein released to the public domain at .
The base58 implementation is based on 'libbase58' by Luke Dashjr at .
The CBOR implementation follows RFC 8949, *"Concise Binary Object Representation (CBOR)"*, available at .
### References
[1] Pierre L’Ecuyer, David Munger, Boris Oreshkin and Richard Simard (2017), *"Random numbers for parallel computers: Requirements and methods, with emphasis on GPUs"*, Mathematics and Computers in Simulation, Vol. 135, May 2017, pp. 3-17 [doi:10.1016/j.matcom.2016.05.00](https://doi.org/10.1016/j.matcom.2016.05.005).
[2] Jean-Philippe Aumasson and Daniel J. Bernstein (2012), *"SipHash: a fast short-input PRF"*, Paper 2012/351, Cryptology ePrint Archive, .
### Links
◈ secretbase R package:
Mbed TLS website:
SipHash streaming implementation:
SipHash reference implementation:
libbase58:
CBOR RFC 8949:
--
Please note that this project is released with a [Contributor Code of Conduct](https://shikokuchuo.net/secretbase/CODE_OF_CONDUCT.html). By participating in this project you agree to abide by its terms.