Overview

Ockam is a collection of tools to help you establish secure connections and trustful exchange of information within connected systems.

This documentation page describes the core concepts and the underlying technology behind Ockam. To learn more please contact our team or join the Ockam community of Slack.

Hello Ockam

Before we dig deeper into the ideas behind Ockam, let's write a quick example to connect with a test instance of the Ockam Network.

With Go version 1.11+ installed, get the ockam Go package:

go get github.com/ockam-network/ockam

Copy the below example code into a file called hello_ockam.go+

package main

import (
	"fmt"
	"os"

	"github.com/ockam-network/ockam/node"
	"github.com/ockam-network/ockam/node/remote/http"
)

// This example shows how a device can connect to the Ockam Testnet.

func main() {
	// create a 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)))
	exitOnError(err)

	// ask the local node to find peers and sync with network state
	err = ockamNode.Sync()
	exitOnError(err)

	// get a reference to the chain that is being managed by the distributed ockam network
	// that the local node is connected to
	ockamChain := ockamNode.Chain()

	// print some information about the chain
	fmt.Printf("Chain ID: %s\n", ockamChain.ID())
	fmt.Printf("Latest Block Height: %s\n", ockamChain.LatestBlock().Height())
	fmt.Printf("Latest Block Hash: %s\n", ockamChain.LatestBlock().Hash())
}

func exitOnError(err error) {
	if err != nil {
		fmt.Fprintf(os.Stderr, "%+v\n", err)
		os.Exit(1)
	}
}

Then, run it as follows:

go run hello_ockam.go

This should print the current state of the Ockam Test Network.

Now, that we've said hello to the network, let's dig a little deeper.

Secure Connectivity & Messaging

IoT systems are, at their core, messaging systems. Connected devices, around us, exchange billions of messages everyday. Applications send commands to remote devices as messages. Sensors collect data about the physical world and share them with servers as messages. Devices, in proximity of each other, use messages to communicate wirelessly. Firmware and configuration updates are also delivered as a series of messages.

The transport protocols used to carry these messages vary across systems – TCP, TLS, HTTP, MQTT, CoAP, Bluetooth, NFC, LoRaWAN, NB-IoT, and many more. The schema, structure, and serialization format of messages also differ heavily across applications – Custom Binary, JSON, XML, Protocol Buffers, and many more.

This high degree of variation, in communication protocols, is why reasoning about security, trustworthiness and privacy has proven to be daunting for the larger IoT community. However, by focusing our efforts on the message layer and how trust is established in each type of message flowing within a system, Ockam enables us to build a robust, transport agnostic, end-to-end architecture for trust within our IoT solutions.

Trust Architecture

We build connected systems so we can rely on the automation they bring to our lives and our businesses. Our wish is to trust these systems to collect information and take actions on our behalves.

This trust, however, should not be absolute. An overall system is typically composed of several moving parts (entities). To deliver the promise of the entire system, every entity within the system must establish trust in every interaction it has with any other entity that is part of the system. The operating environment is also usually highly dynamic – devices (entities) may enter or leave a deployment, firmware is updated frequently, configuration may be changed by an administrator, attackers may try to compromise the system etc.

Architects of such complex, dynamic systems need simple protocols and tools that allow us to easily make explicit, nuanced decisions about trust within the granular context of each interaction at play within our systems. Broad stroke decisions can result in critical weaknesses.

Before we discuss further, let’s establish a shared understanding of what it means to trust. In the book Achieving Digital Trust, Jeffrey Ritter writes:

Trust (or the absence of trust) is the resulting sum of a rules-based, information-fueled calculation.
Trust is the affirmative output of a disciplined, analytical decision process that measures and scores the suitability of the next actions taken by you, your team, your business, or your community.

Trust is the calculation of the probability of outcomes.

When deciding to act on any new information — a sensor reading message, a remote alarm message, a message that commands an actuator or contains a firmware update — we must apply a set of rules on all the information available to us, within that context, to decide if we can trust this new information enough to act on it.

Since connected systems are, at their core, messaging systems a natural place to apply these rules is when one entity (trustor) receives a new message from another entity (trustee) and is deciding on whether on not to act on this message.

