onerng

README

⚠️ Warning: This code is grossly incomplete and under-tested! Don't use it yet, except to hack on it.

go-onerng

This is an unofficial Go version of the OneRNG tools distributed at https://onerng.info/. Much credit is due to the OneRNG creators - this all started as a port of a bunch of Bash and Python code to Go.

The different commands available were discovered by reading the firmware source code.

Roadmap

This is still fairly immature. Here's what I want to be able to do with it:

• print the version (cmdv)
• print the ID (cmdI)
• verify the image (cmdX & verify PGP signature)
• generate some amount of entropy (onerng read command)
• add extra AES128-whitening
• run as a daemon and integrate with rngd

Documentation

Overview

Package onerng provides functions to help interface with the OneRNG hardware RNG.

See http://onerng.info for information about the device, and see especially http://www.moonbaseotago.com/onerng/theory.html for the theory of operation.

To use this package, you must first plug the OneRNG into an available USB port, and your OS should auto-detect the device as a USB serial modem. On Linux, you may need to load the cdc_acm module.

Once you know which device file points to the OneRNG, you can instantiate a *OneRNG struct instance. All communication with the OneRNG is done through this instance.

o := &OneRNG{Path: "/dev/ttyACM0"}
version, err := o.Version(context.TODO())
if err != nil {
	return err
}
fmt.Printf("version is %d\n", version)

Reading data from the OneRNG can be done with the Read function:

o := &OneRNG{Path: "/dev/ttyACM0"}
_, err = o.Read(context.TODO(), os.Stdout, -1, EnableRF | DisableWhitener)
if err != nil {
	return err
}

Index

• func Verify(_ context.Context, image io.Reader, pubkey string) error
• type NoiseMode
• type OneRNG
  • func (o *OneRNG) AESWhitener(ctx context.Context, out io.Writer) (io.WriteCloser, error)
  • func (o *OneRNG) Flush(ctx context.Context) error
  • func (o *OneRNG) Identify(ctx context.Context) (string, error)
  • func (o *OneRNG) Image(ctx context.Context) ([]byte, error)
  • func (o *OneRNG) Init(ctx context.Context) error
  • func (o *OneRNG) Read(ctx context.Context, out io.Writer, n int64, flags NoiseMode) (written int64, err error)
  • func (o *OneRNG) Version(ctx context.Context) (int, error)

Functions

func Verify

func Verify(_ context.Context, image io.Reader, pubkey string) error

Verify reads a signed firmware image, extracts the signature, and verifies it against the given public key.

Details are printed to Stderr on success, otherwise an error is returned.

The general logic is ported from the official onerng_verify.py script distributed alongside the OneRNG package.

Types

type NoiseMode

type NoiseMode uint32

NoiseMode represents the different noise-generation modes available to the OneRNG

const (
	// DisableWhitener - Disable the on-board CRC16 generator - no effect if both noise generators are disabled
	DisableWhitener NoiseMode = 1 << iota
	// EnableRF - Enable noise generation from RF
	EnableRF
	// DisableAvalanche - Disable noise generation from the Avalanche Diode
	DisableAvalanche

	// Default mode - Avalanche enabled, RF disabled, Whitener enabled.
	Default NoiseMode = 0
	// Silent - a convenience - everything disabled
	Silent NoiseMode = DisableAvalanche
)

type OneRNG

type OneRNG struct {
	Path string
	// contains filtered or unexported fields
}

OneRNG - a OneRNG device

func (*OneRNG) AESWhitener

func (o *OneRNG) AESWhitener(ctx context.Context, out io.Writer) (io.WriteCloser, error)

AESWhitener creates a "whitener" that wraps the provided writer. The random data that the OneRNG generates is sometimes a little "too" random for some purposes (i.e. rngd), so this can be used to further mangle that data in non- predictable ways.

This uses AES-128.

func (*OneRNG) Flush

func (o *OneRNG) Flush(ctx context.Context) error

Flush the OneRNG's entropy pool

func (*OneRNG) Identify

func (o *OneRNG) Identify(ctx context.Context) (string, error)

Identify - query the OneRNG for its ID

func (*OneRNG) Image

func (o *OneRNG) Image(ctx context.Context) ([]byte, error)

Image extracts the firmware image. This image is padded with random data to either 128Kb or 256Kb (depending on hardware), and signed.

See also the Verify function.

func (*OneRNG) Init

func (o *OneRNG) Init(ctx context.Context) error

Init - wait for the device to finish initializing and start returning data

func (*OneRNG) Read

func (o *OneRNG) Read(ctx context.Context, out io.Writer, n int64, flags NoiseMode) (written int64, err error)

Read n bytes of data from the OneRNG into the given Writer. Set flags to configure the OneRNG's. Set n to -1 to continuously read until an error is encountered, or the context is cancelled.

The OneRNG device will be closed when the operation completes.

func (*OneRNG) Version

func (o *OneRNG) Version(ctx context.Context) (int, error)

Version - query the OneRNG for its hardware version