logverification

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 22, 2025 License: MIT Imports: 19 Imported by: 4

Documentation

Index

Constants

View Source 
const (
	DefaultMassifHeight = 14

	// LeafTypePlain is the domain separator for events
	LeafTypePlain = uint8(0)
)

Variables

View Source 
var (
	ErrNonEmptyAppIDRequired    = errors.New("app id field is required and must be non-empty")
	ErrNonEmptyEventIDRequired  = errors.New("event identity field is required and must be non-empty")
	ErrNonEmptyTenantIDRequired = errors.New("tenant identity field is required and must be non-empty")
	ErrCommitEntryRequired      = errors.New("merkle log commit field is required")
	ErrIdTimestampRequired      = errors.New("idtimestamp field is required and must be non-empty")
)
View Source 
var (
	ErrIntermediateNode          = errors.New("app entry references an intermediate node on the merkle log")
	ErrDuplicateAppEntryMMRIndex = errors.New("app entry mmrIndex is the same as the previous event")
	ErrAppEntryNotOnLeaf         = errors.New("app entry does not correspond to the event found on the leaf node")
	ErrInclusionProofVerify      = errors.New("app entry failed to verify the inclusion proof on the merkle log")
	ErrNotEnoughAppEntriesInList = errors.New("the number of app entries in the list is less than the number of leafs on the log")
)
View Source 
var (
	ErrNilMassifContext = errors.New("nil massif context")
)

Functions

func EventIdentity 

func EventIdentity(eventJson []byte) (string, error)

EventIdentity gets the event identity from the given event json

func EventProof 

func EventProof(verifiableMMREntry VerifiableMMREntry, massif *massifs.MassifContext) ([][]byte, error)

EventProof gets the event proof for the given event and the given massif the event is contained in.

func LeafRange 

func LeafRange(sortedEvents []app.AppEntry) (uint64, uint64)

LeafRange gets the range of leaf indexes for a given list of 

events, that have been sorted from lowest mmr index to highest mmr index.

Returns the lower and upper bound of the leaf indexes for the leaf range.

func LogState 

func LogState(signedState *cose.CoseSign1Message, codec cbor.CBORCodec) (*massifs.MMRState, error)

LogState returns the unsigned state of the log, given a signed state.

func Massif 

func Massif(mmrIndex uint64, massifReader MassifGetter, tenantId string, massifHeight uint8) (*massifs.MassifContext, error)

Massif gets the massif (blob) that contains the given mmrIndex, from azure blob storage 

defined by the azblob configuration.

func MerklelogEntry 

func MerklelogEntry(eventJson []byte) (*assets.MerkleLogEntry, error)

MerklelogEntry safely decode the event json from the api and recovers the merkle log entry field

func SignedLogState 

func SignedLogState(
	ctx context.Context,
	reader azblob.Reader,
	hasher hash.Hash,
	codec cbor.CBORCodec,
	tenantID string,
	massifIndex uint64,
) (*cose.CoseSign1Message, error)

SignedLogState gets the signed state of the log for the massif at the given massif Index.

func TenantIdentity 

func TenantIdentity(eventJson []byte) (string, error)

TenantIdentity gets the event's tenant identity from the given event json

func UpdateMassifContext 

func UpdateMassifContext(massifReader MassifGetter, massifContext *massifs.MassifContext, mmrIndex uint64, tenantID string, massifHeight uint8) error

UpdateMassifContext, updates the given massifContext to the massif that stores 

the given mmrIndex for the given tenant.

A Massif is a blob that contains a portion of the merkle log. A MassifContext is the context used to get specific massifs.

func Validate added in v0.4.0 

func Validate(appEntry app.AppEntry) error

Validate performs basic validation on the AppEntryGetter, ensuring that critical fields are present.

func VerifyConsistency 

func VerifyConsistency(
	ctx context.Context,
	hasher hash.Hash,
	reader azblob.Reader,
	tenantID string,
	logStateA *massifs.MMRState,
	logStateB *massifs.MMRState,
) (bool, error)

