ionhash

README

** This package is considered beta. While the API is relatively stable it is still subject to change. **

Amazon Ion Hash Go

An implementation of Amazon Ion Hash in Go.

Getting Started

You can start using ion-hash-go by simply importing it, e.g.,

import (
	ionhash "github.com/amzn/ion-hash-go"
)

Generating a hash while reading

// Create a hasher provider, using MD5
hasherProvider := ionhash.NewCryptoHasherProvider("MD5")

// Create an Ion reader over the input [1,2,3]
ionReader := ion.NewReaderString("[1,2,3]")

// Create a hash reader
hashReader, err := ionhash.NewHashReader(ionReader, hasherProvider)
if err != nil {
	panic(err)
}

// Read over the top level value and calculate its hash
hashReader.Next()
hashReader.Next()


// Get the hash value
res, err := hashReader.Sum(nil)
if err != nil {
	panic(err)
}

// Print out the hash in Hex
fmt.Printf("Digest = %x\n", res) // prints: Digest = 8f3bf4b1935cf469c9c10c31524b2625

Generating a hash while writing

// Create a hasher provider, using MD5
hasherProvider := ionhash.NewCryptoHasherProvider("MD5")

// Create an Ion writer
ionWriter := ion.NewTextWriter(new(bytes.Buffer))

// Create a hash writer
hashWriter, err := ionhash.NewHashWriter(ionWriter, hasherProvider)
if err != nil {
	panic(err)
}

// Write the list [1,2,3]
hashWriter.BeginList()
hashWriter.WriteInt(1)
hashWriter.WriteInt(2)
hashWriter.WriteInt(3)
hashWriter.EndList()

// Get the hash value
res, err := hashWriter.Sum(nil)
if err != nil {
	panic(err)
}

// Print out the hash in Hex
fmt.Printf("Digest = %x\n", res) // prints: Digest = 8f3bf4b1935cf469c9c10c31524b2625/

Development

This package uses Go Modules to model its dependencies.

Assuming the go command is in your path, building the module can be done as:

$ go build -v ./...

Running all the tests can be executed with:

$ go test -v ./...

We use goimports to format our imports and files in general. Running this before commit is advised:

$ goimports -w .

It is recommended that you hook this in your favorite IDE (Tools > File Watchers in Goland, for example).

Known Issues

< No current known issues >

License

This library is licensed under the Apache-2.0 License.

Documentation

Index

• type Algorithm
• type CryptoHasherProvider
  • func NewCryptoHasherProvider(algorithm Algorithm) *CryptoHasherProvider
  • func (chp *CryptoHasherProvider) NewHasher() (IonHasher, error)
• type HashReader
  • func NewHashReader(ionReader ion.Reader, hasherProvider IonHasherProvider) (HashReader, error)
• type HashWriter
  • func NewHashWriter(ionWriter ion.Writer, hasherProvider IonHasherProvider) (HashWriter, error)
• type InvalidArgumentError
  • func (e *InvalidArgumentError) Error() string
• type InvalidIonTypeError
  • func (e *InvalidIonTypeError) Error() string
• type InvalidOperationError
  • func (e *InvalidOperationError) Error() string
• type IonHasher
• type IonHasherProvider
• type UnknownSymbolError
  • func (e *UnknownSymbolError) Error() string

Types

type Algorithm

type Algorithm string

Algorithm is the name of the hash algorithm used to calculate the hash.

const (
	MD4        Algorithm = "MD4"
	MD5        Algorithm = "MD5"
	SHA1       Algorithm = "SHA1"
	SHA224     Algorithm = "SHA224"
	SHA256     Algorithm = "SHA256"
	SHA384     Algorithm = "SHA384"
	SHA512     Algorithm = "SHA512"
	RIPEMD160  Algorithm = "RIPMD160"
	SHA3s224   Algorithm = "SHA3_224"
	SHA3s256   Algorithm = "SHA3_256"
	SHA3s384   Algorithm = "SHA3_384"
	SHA3s512   Algorithm = "SHA3_512"
	SHA512s224 Algorithm = "SHA512_224"
	SHA512s256 Algorithm = "SHA512_256"
	BLAKE2s256 Algorithm = "BLAKE2s_256"
	BLAKE2b256 Algorithm = "BLAKE2b_256"
	BLAKE2b384 Algorithm = "BLAKE2b_384"
	BLAKE2b512 Algorithm = "BLAKE2b_512"
)

Constants for each of the algorithm names supported.

type CryptoHasherProvider

type CryptoHasherProvider struct {
	IonHasherProvider
	// contains filtered or unexported fields
}

CryptoHasherProvider struct for crypto hasher provider.

func NewCryptoHasherProvider

func NewCryptoHasherProvider(algorithm Algorithm) *CryptoHasherProvider

NewCryptoHasherProvider returns a new CryptoHasherProvider for the provided algorithm.

func (*CryptoHasherProvider) NewHasher

func (chp *CryptoHasherProvider) NewHasher() (IonHasher, error)

NewHasher returns a new cryptoHasher.

type HashReader

type HashReader interface {
	// Embed interface of Ion reader.
	ion.Reader

	// Sum appends the current hash to b and returns the resulting slice.
	// It resets the Hash to its initial state.
	Sum(b []byte) ([]byte, error)
	// contains filtered or unexported methods
}

A HashReader reads a stream of Ion values and calculates its hash.

The HashReader has a logical position within the stream of values, influencing the values returned from its methods. Initially, the HashReader is positioned before the first value in the stream. A call to Next advances the HashReader to the first value in the stream, with subsequent calls advancing to subsequent values. When a call to Next moves the HashReader to the position after the final value in the stream, it returns false, making it easy to loop through the values in a stream. e.g.,

   var r HashReader
   for r.Next() {
	   // ...
   }

