kvstore

README

KV Store

The key-values (KV) store is Veraison storage layer. It is used for both endorsements and trust anchors.

It is intentionally "dumb": we assume that the filtering smarts are provided by the plugins.

The key is a string synthesised deterministically from a structured endorsement / trust anchor "identifier". It is formatted according to a custom URI format -- see below).

The value is an array of JSON strings each containing an endorsement or trust anchor data associated with that key. The data is opaque to the KV store and varies depending on the attestation format. The only invariant enforced by the KV store is that it is valid JSON.

The IKVStore interface defines the required methods for storing, fetching and deleting KV objects. Note that (for the moment) there is no method for patching data in place. Interface methods for initialising and orderly terminating the underlying DB are also exposed.

This package contains two implementations of the IKVStore:

1. SQL, supporting different SQL engines (e.g., SQLite, PostgreSQL, etc. -- see below),
2. Memory, a thread-safe in-memory associative array intended for testing.

A New method can be used to create either of these from a Config object.

Configuration

kvstore expects the following entries in configuration:

• backend: the name of the backend to use for the store. Currently supported backends: memory, sql.
• <backend name>: an entry with the name of a backend is used to specify the configuration for that backend. There may be multiple such entries for different backends. Only the entry matching the active backend specified by backend directive will actually be used. The contents for each entry is specific to the backend.

Note: in a config file, kvstore configuration will typically be namespaced under the name of a particular store instance, e.g.

ta-store:
  backend: sql
  sql:
    driver: sqlite3

memory backend configuration

Currently, memory backend does not support any configuration.

sql backend configuration

Note: sqlite3, the default driver for the backend, is unsuitable for production or performance testing.