VerifyConsistency takes two log states, and verifies that log state B is appended onto log state A MMRState is an abstraction, but it is assumed that logStateA comes from a local, trusted copy of the data rather than a fresh download from DataTrails.

This function assumes the two log states are from the same massif.

NOTE: the log state's signatures are not verified in this function, it is expected that the signature verification is done as a separate step to the consistency verification.

func VerifyList 

func VerifyList(reader azblob.Reader, appEntries []app.AppEntry, options ...VerifyOption) ([]uint64, error)
  • VerifyList verifies a given list of app entries against a range of leaves in the immutable merkle log. *
  • The list of app entries for assetsv2 or eventsv1 is the json response from a datatrails list events API call. *
  • The boundaries of the range of leaves are determined by the lowest and largest mmrIndex on the given list of app entries.
  • In the below example the event with the lowest mmrIndex matches leaf2 of the mmr,
  • and the event with the largest mmrIndex matches leaf4 of the mmr: *
  • ↓ leaf range ↓
  • |-------------------------------|
  • | leaf1 leaf2 leaf3 leaf4 leaf5 |
  • |-------------------------------| *
  • Once a range of leaves in the mmr has been established, we iterate over each leaf in the range
  • and each app entry in the list (sorted lowest to highest by mmrIndex). *
  • We check that each event is INCLUDED in the mmr at the leaf index it is in tandem with
  • in the iteration: *
  • |----------------------|
  • | entry1 entry2 entry3 | app entry list (lowest mmrIndex to highest)
  • |----------------------|
  • ↓ ↓ ↓
  • |----------------------|
  • | leaf1 leaf2 leaf3 | leaf range from merklelog
  • |----------------------| *
  • If every app entry within the list is included at its expected leaf index, we say the list is COMPLETE. *
  • If an app entry within the list of app entries is not present on the immutable merklelog
  • at the expected leaf index it is in tandem with, we call that an EXCLUDED event.
  • In the below example, entry2 is an EXCLUDED app entry. (Note: proof of exclusion using the trie index is not shown in this demo) *
  • |-----------------------------|
  • | entry1 entry2 entry3 entry4 | app entry list (lowest mmrIndex to highest)
  • |-----------------------------|
  • ↓ ↓ ↓
  • |-----------------------------|
  • | leaf1 leaf2 leaf3 | leaf range from merklelog
  • |-----------------------------| *
  • If there is a leaf within the range of leaves that does not have an app entry, within the list of app entries included,
  • we call that an OMITTED app entry. *
  • In the below example the app entry included at leaf2 is an example of an ommitted event. *
  • |-----------------------------|
  • | entry1 entry3 entry4 | app entry list (lowest mmrIndex to highest)
  • |-----------------------------|
  • ↓ ↓ ↓
  • |-----------------------------|
  • | leaf1 leaf2 leaf3 leaf4 | leaf range from merklelog
  • |-----------------------------| *
  • Returns the omitted app entry mmrIndexes. *
  • The options argument can be the following: *
  • WithTenantId - the tenantId of the merklelog, the app entry is expected
  • to be included on. E.g. the public tenant
  • for public events.

func VerifyProof 

func VerifyProof(verifiableMMREntry VerifiableMMREntry, proof [][]byte, massif *massifs.MassifContext) (bool, error)

VerifyProof verifies the given proof against the given event

Types

type AppEntryType added in v0.4.0 

type AppEntryType int
const (

	// Unknown app entry is a given app entry that is unknown
	Unknown AppEntryType = iota

	// Included app entry is a given app entry that is included on the immutable log
	Included

	// Excluded app entry is a given app entry that is NOT included on the immutable log
	Excluded

	// Omitted is an app entry on the immutable log, that has not been given within an expected list of app entries.
	Omitted
)

func VerifyAppEntryInList added in v0.4.0 

func VerifyAppEntryInList(
	hasher hash.Hash,
	leafIndex uint64,
	appEntry app.AppEntry,
	reader massifs.MassifReader,
	massifContext *massifs.MassifContext,
	tenantID string,
) (AppEntryType, error)

VerifyAppEntryInList takes the next leaf in the list of leaves and the next app entry in the list of app entries 

