xxdk

package
v5.0.1 Latest Latest
Warning

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

 Go to latest Published: Nov 10, 2022 License: BSD-2-Clause, BSD-2-Clause Imports: 61 Imported by: 1

Documentation

Index

Constants

View Source 
const DEPENDENCIES = `` /* 3354-byte string literal not displayed */
View Source 
const GITVERSION = `d9acd195 Update makefile to build v5 client in bindings`
View Source 
const SEMVER = "5.0.1"
View Source 
const (
	// SaltSize is the length of user salts, in bytes.
	SaltSize = 32
)

Variables

This section is empty.

Functions

func CheckVersionAndSetupStorage 

func CheckVersionAndSetupStorage(def *ndf.NetworkDefinition, storageDir string,
	password []byte, userInfo user.Info, cmixGrp, e2eGrp *cyclic.Group,
	registrationCode string) (storage.Session, error)

CheckVersionAndSetupStorage checks the client version and creates a new storage for user data. This function is common code shared by NewCmix, // NewPrecannedCmix and NewVanityCmix.

func CompressJpeg 

func CompressJpeg(imgBytes []byte) ([]byte, error)

CompressJpeg takes a JPEG image in byte format and compresses it based on desired output size.

func CompressJpegForPreview 

func CompressJpegForPreview(imgBytes []byte) ([]byte, error)

CompressJpegForPreview takes a JPEG image in byte format and compresses it based on desired output size.

func DecodeGroups 

func DecodeGroups(ndf *ndf.NetworkDefinition) (cmixGrp, e2eGrp *cyclic.Group)

DecodeGroups returns the E2E and cMix groups from the NDF.

func DownloadAndVerifySignedNdfWithUrl 

func DownloadAndVerifySignedNdfWithUrl(url, cert string) ([]byte, error)

DownloadAndVerifySignedNdfWithUrl retrieves the NDF from a specified URL. The NDF is processed into a protobuf containing a signature that is verified using the cert string passed in. The NDF is returned as marshaled byte data that may be used to start a client.

func DownloadNdfFromGateway 

func DownloadNdfFromGateway(address string, cert []byte) (
	[]byte, error)

DownloadNdfFromGateway will download an NDF from a gateway on the cMix network. It will take the given address and certificate and send a request to a gateway for an NDF over HTTP/2 using the xx network's gRPC implementation. This returns a JSON marshalled version of the NDF.

func LoadSecretWithMnemonic 

func LoadSecretWithMnemonic(mnemonic, path string) (secret []byte, err error)

LoadSecretWithMnemonic loads the encrypted secret from storage and decrypts the secret using the given mnemonic.

func MakeAuthCB 

func MakeAuthCB(e2e *E2e, cbs AuthCallbacks) auth.Callbacks

MakeAuthCB generates a new auth.Callbacks with the given AuthCallbacks.

func MakeAuthCallbacksAdapter 

func MakeAuthCallbacksAdapter(ac AuthCallbacks, e2e *E2e) *authCallbacksAdapter

MakeAuthCallbacksAdapter creates an authCallbacksAdapter.

func NewCmix 

func NewCmix(
	ndfJSON, storageDir string, password []byte, registrationCode string) error

NewCmix creates client storage, generates keys, and connects and registers with the network. Note that this does not register a username/identity, but merely creates a new cryptographic identity for adding such information at a later date.

func NewPrecannedCmix 

func NewPrecannedCmix(precannedID uint, defJSON, storageDir string,
	password []byte) error

NewPrecannedCmix creates an insecure user with predetermined keys with nodes. It creates client storage, generates keys, connects, and registers with the network. Note that this does not register a username/identity, but merely creates a new cryptographic identity for adding such information at a later date.

func NewProtoCmix_Unsafe 

func NewProtoCmix_Unsafe(ndfJSON, storageDir string, password []byte,
	protoUser *user.Proto) error

NewProtoCmix_Unsafe initializes a client object from a JSON containing predefined cryptographic that defines a user. This is designed for some specific deployment procedures and is generally unsafe.

func NewVanityCmix 

func NewVanityCmix(ndfJSON, storageDir string, password []byte,
	registrationCode string, userIdPrefix string) error

NewVanityCmix creates a user with a receptionID that starts with the supplied prefix. It creates client storage, generates keys, and connects and registers with the network. Note that this does not register a username/ identity, but merely creates a new cryptographic identity for adding such information at a later date.