• driver: The name of the golang SQL driver. Veraison currently includes the following drivers: sqlite3, mysql (MySQL and MariaDB), and pgx (Postgres).
• datasource: This points to the database the driver will access. The format is driver-dependent.
  • sqlite3: the path to the sqlite3 database file
  • pgx: a URL in the form postgresql://<user>:<passwd>@<host>:<port>/<database>
  • mysql: string in the form <user>:<password>@<protocol>(<address>)/<database> (Please see the drivers' documentation for more details.)
• tablename (optional): the name of the table within the SQL database that will
• be used by the store. If this is not specified, it will default to "kvstore".

Alternative SQL drivers

To use another SQL driver (see here) in your code that uses IKVStore, the calling code needs to (anonymously) import the supporting driver.

For example, to use PostgreSQL:

import _ "github.com/lib/pq"

Instead, to use SQLite:

import _ "github.com/mattn/go-sqlite3"

SQL schemas

CREATE TABLE endorsements (
  kv_key text NOT NULL,
  kv_val text NOT NULL
);

CREATE TABLE trust_anchors (
  kv_key text NOT NULL,
  kv_val text NOT NULL
);

CREATE TABLE policies (
  kv_key text NOT NULL,
  kv_val text NOT NULL
);

URI format

scheme ":" authority path-absolute

where:

• scheme encodes the attestation format (e.g., "psa", "tcg-dice", "tpm-enacttrust", "open-dice", "tcg-tpm", etc.)
• authority encodes the tenant
• path-absolute encodes the parts of the key, identified positionally. Missing optional parts are encoded as empty path segments.

Attestation technology specific code (i.e., plugins) must provide their own synthesis functions.

Examples

PSA

• Trust Anchor ID
  • psa-iot://TenantID.Fmt()/ImplID.Fmt()/InstID.Fmt()`
• Software ID (Model is optional)
  • psa-iot://TenantID.Fmt()/ImplID.Fmt()/Model.Fmt()
  • psa-iot://TenantID.Fmt()/ImplID.Fmt()/

EnactTrust TPM

• Trust Anchor ID
  • tpm-enacttrust://TenantID.Fmt()/NodeID.Fmt()
• Software ID
  • tpm-enacttrust://TenantID.Fmt()/NodeID.Fmt()

Documentation

Overview

Copyright 2021-2023 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2021-2023 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2021-2023 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2022-2023 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2021-2023 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Copyright 2021-2024 Contributors to the Veraison project. SPDX-License-Identifier: Apache-2.0

Index

• Constants
• Variables
• type IKVStore
  • func New(v *viper.Viper, logger *zap.SugaredLogger) (IKVStore, error)
• type Memory
  • func (o *Memory) Add(key string, val string) error
  • func (o *Memory) Close() error
  • func (o *Memory) Del(key string) error
  • func (o Memory) Dump()
  • func (o Memory) Get(key string) ([]string, error)
  • func (o Memory) GetKeys() ([]string, error)
  • func (o *Memory) Init(unused *viper.Viper, logger *zap.SugaredLogger) error
  • func (o *Memory) Set(key string, val string) error
  • func (o *Memory) Setup() error
• type SQL
  • func (o SQL) Add(key string, val string) error
  • func (o *SQL) Close() error
  • func (o SQL) Del(key string) error
  • func (o SQL) Get(key string) ([]string, error)
  • func (o SQL) GetKeys() ([]string, error)
  • func (o *SQL) Init(v *viper.Viper, logger *zap.SugaredLogger) error
  • func (o SQL) Set(key string, val string) error
  • func (o SQL) Setup() error

Constants

const (
	DirectiveBackend = "backend"
)

Common directives -- MUST NOT be reused by specialisations

Variables

var (
	DefaultTableName = "kvstore"
)

var ErrKeyNotFound = errors.New("key not found")

Types

type IKVStore

type IKVStore interface {
	// Init initializes the store. The parameters expected inside
	// viper.Viper are implementation-specific -- please see the
	// documentation for the implementation you're using.
	Init(v *viper.Viper, logger *zap.SugaredLogger) error

	// Close the store, shutting down the underlying connection (if one
	// exists in the implementation), and disallowing any further
	// operations.
	Close() error

	// Setup a new store for use. What this actually entails is  specific
	// to a backend.
	Setup() error

	// Get returns a []string of values for the specified key. If the
	// specified key is not in the store, a ErrKeyNotFound is returned. The
	// values are in the order they were added, with the most recent value
	// last.
	Get(key string) ([]string, error)

	// GetKeys returns a []string of keys currently set in the store.
	GetKeys() ([]string, error)

	// Set the specified key to the specified value, discarding any
	// existing values.
	Set(key, val string) error

	// Del removes the specified key from the store, discarding its
	// associated values. If the key does not exist, ErrKeyNotFound will be
	// returned.
	Del(key string) error

	// Add the specified value to the specified key. If the key does
	// not already exist, this behaves like Set. If the key exists, the
	// specified val is appended to the existing value(s).
	Add(key, val string) error
}

IKVStore is the interface to a key-value store. Keys and values are both strings. A key can be associated with multiple values.

func New

func New(v *viper.Viper, logger *zap.SugaredLogger) (IKVStore, error)

type Memory

type Memory struct {
	Data map[string][]string
	// contains filtered or unexported fields
}

func (*Memory) Add

func (o *Memory) Add(key string, val string) error

func (*Memory) Close

func (o *Memory) Close() error

func (*Memory) Del

func (o *Memory) Del(key string) error

func (Memory) Dump

func (o Memory) Dump()

func (Memory) Get

func (o Memory) Get(key string) ([]string, error)

func (Memory) GetKeys

func (o Memory) GetKeys() ([]string, error)

func (*Memory) Init

func (o *Memory) Init(unused *viper.Viper, logger *zap.SugaredLogger) error

Init initializes the KVStore. There are no configuration options for this implementation.

func (*Memory) Set

func (o *Memory) Set(key string, val string) error

func (*Memory) Setup

func (o *Memory) Setup() error

type SQL

type SQL struct {
	TableName   string
	DB          *sql.DB
	Placeholder sq.PlaceholderFormat
	// contains filtered or unexported fields
}

func (SQL) Add

func (o SQL) Add(key string, val string) error

func (*SQL) Close

func (o *SQL) Close() error

func (SQL) Del

func (o SQL) Del(key string) error

func (SQL) Get

func (o SQL) Get(key string) ([]string, error)

func (SQL) GetKeys

func (o SQL) GetKeys() ([]string, error)

func (*SQL) Init

func (o *SQL) Init(v *viper.Viper, logger *zap.SugaredLogger) error

Init initializes the KVStore. The config may contain the following values, all of which are optional: "sql.tablename" - The name of the table with key-values pairs (defaults to

"kvstore".

"sql.driver" - The SQL driver to use; see

https://github.com/golang/go/wiki/SQLDrivers (defaults to
"sqlite3").

"sql.datasource" - The name of the data source to use. Valid values are

driver-specific (defaults to "db=veraison.sql".

func (SQL) Set

func (o SQL) Set(key string, val string) error

func (SQL) Setup

func (o SQL) Setup() error