pki

package
v0.0.63 Latest Latest
Warning

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

Go to latest
Published: Aug 7, 2025 License: AGPL-3.0, AGPL-3.0 Imports: 31 Imported by: 2

Documentation

Index

Constants

View Source
const (
	// LayerGateway is the Layer that gateways list in their MixDescriptors.
	LayerGateway = 255

	// LayerService is the Layer that service nodes list in their MixDescriptors.
	LayerService = 254

	PublicKeyHashSize       = 32
	SharedRandomLength      = 40
	SharedRandomValueLength = 32

	// DocumentVersion identifies the document format version
	DocumentVersion = "v0"
)
View Source
const (
	DescriptorVersion = "v0"
)
View Source
const NumPKIDocsToFetch = 3

Variables

View Source
var (
	ErrNoSignature       = errors.New("MixDescriptor has no signature")
	ErrInvalidSignature  = errors.New("MixDescriptor has an invalid signature")
	ErrTooManySignatures = errors.New("MixDescriptor has more than one signature")
)
View Source
var (
	// ErrDocumentGone is the error returned when there never will be a document
	// for a given epoch.
	ErrDocumentGone = errors.New("pki: requested epoch will never get a document")

	// ErrNoDocument is the error returned when there was no consensus found
	ErrNoDocument = errors.New("pki: requested epoch has no document")

	// ErrInvalidPostEpoch is the error returned when the server rejects a
	// descriptor upload for a given epoch due to time reasons.
	ErrInvalidPostEpoch = errors.New("pki: post for epoch will never succeeed")

	// ErrInvalidEpoch is the error to return when the document epoch is invalid.
	ErrInvalidEpoch = errors.New("invalid document epoch")

	// ErrDocumentNotSigned is the error returned when deserializing an unsigned
	// document
	ErrDocumentNotSigned = errors.New("document not signed")

	// TrustOnFirstUseAuth is a MixDescriptor.AuthenticationType
	TrustOnFirstUseAuth = "tofu"

	// OutOfBandAuth is a MixDescriptor.AuthenticationType
	OutOfBandAuth = "oob"
)
View Source
var (
	// TransportInvalid is the invalid transport.
	TransportInvalid string

	// TransportTCP is TCP, with the IP version determined by the results of
	// a name server lookup.
	TransportTCP string = "tcp"

	// TransportWS is Websocket
	TransportWS string = "ws"

	// TransportTCPv4 is TCP over IPv4.
	TransportTCPv4 string = "tcp4"

	// TransportTCPv6 is TCP over IPv6.
	TransportTCPv6 string = "tcp6"

	// TransportQUIC is QUIC, with the IP version determined by the results
	// of a name server lookup
	TransportQUIC string = "quic"

	// TransportOnion is a tor hidden service, to be announced in PKI
	TransportOnion string = "onion"

	// InternalTransports is the list of transports used for non-client related
	// communications.
	InternalTransports = []string{TransportTCPv4, TransportTCPv6, TransportQUIC}

	// ClientTransports is the list of transports used by default for client
	// to provider communication.
	ClientTransports = []string{TransportTCP, TransportTCPv4, TransportTCPv6, TransportQUIC, TransportWS, TransportOnion}
)
View Source
var (
	// PublishConsensusDeadline is when the authority publishes the consensus
	PublishConsensusDeadline = epochtime.Period - (epochtime.Period / 8)
)

Functions

func Chunk added in v0.0.46

func Chunk(blob []byte, chunkSize int) ([][]byte, error)

func HandleTimerEvent added in v0.0.50

func HandleTimerEvent(timer *time.Timer, pkiCtx context.Context, haltCh <-chan interface{}, log *logging.Logger) bool

HandleTimerEvent processes timer and cancellation events

func IsDescriptorWellFormed

func IsDescriptorWellFormed(d *MixDescriptor, epoch uint64) error

IsDescriptorWellFormed validates the descriptor and returns a descriptive error iff there are any problems that would make it unusable as part of a PKI Document.

func IsDocumentWellFormed

func IsDocumentWellFormed(d *Document, verifiers []sign.PublicKey) error