func ParseNDF 

func ParseNDF(ndfString string) (*ndf.NetworkDefinition, error)

ParseNDF parses the initial NDF string for the client. This function does not check the signature; it is deprecated.

func StoreReceptionIdentity 

func StoreReceptionIdentity(key string, identity ReceptionIdentity, net *Cmix) error

StoreReceptionIdentity stores the given identity in Cmix storage with the given key. This is the ideal way to securely store identities, as the caller of this function is only required to store the given key separately rather than the keying material.

func StoreSecretWithMnemonic 

func StoreSecretWithMnemonic(secret []byte, path string) (string, error)

StoreSecretWithMnemonic creates a mnemonic and uses it to encrypt the secret. This encrypted data saved in storage.

Types

type AuthCallbacks 

type AuthCallbacks interface {
	Request(partner contact.Contact, receptionID receptionID.EphemeralIdentity,
		round rounds.Round, user *E2e)
	Confirm(partner contact.Contact, receptionID receptionID.EphemeralIdentity,
		round rounds.Round, user *E2e)
	Reset(partner contact.Contact, receptionID receptionID.EphemeralIdentity,
		round rounds.Round, user *E2e)
}

AuthCallbacks is an adapter for the auth.Callbacks interface that allows for initializing an E2e object without an E2e-dependant auth.Callbacks.

type CMIXParams 

type CMIXParams struct {
	Network cmix.Params
	CMIX    cmix.CMIXParams
}

CMIXParams contains the parameters for Network tracking and for specific CMIX messaging settings.

FIXME: this breakdown could be cleaner and is an unfortunate side effect of 

several refactors of the codebase.

func GetDefaultCMixParams 

func GetDefaultCMixParams() CMIXParams

GetDefaultCMixParams returns a new CMIXParams with the default parameters.

func (*CMIXParams) Marshal 

func (p *CMIXParams) Marshal() ([]byte, error)

Marshal creates JSON data of the object.

func (*CMIXParams) Unmarshal 

func (p *CMIXParams) Unmarshal(jsonData []byte) error

Unmarshal fills an empty object with the deserialized contents of the JSON data.

type Cmix 

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

func LoadCmix 

func LoadCmix(storageDir string, password []byte, parameters CMIXParams) (
	*Cmix, error)

LoadCmix initializes a Cmix object from existing storage and starts the network.

func OpenCmix 

func OpenCmix(storageDir string, password []byte) (*Cmix, error)

OpenCmix creates client storage but does not connect to the network or login. Note that this is a helper function that, in most applications, should not be used on its own. Consider using LoadCmix instead, which calls this function for you.

func (*Cmix) AddService 

func (c *Cmix) AddService(sp Service) error

AddService adds a service to be controlled by the client thread control. These will be started and stopped with the network follower.

func (*Cmix) ChangeNumberOfNodeRegistrations 

func (c *Cmix) ChangeNumberOfNodeRegistrations(toRun int, timeout time.Duration) error

ChangeNumberOfNodeRegistrations changes the number of parallel node registrations up to the initialized maximum.

func (*Cmix) ConstructProtoUserFile 

func (c *Cmix) ConstructProtoUserFile() ([]byte, error)

ConstructProtoUserFile is a helper function that is used for proto client testing. This is used for development testing.

func (*Cmix) GetCmix 

func (c *Cmix) GetCmix() cmix.Client

GetCmix returns the client network interface.

func (*Cmix) GetComms 

func (c *Cmix) GetComms() *client.Comms

GetComms returns the client comms object.

func (*Cmix) GetErrorsChannel 

func (c *Cmix) GetErrorsChannel() <-chan interfaces.ClientError

GetErrorsChannel returns a channel that passes errors from the long-running threads controlled by StartNetworkFollower and StopNetworkFollower.

func (*Cmix) GetEventReporter 

func (c *Cmix) GetEventReporter() event.Reporter

GetEventReporter returns the event reporter.

func (*Cmix) GetNodeRegistrationStatus 

func (c *Cmix) GetNodeRegistrationStatus() (int, int, error)

GetNodeRegistrationStatus gets the current state of nodes registration. It returns the number of nodes that the user is currently registered with and the total number of nodes in the NDF. An error is returned if the network is not healthy.

func (*Cmix) GetPreferredBins 

func (c *Cmix) GetPreferredBins(countryCode string) ([]string, error)

GetPreferredBins returns the geographic bin or bins that the provided two character country code is a part of.

