README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r}
#| include: false
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  out.width = "100%"
)
```

# secretbase

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/secretbase?color=17411d)](https://CRAN.R-project.org/package=secretbase)
[![secretbase status badge](https://shikokuchuo.r-universe.dev/badges/secretbase)](https://shikokuchuo.r-universe.dev/secretbase)
[![R-CMD-check](https://github.com/shikokuchuo/secretbase/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/shikokuchuo/secretbase/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/shikokuchuo/secretbase/graph/badge.svg)](https://app.codecov.io/gh/shikokuchuo/secretbase)
<!-- badges: end -->

```
  ________  
 /\ sec   \
/  \ ret   \
\  /  base /
 \/_______/
```

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/shikokuchuo/secretbase)

Fast and memory-efficient streaming hash functions, binary/text 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 (including the URL-safe variant) and base58 encoding, ‘CBOR’ and 'JSON' serialization.

| Function | Purpose |
|----------|---------|
| `sha3()` `sha256()` `keccak()` | Cryptographic hashes |
| `shake256()` | Extendable-output function (XOF) |
| `siphash13()` | Keyed, fast pseudo-random function |
| `base64enc()` `base64dec()` | Base64 encoding (incl. URL-safe variant) |
| `base58enc()` `base58dec()` | Base58 encoding with checksum |
| `cborenc()` `cbordec()` | CBOR serialization |
| `jsonenc()` `jsondec()`        | JSON 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. <sup>[1]</sup>

#### 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)
```

Set `url = TRUE` for the URL- and filename-safe variant (RFC 4648 section 5), which uses the `-` and `_` alphabet without padding:
```{r}
#| label: base64url
base64enc("secret base", url = TRUE)
base64dec(base64enc("secret base", url = TRUE), url = TRUE)
```

#### 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)))
```

#### JSON

Minimal JSON encoder/decoder for HTTP API request/response bodies:

```{r}
jsonenc(list(name = "John", age = 30L, active = TRUE))
jsondec('{"name": "John", "age": 30, "active": 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 <https://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf>.

The SHA-256, SHA-3, Keccak, and base64 implementations are based on those by the 'Mbed TLS' Trusted Firmware Project at <https://www.trustedfirmware.org/projects/mbed-tls>.

The SipHash family of pseudo-random functions by Jean-Philippe Aumasson and Daniel J. Bernstein was published in 2012 at <https://ia.cr/2012/351>. <sup>[2]</sup>

The SipHash implementation is based on that of Daniele Nicolodi, David Rheinsberg and Tom Gundersen at <https://github.com/c-util/c-siphash>, which is in turn based on the reference implementation by Jean-Philippe Aumasson and Daniel J. Bernstein released to the public domain at <https://github.com/veorq/SipHash>.

The base58 implementation is based on 'libbase58' by Luke Dashjr at <https://github.com/luke-jr/libbase58>.

The CBOR implementation follows RFC 8949, *"Concise Binary Object Representation (CBOR)"*, available at <https://www.rfc-editor.org/rfc/rfc8949>.

The JSON implementation is not fully compliant with RFC 8259, *"The JavaScript Object Notation (JSON) Data Interchange Format"*, available at <https://www.rfc-editor.org/rfc/rfc8259>.

### 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, <https://ia.cr/2012/351>.

### Links

◈ secretbase R package: <https://shikokuchuo.net/secretbase/>

Mbed TLS website: <https://www.trustedfirmware.org/projects/mbed-tls><br />
SipHash streaming implementation: <https://github.com/c-util/c-siphash><br />
SipHash reference implementation: <https://github.com/veorq/SipHash><br />
libbase58: <https://github.com/luke-jr/libbase58><br />
CBOR RFC 8949: <https://www.rfc-editor.org/rfc/rfc8949><br />
JSON RFC 8259: <https://www.rfc-editor.org/rfc/rfc8259>

--

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.