IsDocumentWellFormed validates the document and returns a descriptive error iff there are any problems that invalidates the document.

func IsReplicaDescriptorWellFormed added in v0.0.44

func IsReplicaDescriptorWellFormed(d *ReplicaDescriptor, epoch uint64) error

IsReplicaDescriptorWellFormed validates the descriptor and returns a descriptive error iff there are any problems that would make it unusable as part of a PKI Document.

func MultiSignDocument

func MultiSignDocument(signer sign.PrivateKey, verifier sign.PublicKey, peerSignatures []*cert.Signature, verifiers map[[32]byte]sign.PublicKey, d *Document) ([]byte, error)

MultiSignDocument signs and serializes the document with the provided signing key, adding the signature to the existing signatures.

func SetupWorkerContext added in v0.0.50

func SetupWorkerContext(haltCh <-chan interface{}, log *logging.Logger) (context.Context, context.CancelFunc, func() bool)

SetupWorkerContext creates a context with cancellation for PKI workers

func SignDocument

func SignDocument(signer sign.PrivateKey, verifier sign.PublicKey, d *Document) ([]byte, error)

SignDocument signs and serializes the document with the provided signing key.

Types

type Chunker added in v0.0.46

type Chunker struct {
	ChunkSize int
	Total     int
}

type Client

type Client interface {
	// Get returns the PKI document along with the raw serialized form for the provided epoch.
	Get(ctx context.Context, epoch uint64) (*Document, []byte, error)

	// Post posts the node's descriptor to the PKI for the provided epoch.
	Post(ctx context.Context, epoch uint64, signingPrivateKey sign.PrivateKey, signingPublicKey sign.PublicKey, d *MixDescriptor, loopstats *loops.LoopStats) error

	// PostReplica posts the pigeonhole storage replica node's descriptor to the PKI for the provided epoch.
	PostReplica(ctx context.Context, epoch uint64, signingPrivateKey sign.PrivateKey, signingPublicKey sign.PublicKey, d *ReplicaDescriptor) error

	// Deserialize returns PKI document given the raw bytes.
	Deserialize(raw []byte) (*Document, error)
}

Client is the abstract interface used for PKI interaction.

type Dechunker added in v0.0.46

type Dechunker struct {
	ChunkNum   int
	ChunkTotal int
	Chunks     *bytes.Buffer
	Output     []byte
}

func NewDechunker added in v0.0.46

func NewDechunker() *Dechunker

func (*Dechunker) Consume added in v0.0.46

func (d *Dechunker) Consume(payload []byte, num, total int) error

type Document

