-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
178 lines (126 loc) · 6.37 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
---
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 -->
[](https://CRAN.R-project.org/package=secretbase)
[](https://community.r-multiverse.org/secretbase)
[](https://shikokuchuo.r-universe.dev/secretbase)
[](https://github.com/shikokuchuo/secretbase/actions)
[](https://app.codecov.io/gh/shikokuchuo/secretbase)
[](https://zenodo.org/doi/10.5281/zenodo.10553139)
<!-- badges: end -->
```
________
/\ sec \
/ \ ret \
\ / base /
\/_______/
```
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.
Implementations include the SHA-256, SHA-3 and 'Keccak' cryptographic hash functions, SHAKE256 extendable-output function (XOF), and 'SipHash' pseudo-random function.
### Overview
```{r secretbase}
library(secretbase)
```
#### SHA-3
For the SHA-3 cryptographic hash algorithm, specify `bits` as one of `224`, `256`, `384` or `512`:
```{r sha3}
sha3("secret base")
sha3("secret base", convert = FALSE)
sha3("秘密の基地の中", bits = 512L)
```
#### Hash strings and raw vectors
Character strings and raw vectors are hashed directly (as above).
#### Stream hash R objects
All other objects are stream hashed using R serialization
- memory-efficient as performed without allocation of the serialized object
- portable as always uses R serialization version 3, big-endian representation, skipping headers (which contain R version and native encoding information)
```{r streaming}
sha3(data.frame(a = 1, b = 2), bits = 224L)
sha3(NULL)
```
#### Stream hash files
Files are read and hashed incrementally, accepting files larger than memory:
```{r files}
file <- tempfile(); cat("secret base", file = file)
sha3(file = file)
```
```{r unlink, echo=FALSE}
unlink(file)
```
#### Hash to integer / SHAKE256 XOF
May be used as deterministic random seeds for R's pseudo random number generators (RNGs). <br />
Specify `convert = NA` and `bits = 32` for a single integer value:
```{r integer}
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>
#### Keccak
```{r keccak}
keccak("secret base", bits = 384L)
```
#### SHA-256
```{r sha256}
sha256("secret base")
```
For SHA-256 HMAC, pass to `key` a character string or raw vector:
```{r hmac}
sha256("secret base", key = "秘密の基地の中")
```
#### SipHash
SipHash-1-3 is optimized for performance. <br />
Pass to `key` a character string or raw vector of up to 16 bytes (128 bits):
```{r siphash}
siphash13("secret base", key = charToRaw("秘密の基地の中"))
```
#### Base64 Encoding / Decoding
Strings:
```{r base64str}
base64enc("secret base")
base64dec(base64enc("secret base"))
```
Raw vectors:
```{r base64raw}
base64enc(as.raw(c(1L, 2L, 4L)), convert = FALSE)
base64dec(base64enc(as.raw(c(1L, 2L, 4L))), convert = FALSE)
```
Serialized objects:
```{r base64ser}
base64enc(data.frame())
base64dec(base64enc(data.frame()), convert = NA)
```
### Installation
Install the latest release from CRAN or R-multiverse:
```{r cran, eval=FALSE}
install.packages("secretbase")
```
The current development version is available from R-universe:
```{r runiv, eval=FALSE}
install.packages("secretbase", repos = "https://shikokuchuo.r-universe.dev")
```
### 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>.
### 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>
--
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.