registry

README

Oasis Metadata Registry Tools

This repository contains tools for working with the Oasis Metadata Registry.

Building

To build the oasis-registry tool, run:

make build

Usage

NOTE: Currently, you will need to build the oasis-registry tool yourself.

NOTE: Support for signing entity metadata statements with the Ledger-based signer is available in Oasis app 1.9.0+ releases which will soon be available via Ledger Live's Manager.

To sign an entity metadata statement, e.g.

{
  "v": 1,
  "serial": 1,
  "name": "My entity name",
  "url": "https://my.entity/url",
  "email": "my@entity.org",
  "keybase": "my_keybase_handle",
  "twitter": "my_twitter_handle"
}

save it as a JSON file, e.g. entity-metadata.json, and run:

./oasis-registry/oasis-registry entity update \
  <SIGNER-FLAGS> \
  entity-metadata.json

where <SIGNER-FLAGS> are replaced by the appropriate signer CLI flags for your signer (e.g. Ledger-based signer, File-based signer).

For more details, run:

./oasis-registry/oasis-registry entity update --help

NOTE: The same signer flags as used by the Oasis Node CLI are supported. See Oasis CLI Tools' documentation on Signer Flags for more details.

The oasis-registry entity update command will output a preview of the entity metadata statement you are about to sign:

You are about to sign the following entity metadata descriptor:
  Version: 1
  Serial:  1
  Name:    My entity name
  URL:     https://my.entity/url
  Email:   my@entity.org
  Keybase: my_keybase_handle
  Twitter: my_twitter_handle

and ask you for confirmation.

It will store the signed entity metadata statement to the registry/entity/<HEX-ENCODED-ENTITY-PUBLIC-KEY>.json file, where <HEX-ENCODED-ENTITY-PUBLIC-KEY> corresponds to your hex-encoded entity's public key, e.g. 918cfe60b903e9d2c3003eaa78997f4fd95d66597f20cea8693e447b6637604c.json.

Contributing Entity Metadata Statement to Production Oasis Metadata Registry

See the Contributing New Statements guide at the Oasis Metadata Registry's web site.

Development

Examples

For some examples of using this Go library, check the examples/ directory.

To build all examples, run:

make build-examples

To run the lookup example that lists the entity metadata statements in the production Oasis Metadata Registry, run:

./examples/lookup/lookup

It should give an output similar to:

[ms7M1v8HfItCnNNJ0tfE/PsYQsmeD+XpfGF1v0zR2Xo=]
  Name:    Everstake
  URL:     https://everstake.one
  Email:   inbox@everstake.one
  Keybase: everstake
  Twitter: everstake_pool

[gb8SHLeDc69Elk7OTfqhtVgE2sqxrBCDQI84xKR+Bjg=]
  Name:    Bi23 Labs
  URL:     https://bi23.com
  Email:   support@bi23.com
  Keybase: sunxmldapp
  Twitter: bi23com

... output trimmed ...

Test Vectors

To generate the entity metadata test vectors, run:

make gen_vectors

Tests

To run all tests, run:

make test

This will run all Make's test targets which include Go unit tests and CLI tests.

NOTE: CLI tests with Ledger signer will be skipped unless the LEDGER_SIGNER_PATH is set and exported.

Tests with Ledger-based signer

To run CLI tests with Ledger-based signer, you need to follow these steps:

1. Download the latest Oasis Core Ledger release from https://github.com/oasisprotocol/oasis-core-ledger/releases.

2. Extract the oasis_core_ledger_<VERSION>_<OS>_amd64.tar.gz tarball.

3. Set LEDGER_SIGNER_PATH environment variable to the path of the extracted ledger-signer binary and export it, e.g.:

   export LEDGER_SIGNER_PATH="/path/to/oasis_core_ledger_1.2.0_linux_amd64/ledger-signer"
   

4. Connect your Ledger device and make sure the Oasis app is open.

5. Run tests with:

   make test-cli-ledger
   

Documentation

Overview

Package registry provides an interface to the Oasis off-chain registry of signed statements.

Index

• Constants
• Variables
• type EntityMetadata
  • func (e *EntityMetadata) Equal(other *EntityMetadata) bool
  • func (e *EntityMetadata) Load(id signature.PublicKey, r io.Reader) error
  • func (e *EntityMetadata) PrettyPrint(ctx context.Context, prefix string, w io.Writer)
  • func (e EntityMetadata) PrettyType() (interface{}, error)
  • func (e *EntityMetadata) ValidateBasic() error
• type GitConfig
  • func NewGitConfig() GitConfig
  • func NewTestGitConfig() GitConfig
• type MutableProvider
  • func NewFilesystemPathProvider(path string) (MutableProvider, error)
  • func NewFilesystemProvider(fs billy.Filesystem) (MutableProvider, error)
• type Provider
  • func NewGitProvider(cfg GitConfig) (Provider, error)
• type SignedEntityMetadata
  • func SignEntityMetadata(signer signature.Signer, meta *EntityMetadata) (*SignedEntityMetadata, error)
  • func (s *SignedEntityMetadata) Open(meta *EntityMetadata) error
  • func (s *SignedEntityMetadata) Save(w io.Writer) error

Constants