type Document struct {
	// Epoch is the epoch for which this Document instance is valid for.
	Epoch uint64

	// GenesisEpoch is the epoch on which authorities started consensus
	GenesisEpoch uint64

	// SendRatePerMinute is the number of packets per minute a client can send.
	SendRatePerMinute uint64

	// Mu is the inverse of the mean of the exponential distribution
	// that the Sphinx packet per-hop mixing delay will be sampled from.
	Mu float64

	// MuMaxDelay is the maximum Sphinx packet per-hop mixing delay in
	// milliseconds.
	MuMaxDelay uint64

	// LambdaP is the inverse of the mean of the exponential distribution
	// that clients will sample to determine the time interval between sending
	// messages from it's FIFO egress queue or drop decoy messages if the queue
	// is empty.
	LambdaP float64

	// LambdaPMaxDelay is the maximum time interval in milliseconds.
	LambdaPMaxDelay uint64

	// LambdaL is the inverse of the mean of the exponential distribution
	// that clients will sample to determine the time interval between sending
	// decoy loop messages.
	LambdaL float64

	// LambdaLMaxDelay is the maximum time interval in milliseconds.
	LambdaLMaxDelay uint64

	// LambdaD is the inverse of the mean of the exponential distribution
	// that clients will sample to determine the time interval between sending
	// decoy drop messages.
	LambdaD float64

	// LambdaDMaxDelay is the maximum time interval in milliseconds.
	LambdaDMaxDelay uint64

	// LambdaM is the inverse of the mean of the exponential distribution
	// that mixes will sample to determine send timing of mix loop decoy traffic.
	LambdaM float64

	// LambdaMMaxDelay is the maximum send interval in milliseconds.
	LambdaMMaxDelay uint64

	// LambdaG is the inverse of the mean of the exponential distribution
	// that mixes will sample to determine send timing of gateway node loop decoy traffic.
	LambdaG float64

	// LambdaMMaxDelay is the maximum send interval in milliseconds.
	LambdaGMaxDelay uint64

	// Topology is the mix network topology, excluding providers.
	Topology [][]*MixDescriptor

	// GatewayNodes is the list of nodes that can allow clients to interact
	// with the mix network.
	GatewayNodes []*MixDescriptor

	// ServiceNodes is the list of nodes that can allow services to interact
	// with tehe mix network.
	ServiceNodes []*MixDescriptor

	// StorageReplicas is the list of Storage Replica nodes that do not talk over the mixnet
	// but are expected to handle connections from the Service Nodes and the other replicas.
	StorageReplicas []*ReplicaDescriptor

	// Signatures holds detached Signatures from deserializing a signed Document
	Signatures map[[PublicKeyHashSize]byte]cert.Signature `cbor:"-"`

	// SharedRandomCommit used by the voting process.
	SharedRandomCommit map[[PublicKeyHashSize]byte][]byte

	// SharedRandomReveal used by the voting process.
	SharedRandomReveal map[[PublicKeyHashSize]byte][]byte

	// SharedRandomValue produced by voting process.
	SharedRandomValue []byte

	// PriorSharedRandom used by applications that need a longer lived SRV.
	PriorSharedRandom [][]byte

	// SphinxGeometryHash is used to ensure all mixnet actors have the same
	// Sphinx Geometry.
	SphinxGeometryHash []byte

	// Version uniquely identifies the document format as being for the
	// specified version so that it can be rejected if the format changes.
	Version string

	// PKISignatureScheme specifies the cryptographic signature scheme
	PKISignatureScheme string
}

Document is a PKI document.

func FromPayload

func FromPayload(verifier sign.PublicKey, payload []byte) (*Document, error)

FromPayload deserializes, then verifies a Document, and returns the Document or error.

func ParseDocument

func ParseDocument(b []byte) (*Document, error)

ParseDocument deserializes the document.

func (*Document) AddSignature

func (d *Document) AddSignature(verifier sign.PublicKey, signature cert.Signature) error

AddSignature will add a Signature over this Document if it is signed by verifier.

func (*Document) GetGateway added in v0.0.33

func (d *Document) GetGateway(name string) (*MixDescriptor, error)

GetGateway returns the MixDescriptor for the given gateway Name.

func (*Document) GetGatewayByKeyHash added in v0.0.33

func (d *Document) GetGatewayByKeyHash(keyhash *[32]byte) (*MixDescriptor, error)

GetGatewayByKeyHash returns the specific gateway descriptor corresponding to the specified IdentityKey hash.

func (*Document) GetMix

func (d *Document) GetMix(name string) (*MixDescriptor, error)

GetMix returns the MixDescriptor for the given mix Name.

func (*Document) GetMixByKeyHash

func (d *Document) GetMixByKeyHash(keyhash *[32]byte) (*MixDescriptor, error)

GetMixByKey returns the specific mix descriptor corresponding to the specified IdentityKey hash.

func (*Document) GetMixLayer

func (d *Document) GetMixLayer(keyhash *[32]byte) (uint8, error)

GetMixLayer returns the assigned layer for the given mix from Topology

func (*Document) GetMixesInLayer

func (d *Document) GetMixesInLayer(layer uint8) ([]*MixDescriptor, error)

GetMixesInLayer returns all the mix descriptors for a given layer.

func (*Document) GetNode

func (d *Document) GetNode(name string) (*MixDescriptor, error)

GetNode returns the specific descriptor corresponding to the specified node Name.

func (*Document) GetNodeByKeyHash

func (d *Document) GetNodeByKeyHash(keyhash *[32]byte) (*MixDescriptor, error)

