Skip to content

Commit 9333863

Browse files
kernelmethodkernelmethod
committed
Add homepage content to the documentation
Add some basic content about the package and how it should be used to the documentation's homepage. Run doctests alongside unit tests.
1 parent cf4b8ce commit 9333863

File tree

7 files changed

+170
-16
lines changed

7 files changed

+170
-16
lines changed

‎README.md

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,15 @@
55
[![Build Status](https://github.com/kernelmethod/ChaChaCiphers.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/kernelmethod/ChaChaCiphers.jl/actions/workflows/CI.yml?query=branch%3Amain)
66
[![Coverage](https://codecov.io/gh/kernelmethod/ChaChaCiphers.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/kernelmethod/ChaChaCiphers.jl)
77

8-
`ChaChaCiphers` is a Julia package that provides a CUDA-compatible
9-
implementation of the ChaCha stream cipher family, and implements the
10-
`Random.AbstractDevice` interface to use ChaCha for cryptographically secure
11-
random number generation (CRNG).
12-
13-
This package seeks to accomplish the following goals:
14-
15-
- Provide performant and reproducible CRNG for CPU and GPU computations
16-
- Implement basic cryptographic primitives that can be used as a building block
17-
in higher-level cryptographic code (e.g. for building ChaCha20-Poly1305).
8+
[ChaChaCiphers](https://github.com/kernelmethod/ChaChaCiphers.jl) is a
9+
CUDA-compatible, pure-Julia implementation of the ChaCha family of stream
10+
ciphers. This package provides:
11+
12+
- fast, cryptographically-secure, and reproducible random number generators
13+
implementing Julia's `AbstractRNG` interface for both CPU and GPU, and
14+
- implementations of ChaCha stream ciphers such as ChaCha20 that can be used as
15+
building blocks for other cryptographic primitives, such as the
16+
ChaCha20-Poly1305 AEAD algorithm.
1817

1918
## Usage
2019

‎docs/make.jl

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ makedocs(;
1515
),
1616
pages=[
1717
"Home" => "index.md",
18+
"API" => "api.md",
1819
],
1920
)
2021

‎docs/src/api.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# API
2+
3+
```@index
4+
```
5+
6+
```@meta
7+
CurrentModule = ChaChaCiphers
8+
```
9+
10+
```@autodocs
11+
Modules = [ChaChaCiphers]
12+
```

‎docs/src/index.md

Lines changed: 124 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,132 @@
1+
# ChaChaCiphers
2+
3+
[ChaChaCiphers](https://github.com/kernelmethod/ChaChaCiphers.jl) is a
4+
CUDA-compatible, pure-Julia implementation of the ChaCha family of stream
5+
ciphers. This package provides:
6+
7+
- fast, cryptographically-secure, and reproducible random number generators
8+
implementing Julia's `AbstractRNG` interface for both CPU and GPU, and
9+
- implementations of ChaCha stream ciphers such as ChaCha20 that can be used as
10+
building blocks for other cryptographic primitives, such as ChaCha20-Poly1305.
11+
12+
!!! warning
13+
ChaCha is not sufficient by itself for encrypting data, and misuse can
14+
compromise application security. Please review [the warnings
15+
section](#warnings-and-disclaimers) for more details.
16+
17+
## Basic usage
18+
119
```@meta
2-
CurrentModule = ChaChaCiphers
20+
DocTestSetup = quote
21+
using ChaChaCiphers
22+
key = UInt32.([
23+
0xe2e39848, 0x70bb974d, 0x845f88b4, 0xb30725e4,
24+
0x15c309dc, 0x72d545bb, 0x466e99e3, 0x6a759f91
25+
]);
26+
nonce = UInt64(0);
27+
rng = ChaCha20Stream(key, nonce);
28+
end
329
```
430

5-
# ChaChaCiphers
31+
To start generating random numbers with ChaChaCiphers, create a new keystream
32+
with a function like [`ChaCha20Stream`](@ref) or [`ChaCha12Stream`](@ref):
33+
34+
```jldoctest
35+
julia> using ChaChaCiphers
636
7-
Documentation for [ChaChaCiphers](https://github.com/kernelmethod/ChaChaCiphers.jl).
37+
julia> rng = ChaCha20Stream();
38+
```
39+
40+
This will generate a keystream using a key sampled from the operating system's
41+
random stream. Alternatively, you can explicitly specify a `key` and `nonce` as
42+
follows:
43+
44+
```jldoctest
45+
julia> key = UInt32.([
46+
0xe2e39848, 0x70bb974d, 0x845f88b4, 0xb30725e4,
47+
0x15c309dc, 0x72d545bb, 0x466e99e3, 0x6a759f91
48+
]);
49+
50+
julia> nonce = UInt64(0);
851
9-
```@index
52+
julia> rng = ChaCha20Stream(key, nonce);
1053
```
1154

12-
```@autodocs
13-
Modules = [ChaChaCiphers]
55+
After generating a keystream, you can supply it as the `rng` parameter to
56+
`Random` functions like `rand` and `randn`:
57+
58+
```jldoctest
59+
julia> using Random
60+
61+
julia> rand(rng, 1:10)
62+
3
63+
64+
julia> randn(rng, Float32, 3)
65+
3-element Vector{Float32}:
66+
-0.50947624
67+
-0.9306026
68+
-0.084067896
1469
```
70+
71+
Review the API documentation for more details.
72+
73+
## About ChaCha
74+
75+
ChaCha was first introduced as a variant of the Salsa20 stream cipher by Daniel
76+
Bernstein in 2008[^Bernstein08]. ChaCha produces a stream of 512-bit blocks that
77+
act as a CRNG seeded with a key and nonce.
78+
79+
ChaCha is used as the basis for the Linux kernel's CRNG[^LWN16]. It is one of
80+
the two major components of the ChaCha20-Poly1305 Authenticated Encryption with
81+
Associated Data (AEAD) algorithm specified by IETF RFC 8439[^RFC8439], which in
82+
turn is used by [TLS](https://datatracker.ietf.org/doc/html/rfc7905),
83+
[OpenSSH](http://bxr.su/OpenBSD/usr.bin/ssh/PROTOCOL.chacha20poly1305),
84+
[Wireguard](https://www.wireguard.com/protocol/), and more.
85+
86+
ChaCha makes it easy to seek to any given portion of the keystream, which allows
87+
extremely efficient parallel computation on CPU and GPU. It can also be computed
88+
in constant time very efficiently in software, whereas comparable symmetric
89+
ciphers (e.g. AES-CTR) require hardware support to achieve the same performance.
90+
91+
[^Bernstein08]:
92+
"ChaCha, a variant of Salsa20":
93+
[https://cr.yp.to/chacha/chacha-20080128.pdf](https://cr.yp.to/chacha/chacha-20080128.pdf)
94+
95+
[^LWN16]:
96+
"Replacing /dev/urandom":
97+
[https://lwn.net/Articles/686033/](https://lwn.net/Articles/686033/)
98+
99+
[^RFC8439]:
100+
[IETF RFC 8439](https://datatracker.ietf.org/doc/html/rfc8439)
101+
102+
## Warnings and disclaimers
103+
104+
### Security
105+
106+
ChaCha is not by itself sufficient to keep your data secure. In particular, it
107+
doesn't provide any guarantees of data integrity or authenticity, and the
108+
ciphertexts it produces are
109+
[malleable](https://en.wikipedia.org/wiki/Malleability_%28cryptography%29_).
110+
111+
Most likely, if you are looking for an algorithm to encrypt your data, you'll
112+
want an [AEAD algorithm](https://en.wikipedia.org/wiki/Authenticated_encryption)
113+
such as [ChaCha20-Poly1305](https://datatracker.ietf.org/doc/html/rfc8439) or
114+
[AES-GCM](https://datatracker.ietf.org/doc/html/rfc8452).
115+
116+
This package has not received a formal security analysis from an external party.
117+
Please use with caution.
118+
119+
### Alternatives
120+
121+
If you don't strictly need a cryptographically secure random number generator,
122+
you should consider using [Julia's built-in
123+
RNG](https://docs.julialang.org/en/v1/stdlib/Random/), which as of v1.7 uses
124+
[Xoshiro256++](https://prng.di.unimi.it/) and can easily beat ChaCha by an order
125+
of magnitude or more in speed.
126+
127+
Alternatively, if you need a CRNG but don't care about reproducibility, you may
128+
wish to consider using
129+
[`RandomDevice`](https://docs.julialang.org/en/v1/stdlib/Random/#Random.RandomDevice)
130+
from Julia's standard library, which pulls from the operating system's random
131+
stream. In practice however [`ChaChaStream`](@ref) may be much faster than using
132+
`RandomDevice`.

‎test/Manifest.toml

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@
33
julia_version = "1.7.2"
44
manifest_format = "2.0"
55

6+
[[deps.ANSIColoredPrinters]]
7+
git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c"
8+
uuid = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
9+
version = "0.0.1"
10+
611
[[deps.AbstractFFTs]]
712
deps = ["ChainRulesCore", "LinearAlgebra"]
813
git-tree-sha1 = "6f1d9bc1c08f9f4a8fa92e3ea3cb50153a1b40d4"
@@ -87,6 +92,12 @@ git-tree-sha1 = "b19534d1895d702889b219c382a6e18010797f0b"
8792
uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
8893
version = "0.8.6"
8994

95+
[[deps.Documenter]]
96+
deps = ["ANSIColoredPrinters", "Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
97+
git-tree-sha1 = "122d031e8dcb2d3e767ed434bc4d1ae1788b5a7f"
98+
uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
99+
version = "0.27.17"
100+
90101
[[deps.Downloads]]
91102
deps = ["ArgTools", "LibCURL", "NetworkOptions"]
92103
uuid = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
@@ -108,6 +119,12 @@ git-tree-sha1 = "556190e1e0ea3e37d83059fc9aa576f1e2104375"
108119
uuid = "61eb1bfa-7361-4325-ad38-22787b887f55"
109120
version = "0.14.1"
110121

122+
[[deps.IOCapture]]
123+
deps = ["Logging", "Random"]
124+
git-tree-sha1 = "f7be53659ab06ddc986428d3a9dcc95f6fa6705a"
125+
uuid = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
126+
version = "0.2.2"
127+
111128
[[deps.InteractiveUtils]]
112129
deps = ["Markdown"]
113130
uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"

‎test/Project.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
[deps]
22
BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
33
CUDA = "052768ef-5323-5732-b1bb-66c8b64840ba"
4+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
45
Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
56
StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
67
Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"

‎test/runtests.jl

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
using ChaChaCiphers, Documenter, Test
2+
13
include("test_core.jl")
24
include("test_chacha.jl")
35
include("test_keystream.jl")
6+
7+
@testset "Package doctests" begin
8+
doctest(ChaChaCiphers; manual=false)
9+
end

0 commit comments

Comments
 (0)