protocol

package
v0.0.0-...-11acf48 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 22, 2018 License: BSD-3-Clause Imports: 4 Imported by: 0

Documentation

Overview

Package protocol is a library for building compatible CONIKS clients and servers.

protocol implements the server- and client-side components of the CONIKS key management and verification protocols. More specifically, protocol provides an API for maintaining an auditable, privacy-preserving key directory on a server, as well as an API for checking the consistency of the directory at the client.

Auditlog

This module implements a CONIKS audit log that a CONIKS auditor maintains. An audit log is a mirror of many CONIKS key directories' STR history, allowing CONIKS clients to audit the CONIKS directories.

Auditor

This module implements a generic CONIKS auditor, that is all the functionality that clients and auditors need to verify a server's STR history.

Client

This module implements all consistency checks performed by a CONIKS client on directory proofs received from a CONIKS server. These operations include the verification of username-to-key bindings (authentication paths), and non-equivocation checks (signed tree roots).

Directory

This module implements a CONIKS key directory that a CONIKS key server maintains. A directory is a publicly auditable, tamper-evident, privacy-preserving data structure that contains mappings from usernames to public keys. It currently supports registration of new mappings, latest-version key lookups, historical key lookups, and monitoring of mappings.

Tests

This module contains integration test cases for CONIKS directory, CONIKS client and CONIKS auditor modules.

Error

This module defines the constants representing the types of errors that a CONIKS server may return to a client, and the results of a consistency check or a cryptographic verification that a CONIKS client performs.

Message

This module defines the message format of the CONIKS client requests and corresponding CONIKS server responses for each CONIKS protocol. It also provides constructors for the response messages for each protocol.

Policy

This module defines the directory's current CONIKS security/privacy policies, which include the public part of the VRF key used to generate private indices, the cryptographic algorithms in use, as well as the protocol version number.

Temporary Binding

This module implements a temporary binding, which serves both as a proof of registration with a directory and as a signed promise by a CONIKS server to include the corresponding name-to-key binding in the next directory snapshot. As such, TBs allow clients to begin using a newly registered name-to-key binding for encryption/signing immediately without having to wait for the binding's inclusion in the next snapshot. However, clients must still check in the next epoch that the binding has been included in the snapshot to ensure that the server has not equivocated about it.

Index

Constants

View Source 
const (
	RegistrationType = iota
	KeyLookupType
	KeyLookupInEpochType
	MonitoringType
	AuditType
	STRType
)

The types of requests CONIKS clients send during the CONIKS protocols.