func (*Cmix) GetRng 

func (c *Cmix) GetRng() *fastRNG.StreamGenerator

GetRng returns the client RNG object.

func (*Cmix) GetRoundEvents 

func (c *Cmix) GetRoundEvents() interfaces.RoundEvents

GetRoundEvents registers a callback for round events.

func (*Cmix) GetRunningProcesses 

func (c *Cmix) GetRunningProcesses() []string

GetRunningProcesses returns the names of all running processes at the time of this call. Note that this list may change and is subject to race conditions if multiple threads are in the process of starting or stopping.

func (*Cmix) GetStorage 

func (c *Cmix) GetStorage() storage.Session

GetStorage returns the client storage object.

func (*Cmix) GetTransmissionIdentity 

func (c *Cmix) GetTransmissionIdentity() TransmissionIdentity

GetTransmissionIdentity returns the current TransmissionIdentity for this client.

func (*Cmix) HasRunningProcessies 

func (c *Cmix) HasRunningProcessies() bool

HasRunningProcessies checks if any background threads are running and returns true if one or more are.

func (*Cmix) IsReady 

func (c *Cmix) IsReady(percentReady float64) (isReady bool, howClose float64)

IsReady returns true if at least percentReady of node registrations has completed. If not all have completed, then it returns false and howClose will be a percent (0-1) of node registrations completed.

func (*Cmix) NetworkFollowerStatus 

func (c *Cmix) NetworkFollowerStatus() Status

NetworkFollowerStatus gets the state of the network follower. It returns a status with the following values: 

Stopped  - 0
Running  - 2000
Stopping - 3000

func (*Cmix) PauseNodeRegistrations 

func (c *Cmix) PauseNodeRegistrations(timeout time.Duration) error

PauseNodeRegistrations stops all node registrations and returns a function to resume them.

func (*Cmix) RegisterEventCallback 

func (c *Cmix) RegisterEventCallback(name string, myFunc event.Callback) error

RegisterEventCallback records the given function to receive ReportableEvent objects.

func (*Cmix) ReportEvent 

func (c *Cmix) ReportEvent(priority int, category, evtType, details string)

ReportEvent reports an event from the client to api users, providing a priority, category, eventType, and details.

func (*Cmix) StartNetworkFollower 

func (c *Cmix) StartNetworkFollower(timeout time.Duration) error

StartNetworkFollower kicks off the tracking of the network. It starts long- running network client threads and returns an object for checking state and stopping those threads.

Call this when returning from sleep and close when going back to sleep.

These threads may become a significant drain on battery when offline, ensure they are stopped if there is no internet access.

Threads Started:

  • Network Follower (/network/follow.go) tracks the network events and hands them off to workers for handling.
  • Historical Round Retrieval (/network/rounds/historical.go) retrieves data about rounds that are too old to be stored by the client.
  • Message Retrieval Worker Group (/network/rounds/retrieve.go) requests all messages in a given round from the gateway of the last nodes.
  • Message Handling Worker Group (/network/message/handle.go) decrypts and partitions messages when signals via the Switchboard.
  • Health Tracker (/network/health), via the network instance, tracks the state of the network.
  • Garbled Messages (/network/message/garbled.go) can be signaled to check all recent messages that could be decoded. It uses a message store on disk for persistence.
  • Critical Messages (/network/message/critical.go) ensures all protocol layer mandatory messages are sent. It uses a message store on disk for persistence.
  • KeyExchange Trigger (/keyExchange/trigger.go) responds to sent rekeys and executes them.
  • KeyExchange Confirm (/keyExchange/confirm.go) responds to confirmations of successful rekey operations.
  • Auth Callback (/auth/callback.go) handles both auth confirm and requests.

func (*Cmix) StopNetworkFollower 

func (c *Cmix) StopNetworkFollower() error

StopNetworkFollower stops the network follower if it is running. It returns an error if the follower is in the wrong state to stop or if it fails to stop it.

If the network follower is running and this fails, the client object will most likely be in an unrecoverable state and need to be trashed.

func (*Cmix) UnregisterEventCallback 

func (c *Cmix) UnregisterEventCallback(name string)

UnregisterEventCallback deletes the callback identified by the name.

type Container 

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

Container contains the trigger to call to initiate a backup.

func (*Container) SetBackup 

func (bc *Container) SetBackup(triggerBackup TriggerBackup)

