ockam

README

Overview

Ockam is a decentralized and open platform for easily adding identity, trust and interoperability to connected devices.

This repository contains:

1. The ockam command line program for simple interactions with the Ockam Network.
2. The github.com/ockam-network/ockam Go package to develop Go applications that programatically interact with the Ockam Network.

In the near future, we plan to add ockam packages for other programming languages.

Command Line

The simplest way to get started is to download the latest ockam command for your operating system. You can get it from our release bundles or using this simple script:

curl -L https://git.io/fhZgf | sh

This will download the command to ./bin/ockam in your current directory. The binary is self contained, so if you wish to you can copy it to somewhere more convenient in your system path, for example:

cp ./bin/ockam /usr/local/bin/

Once the command is in you path, you can run:

ockam --version

Next you may call:

ockam register

which will generate a unique ockam decentralized identity for your computer and register it on the Ockam TestNet.

Go Package

You can add the ockam Go package to your project just like any other Go package, by calling go get:

go get github.com/ockam-network/ockam

We require Go version 1.11+.

Hello Ockam

Here is some simple Go code to connect with the Ockam TestNet:

// create a lightweight local ockam node and give it a way to find peers on the ockam test network
ockamNode, err := node.New(node.PeerDiscoverer(http.Discoverer("test.ockam.network", 26657)))
if err != nil {
	log.Fatal(err)
}

// ask the local node to find peers and sync with network state
err = ockamNode.Sync()
if err != nil {
	log.Fatal(err)
}

// print the id of the chain that the network is maintaining.
ockamChain := ockamNode.Chain()
fmt.Printf("Chain ID: %s\n", ockamChain.ID())

Note: The Ockam Testnet is provided and maintained by the Ockam team to help you build and experiment with applications that interact with Ockam. The TestNet has no service level gauruntees, may have intermittent availability, may be down for maintenance, and may be restarted at anytime. If your application needs a production ready network, please email the Ockam team at hello@ockam.io

Register an Entity

// create a new ed25519 signer
signer, err := ed25519.New()
if err != nil {
	log.Fatal(err)
}

// create a new ockam entity to represent a temperature sensor
temperatureSensor, err := entity.New(
	entity.Attributes{
		"name":         "Temperature Sensor",
		"manufacturer": "Element 14",
		"model":        "Raspberry Pi 3 Model B+",
	},
	entity.Signer(signer),
)
if err != nil {
	log.Fatal(err)
}

// register the entity by creating a signed registration claim
registrationClaim, err := ockamChain.Register(temperatureSensor)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("registrationClaim - %s\n", registrationClaim.ID())

This verifiable registration claim embeds the DID Document that represents this newly created entity.

{
	"@context": [
		"https://w3id.org/identity/v1",
		"https://w3id.org/security/v1"
	],
	"id": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5/claim/1brpf2pkh6",
	"type": [
		"EntityRegistrationClaim"
	],
	"issuer": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5",
	"issued": "2019-01-10",
	"claim": {
		"authentication": [
			{
				"publicKey": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5#key-1",
				"type": "Ed25519SignatureAuthentication2018"
			}
		],
		"id": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5",
		"manufacturer": "Element 14",
		"model": "Raspberry Pi 3 Model B+",
		"name": "Temperature Sensor",
		"publicKey": [
			{
				"id": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5#key-1",
				"publicKeyHex": "3c93f446990ecd3ce64bcf9a5f949423d2e348948ee3aeb1c78924490f6b50f9",
				"type": "Ed25519VerificationKey2018"
			}
		],
		"registrationClaim": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5/claim/1brpf2pkh6"
	},
	"signatures": [
		{
			"created": "2019-01-10T07:53:25Z",
			"creator": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5#key-1",
			"domain": "ockam",
			"nonce": "1brpf2pkh6",
			"signatureValue": "4v3cTB5u0/nA/xxrGU3gQ38IaP1MJJ7tQyPQtBtZmVLE36M96d2XRo0ArFyxQV2CsDMtP57n/vnvZWN88Du+Bg==",
			"type": "Ed25519Signature2018"
		}
	]
}

Submit a Claim

Submit a claim with some custom data:

// create a temperature claim with this new sensor entity as both the issuer and the subject of the claim
temperatureClaim, err := claim.New(
	claim.Data{"temperature": 100},
	claim.Issuer(temperatureSensor),
	claim.Subject(temperatureSensor),
)
if err != nil {
	log.Fatal(err)
}

// submit the claim to be
err = ockamChain.Submit(temperatureClaim)
if err != nil {
	log.Fatal(err)
}

fmt.Printf("Submitted - " + temperatureClaim.ID())

{
	"@context": [
		"https://w3id.org/identity/v1",
		"https://w3id.org/security/v1"
	],
	"id": "did:ockam:2PdDcphFfkW5eU1C1mFB1i9H8ZsgC/claim/iu5aczbwnt",
	"type": [
		""
	],
	"issuer": "did:ockam:2PdDcphFfkW5eU1C1mFB1i9H8ZsgC",
	"issued": "2019-01-10",
	"claim": {
		"id": "did:ockam:2PdDcphFfkW5eU1C1mFB1i9H8ZsgC",
		"temperature": 100
	},
	"signatures": [
		{
			"created": "2019-01-10T08:00:31Z",
			"creator": "did:ockam:2PdDcphFfkW5eU1C1mFB1i9H8ZsgC#key-1",
			"domain": "ockam",
			"nonce": "iu5aczbwnt",
			"signatureValue": "UpCPc/Z6bGwUXfgNgRFxpQU2kSt8HBoe8E94JyvlAKG1yBNBfqb4oUKdPZPHOQH37JtiIFap9eGS4qMBP35DDA==",
			"type": "Ed25519Signature2018"
		}
	]
}

Build

The build and run ockam code:

./build && ./build install && ockam --version

This requires recent versions of Bash and Docker installed on your development machine.

You may also work within a Vagrant and Virtualbox environment, see details on that and other build tools in the Contributing Guide

Contributing to Ockam

• Ask a question
• Report an issue or a bug
• Share an idea for a new feature
• Contribute Code
  • Development Environment
  • Build
  • Lint
  • Test
  • Project Conventions
    • Spacing and Indentation
    • Code Format
    • Commit Messages
    • Git Workflow
    • Signed Commits
  • Error Handling
  • Effective Go
  • Send a Pull Request
• Code of Conduct

Contributors

• Brian Schroeder
• Brett Nitschke
• Logan Jager
• Matthew Gregory
• Mrinal Wadhwa
• Rolf Kaiser

Documentation

Index

• func Version() string
• type Block
• type Chain
• type Claim
• type Entity
• type Fields
• type Logger
• type Node
• type NodeDiscoverer
• type PublicKey
• type Signature
• type Signer

Functions

func Version

func Version() string

Version returns the current version of Ockam

Types

type Block

type Block interface {
	Height() string
	Hash() string
}

Block represents a block in the Ockam Blockchain

type Chain

type Chain interface {
	ID() string
	Sync() error
	LatestBlock() Block
	Register(Entity) (Claim, error)
	Submit(Claim) error
}

Chain represents a chain of blocks that is maintained by a network of nodes

type Claim

type Claim interface {
	ID() string
	Nonce() string

	Type() string
	SetType(string)

	Issuer() Entity
	SetIssuer(Entity)

	Subject() Entity
	SetSubject(Entity)

	Data() map[string]interface{}
	SetData(map[string]interface{})

	Signatures() []Signature
	AddSignature(Signature)

	json.Marshaler
}

Claim is

type Entity

type Entity interface {
	ID() *did.DID
	PublicKeys() []PublicKey
	Signers() []Signer
	Attributes() map[string]interface{}
}

Entity represents and Ockam entity

type Fields

type Fields map[string]interface{}

Fields is

type Logger

type Logger interface {
	Error(format string, v ...interface{})
	Warn(format string, v ...interface{})
	Notice(format string, v ...interface{})
	Info(format string, v ...interface{})
	Debug(format string, v ...interface{})
	WithFields(fields Fields) Logger
}

Logger is an interface for Logging.

type Node

type Node interface {
	Chain
	Peers() []Node
	Chain() Chain
}

Node represents a node connected to a network of other peer nodes

type NodeDiscoverer

type NodeDiscoverer interface {
	Discover() ([]Node, error)
}

NodeDiscoverer provides the means to discover other nodes on in a network

type PublicKey

type PublicKey interface {
	Label() string
	SetLabel(string)

	Owner() Entity
	SetOwner(Entity)

	Type() string
	Encoding() string
	Value() string

	DID() *did.DID
}

PublicKey is

type Signature

type Signature interface {
	// Type
	// https://w3c-ccg.github.io/ld-cryptosuite-registry/#ed25519signature2018
	Type() string
	Creator() string
	Created() string
	Domain() string

	// Nonce
	// https://web-payments.org/vocabs/security#nonce
	Nonce() string

	// SignatureValue
	// https://web-payments.org/vocabs/security#signatureValue
	SignatureValue() []byte

	SignedValue() []byte
}

Signature is https://w3c-dvcg.github.io/ld-signatures/#linked-data-signature-overview

type Signer

type Signer interface {
	PublicKey() PublicKey
	Sign(Claim) error
	SignatureType() string
}

Signer is