View Source 
const (
	// Version indicates the current protocol version.
	Version = "0.3"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditingRequest 

type AuditingRequest struct {
	DirInitSTRHash [crypto.HashSizeByte]byte
	StartEpoch     uint64
	EndEpoch       uint64
}

An AuditingRequest is a message with a CONIKS key directory's address as a string, and a StartEpoch and an EndEpoch as uint64's that a CONIKS client sends to a CONIKS auditor to request the given directory's STRs for the given epoch range. To obtain a single STR, the client must set StartEpoch = EndEpoch in the request.

The response to a successful request is an STRHistoryRange with a list of STRs covering the epoch range [StartEpoch, EndEpoch].

type DirSTR 

type DirSTR struct {
	*merkletree.SignedTreeRoot
	Policies *Policies
}

DirSTR disambiguates merkletree.SignedTreeRoot's AssocData interface, for the purpose of exporting and unmarshalling.

func NewDirSTR 

func NewDirSTR(str *merkletree.SignedTreeRoot) *DirSTR

NewDirSTR constructs a new DirSTR from a merkletree.SignedTreeRoot

func (*DirSTR) Serialize 

func (str *DirSTR) Serialize() []byte

Serialize overrides merkletree.SignedTreeRoot.Serialize

func (*DirSTR) VerifyHashChain 

func (str *DirSTR) VerifyHashChain(savedSTR *DirSTR) bool

VerifyHashChain wraps merkletree.SignedTreeRoot.VerifyHashChain

type DirectoryProof 

type DirectoryProof struct {
	AP  []*merkletree.AuthenticationPath
	STR []*DirSTR
	TB  *TemporaryBinding `json:",omitempty"`
}

A DirectoryProof response includes a list of authentication paths AP for a given username-to-key binding in the directory and a list of signed tree roots STR for a range of epochs, and optionally a temporary binding for the given binding for a single epoch.

type DirectoryResponse 

type DirectoryResponse interface{}

A DirectoryResponse is a message that includes cryptographic proofs about the key directory that a CONIKS key directory or auditor returns to a CONIKS client.

type ErrorCode 

type ErrorCode int

An ErrorCode implements the built-in error interface type. 

const (
	ReqSuccess ErrorCode = iota + 100
	ReqNameExisted
	ReqNameNotFound
	// auditor->client: no observed history for the requested directory
	ReqUnknownDirectory

	ErrDirectory
	ErrAuditLog
	ErrMalformedMessage
)

These codes indicate the status of a client-server or client-auditor message exchange. Codes prefixed by "Req" indicate different client request results. Codes prefixed by "Err" indicate an internal server/auditor error or a malformed message. 

const (
	CheckBadSignature ErrorCode = iota + 200
	CheckBadVRFProof
	CheckBindingsDiffer
	CheckBadCommitment
	CheckBadLookupIndex
	CheckBadAuthPath
	CheckBadSTR
	CheckBadPromise
	CheckBrokenPromise
)

These codes indicate the result of a consistency check or cryptographic verification. These codes are prefixed by "Check".

func (ErrorCode) Error 

func (e ErrorCode) Error() string

Error returns the error message corresponding to the error code e.

type KeyLookupInEpochRequest 

type KeyLookupInEpochRequest struct {
	Username string
	Epoch    uint64
}

A KeyLookupInEpochRequest is a message with a username as a string and an epoch as a uint64 that a CONIKS client sends to the directory to retrieve the public key bound to the username in the given epoch. The client sends this request type when it needs to obtain a user's key for a past epoch. The client can send a KeyLookupRequest if it needs to look up a user's key for the latest epoch.

The response to a successful request is a DirectoryProofs with an AP of length 1 containing the auth path for the requested Epoch, and a list of STRs covering the epoch range [Epoch, d.LatestSTR().Epoch].

type KeyLookupRequest 

type KeyLookupRequest struct {
	Username string
}

A KeyLookupRequest is a message with a username as a string that a CONIKS client sends to a CONIKS directory to retrieve the public key bound to the given username at the latest epoch. If the client needs to look up a username's key for a prior epoch, it must send a KeyLookupInEpochRequest.

The response to a successful request is a DirectoryProof with a TB if the requested username was registered during the latest epoch (i.e. the new binding hasn't been committed to the directory).

type MonitoringRequest 

type MonitoringRequest struct {
	Username   string
	StartEpoch uint64
	EndEpoch   uint64
}

A MonitoringRequest is a message with a username as a string and the start and end epochs of an epoch range as two uint64 that a CONIKS client sends to the directory to monitor the given user's key in a CONIKS key directory, i.e. to ensure that the key bound to the username hasn't changed unexpectedly.

If the client needs to check the consistency of a user's binding for a range of epochs (e.g. if the client went offline for several epochs and was unable to monitor its user's binding during that period), it indicates the beginning of the range with the start epoch, and the end of the range with the end epoch. An end epoch with a value greater than the key directory's latest epoch sets the end of the epoch range at the directory's latest epoch.

Specifically, there are two cases for doing monitoring: prior history verification which can be used to verify the absence of the binding before registration, and name-to-key binding monitoring which can be used to verify the inclusion of the binding after registration.

type Policies 

type Policies struct {
	Version       string
	HashID        string
	VrfPublicKey  vrf.PublicKey
	EpochDeadline Timestamp
}

Policies is a summary of the directory's current CONIKS security/privacy policies. This includes the public part of the VRF key used to generate private indices, the cryptographic algorithms in use, as well as the protocol version number.

func GetPolicies 

func GetPolicies(str *merkletree.SignedTreeRoot) *Policies

GetPolicies returns the set of policies included in the STR.

func NewPolicies 

func NewPolicies(epDeadline Timestamp, vrfPublicKey vrf.PublicKey) *Policies

NewPolicies returns a new Policies with the given epoch deadline and public VRF key.

func (*Policies) Serialize 

func (p *Policies) Serialize() []byte

Serialize serializes the policies for signing the tree root. Default policies serialization includes the library version (see version.go), the cryptographic algorithms in use (i.e., the hashing algorithm), the epoch deadline and the public part of the VRF key.

type RegistrationRequest 

type RegistrationRequest struct {
	Username               string
	Key                    []byte
	AllowUnsignedKeychange bool `json:",omitempty"`
	AllowPublicLookup      bool `json:",omitempty"`
}

A RegistrationRequest is a message with a username as a string and a public key as bytes that a CONIKS client sends to a CONIKS directory to register a new entry (i.e. name-to-key binding). Optionally, the client can include the user's key change and visibility policies as boolean values in the request. These flags are currently unused by the CONIKS protocols.

The response to a successful request is a DirectoryProof with a TB for the requested username and public key.

type Request 

type Request struct {
	Type    int
	Request interface{}
}

A Request message defines the data a CONIKS client must send to a CONIKS directory for a particular request.

type Response 

type Response struct {
	Error             ErrorCode
	DirectoryResponse `json:",omitempty"`
}

A Response message indicates the result of a CONIKS client request with an appropriate error code, and defines the set of cryptographic proofs a CONIKS directory must return as part of its response.

func NewErrorResponse 

func NewErrorResponse(e ErrorCode) *Response

NewErrorResponse creates a new response message indicating the error that occurred while a CONIKS directory or a CONIKS auditor was processing a client request.

func NewKeyLookupInEpochProof 

func NewKeyLookupInEpochProof(ap *merkletree.AuthenticationPath,
	str []*DirSTR, e ErrorCode) *Response

NewKeyLookupInEpochProof creates the response message a CONIKS directory sends to a client upon a KeyLookupRequest, and returns a Response containing a DirectoryProofs struct. directory.KeyLookupInEpoch() passes an authentication path ap and error code e according to the result of the lookup, and a list of signed tree roots for the requested range of epochs str.

See directory.KeyLookupInEpoch() for details on the contents of the created DirectoryProofs.

func NewKeyLookupProof 

func NewKeyLookupProof(ap *merkletree.AuthenticationPath, str *DirSTR,
	tb *TemporaryBinding, e ErrorCode) *Response

NewKeyLookupProof creates the response message a CONIKS directory sends to a client upon a KeyLookupRequest, and returns a Response containing a DirectoryProof struct. The length of `AP` and `STR` must to be equal to 1. directory.KeyLookup() passes an authentication path ap, temporary binding tb and error code e according to the result of the key lookup, and the signed tree root for the latest epoch str.

See directory.KeyLookup() for details on the contents of the created DirectoryProof.

func NewMonitoringProof 

func NewMonitoringProof(ap []*merkletree.AuthenticationPath,
	str []*DirSTR) *Response

NewMonitoringProof creates the response message a CONIKS directory sends to a client upon a MonitoringRequest, and returns a Response containing a DirectoryProofs struct. directory.Monitor() passes a list of authentication paths ap and a list of signed tree roots for the requested range of epochs str.

See directory.Monitor() for details on the contents of the created DirectoryProofs.

func NewRegistrationProof 

func NewRegistrationProof(ap *merkletree.AuthenticationPath, str *DirSTR,
	tb *TemporaryBinding, e ErrorCode) *Response

NewRegistrationProof creates the response message a CONIKS directory sends to a client upon a RegistrationRequest, and returns a Response containing a DirectoryProof struct. The length of `AP` and `STR` must to be equal to 1. directory.Register() passes an authentication path ap, temporary binding tb and error code e according to the result of the registration, and the signed tree root for the latest epoch str.

See directory.Register() for details on the contents of the created DirectoryProof.

func NewSTRHistoryRange 

func NewSTRHistoryRange(str []*DirSTR) *Response

NewSTRHistoryRange creates the response message a CONIKS auditor sends to a client upon an AuditingRequest, and returns a Response containing an STRHistoryRange struct. auditlog.GetObservedSTRs() passes a list of one or more signed tree roots that the auditor observed for the requested range of epochs str.

See auditlog.GetObservedSTRs() for details on the contents of the created STRHistoryRange.

func (*Response) GetKey 

func (msg *Response) GetKey() ([]byte, error)

GetKey returns the key extracted from a validated CONIKS directory's response.

If the response contains a single authentication path, the key is obtained from that authentication path or the temporary binding, depending on the returned proof type.

If the response contains a range of authentication paths, the key is obtained from the authentication path corresponding to the most recent signed tree root. FIXME: remove this obsolete function

func (*Response) Validate 

func (msg *Response) Validate() error

Validate returns immediately if the message includes an error code. Otherwise, it verifies whether the message has proper format.

type STRHistoryRange 

type STRHistoryRange struct {
	STR []*DirSTR
}

An STRHistoryRange response includes a list of signed tree roots STR representing a range of the STR hash chain. If the range only covers the latest epoch, the list only contains a single STR. A CONIKS auditor returns this DirectoryResponse type upon an AuditingRequest from a client, and a CONIKS directory returns this message upon an STRHistoryRequest from an auditor.

type STRHistoryRequest 

type STRHistoryRequest struct {
	StartEpoch uint64
	EndEpoch   uint64
}

An STRHistoryRequest is a message with a StartEpoch and optional EndEpoch of an epoch range as two uint64's that a CONIKS auditor sends to a directory to retrieve a range of STRs starting at epoch StartEpoch.

The response to a successful request is an STRHistoryRange with a list of STRs covering the epoch range [StartEpoch, EndEpoch], or [StartEpoch, d.LatestSTR().Epoch] if EndEpoch is omitted.

type TemporaryBinding 

type TemporaryBinding struct {
	Index     []byte
	Value     []byte
	Signature []byte
}

A TemporaryBinding consists of the private Index for a username, the Value (i.e. public key etc.) mapped to this index in a key directory, and a digital Signature of these fields.

A TB serves as a proof of registration and as a signed promise by a CONIKS server to include the corresponding name-to-key binding in the next directory snapshot. As such, TBs allow clients to begin using the contained name-to-key binding for encryption/signing without having to wait for the binding's inclusion in the next snapshot.

func (*TemporaryBinding) Serialize 

func (tb *TemporaryBinding) Serialize(strSig []byte) []byte

Serialize serializes the temporary binding into a specified format.

type Timestamp 

type Timestamp uint64

Timestamp is used for defining a CONIKS server's epoch deadline.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.