SetBackup sets the backup trigger function which will cause a backup to start on the next event that triggers is.

func (*Container) TriggerBackup 

func (bc *Container) TriggerBackup(reason string)

TriggerBackup triggers a backup if a backup trigger has been set. The passed in reason will be printed to the log when the backup is sent. It should be in the paste tense. For example, if a contact is deleted, the reason can be "contact deleted" and the log will show: 

Triggering backup: contact deleted

type DefaultAuthCallbacks 

type DefaultAuthCallbacks struct{}

DefaultAuthCallbacks is a simple structure for providing a default AuthCallbacks implementation. It should generally not be used.

func (DefaultAuthCallbacks) Confirm 

func (a DefaultAuthCallbacks) Confirm(contact.Contact,
	receptionID.EphemeralIdentity, rounds.Round, *E2e)

Confirm will be called when an auth Confirm message is processed.

func (DefaultAuthCallbacks) Request 

func (a DefaultAuthCallbacks) Request(contact.Contact,
	receptionID.EphemeralIdentity, rounds.Round, *E2e)

Request will be called when an auth Request message is processed.

func (DefaultAuthCallbacks) Reset 

func (a DefaultAuthCallbacks) Reset(contact.Contact,
	receptionID.EphemeralIdentity, rounds.Round, *E2e)

Reset will be called when an auth Reset operation occurs.

type E2EParams 

type E2EParams struct {
	Session        session.Params
	Base           e2e.Params
	Rekey          rekey.Params
	EphemeralRekey rekey.Params
	Auth           auth.Params
}

E2EParams holds all the settings for e2e and it's various submodules.

Note that Base wraps cmix.CMIXParams to control message send params, so that xxdk library users should copy the desired settings to both. FIXME: this should not wrap a copy of cmix.CMIXParams.

func GetDefaultE2EParams 

func GetDefaultE2EParams() E2EParams

GetDefaultE2EParams returns a new E2EParams with the default parameters.

func (*E2EParams) Marshal 

func (p *E2EParams) Marshal() ([]byte, error)

Marshal creates JSON data of the object.

func (*E2EParams) Unmarshal 

func (p *E2EParams) Unmarshal(jsonData []byte) error

Unmarshal fills an empty object with the deserialized contents of the JSON data.

type E2e 

type E2e struct {
	*Cmix
	// contains filtered or unexported fields
}

E2e object bundles a ReceptionIdentity with a Cmix object and can be used for high-level operations, such as connections.

func Login 

func Login(net *Cmix, callbacks AuthCallbacks,
	identity ReceptionIdentity, params E2EParams) (m *E2e, err error)

Login creates a new E2e backed by the xxdk.Cmix persistent versioned.KV. It bundles a Cmix object with a ReceptionIdentity object and initializes the auth.State and e2e.Handler objects.

func LoginEphemeral 

func LoginEphemeral(net *Cmix, callbacks AuthCallbacks,
	identity ReceptionIdentity, params E2EParams) (m *E2e, err error)

LoginEphemeral creates a new E2e backed by a totally ephemeral versioned.KV.

func (*E2e) ConstructProtoUserFile 

func (m *E2e) ConstructProtoUserFile() ([]byte, error)

ConstructProtoUserFile is a helper function that is used for proto client testing. This is used for development testing.

func (*E2e) DeleteContact 

func (m *E2e) DeleteContact(partnerId *id.ID) error

DeleteContact removes a partner from E2e's storage.

func (*E2e) DeleteContactNotify 

func (m *E2e) DeleteContactNotify(partnerId *id.ID, params e2e.Params) error

DeleteContactNotify removes a partner from E2e's storage and sends an E2E message to the contact notifying them.

func (*E2e) GetAuth 

func (m *E2e) GetAuth() auth.State

GetAuth returns the auth.State.

func (*E2e) GetBackupContainer 

func (m *E2e) GetBackupContainer() *Container

GetBackupContainer returns the backup Container.

func (*E2e) GetE2E 

func (m *E2e) GetE2E() e2e.Handler

GetE2E returns the e2e.Handler.

func (*E2e) GetReceptionIdentity 

func (m *E2e) GetReceptionIdentity() ReceptionIdentity

GetReceptionIdentity returns a safe copy of the E2e ReceptionIdentity.

func (*E2e) MakePrecannedAuthenticatedChannel 

func (m *E2e) MakePrecannedAuthenticatedChannel(precannedID uint) (
	contact.Contact, error)