GetNodeByKeyHash returns the specific descriptor corresponding to the specified IdentityKey hash.

func (*Document) GetReplicaIDByIdentityKey added in v0.0.50

func (d *Document) GetReplicaIDByIdentityKey(idkey sign.PublicKey) (uint8, error)

func (*Document) GetReplicaNodeByKeyHash added in v0.0.44

func (d *Document) GetReplicaNodeByKeyHash(keyhash *[32]byte) (*ReplicaDescriptor, error)

func (*Document) GetReplicaNodeByReplicaID added in v0.0.50

func (d *Document) GetReplicaNodeByReplicaID(replicaID uint8) (*ReplicaDescriptor, error)

func (*Document) GetServiceNode added in v0.0.33

func (d *Document) GetServiceNode(name string) (*MixDescriptor, error)

GetService returns the MixDescriptor for the given service Name.

func (*Document) GetServiceNodeByKeyHash added in v0.0.33

func (d *Document) GetServiceNodeByKeyHash(keyhash *[32]byte) (*MixDescriptor, error)

GetServiceByKeyHash returns the specific service descriptor corresponding to the specified IdentityKey hash.

func (*Document) MarshalCertificate added in v0.0.41

func (d *Document) MarshalCertificate() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler interface and wraps a Document with a cert.Certificate

func (*Document) String

func (d *Document) String() string

String returns a string representation of a Document.

func (*Document) Sum256

func (d *Document) Sum256() [32]byte

func (*Document) UnmarshalCertificate added in v0.0.41

