Fix a bug in keystream construction

Fix a small bug where the `doublerounds` keyword argument does not get
propagated when no other arguments are provided.

Add a little more documentation for ChaChaStream.

Author: kernelmethod

src/core.jl

@@ -65,7 +65,7 @@ abstract type AbstractChaChaStream <: AbstractRNG end
 # Constructors
 
 (::Type{T})(; kws...) where {T <: AbstractChaChaStream} =
-    T(SVector{8,UInt32}(rand(RandomDevice(), UInt32, 8)))
+    T(SVector{8,UInt32}(rand(RandomDevice(), UInt32, 8)); kws...)
 (::Type{T})(key; kws...) where {T <: AbstractChaChaStream} =
     T(key, UInt64(0); kws...)
 (::Type{T})(state::ChaChaState) where {T <: AbstractChaChaStream} =

src/keystream.jl

@@ -4,10 +4,47 @@ using StaticArrays
 using ChaChaCiphers.ChaCha
 
 """
-    ChaChaStream
+    ChaChaStream <: AbstractChaChaStream
 
-A cryptographically secure pseudo-random number generator
-(CRNG) based on the ChaCha stream cipher.
+`ChaChaStream` provides access to the keystream generated by the
+ChaCha stream cipher. It can be used as a cryptographically
+secure random number generator (CRNG) for Julia's random number
+generation functions.
+
+## Examples
+
+Create a `ChaChaStream` with a randomly-generated key and nonce:
+
+```@meta
+DocTestSetup = quote
+    using ChaChaCiphers
+    using Random
+end
+```
+
+```jldoctest
+julia> stream = ChaCha20Stream();
+```
+
+Create a `ChaChaStream` with a pre-specified key and nonce, and
+use it to generate random data:
+
+```jldoctest
+julia> key = UInt32.([
+          0xe2e39848, 0x70bb974d, 0x845f88b4, 0xb30725e4,
+          0x15c309dc, 0x72d545bb, 0x466e99e3, 0x6a759f91
+       ]);
+
+julia> nonce = UInt64(1234);
+
+julia> stream = ChaCha20Stream(key, nonce);
+
+julia> randn(stream)
+0.7689072580509484
+
+julia> randstring(stream, 'a':'z', 8)
+"klmptewr"
+```
 """
 mutable struct ChaChaStream <: AbstractChaChaStream
     key :: SVector{8,UInt32}
@@ -24,7 +61,7 @@ mutable struct ChaChaStream <: AbstractChaChaStream
         position = 1;
         doublerounds = 10
     )
-        if doublerounds < 0 || !iseven(doublerounds)
+        if doublerounds ≤ 0
             error("`doublerounds` must be an even positive number")
         end
 
@@ -39,11 +76,32 @@ mutable struct ChaChaStream <: AbstractChaChaStream
 end
 
 # Constructors
+
+"""
+    ChaCha20Stream(args...)
+
+Create a keystream for a ChaCha20 stream cipher.
+"""
 ChaCha20Stream(args...) = ChaChaStream(args...; doublerounds=10)
+
+"""
+    ChaCha12Stream(args...)
+
+Create a keystream for a ChaCha12 stream cipher.
+"""
 ChaCha12Stream(args...) = ChaChaStream(args...; doublerounds=6)
 
-Base.show(io::IO, rng::ChaChaStream) =
-    write(io, "ChaChaStream(key=$(rng.key), nonce=$(rng.nonce), counter=$(rng.counter))")
+function Base.show(io::IO, rng::ChaChaStream)
+    msg = """
+        ChaChaStream(
+            key = $(key(rng))
+            nonce = $(nonce(rng)),
+            counter = $(counter(rng)),
+            rounds = $(2 * doublerounds(rng))
+        )"""
+
+    write(io, msg)
+end
 
 buffer_size(stream::ChaChaStream) = length(stream.buffer) - stream.position + 1
 

test/test_keystream.jl

@@ -6,6 +6,21 @@ using Statistics
 using Test
 
 @testset "ChaChaStream random number generation tests" begin
+    @testset "Test create keystream" begin
+        # Create a ChaChaStream with the default parameters
+        stream = ChaChaStream()
+        @test stream.nonce == 0
+        @test stream.position == 1
+
+        stream = ChaChaStream(; doublerounds=4)
+        @test stream.doublerounds == 4
+
+        # We should receive an error if we try to create a
+        # keystream with non-positive number of doublerounds
+        @test_throws ErrorException ChaChaStream(; doublerounds=0)
+        @test_throws ErrorException ChaChaStream(; doublerounds=-10)
+    end
+
     @testset "Sample random numbers from a collection" begin
         stream = ChaCha12Stream(zeros(8), 0)
         samples = rand(stream, Int(0):Int(1), 65536)