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.

• Get the Golang package
• Write your first Hello Ockam program
• Register an Entity
• Submit a Claim
• Use the Ockam Command
• Build the source code
• Contribute to Ockam
• Contributors
• License and attributions

Go Package

You can add the ockam Golang package to your project using 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())

A runnable version of the above example can be found in the example directory. You may run it by calling:

go run -mod=vendor example/01_hello_ockam.go

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 guarantees, 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

In Ockam, things are modeled as entities. Each Entity has a DID that begins with did:ockam: and uses the ockam DID method.

An example ockam DID, looks like this: did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5

// 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())

A runnable version of the above example can be found in the example directory. You may run it by calling:

go run -mod=vendor example/02_register_entity.go

The above program generates a new ed25519 signer, then creates a new entity and assigns it that signer. The above code also adds some attributes to the entity, like its manufacturer's name.

Finally the code above, as part of the Register method generates an EntityRegistrationClaim. This verifiable registration claim embeds the DID Document that represents this newly created entity.

The claim is then cryprographically signed using the entity's signer and then subitted to the network.

An example EntityRegistrationClaim claim looks like this:

{
	"@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

Once an entity is registered, it can make signed verifiable claims about itself or other entities.

Here is some code to create and submit a new signed claim that includes a temperature reading:

// 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())

A runnable version of the above example can be found in the example directory. You may run it by calling:

go run -mod=vendor example/03_submit_claim.go

The above code generates a signed claim of the following form:

{
	"@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"
		}
	]
}

Command Line

The ockam command is a useful tool to interact with the Ockam Network. You can install the commad for your operating system 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 that identity on the Ockam TestNet.

Build

To build and run ockam from source:

./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, a Vagrnatfile is included. Our Contributing Guide has more details on how to build and contribute to Ockam.

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

License and attributions

This code is licensed under the terms of the Apache License 2.0

This code depends on other open source packages, attributions for those packages are in the NOTICE file

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