Next also returns false in case of error. This can be distinguished from a legitimate end-of-stream by calling HashReader.Err after exiting the loop.

When positioned on an Ion value, the type of the value can be retrieved by calling HashReader.Type. If it has an associated field name (inside a struct) or annotations, they can be read by calling HashReader.FieldName and HashReader.Annotations respectively.

For atomic values, an appropriate XxxValue method can be called to read the value. For lists, sexps, and structs, you should instead call HashReader.StepIn to move the HashReader in to the contained sequence of values. The HashReader will initially be positioned before the first value in the container. Calling HashReader.Next without calling HashReader.StepIn will skip over the composite value and return the next value in the outer value stream.

At any point while reading through a composite value, including when HashReader.Next returns false to indicate the end of the contained values, you may call HashReader.StepOut to move back to the outer sequence of values. The HashReader will be positioned at the end of the composite value, such that a call to HashReader.Next will move to the immediately-following value (if any).

HashReader.Sum will return the hash of the entire stream of Ion values that have been seen thus far, e.g.,

    cryptoHasherProvider := NewCryptoHasherProvider(SHA256)
	   r := NewTextReaderStr("[foo, bar] [baz]")
    hr := NewHashReader(r, cryptoHasherProvider)
	   for hr.Next() {
		   if err := hr.StepIn(); err != nil {
			   return err
		   }
		   for hr.Next() {
			   fmt.Println(hr.StringValue())
		   }
		   if err := hr.StepOut(); err != nil {
			   return err
		   }
	   }
	   if err := hr.Err(); err != nil {
		   return err
	   }

    fmt.Printf("%v", hr.Sum(nil))

func NewHashReader

func NewHashReader(ionReader ion.Reader, hasherProvider IonHasherProvider) (HashReader, error)

NewHashReader takes an Ion reader and a hash provider and returns a new HashReader.

type HashWriter

type HashWriter interface {
	// Embed interface of Ion writer.
	ion.Writer

	IsNull() bool
	Type() ion.Type

	// Sum appends the current hash to b and returns the resulting slice.
	// It resets the Hash to its initial state.
	Sum(b []byte) ([]byte, error)
	// contains filtered or unexported methods
}

A HashWriter writes a stream of Ion values and calculates its hash.

The various Write methods write atomic values to the current output stream. Methods prefixed with Begin start writing a list, sexp, or struct respectively. Subsequent calls to Write will write values inside of the container until a matching End method is called, e.g.,

   var hw HashWriter
   hw.BeginSexp()
   {
	   hw.WriteInt(1)
	   hw.WriteSymbol("+")
	   hw.WriteInt(1)
   }
   hw.EndSexp()

When writing values inside a struct, the FieldName method must be called before each value to set the value's field name. The Annotation method may likewise be called before writing any value to add an annotation to the value.

   var hw HashWriter
   hw.Annotation("user")
   hw.BeginStruct()
   {
	   hw.FieldName("id")
	   hw.WriteString("foo")
	   hw.FieldName("name")
	   hw.WriteString("bar")
   }
   hw.EndStruct()

When you're done writing values, you should call Finish to ensure everything has been flushed from in-memory buffers. While individual methods all return an error on failure, implementations will remember any errors, no-op subsequent calls, and return the previous error. This lets you keep code a bit cleaner by only checking the return value of the final method call (generally Finish).

Sum will return the hash of the entire stream of Ion values that have been written thus far.

	   var hw HashWriter
	   writeSomeStuff(hw)
	   if err := hw.Finish(); err != nil {
		   return err
	   }
    fmt.Printf("%v", hw.Sum(nil))

func NewHashWriter

func NewHashWriter(ionWriter ion.Writer, hasherProvider IonHasherProvider) (HashWriter, error)

NewHashWriter takes an Ion Writer and a hash provider and returns a new HashWriter.

type InvalidArgumentError

type InvalidArgumentError struct {
	// contains filtered or unexported fields
}

InvalidArgumentError is returned when one of the arguments given to a function was not valid.

func (*InvalidArgumentError) Error

func (e *InvalidArgumentError) Error() string

type InvalidIonTypeError

type InvalidIonTypeError struct {
	// contains filtered or unexported fields
}

InvalidIonTypeError is returned when processing an unexpected Ion type.

func (*InvalidIonTypeError) Error

func (e *InvalidIonTypeError) Error() string

type InvalidOperationError

type InvalidOperationError struct {
	// contains filtered or unexported fields
}

An InvalidOperationError is returned when a method call is invalid for the struct's current state.

func (*InvalidOperationError) Error

func (e *InvalidOperationError) Error() string

type IonHasher

type IonHasher interface {
	// Write (via the embedded io.Writer interface) adds more data to the running hash.
	io.Writer

	// Sum appends the current hash to b and returns the resulting slice.
	// It does not change the underlying hash state.
	Sum(b []byte) []byte

	// Reset resets the Hash to its initial state.
	Reset()
}

IonHasher inherits functions from Ion Writer and adds the Sum function. The Sum function provides read access to the underlying hash value.

type IonHasherProvider

type IonHasherProvider interface {
	// Return a new IonHasher.
	NewHasher() (IonHasher, error)
}

IonHasherProvider is used for creating new instances of IonHasher.

type UnknownSymbolError

type UnknownSymbolError struct {
	// contains filtered or unexported fields
}

UnknownSymbolError is returned when processing an unknown field name symbol.

func (*UnknownSymbolError) Error

func (e *UnknownSymbolError) Error() string