func (d *Document) UnmarshalCertificate(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler interface and populates Document with detached Signatures

type DocumentFetcher added in v0.0.50

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

DocumentFetcher provides common PKI document fetching functionality

func NewDocumentFetcher added in v0.0.50

func NewDocumentFetcher(client Client, log *logging.Logger) *DocumentFetcher

NewDocumentFetcher creates a new document fetcher

func (*DocumentFetcher) FetchDocuments added in v0.0.50

func (f *DocumentFetcher) FetchDocuments(
	ctx context.Context,
	epochs []uint64,
	isCanceled func() bool,
	getFailedFetch func(uint64) (bool, error),
	setFailedFetch func(uint64, error),
) []FetchDocumentResult

FetchDocuments fetches PKI documents for the given epochs

type FetchDocumentResult added in v0.0.50

type FetchDocumentResult struct {
	Epoch   uint64
	Doc     *Document
	RawDoc  []byte
	Error   error
	Skipped bool
}

FetchDocumentResult represents the result of fetching a single document

type MixDescriptor

type MixDescriptor struct {
	// Name is the human readable (descriptive) node identifier.
	Name string

	// Epoch is the Epoch in which this descriptor was created
	Epoch uint64

	// IdentityKey is the node's identity (signing) key.
	IdentityKey []byte

	// LinkKey is the node's wire protocol public key.
	LinkKey []byte

	// MixKeys is a map of epochs to Sphinx keys.
	MixKeys map[uint64][]byte

	// Addresses is the map of transport to address combinations that can
	// be used to reach the node.
	Addresses map[string][]string

	// Kaetzchen is the map of provider autoresponder agents by capability
	// to parameters.
	Kaetzchen map[string]map[string]interface{}

	// KaetzchenAdvertizedData is used by the operator to advertize
	// additional information about specific services. This is different
	// from the above Kaetzchen map in that these keys will never be
	// modified or passed over commandline to the plugin.
	KaetzchenAdvertizedData map[string]map[string]interface{}

	// IsGatewayNode indicates that this Mix is a gateway node.
	// Essentially a gateway allows clients to interact with the mixnet.
	// This option being set to true is mutually exclusive with
	// `IsServiceNode` being set to true.
	IsGatewayNode bool

	// IsServiceNode indicates that this Mix is a service node.
	// Service nodes run services which the mixnet interacts with.
	IsServiceNode bool

	// LoadWeight is the node's load balancing weight (unused).
	LoadWeight uint8

	// AuthenticationType is the authentication mechanism required
	AuthenticationType string

	// Version uniquely identifies the descriptor format as being for the
	// specified version so that it can be rejected if the format changes.
	Version string
}

MixDescriptor is a description of a given Mix or Provider (node).

func (*MixDescriptor) GetRawCourierLinkKey added in v0.0.50

func (d *MixDescriptor) GetRawCourierLinkKey() (string, error)

func (*MixDescriptor) MarshalBinary

func (d *MixDescriptor) MarshalBinary() ([]byte, error)

MarshalBinary implmements encoding.BinaryMarshaler

func (*MixDescriptor) String

func (d *MixDescriptor) String() string

String returns a human readable MixDescriptor suitable for terse logging.

func (*MixDescriptor) UnmarshalBinary

func (d *MixDescriptor) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler interface

func (*MixDescriptor) UnmarshalMixKeyAsKEM

func (d *MixDescriptor) UnmarshalMixKeyAsKEM(epoch uint64, g *geo.Geometry) (kem.PublicKey, error)

func (*MixDescriptor) UnmarshalMixKeyAsNike

func (d *MixDescriptor) UnmarshalMixKeyAsNike(epoch uint64, g *geo.Geometry) (nike.PublicKey, error)

type ReplicaDescriptor added in v0.0.44

type ReplicaDescriptor struct {
	// Name is the unique name of the pigeonhole storage replica.
	Name string

	// Epoch is the Epoch in which this descriptor was created
	Epoch uint64

	// IdentityKey is the node's identity (signing) key.
	IdentityKey []byte

	// LinkKey is our PQ Noise Public Key.
	LinkKey []byte

	// EnvelopeKeys is mapping from Replica Epoch ID to Public NIKE Key used with our MKEM scheme.
	EnvelopeKeys map[uint64][]byte

	// Addresses is the map of transport to address combinations that can
	// be used to reach the node.
	Addresses map[string][]string
}

ReplicaDescriptor describe pigeonhole storage replica nodes.

func (*ReplicaDescriptor) DisplayWithSchemes added in v0.0.50

func (d *ReplicaDescriptor) DisplayWithSchemes(linkScheme kem.Scheme, identityScheme sign.Scheme, envelopeScheme nike.Scheme) string

func (*ReplicaDescriptor) Marshal added in v0.0.44

func (d *ReplicaDescriptor) Marshal() ([]byte, error)

MarshalBinary implmements encoding.BinaryMarshaler

func (*ReplicaDescriptor) Unmarshal added in v0.0.44

func (d *ReplicaDescriptor) Unmarshal(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler interface

type SharedRandom

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

SharedRandom is a container for commit-and-reveal protocol messages

func (*SharedRandom) Commit

func (s *SharedRandom) Commit(epoch uint64) ([]byte, error)

Commit produces a SharedRandom commit value for the given epoch

func (*SharedRandom) GetCommit

func (s *SharedRandom) GetCommit() []byte

GetCommit returns the commit value

func (*SharedRandom) GetEpoch

func (s *SharedRandom) GetEpoch() uint64

GetEpoch returns the epoch value

func (*SharedRandom) Reveal

func (s *SharedRandom) Reveal() []byte

Reveal returns the reveal value

func (*SharedRandom) SetCommit

func (s *SharedRandom) SetCommit(rawCommit []byte)

SetCommit sets the commit value

func (*SharedRandom) Verify

func (s *SharedRandom) Verify(reveal []byte) bool

Verify checks that the reveal value verifies the commit value

type SignedReplicaUpload added in v0.0.44

type SignedReplicaUpload struct {
	// Signature is the signature over the serialized SignedReplicaUpload.
	Signature *cert.Signature

	// ReplicaDescriptor is the replica descriptor.
	ReplicaDescriptor *ReplicaDescriptor
}

func (*SignedReplicaUpload) Marshal added in v0.0.44

func (s *SignedReplicaUpload) Marshal() ([]byte, error)

func (*SignedReplicaUpload) Sign added in v0.0.44

func (s *SignedReplicaUpload) Sign(privKey sign.PrivateKey, pubKey sign.PublicKey) error

func (*SignedReplicaUpload) Unmarshal added in v0.0.44

func (s *SignedReplicaUpload) Unmarshal(data []byte) error

func (*SignedReplicaUpload) Verify added in v0.0.44

func (s *SignedReplicaUpload) Verify(pubKey sign.PublicKey) bool

type SignedUpload added in v0.0.32

type SignedUpload struct {
	// Signature is the signature over the serialized SignedUpload.
	Signature *cert.Signature

	// MixDescriptor is the mix descriptor.
	MixDescriptor *MixDescriptor

	// LoopStats is the mix loop statistics.
	LoopStats *loops.LoopStats
}

func (*SignedUpload) Marshal added in v0.0.32

func (s *SignedUpload) Marshal() ([]byte, error)

func (*SignedUpload) Sign added in v0.0.32

func (s *SignedUpload) Sign(privKey sign.PrivateKey, pubKey sign.PublicKey) error

func (*SignedUpload) Unmarshal added in v0.0.32

func (s *SignedUpload) Unmarshal(data []byte) error

func (*SignedUpload) Verify added in v0.0.32

func (s *SignedUpload) Verify(pubKey sign.PublicKey) bool

type WorkerBase added in v0.0.50

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

WorkerBase provides common PKI worker functionality shared between courier and replica

func NewWorkerBase added in v0.0.50

func NewWorkerBase(impl Client, log *logging.Logger) *WorkerBase

NewWorkerBase creates a new PKI worker base

func (*WorkerBase) ClearFailedFetch added in v0.0.50

func (w *WorkerBase) ClearFailedFetch(epoch uint64)

ClearFailedFetch removes a failed fetch record for the given epoch

func (*WorkerBase) DocumentsToFetch added in v0.0.50

func (w *WorkerBase) DocumentsToFetch() []uint64

DocumentsToFetch returns the list of epochs for which documents should be fetched

func (*WorkerBase) EntryForEpoch added in v0.0.50

func (w *WorkerBase) EntryForEpoch(epoch uint64) *Document

EntryForEpoch returns the PKI document for the specified epoch

func (*WorkerBase) FetchDocuments added in v0.0.50

func (w *WorkerBase) FetchDocuments(pkiCtx context.Context, isCanceled func() bool) []FetchDocumentResult

FetchDocuments fetches PKI documents for required epochs using the shared fetcher

func (*WorkerBase) GetFailedFetch added in v0.0.50

func (w *WorkerBase) GetFailedFetch(epoch uint64) (bool, error)

GetFailedFetch checks if a fetch for the given epoch has previously failed

func (*WorkerBase) GetLogger added in v0.0.50

func (w *WorkerBase) GetLogger() *logging.Logger

GetLogger returns the logger instance

func (*WorkerBase) PKIDocument added in v0.0.50

func (w *WorkerBase) PKIDocument() *Document

PKIDocument returns the PKI document for the current epoch

func (*WorkerBase) PruneDocuments added in v0.0.50

func (w *WorkerBase) PruneDocuments()

PruneDocuments removes old PKI documents

func (*WorkerBase) PruneFailures added in v0.0.50

func (w *WorkerBase) PruneFailures()

PruneFailures removes old failed fetch records

func (*WorkerBase) SetDocumentForEpoch added in v0.0.50

func (w *WorkerBase) SetDocumentForEpoch(epoch uint64, doc *Document, rawDoc []byte)

SetDocumentForEpoch sets a PKI document for a specific epoch; for testing only

func (*WorkerBase) SetFailedFetch added in v0.0.50

func (w *WorkerBase) SetFailedFetch(epoch uint64, err error)

SetFailedFetch records a failed fetch for the given epoch

func (*WorkerBase) StoreDocument added in v0.0.50

func (w *WorkerBase) StoreDocument(epoch uint64, doc *Document, rawDoc []byte)

StoreDocument stores a fetched document

func (*WorkerBase) UpdateTimer added in v0.0.50

func (w *WorkerBase) UpdateTimer(timer *time.Timer)

UpdateTimer updates the timer for the next PKI worker wake-up

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL