certificate

README

Certificates

A certificate consists of

• a tree.
• a signature on the tree root hash valid under some public key.
• an optional delegation that links that public key to root public key.

Read More

• Certified Data
• Certification

Documentation

Overview

Example (B)

package main

import (
	"fmt"

	cert "github.com/aviate-labs/agent-go/certificate"
)

func main() {
	fmt.Printf("%X", cert.Leaf("good").Reconstruct())
}

Output:
7B32AC0C6BA8CE35AC82C255FC7906F7FC130DAB2A090F80FE12F9C2CAE83BA6

Example (C)

package main

import (
	"fmt"

	cert "github.com/aviate-labs/agent-go/certificate"
)

func main() {
	fmt.Printf("%X", cert.Labeled{
		Label: []byte("c"),
		Tree:  cert.Empty{},
	}.Reconstruct())
}

Output:
EC8324B8A1F1AC16BD2E806EDBA78006479C9877FED4EB464A25485465AF601D

Example (Root)

package main

import (
	"fmt"

	cert "github.com/aviate-labs/agent-go/certificate"
)

var tree = cert.Fork{
	LeftTree: cert.Fork{
		LeftTree: cert.Labeled{
			Label: []byte("a"),
			Tree: cert.Fork{
				LeftTree: cert.Fork{
					LeftTree: cert.Labeled{
						Label: []byte("x"),
						Tree:  cert.Leaf("hello"),
					},
					RightTree: cert.Empty{},
				},
				RightTree: cert.Labeled{
					Label: []byte("y"),
					Tree:  cert.Leaf("world"),
				},
			},
		},
		RightTree: cert.Labeled{
			Label: []byte("b"),
			Tree:  cert.Leaf("good"),
		},
	},
	RightTree: cert.Fork{
		LeftTree: cert.Labeled{
			Label: []byte("c"),
			Tree:  cert.Empty{},
		},
		RightTree: cert.Labeled{
			Label: []byte("d"),
			Tree:  cert.Leaf("morning"),
		},
	},
}

func main() {
	fmt.Printf("%X", tree.Reconstruct())
}

Output:
EB5C5B2195E62D996B84C9BCC8259D19A83786A2F59E0878CEC84C811F669AA0

Example (X)

Source: https://sdk.dfinity.org/docs/interface-spec/index.html#_example ─┬─┬╴"a" ─┬─┬╴"x" ─╴"hello"

│ │      │ └╴Empty
│ │      └╴  "y" ─╴"world"
│ └╴"b" ──╴"good"
└─┬╴"c" ──╴Empty
  └╴"d" ──╴"morning"

package main

import (
	"fmt"

	cert "github.com/aviate-labs/agent-go/certificate"
)

func main() {
	fmt.Printf("%X", cert.Fork{
		LeftTree: cert.Labeled{
			Label: []byte("x"),
			Tree:  cert.Leaf("hello"),
		},
		RightTree: cert.Empty{},
	}.Reconstruct())
}

Output:
1B4FEFF9BEF8131788B0C9DC6DBAD6E81E524249C879E9F10F71CE3749F5A638

Index

• Constants
• func DomainSeparator(t string) []byte
• func Lookup(path [][]byte, node Node) []byte
• func LookupPath(p ...string) [][]byte
• func Serialize(node Node) ([]byte, error)
• type Cert
• type Certificate
  • func New(canisterID principal.Principal, rootKey []byte, certificate []byte) (*Certificate, error)
  • func (c Certificate) Verify() error
• type Delegation
  • func (d *Delegation) UnmarshalCBOR(bytes []byte) error
• type Empty
  • func (e Empty) Reconstruct() [32]byte
  • func (e Empty) String() string
• type Fork
  • func (f Fork) Reconstruct() [32]byte
  • func (f Fork) String() string
• type HashTree
  • func NewHashTree(root Node) HashTree
  • func (t HashTree) Digest() [32]byte
  • func (t HashTree) MarshalCBOR() ([]byte, error)
  • func (t *HashTree) UnmarshalCBOR(bytes []byte) error
• type Label
  • func (l Label) String() string
• type Labeled
  • func (l Labeled) Reconstruct() [32]byte
  • func (l Labeled) String() string
• type Leaf
  • func (l Leaf) Reconstruct() [32]byte
  • func (l Leaf) String() string
• type Node
  • func Deserialize(data []byte) (Node, error)
  • func DeserializeNode(s []any) (Node, error)
  • func LookupNode(path [][]byte, node Node) *Node
• type Pruned
  • func (p Pruned) Reconstruct() [32]byte
  • func (p Pruned) String() string

Examples

• Package (B)
• Package (C)
• Package (Root)
• Package (X)
• Deserialize
• Lookup
• Pruned
• Serialize

Constants

const DerPrefix = "308182301d060d2b0601040182dc7c0503010201060c2b0601040182dc7c05030201036100"

DerPrefix is the DER prefix of IC main net.

const RootKey = "" /* 266-byte string literal not displayed */

RootKey is the root key of IC main net.

Functions

func DomainSeparator

func DomainSeparator(t string) []byte

func Lookup

func Lookup(path [][]byte, node Node) []byte

Lookup looks up the given path in the certificate tree.

Example

fmt.Println(string(certificate.Lookup(certificate.LookupPath("a", "x"), tree)))
fmt.Println(string(certificate.Lookup(certificate.LookupPath("a", "y"), tree)))
fmt.Println(string(certificate.Lookup(certificate.LookupPath("b"), tree)))
fmt.Println(string(certificate.Lookup(certificate.LookupPath("d"), tree)))

Output:
hello
world
good
morning

func LookupPath

func LookupPath(p ...string) [][]byte

LookupPath returns a path from the given labels.

func Serialize

func Serialize(node Node) ([]byte, error)

Example

package main

import (
	"fmt"

	cert "github.com/aviate-labs/agent-go/certificate"
)

var tree = cert.Fork{
	LeftTree: cert.Fork{
		LeftTree: cert.Labeled{
			Label: []byte("a"),
			Tree: cert.Fork{
				LeftTree: cert.Fork{
					LeftTree: cert.Labeled{
						Label: []byte("x"),
						Tree:  cert.Leaf("hello"),
					},
					RightTree: cert.Empty{},
				},
				RightTree: cert.Labeled{
					Label: []byte("y"),
					Tree:  cert.Leaf("world"),
				},
			},
		},
		RightTree: cert.Labeled{
			Label: []byte("b"),
			Tree:  cert.Leaf("good"),
		},
	},
	RightTree: cert.Fork{
		LeftTree: cert.Labeled{
			Label: []byte("c"),
			Tree:  cert.Empty{},
		},
		RightTree: cert.Labeled{
			Label: []byte("d"),
			Tree:  cert.Leaf("morning"),
		},
	},
}

func main() {
	b, _ := cert.Serialize(tree)
	fmt.Printf("%x", b)
}

Output:
8301830183024161830183018302417882034568656c6c6f810083024179820345776f726c6483024162820344676f6f648301830241638100830241648203476d6f726e696e67

Types

type Cert

type Cert struct {
	// Tree is the certificate tree.
	Tree HashTree `cbor:"tree"`
	// Signature is the signature of the certificate tree.
	Signature []byte `cbor:"signature"`
	// Delegation is the delegation of the certificate.
	Delegation *Delegation `cbor:"delegation"`
}

Cert is a certificate gets returned by the IC.

type Certificate

type Certificate struct {
	Cert       Cert
	RootKey    []byte
	CanisterID principal.Principal
}

Certificate is a certificate gets returned by the IC and can be used to verify the state root based on the root key and canister ID.

func New

func New(canisterID principal.Principal, rootKey []byte, certificate []byte) (*Certificate, error)

New creates a new certificate.

func (Certificate) Verify

func (c Certificate) Verify() error

Verify verifies the certificate.

type Delegation

type Delegation struct {
	// SubnetId is the subnet ID of the delegation.
	SubnetId principal.Principal `cbor:"subnet_id"`
	// The nested certificate typically does not itself again contain a
	// delegation, although there is no reason why agents should enforce that
	// property.
	Certificate Certificate `cbor:"certificate"`
}

Delegation is a delegation of a certificate.

func (*Delegation) UnmarshalCBOR

func (d *Delegation) UnmarshalCBOR(bytes []byte) error

UnmarshalCBOR unmarshals a delegation.

type Empty

type Empty struct{}

func (Empty) Reconstruct

func (e Empty) Reconstruct() [32]byte

func (Empty) String

func (e Empty) String() string

type Fork

type Fork struct {
	LeftTree  Node
	RightTree Node
}

func (Fork) Reconstruct

func (f Fork) Reconstruct() [32]byte

func (Fork) String

func (f Fork) String() string

type HashTree

type HashTree struct {
	Root Node
}

HashTree is a hash tree.

func NewHashTree

func NewHashTree(root Node) HashTree

NewHashTree creates a new hash tree.

func (HashTree) Digest

func (t HashTree) Digest() [32]byte

Digest returns the digest of the hash tree.

func (HashTree) MarshalCBOR

func (t HashTree) MarshalCBOR() ([]byte, error)

MarshalCBOR marshals a hash tree.

func (*HashTree) UnmarshalCBOR

func (t *HashTree) UnmarshalCBOR(bytes []byte) error

UnmarshalCBOR unmarshals a hash tree.

type Label

type Label []byte

func (Label) String

func (l Label) String() string

type Labeled

type Labeled struct {
	Label Label
	Tree  Node
}

func (Labeled) Reconstruct

func (l Labeled) Reconstruct() [32]byte

func (Labeled) String

func (l Labeled) String() string

type Leaf

type Leaf []byte

func (Leaf) Reconstruct

func (l Leaf) Reconstruct() [32]byte

func (Leaf) String

func (l Leaf) String() string

type Node

type Node interface {
	Reconstruct() [32]byte
	fmt.Stringer
}

func Deserialize

func Deserialize(data []byte) (Node, error)

Example

package main

import (
	"encoding/hex"
	"fmt"

	cert "github.com/aviate-labs/agent-go/certificate"
)

func main() {
	data, _ := hex.DecodeString("8301830183024161830183018302417882034568656c6c6f810083024179820345776f726c6483024162820344676f6f648301830241638100830241648203476d6f726e696e67")
	fmt.Println(cert.Deserialize(data))
}

Output:
{{a:{{x:hello|∅}|y:world}|b:good}|{c:∅|d:morning}} <nil>

func DeserializeNode

func DeserializeNode(s []any) (Node, error)

func LookupNode

func LookupNode(path [][]byte, node Node) *Node

type Pruned

type Pruned [32]byte

Example

package main

import (
	"encoding/hex"
	"fmt"

	cert "github.com/aviate-labs/agent-go/certificate"
)

var pruned = cert.Fork{
	LeftTree: cert.Fork{
		LeftTree: cert.Labeled{
			Label: []byte("a"),
			Tree: cert.Fork{
				LeftTree: cert.Pruned(h2b("1B4FEFF9BEF8131788B0C9DC6DBAD6E81E524249C879E9F10F71CE3749F5A638")),
				RightTree: cert.Labeled{
					Label: []byte("y"),
					Tree:  cert.Leaf("world"),
				},
			},
		},
		RightTree: cert.Labeled{
			Label: []byte("b"),
			Tree:  cert.Pruned(h2b("7B32AC0C6BA8CE35AC82C255FC7906F7FC130DAB2A090F80FE12F9C2CAE83BA6")),
		},
	},
	RightTree: cert.Fork{
		LeftTree: cert.Pruned(h2b("EC8324B8A1F1AC16BD2E806EDBA78006479C9877FED4EB464A25485465AF601D")),
		RightTree: cert.Labeled{
			Label: []byte("d"),
			Tree:  cert.Leaf("morning"),
		},
	},
}

func main() {
	fmt.Printf("%X", pruned.Reconstruct())
}

func h2b(s string) [32]byte {
	var bs [32]byte
	b, _ := hex.DecodeString(s)
	copy(bs[:], b)
	return bs
}

Output:
EB5C5B2195E62D996B84C9BCC8259D19A83786A2F59E0878CEC84C811F669AA0

func (Pruned) Reconstruct

func (p Pruned) Reconstruct() [32]byte

func (Pruned) String

func (p Pruned) String() string