By focusing attention on such application layer exchange of messages, Ockam hides the complexity of dealing with a variety of transport protocols, hardware and network topologies. This change in focus makes it simpler to explicitly consider subtle factors that shape trust within the architecture of a connected IoT solution.

The question then becomes: what rules should the trustor apply in a particular situation?

Minimum Criteria for Trust

We need a set of explicit criteria to decide if we can trust any new message enough to act on it. Trust within connected systems is context specific, multi-faceted and nuanced. Solution builders must decide which criteria build trust within a given context.

Different scenarios may require varying degrees of trust. For instance, a firmware update may require a greater degree of trust than a message from a temperature sensor in a weather station. In contrast, a temperature sensor message from a machine on a factory floor that could cause an emergency shutdown, if it crosses a threshold, should require a really high degree of trust. Ockam’s goal is to enable system builders to easily gauge against such criteria and build secure systems that can be relied on.

Security and privacy are great guiding principles for a minimum criteria that must be thoughtfully considered in every message exchange. The STRIDE model, developed in 1999 by Praerit Garg and Loren Kohnfelder at Microsoft, provides an easy to remember mnemonic for the minimum set of threats that every messaging based system must consider:

  • .
  • S
  • T
  • R
  • I
  • D
  • E
  • Threat
  • Spoofing identity
  • Tampering with data
  • Repudiation
  • Information disclosure
  • Denial of service
  • Elevation of privilege
  • Desired property
  • Authenticity
  • Integrity
  • Non-repudiability
  • Confidentiality
  • Availability
  • Authorization

In a situation where entity B receives a message, The STRIDE model gives B a minimum starting criteria to gauge if it should trust this message:

Identification

  • Figure out who the message is from. (answer in the above case may be A).

Authenticity

  • Prove to a reasonable level of assurance that the message really came from A and the identification process was not fooled.

Integrity

  • Prove to a reasonable level of assurance that the message B has received is exactly the message A sent.undefined
  • Prove to a reasonable level of assurance that the message B has received is not a replay of a message A created in the past.

Non-repudiability

  • Prove to a reasonable level of assurance that given what B knows, B could prove to someone else that the message came from A.

Confidentiality

  • Prove that someone other that A or B did not see the contents of message while in transit. (Encryption)
  • Prove that a future compromise of B's private keys will not expose past session data. (Perfect Forward Secrecy)
  • Prove that someone other that A or B was not able to observe metadata about which entities exchanged messages and when. (Privacy)
  • Prove that A would not be able to co-relatable B's activity with other publicly available activity. (Privacy)
  • Prove that private key material is not accidentally leaked during the exchange.

Availability

  • Prove that the message is not a malicious attempt to overwhelm B and take it out of service.

Authorization

  • Prove that A is allowed to produce information that is contained in the message.
  • Prove that the message is not a malicious attempt to escalate privilege.

While the above list of rules is not exhaustive, it provides a robust framework to start reasoning about trust within systems, one message exchange at a time.

Application needs will vary, some systems will prefer to have repudiability to favor privacy, while other applications would prefer to have non-repudiability to favor accountability, some scenarios would demand confidentiality while others won't.

However, all connected systems must have at least a guarantee of data integrity. Any system without trust in integrity of messages cannot be relied on and is rendered futile. It is also important to note that proving data integrity requires identification and authenticity. Hence the absolute minimum criteria for trust is Identification, Authenticity and Integrity.

Achieving all of the above criteria needs careful and robust implementations of identity management, credential management, cryptography, authentication and messaging protocols. Ockam SDK abstracts this complicity and makes it easy for you to develop reliable and trustworthy systems.

Decentralized Identifiers

As we noted above, Identification and Authenticity are critical components in establishing data integrity. Decentralized Identifier (DID) is a new type of identifier (standard under development at W3C) that can prove its authenticity unlike a MAC address, IP address or UUID.

DIDs are fully under the control of the DID subject (entity) and this control can be cryptographically proven.

In Ockam people, places, services, and things are modeled as entities. Each Entity has at least one DID that begins with did:ockam: and uses the ockam DID method. An example Ockam DID looks like this: did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5.

A DID is also a URL that resolves to a DID document. DID documents allow an Entity to declare its current public keys, authentication methods, communication endpoints and other metadata.

{
  "id": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5"
  "publicKey": [
    {
      "id": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5#key-1",
      "publicKeyHex": "3c93f446990ecd3ce64bcf9a5f949423d2e348948ee3aeb1c78924490f6b50f9",
      "type": "Ed25519VerificationKey2018"
    }
  ],
  "authentication": [
    {
      "publicKey": "did:ockam:2QyqWz4xWB5o4Pr9G9fcZjXTE2ej5#key-1",
      "type": "Ed25519SignatureAuthentication2018"
    }
  ]
}

An entity may control more than one DID to maintain privacy. It may then chose to use pairwise unique DIDs for each relationship to ensure that interactions in different contexts are not co-relatable.

Device and Service Registry

If an Entity (device or service) wishes to make its public keys and other metadata discoverable, it may register itself with an Ockam Network Zone. Registration stores the corresponding DID document in the blockchain based Entity Registry and ensures that the only the subject entity can edit the document. This way DIDs and their corresponding keys are not controlled by any central party like a certificate authority and are fully under the control of DID subject.

Here is some sample code to 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 generates a new ed25519 signer, then creates a new entity and assigns it that signer. It also adds other attributes to the entity (e.g., its manufacturer's name).

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 cryptographically signed using the entity's signer and then submitted 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"
		}
	]
}

The Entity Registry makes device and service public keys and endpoints discoverable which can greatly simplify on boarding workflows. It also enables us to establish a Web of Trust around an entity.

Hardware Vault and Cryptography

The ideal place to store private keys and credentials is hardware based cryptographic modules or enclaves, Ockam SDK provides an easy abstractions called Vault to leverage hardware key storage and hardware accelerated cryptography to sign device or service generated data. Hardware specific Vault implementations can be easily added to support your hardware.

Key and Credential Management

Ockam Network combined with DID documents in the Entity Registry provides a decentralized solution for key lifecycle management. The replaces complex and brittle PKI hierarchies with a more robust Web of Trust model. It also greatly simplifies the rotation and revocation of key and credentials which can be a challenge with PKI.

Trustful Communication

Establishing trust over and above the minimum criteria requires attestations. We use Verifiable Credentials (standard under development at W3C) to enable one entity to make signed claims and issue credentials to other entities.

For instance, multiple parties responsible for manufacturing and operating a device may write claims about that device to Ockam Network to create a Web of Trust around that device. Other entities may then require additional rules to be satisfied (over and above the minimum criteria) before they trust a message for this device - I will only trust messages from devices that have been attested by ACME corp.

Here's an example that creates 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
err = ockamChain.Submit(temperatureClaim)
if err != nil {
	log.Fatal(err)
}

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

This 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"
		}
	]
}

We also provide a Peer-to-peer Mutual Authentication protocol that leverages DIDs and does not involve a centralized identity provider (IDP). DID based authentication enables a device to establish a mutually authenticated channel of communication with a service. This channel can be used to reliably deliver signed data, firmware and new configuration.

DID based authentication also enables a device to establish a mutually authenticated channel with another device.

End-to-End encrypted messaging

Applications that require confidentiality and privacy require end-to-end encrypted messaging. Ockam is building a decentralized, end-to-end encrypted, publish/subscribe messaging infrastructure that is optimized for IoT.

Trusted Twins

Devices, that are intermittently connected, greatly benefit from a cloud based digital twin of the device that is persistently connected so that other entities (devices or applications) can interact with device state and enqueue messages even when a device is offline. Within Ockam we establish mutual trust between a device and its twin using the various techniques discussed above combined with secure enclave technologies like Intel SGX. Low power devices can also leverage Ockam Trusted Twins to amplify their limited resources.

Ockam Blockchain Network

Ockam Blockchain Network is a byzantine fault tolerant (BFT), fast finality, safety favoring, light client friendly, and horizontally scalable blockchain network optimized for IoT. It can help you design for trust scenarios that require multi-party trust and is used within our system to decentralize key management, establish web of trust in entities and to greatly simplify credential rotation and revocation.There is public test network instance available at ockam.network to help you build and experiment with applications.If your system needs a production-ready network, please email the Ockam team at hello@ockam.io.

© 2017-2019 Ockam.io. All right reserved.
Privacy Policy