and verifies that the app entry is in that leaf position.

type DecodedEvent added in v0.1.6 

type DecodedEvent struct {
	V3Event   simplehash.V3Event
	MerkleLog *assets.MerkleLogEntry
}

DecodedEvent

func NewDecodedEvent added in v0.1.6 

func NewDecodedEvent(eventJson []byte) (*DecodedEvent, error)

NewDecodedEvent takes a single event JSON and returns a DecodedEvent

func NewDecodedEvents added in v0.1.6 

func NewDecodedEvents(eventsJson []byte) ([]DecodedEvent, error)

NewDecodedEvents takes a list of events JSON (e.g. from the events list API), converts them into DecodedEvents and then returns them sorted by ascending MMR index.

func (*DecodedEvent) Validate added in v0.1.7 

func (e *DecodedEvent) Validate() error

Validate performs basic validation on the DecodedEvent, ensuring that critical fields are present for verification purposes.

type EventHasher 

type EventHasher interface {
	HashEvent(eventJson []byte) ([]byte, error)
}

type MassifGetter added in v0.4.0 

type MassifGetter interface {
	GetMassif(
		ctx context.Context, tenantIdentity string, massifIndex uint64, opts ...massifs.ReaderOption,
	) (massifs.MassifContext, error)
}

type MassifOption 

type MassifOption func(*MassifOptions)

func WithMassifHeight 

func WithMassifHeight(massifHeight uint8) MassifOption

WithMassifHeight is an optional massif height for the massif 

instead of the default.

func WithMassifTenantId 

func WithMassifTenantId(tenantId string) MassifOption

WithMassifTenantId is an optional tenant ID to use instead 

of the tenantId found on the eventJson.

func WithNonLeafNode 

func WithNonLeafNode(nonLeafNode bool) MassifOption

WithNonLeafNode is an optional suppression 

of errors that occur due to attempting to get
a massif based on a non leaf node mmrIndex.

type MassifOptions 

type MassifOptions struct {

	// NonLeafNode is an optional suppression
	//
	//	of errors that occur due to attempting to get
	//  a massif based on a non leaf node mmrIndex.
	NonLeafNode bool

	// TenantId is an optional tenant ID to use instead
	//  of the TenantId found on the eventJson.
	TenantId string

	// MassifHeight is an optional massif height for the massif
	//  instead of the default.
	MassifHeight uint8
}

func ParseMassifOptions 

func ParseMassifOptions(options ...MassifOption) MassifOptions

ParseMassifOptions parses the given options into a MassifOptions struct

type VerifiableLogEntryOption added in v0.3.0 

type VerifiableLogEntryOption func(*VerifiableLogEntryOptions)

func WithMerkleLogConfirm added in v0.3.0 

func WithMerkleLogConfirm(merkleLogConfirm *assets.MerkleLogConfirm) VerifiableLogEntryOption

WithMerkleLogConfirm is an optional merklelog confirmation which can be used to verify the consistency of the verifiablelog entry

type VerifiableLogEntryOptions added in v0.3.0 

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

func ParseVerifableLogEntryOptions added in v0.3.0 

func ParseVerifableLogEntryOptions(options ...VerifiableLogEntryOption) VerifiableLogEntryOptions

ParseVerifableLogEntryOptions parses the given options into a VerifiableLogEntryOptions struct

type VerifiableMMREntry added in v0.3.0 

type VerifiableMMREntry interface {

	// MMREntry returns the mmr entry to verify the inclusion of.
	MMREntry() ([]byte, error)

	// MMRIndex returns the mmr index of the mmr entry.
	MMRIndex() uint64
}

VerifiableMMREntry is an MMR Entry that can have its inclusion verified

type VerifyOption 

type VerifyOption func(*VerifyOptions)

func WithTenantId 

func WithTenantId(tenantId string) VerifyOption

WithTenantId is an optional tenant ID to use instead 

of the tenantId found on the eventJson.

type VerifyOptions 

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

func ParseOptions 

func ParseOptions(options ...VerifyOption) VerifyOptions

ParseOptions parses the given options into a VerifyOptions struct

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.