MakePrecannedAuthenticatedChannel creates an insecure E2E relationship with a precanned user.

func (*E2e) RegisterForNotifications 

func (m *E2e) RegisterForNotifications(token string) error

RegisterForNotifications allows a client to register for push notifications. Note that clients are not required to register for push notifications, especially as these rely on third parties (i.e., Firebase *cough* *cough* Google's palantir *cough*) that may represent a security risk to the user.

func (*E2e) UnregisterForNotifications 

func (m *E2e) UnregisterForNotifications() error

UnregisterForNotifications turns off notifications for this client.

type ReceptionIdentity 

type ReceptionIdentity struct {
	ID            *id.ID
	RSAPrivatePem []byte
	Salt          []byte
	DHKeyPrivate  []byte
	E2eGrp        []byte
}

ReceptionIdentity is used by the E2e object for managing identities used for message pickup.

func LoadReceptionIdentity 

func LoadReceptionIdentity(key string, net *Cmix) (ReceptionIdentity, error)

LoadReceptionIdentity loads the given identity in Cmix storage with the given key.

func MakeLegacyReceptionIdentity 

func MakeLegacyReceptionIdentity(net *Cmix) (ReceptionIdentity, error)

MakeLegacyReceptionIdentity generates the cryptographic identity for receiving messages based on the extant stored user.Info.

func MakeReceptionIdentity 

func MakeReceptionIdentity(net *Cmix) (ReceptionIdentity, error)

MakeReceptionIdentity generates a new cryptographic identity for receiving messages.

func UnmarshalReceptionIdentity 

func UnmarshalReceptionIdentity(marshaled []byte) (ReceptionIdentity, error)

UnmarshalReceptionIdentity takes in a marshalled ReceptionIdentity and converts it to an object.

func (ReceptionIdentity) DeepCopy 

func (r ReceptionIdentity) DeepCopy() ReceptionIdentity

DeepCopy produces a safe copy of the ReceptionIdentity.

func (ReceptionIdentity) GetContact 

func (r ReceptionIdentity) GetContact() contact.Contact

GetContact returns a contact.Contact object of the reception identity.

func (ReceptionIdentity) GetDHKeyPrivate 

func (r ReceptionIdentity) GetDHKeyPrivate() (*cyclic.Int, error)

GetDHKeyPrivate returns the DHKeyPrivate.

func (ReceptionIdentity) GetGroup 

func (r ReceptionIdentity) GetGroup() (*cyclic.Group, error)

GetGroup returns the cyclic.Group.

func (ReceptionIdentity) GetRSAPrivateKey 

func (r ReceptionIdentity) GetRSAPrivateKey() (*rsa.PrivateKey, error)

GetRSAPrivateKey returns the RSAPrivatePem.

func (ReceptionIdentity) Marshal 

func (r ReceptionIdentity) Marshal() ([]byte, error)

Marshal returns the JSON representation of a ReceptionIdentity.

type Service 

type Service func() (stoppable.Stoppable, error)

Service is a service process that starts itself in a new thread, returning from the originator a stoppable to control it.

type Status 

type Status int

Status holds the status of the network. 

const (
	// Stopped signifies that the network follower is stopped; none of its
	// processes are running.
	Stopped Status = 0

	// Running signifies that the network follower and its processes are active
	// and running.
	Running Status = 2000

	// Stopping signifies that the network follower has been signalled to stop
	// and is in the processes of stopping the processes.
	Stopping Status = 3000
)

func (Status) String 

func (s Status) String() string

String returns a human-readable string version of the status. This function adheres to the fmt.Stringer interface.

type TransmissionIdentity 

type TransmissionIdentity struct {
	ID            *id.ID
	RSAPrivatePem *rsa.PrivateKey
	Salt          []byte

	// Timestamp of when the user has registered with the network
	RegistrationTimestamp int64
}

TransmissionIdentity represents the identity used to transmit over the network via a specific Cmix object.

func (TransmissionIdentity) DeepCopy 

func (t TransmissionIdentity) DeepCopy() TransmissionIdentity

DeepCopy produces a safe copy of a TransmissionIdentity.

type TriggerBackup 

type TriggerBackup func(reason string)

TriggerBackup function is called to start a backup. The reason is used for logging purposes and should describe the event that triggered a backup.

For example, the reason can say "contact added" when a new contact is saved.

Source Files

View all Source files

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.