const (
	// MaxStatementSize is the maximum encoded signed statement size in bytes.
	MaxStatementSize = 16 * 1024

	// MaxEntityNameLength is the maximum length of the entity metadata's Name field.
	MaxEntityNameLength = 50
	// MaxEntityURLLength is the maximum length of the entity metadata's URL field.
	MaxEntityURLLength = 64
	// MaxEntityEmailLength is the maximum length of the entity metadata's Email field.
	MaxEntityEmailLength = 32
	// MaxEntityKeybaseLength is the maximum length of the entity metadata's Keybase field.
	MaxEntityKeybaseLength = 32
	// MaxEntityTwitterLength is the maximum length of the entity metadata's Twitter field.
	MaxEntityTwitterLength = 32

	// MinSupportedVersion is the minimum supported entity metadata version.
	MinSupportedVersion = 1
	// MaxSupportedVersion is the maximum supported entity metadata version.
	MaxSupportedVersion = 1
)

Variables

var (
	// ErrNoSuchEntity is the error returned where the requested entity cannot be found.
	ErrNoSuchEntity = errors.New("registry: no such entity")

	// ErrCorruptedRegistry is the error returned where the registry is corrupted (does not conform
	// to the specifications or contains data that fails signature verification).
	ErrCorruptedRegistry = errors.New("registry: corrupted registry")
)

var (
	// TwitterHandleRegexp is the regular expression used for validating the Twitter field.
	TwitterHandleRegexp = regexp.MustCompile(`^[A-Za-z0-9_]+$`)
	// KeybaseHandleRegexp is the regular expression used for validating the Keybase field.
	KeybaseHandleRegexp = regexp.MustCompile(`^[A-Za-z0-9_]+$`)
)

var EntityMetadataSignatureContext = signature.NewContext("oasis-metadata-registry: entity")

EntityMetadataSignatureContext is the domain separation context used for entity metadata.

Types

type EntityMetadata

type EntityMetadata struct {
	cbor.Versioned

	// Serial is the serial number of the entity metadata statement.
	Serial uint64 `json:"serial"`

	// Name is the entity name.
	Name string `json:"name,omitempty"`

	// URL is an URL associated with an entity.
	URL string `json:"url,omitempty"`

	// Email is the entity's contact e-mail address.
	Email string `json:"email,omitempty"`

	// Keybase is the keybase.io handle.
	Keybase string `json:"keybase,omitempty"`

	// Twitter is the Twitter handle.
	Twitter string `json:"twitter,omitempty"`
}

EntityMetadata contains metadata about an entity.

func (*EntityMetadata) Equal

func (e *EntityMetadata) Equal(other *EntityMetadata) bool

Equal compares vs another entity metadata for equality.

func (*EntityMetadata) Load

func (e *EntityMetadata) Load(id signature.PublicKey, r io.Reader) error

Load loads and verifies entity metadata from a given reader containing signed entity metadata.

func (*EntityMetadata) PrettyPrint

func (e *EntityMetadata) PrettyPrint(ctx context.Context, prefix string, w io.Writer)

PrettyPrint writes a pretty-printed representation of EntityMetadata to the given writer.

func (EntityMetadata) PrettyType

func (e EntityMetadata) PrettyType() (interface{}, error)

PrettyType returns a representation of EntityMetadata that can be used for pretty printing.

func (*EntityMetadata) ValidateBasic

func (e *EntityMetadata) ValidateBasic() error

ValidateBasic performs basic validity checks on the entity metadata.

type GitConfig

type GitConfig struct {
	// URL is the repository URL.
	URL string

	// Branch is the Git branch to use.
	Branch string
}

GitConfig contains the configuration of the Git provider.

func NewGitConfig

func NewGitConfig() GitConfig

NewGitConfig creates a default Git provider configuration pointing to the production branch.

func NewTestGitConfig

func NewTestGitConfig() GitConfig

NewTestGitConfig creates a Git provider configuration pointing to the test branch.

type MutableProvider

type MutableProvider interface {
	Provider

	// BaseDir returns the base registry directory (when available).
	BaseDir() string

	// Init initializes a new registry in the local filesystem.
	Init() error

	// UpdateEntity updates entity metadata in the registry.
	UpdateEntity(entity *SignedEntityMetadata) error
}

MutableProvider is a mutable registry provider interface.

func NewFilesystemPathProvider

func NewFilesystemPathProvider(path string) (MutableProvider, error)

NewFilesystemPathProvider creates a new filesystem-based registry interface for the given path.

func NewFilesystemProvider

func NewFilesystemProvider(fs billy.Filesystem) (MutableProvider, error)

NewFilesystemProvider creates a new filesystem-based registry interface.

type Provider

type Provider interface {
	// Verify verifies the integrity of the whole registry.
	Verify() error

	// VerifyUpdate verifies the integrity of a registry update from src.
	VerifyUpdate(src Provider) error

	// GetEntities returns a list of all entities in the registry.
	GetEntities(ctx context.Context) (map[signature.PublicKey]*EntityMetadata, error)

	// GetEntity returns metadata for a specific entity.
	GetEntity(ctx context.Context, id signature.PublicKey) (*EntityMetadata, error)
}

Provider is the read-only registry provider interface.

func NewGitProvider

func NewGitProvider(cfg GitConfig) (Provider, error)

NewGitProvider creates a new git-backed metadata registry provider.

type SignedEntityMetadata

type SignedEntityMetadata struct {
	signature.Signed
}

SignedEntityMetadata is a signed entity metadata statement.

func SignEntityMetadata

func SignEntityMetadata(signer signature.Signer, meta *EntityMetadata) (*SignedEntityMetadata, error)

SignEntityMetadata serializes the EntityMetadata and signs the result.

func (*SignedEntityMetadata) Open

func (s *SignedEntityMetadata) Open(meta *EntityMetadata) error

Open first verifies the blob signature and then unmarshals the blob.

func (*SignedEntityMetadata) Save

func (s *SignedEntityMetadata) Save(w io.Writer) error

Save serializes and writes entity metadata to the given writer.