awot

README

Automated Web of Trust (awot)

What it is

A fully decentralized solution to the Public-Key Distribution Problem.

Why it exists

Using crypto is great, but advertising public keys in IP network is prone to impersonation or man in the middle attacks. AWOT provides uses an implicit underlying social network to detect and avoid problems such as collision of keys (two keys for a given user) or sibyl attacks. This allows to obtain public keys from trusted peers and redistribute them, while recording how much "trust" one put on those keys.

Please check the write up to fully understand the benefits and drawbacks of this method.

How it works

write up

How to use

This library is to be used on an existing decentralized network. Check out our Peerster to see a working implementation.

And please check out the "go doc" :)

You may need to get used to these objects :

• KeyRecord : A key and its owner's name.
• TrustedKeyRecord : A KeyRecord with a confidence level attached to it.
• KeyExchangeMessage : A message that contains every information needed for sharing and receiving public key association. These are the messages that will need to be sent and received in the network. It contains : the public key, the owner's name of the key, the sender's name of the message and the signature of the key with the owner name, signed by the sender.
• KeyRing : this is the main database that will need to be updated with the received KeyExchangeMessages, it will perform some computations and gives back the trusted keys and confidence levels. It needs to be started, and will spawn a thread.

Documentation

Overview

Package awot provides an API for collecting public keys in a decentralized fashion on a network.

The name "awot" is short for Automatic Web of Trust. As its name suggests, awot is based on a Web of Trust model for sharing and collecting public keys. Contrary to the PGP Web of Trust, awot is automated : it does not require human interaction once loaded. Since there is no required human validation when collecting keys, it is not completely safe from possible attacks. However it tries to solve these problems by computing releveant confidence levels for each obtained key, this can help avoiding key collisions or impersonations. Package awot is best used in addition to a reputation system in a network, a system that can output a "trust" level for each peer, that is how much trust we can put on this peer to share good public keys.

Index

• func DeserializeKey(bytes []byte) (rsa.PublicKey, error)
• func Fingerprint(pub rsa.PublicKey) string
• func SerializeKey(key rsa.PublicKey) ([]byte, error)
• func Verify(msg KeyExchangeMessage, OriginKeyPub rsa.PublicKey) error
• type Edge
  • func (e Edge) From() graph.Node
  • func (e Edge) To() graph.Node
• type EdgeViz
• type GraphViz
  • func GraphVizRepr(ring KeyRing) GraphViz
• type KeyExchangeMessage
• type KeyRecord
• type KeyRing
  • func NewKeyRing(owner string, key rsa.PublicKey, trustedRecords []TrustedKeyRecord, ...) KeyRing
  • func (ring *KeyRing) Add(rec KeyRecord, sigOrigin string, reputationOwner float32)
  • func (ring *KeyRing) AddUnverified(msg KeyExchangeMessage)
  • func (ring KeyRing) Dot() *[]byte
  • func (ring KeyRing) GetKey(name string) (rsa.PublicKey, bool)
  • func (ring KeyRing) GetPeerList() []string
  • func (ring KeyRing) GetRecord(name string) (TrustedKeyRecord, bool)
  • func (ring KeyRing) JSON() ([]byte, error)
  • func (ring *KeyRing) Start(rate time.Duration)
  • func (ring *KeyRing) StartWithReputation(rate time.Duration, reptable ReputationTable)
  • func (ring *KeyRing) Stop()
• type Node
  • func (n Node) DOTID() string
  • func (n Node) ID() int64
• type Path
• type ReputationTable
• type TrustedKeyRecord
  • func (rec *TrustedKeyRecord) ConstructMessage(priK rsa.PrivateKey, origin string) KeyExchangeMessage
• type VertexViz

Functions

func DeserializeKey

func DeserializeKey(bytes []byte) (rsa.PublicKey, error)

DeserializeKey deserializes a pem encoded x509 public key

func Fingerprint

func Fingerprint(pub rsa.PublicKey) string

Fingerprint returns the hex formatted fingerprint of the given rsa public key

func SerializeKey

func SerializeKey(key rsa.PublicKey) ([]byte, error)

SerializeKey encodes the given public key to a x509 format and serializes it to a pem format

func Verify

func Verify(msg KeyExchangeMessage, OriginKeyPub rsa.PublicKey) error

Verify verifies that the received message is signed by the pretended origin Returns nil if valid, an error otherwise

Types

type Edge

type Edge struct {
	F, T Node
	Key  rsa.PublicKey
}

An Edge is a directed edge F->T in the key ring, representing that F signed the key for T

func (Edge) From

func (e Edge) From() graph.Node

From returns the from-node of the edge.

func (Edge) To

func (e Edge) To() graph.Node

To returns the to-node of the edge.

type EdgeViz

type EdgeViz struct {
	Source      string
	Target      string
	Fingerprint string // fingerprint of the public key, in hex format
}

EdgeViz is a Vertex for a visualization of a KeyRing

type GraphViz

type GraphViz struct {
	Nodes []VertexViz
	Links []EdgeViz
}

GraphViz is a Graph for a visualization of a KeyRing

func GraphVizRepr

func GraphVizRepr(ring KeyRing) GraphViz

GraphVizRepr returns a representation of the KeyRing in GraphViz structure

type KeyExchangeMessage

type KeyExchangeMessage struct {
	KeyBytes  []byte // serialized public key
	Owner     string // owner of the public key
	Origin    string // signer
	Signature []byte // signature of (keyPub <-> owner)
}

A KeyExchangeMessage is a signed relation (publickey - owner) This should be used to share a known and relatively trusted public key to other peers

type KeyRecord

type KeyRecord struct {
	Owner  string
	KeyPub rsa.PublicKey
}

A KeyRecord is an association between a public key and an owner

type KeyRing

type KeyRing struct {
	// contains filtered or unexported fields
}

A KeyRing is a directed graph of Node and Edge

func NewKeyRing

func NewKeyRing(owner string, key rsa.PublicKey, trustedRecords []TrustedKeyRecord, threshold float32) KeyRing

NewKeyRing creates a new key-ring given some fully trusted (origin-public key) pairs. For updating the KeyRing, use KeyRing.Start() after creation. Parameters :

owner : the name (id) of the owner of the keychain (typically this network node)
key : the public key of owner
trustedRecords : the fully trusted bootstrap records : trusted public keys of initiators
threshold : the confidence threshold; below it the keys will not be given to the user

func (*KeyRing) Add

func (ring *KeyRing) Add(rec KeyRecord, sigOrigin string, reputationOwner float32)

Add updates the key ring with the given (verified) keyrecord and origin of the signature It assumes that the record's signature has been verified

func (*KeyRing) AddUnverified

func (ring *KeyRing) AddUnverified(msg KeyExchangeMessage)

AddUnverified adds a KeyExchangeMessage that could not yet be verified (e.g. lack of signer's key)

func (KeyRing) Dot

func (ring KeyRing) Dot() *[]byte

Dot marshals a keyring to a dot format, or nil if error

func (KeyRing) GetKey

func (ring KeyRing) GetKey(name string) (rsa.PublicKey, bool)

GetKey returns the key of peer with given name and true if it exists, otherwise returns false. If the confidence level is too low for the key, it does not return the key and reports as if there where none. This should be used e.g. when trying to communicate with a peer and threfore needing its key.

func (KeyRing) GetPeerList

func (ring KeyRing) GetPeerList() []string

GetPeerList returns the list of peer names the keyring has a public key for

func (KeyRing) GetRecord

func (ring KeyRing) GetRecord(name string) (TrustedKeyRecord, bool)

GetRecord returns the record of peer with given name and true if it exists, otherwise returns false. Returns the record even if the confidence level is lower than the threshold. This should be used e.g. when updating reputation of a peer.

func (KeyRing) JSON

func (ring KeyRing) JSON() ([]byte, error)

JSON Marshals a KeyRing to a json format {nodes: ..., edges: a->b}

func (*KeyRing) Start

func (ring *KeyRing) Start(rate time.Duration)

Start starts the updates on the KeyRing It spawns a goroutine that will update the keyring regularly at the given rate

func (*KeyRing) StartWithReputation

func (ring *KeyRing) StartWithReputation(rate time.Duration, reptable ReputationTable)

StartWithReputation starts the updates on the KeyRing using the given ReputationTable for some of them It spawns a goroutine that will update the keyring regularly, at given rate

func (*KeyRing) Stop

func (ring *KeyRing) Stop()

Stop stops the KeyRing. It will keep the state of the ring, but any later add will not update the confidence levels.

type Node

type Node struct {
	// contains filtered or unexported fields
}

A Node is a node in the key ring, representing a peer in the network

func (Node) DOTID

func (n Node) DOTID() string

DOTID returns a string representing the current state of a node

func (Node) ID

func (n Node) ID() int64

ID returns the integer ID of a node

type Path

type Path = []graph.Node

type ReputationTable

type ReputationTable interface {
	Reputation(string) (float32, bool)
}

A ReputationTable is the interface that wraps the Reputation function Reputation returns a reputation of a node with given name, as a float32 between 0 and 1, 0 being the worst reputation and 1 the best. It also returns a boolean informing if the reputation actually exists.

type TrustedKeyRecord

type TrustedKeyRecord struct {
	KeyRecord          // the record publik key - owner
	Confidence float32 // confidence level in the assocatiation owner - public key
	// contains filtered or unexported fields
}

A TrustedKeyRecord is a KeyRecord with a confidence level corresponding to the trust put in the KeyRecord

func (*TrustedKeyRecord) ConstructMessage

func (rec *TrustedKeyRecord) ConstructMessage(priK rsa.PrivateKey, origin string) KeyExchangeMessage

ConstructMessage constructs a KeyExchangeMessage from a TrustedKeyRecord and signs it if needed with given private key and origin name

type VertexViz

type VertexViz struct {
	Index       int64
	Name        string
	Probability float32
	Confidence  float32
}

VertexViz is a Vertex for a visualization of a KeyRing