The purpose of this repository is to make test cases publicly available for the SHA-256 pseudo-random sampling algorithm described by Ronald L. Rivest in 2011.
The test cases in this repository can be used to help check that new implementations are correct.
The Rivest sampling algorithm is for things like selecting precincts at random for an election audit.
The reference implementation of the algorithm (written in Python), along with a description by Rivest, can be found here on Rivest's web site.
Other implementations include--
- an AngularJS browser implementation called Quick Sampler by Chris Jerdonek, and
- an earlier browser implementation by Philip B. Stark.
The tests are located in the file tests.json.
The sample range for each test is the list of whole numbers from 1 to
the upper limit total. The tests should be run "allowing duplicates."
To check that UTF-8 is used for encoding, the tests include some test cases with non-ASCII seed values, and at least one test case has a seed with a non-BMP Unicode character.
The test cases were checked with Python 2.6.9 and the reference
implementation downloaded from Rivest's web site on August 8, 2014
with sampler_version "November 14, 2011."
(The implementation states that it was checked using Python 2.6.7.)
For convenience, we include a copy of that download in this repository
as the file sampler.py.
The test cases were also checked using Quick Sampler.
For convenience, this repository has a bower.json file,
which lets one include the test cases in another web application
using Bower.
To deploy a new version, bump the "version" number in
tests.json, and tag the release with a SemVer
Git tag (it is okay to add a prefix of "v"). For example--
$ git tag v0.2.0
$ git push origin v0.2.0
Note that the Bower spec
says to leave the version number out of bower.json.
The contents of this repository are licensed under a BSD 3-clause license,
unless indicated otherwise. See the LICENSE file
for the BSD license. Note that Rivest's reference implementation,
which this repository contains a copy of, is licensed under
the MIT License and not BSD.
Chris Jerdonek (chris.jerdonek@gmail.com)