whisperv5

package
v1.5.10-0...-6d038e7 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2017 License: GPL-3.0 Imports: 28 Imported by: 0

Documentation

Overview

Package whisper implements the Whisper protocol (version 5).

Whisper combines aspects of both DHTs and datagram messaging systems (e.g. UDP). As such it may be likened and compared to both, not dissimilar to the matter/energy duality (apologies to physicists for the blatant abuse of a fundamental and beautiful natural principle).

Whisper is a pure identity-based messaging system. Whisper provides a low-level (non-application-specific) but easily-accessible API without being based upon or prejudiced by the low-level hardware attributes and characteristics, particularly the notion of singular endpoints.

Index

Constants

View Source 
const (
	EnvelopeVersion    = uint64(0)
	ProtocolVersion    = uint64(5)
	ProtocolVersionStr = "5.0"
	ProtocolName       = "shh"

	NumberOfMessageCodes = 64

	TopicLength = 4

	AESNonceMaxLength = 12

	MaxMessageLength = 0x0FFFFF // todo: remove this restriction after testing. this should be regulated by PoW.
	MinimumPoW       = 10.0     // todo: review after testing.

	DefaultTTL     = 50 // seconds
	SynchAllowance = 10 // seconds
)

Variables

This section is empty.

Functions

func BytesToIntBigEndian 

func BytesToIntBigEndian(b []byte) (res uint64)

func DeriveOneTimeKey 

func DeriveOneTimeKey(key []byte, salt []byte, version uint64) ([]byte, error)

func IsPubKeyEqual 

func IsPubKeyEqual(a, b *ecdsa.PublicKey) bool

func ValidatePublicKey 

func ValidatePublicKey(k *ecdsa.PublicKey) bool

Types

type Envelope 

type Envelope struct {
	Version  []byte
	Expiry   uint32
	TTL      uint32
	Topic    TopicType
	Salt     []byte
	AESNonce []byte
	Data     []byte
	EnvNonce uint64
	// contains filtered or unexported fields
}

Envelope represents a clear-text data packet to transmit through the Whisper network. Its contents may or may not be encrypted and signed.

func NewEnvelope 

func NewEnvelope(ttl uint32, topic TopicType, salt []byte, aesNonce []byte, msg *SentMessage) *Envelope

NewEnvelope wraps a Whisper message with expiration and destination data included into an envelope for network forwarding.

func (*Envelope) DecodeRLP 

func (e *Envelope) DecodeRLP(s *rlp.Stream) error

DecodeRLP decodes an Envelope from an RLP data stream.

func (*Envelope) Hash 

func (e *Envelope) Hash() common.Hash

Hash returns the SHA3 hash of the envelope, calculating it if not yet done.

func (*Envelope) IsSymmetric 

func (e *Envelope) IsSymmetric() bool

func (*Envelope) Open 

func (e *Envelope) Open(watcher *Filter) (msg *ReceivedMessage)

Open tries to decrypt an envelope, and populates the message fields in case of success.

func (*Envelope) OpenAsymmetric 

func (e *Envelope) OpenAsymmetric(key *ecdsa.PrivateKey) (*ReceivedMessage, error)

OpenAsymmetric tries to decrypt an envelope, potentially encrypted with a particular key.

func (*Envelope) OpenSymmetric 

func (e *Envelope) OpenSymmetric(key []byte) (msg *ReceivedMessage, err error)

OpenSymmetric tries to decrypt an envelope, potentially encrypted with a particular key.

func (*Envelope) PoW 

func (e *Envelope) PoW() float64

func (*Envelope) Seal 

func (e *Envelope) Seal(options *MessageParams) error

Seal closes the envelope by spending the requested amount of time as a proof of work on hashing the data.

func (*Envelope) Ver 

func (e *Envelope) Ver() uint64

type Filter 

type Filter struct {
	Src        *ecdsa.PublicKey  // Sender of the message
	KeyAsym    *ecdsa.PrivateKey // Private Key of recipient
	KeySym     []byte            // Key associated with the Topic
	Topics     []TopicType       // Topics to filter messages with
	PoW        float64           // Proof of work as described in the Whisper spec
	AcceptP2P  bool              // Indicates whether this filter is interested in direct peer-to-peer messages
	SymKeyHash common.Hash       // The Keccak256Hash of the symmetric key, needed for optimization

	Messages map[common.Hash]*ReceivedMessage
	// contains filtered or unexported fields
}

func (*Filter) MatchEnvelope 

func (f *Filter) MatchEnvelope(envelope *Envelope) bool

func (*Filter) MatchMessage 

func (f *Filter) MatchMessage(msg *ReceivedMessage) bool

func (*Filter) MatchTopic 

func (f *Filter) MatchTopic(topic TopicType) bool

func (*Filter) Retrieve 

func (f *Filter) Retrieve() (all []*ReceivedMessage)

func (*Filter) Trigger 

func (f *Filter) Trigger(msg *ReceivedMessage)

type Filters 

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

func NewFilters 

func NewFilters(w *Whisper) *Filters

func (*Filters) Get 

func (fs *Filters) Get(id string) *Filter

func (*Filters) Install 

func (fs *Filters) Install(watcher *Filter) (string, error)

func (*Filters) NotifyWatchers 

func (fs *Filters) NotifyWatchers(env *Envelope, p2pMessage bool)

func (*Filters) Uninstall 

func (fs *Filters) Uninstall(id string)

type MailServer 

type MailServer interface {
	Archive(env *Envelope)
	DeliverMail(whisperPeer *Peer, request *Envelope)
}

MailServer represents a mail server, capable of archiving the old messages for subsequent delivery to the peers. Any implementation must ensure that both functions are thread-safe. Also, they must return ASAP. DeliverMail should use directMessagesCode for delivery, in order to bypass the expiry checks.

type MessageParams 

type MessageParams struct {
	TTL      uint32
	Src      *ecdsa.PrivateKey
	Dst      *ecdsa.PublicKey
	KeySym   []byte
	Topic    TopicType
	WorkTime uint32
	PoW      float64
	Payload  []byte
	Padding  []byte
}

Options specifies the exact way a message should be wrapped into an Envelope.

type Peer 

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

peer represents a whisper protocol peer connection.

func (*Peer) ID 

func (p *Peer) ID() []byte

type PostArgs 

type PostArgs struct {
	TTL      uint32        `json:"ttl"`
	From     string        `json:"from"`
	To       string        `json:"to"`
	KeyName  string        `json:"keyname"`
	Topic    TopicType     `json:"topic"`
	Padding  hexutil.Bytes `json:"padding"`
	Payload  hexutil.Bytes `json:"payload"`
	WorkTime uint32        `json:"worktime"`
	PoW      float64       `json:"pow"`
	FilterID string        `json:"filterID"`
	PeerID   hexutil.Bytes `json:"peerID"`
}

type PublicWhisperAPI 

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

PublicWhisperAPI provides the whisper RPC service.

func NewPublicWhisperAPI 

func NewPublicWhisperAPI(w *Whisper) *PublicWhisperAPI

NewPublicWhisperAPI create a new RPC whisper service.

func (*PublicWhisperAPI) AddSymKey 

func (api *PublicWhisperAPI) AddSymKey(name string, key hexutil.Bytes) error

AddSymKey stores the key under the 'name' id.

func (*PublicWhisperAPI) DeleteIdentity 

func (api *PublicWhisperAPI) DeleteIdentity(identity string) error

DeleteIdentity deletes the specifies key if it exists.

func (*PublicWhisperAPI) DeleteSymKey 

func (api *PublicWhisperAPI) DeleteSymKey(name string) error

DeleteSymKey deletes the key associated with the name string if it exists.

func (*PublicWhisperAPI) GenerateSymKey 

func (api *PublicWhisperAPI) GenerateSymKey(name string) error

GenerateSymKey generates a random symmetric key and stores it under the 'name' id. Will be used in the future for session key exchange.

func (*PublicWhisperAPI) GetFilterChanges 

func (api *PublicWhisperAPI) GetFilterChanges(filterId string) []*WhisperMessage

GetFilterChanges retrieves all the new messages matched by a filter since the last retrieval.

func (*PublicWhisperAPI) GetMessages 

func (api *PublicWhisperAPI) GetMessages(filterId string) []*WhisperMessage

GetMessages retrieves all the known messages that match a specific filter.

func (*PublicWhisperAPI) HasIdentity 

func (api *PublicWhisperAPI) HasIdentity(identity string) (bool, error)

HasIdentity checks if the whisper node is configured with the private key of the specified public pair.

func (*PublicWhisperAPI) HasSymKey 

func (api *PublicWhisperAPI) HasSymKey(name string) (bool, error)

HasSymKey returns true if there is a key associated with the name string. Otherwise returns false.

func (*PublicWhisperAPI) MarkPeerTrusted 

func (api *PublicWhisperAPI) MarkPeerTrusted(peerID hexutil.Bytes) error

MarkPeerTrusted marks specific peer trusted, which will allow it to send historic (expired) messages.

func (*PublicWhisperAPI) NewFilter 

func (api *PublicWhisperAPI) NewFilter(args WhisperFilterArgs) (string, error)

NewWhisperFilter creates and registers a new message filter to watch for inbound whisper messages. Returns the ID of the newly created Filter.

func (*PublicWhisperAPI) NewIdentity 

func (api *PublicWhisperAPI) NewIdentity() (string, error)

NewIdentity generates a new cryptographic identity for the client, and injects it into the known identities for message decryption.

func (*PublicWhisperAPI) Post 

func (api *PublicWhisperAPI) Post(args PostArgs) error

Post creates a whisper message and injects it into the network for distribution.

func (*PublicWhisperAPI) Start 

func (api *PublicWhisperAPI) Start() error

Start starts the Whisper worker threads.

func (*PublicWhisperAPI) Stats 

func (api *PublicWhisperAPI) Stats() (string, error)

Stats returns the Whisper statistics for diagnostics.

func (*PublicWhisperAPI) Stop 

func (api *PublicWhisperAPI) Stop() error

Stop stops the Whisper worker threads.

func (*PublicWhisperAPI) UninstallFilter 

func (api *PublicWhisperAPI) UninstallFilter(filterId string)

UninstallFilter disables and removes an existing filter.

func (*PublicWhisperAPI) Version 

func (api *PublicWhisperAPI) Version() (hexutil.Uint, error)

Version returns the Whisper version this node offers.

type ReceivedMessage 

type ReceivedMessage struct {
	Raw []byte

	Payload   []byte
	Padding   []byte
	Signature []byte

	PoW   float64          // Proof of work as described in the Whisper spec
	Sent  uint32           // Time when the message was posted into the network
	TTL   uint32           // Maximum time to live allowed for the message
	Src   *ecdsa.PublicKey // Message recipient (identity used to decode the message)
	Dst   *ecdsa.PublicKey // Message recipient (identity used to decode the message)
	Topic TopicType

	SymKeyHash      common.Hash // The Keccak256Hash of the key, associated with the Topic
	EnvelopeHash    common.Hash // Message envelope hash to act as a unique id
	EnvelopeVersion uint64
}

ReceivedMessage represents a data packet to be received through the Whisper protocol.

func (*ReceivedMessage) SigToPubKey 

func (msg *ReceivedMessage) SigToPubKey() *ecdsa.PublicKey

Recover retrieves the public key of the message signer.

func (*ReceivedMessage) Validate 

func (msg *ReceivedMessage) Validate() bool

Validate checks the validity and extracts the fields in case of success

type SentMessage 

type SentMessage struct {
	Raw []byte
}

SentMessage represents an end-user data packet to transmit through the Whisper protocol. These are wrapped into Envelopes that need not be understood by intermediate nodes, just forwarded.

func NewSentMessage 

func NewSentMessage(params *MessageParams) *SentMessage

NewMessage creates and initializes a non-signed, non-encrypted Whisper message.

func (*SentMessage) Wrap 

func (msg *SentMessage) Wrap(options *MessageParams) (envelope *Envelope, err error)

Wrap bundles the message into an Envelope to transmit over the network.

pow (Proof Of Work) controls how much time to spend on hashing the message, inherently controlling its priority through the network (smaller hash, bigger priority).

The user can control the amount of identity, privacy and encryption through the options parameter as follows:

  • options.From == nil && options.To == nil: anonymous broadcast
  • options.From != nil && options.To == nil: signed broadcast (known sender)
  • options.From == nil && options.To != nil: encrypted anonymous message
  • options.From != nil && options.To != nil: encrypted signed message

type Statistics 

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

type TopicType 

type TopicType [TopicLength]byte

Topic represents a cryptographically secure, probabilistic partial classifications of a message, determined as the first (left) 4 bytes of the SHA3 hash of some arbitrary data given by the original author of the message.

func BytesToTopic 

func BytesToTopic(b []byte) (t TopicType)

func (*TopicType) String 

func (topic *TopicType) String() string

String converts a topic byte array to a string representation.

func (*TopicType) UnmarshalJSON 

func (t *TopicType) UnmarshalJSON(input []byte) error

UnmarshalJSON parses a hex representation to a topic.

type Whisper 

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

Whisper represents a dark communication interface through the Ethereum network, using its very own P2P communication layer.

func New 

func New() *Whisper

New creates a Whisper client ready to communicate through the Ethereum P2P network. Param s should be passed if you want to implement mail server, otherwise nil.

func (*Whisper) APIs 

func (w *Whisper) APIs() []rpc.API

APIs returns the RPC descriptors the Whisper implementation offers

func (*Whisper) AddSymKey 

func (w *Whisper) AddSymKey(name string, key []byte) error

func (*Whisper) DeleteIdentity 

func (w *Whisper) DeleteIdentity(key string)

DeleteIdentity deletes the specified key if it exists.

func (*Whisper) DeleteSymKey 

func (w *Whisper) DeleteSymKey(name string)

func (*Whisper) Envelopes 

func (w *Whisper) Envelopes() []*Envelope

envelopes retrieves all the messages currently pooled by the node.

func (*Whisper) GenerateSymKey 

func (w *Whisper) GenerateSymKey(name string) error

func (*Whisper) GetFilter 

func (w *Whisper) GetFilter(id string) *Filter

func (*Whisper) GetIdentity 

func (w *Whisper) GetIdentity(pubKey string) *ecdsa.PrivateKey

GetIdentity retrieves the private key of the specified public identity.

func (*Whisper) GetSymKey 

func (w *Whisper) GetSymKey(name string) []byte

func (*Whisper) HandlePeer 

func (wh *Whisper) HandlePeer(peer *p2p.Peer, rw p2p.MsgReadWriter) error

handlePeer is called by the underlying P2P layer when the whisper sub-protocol connection is negotiated.

func (*Whisper) HasIdentity 

func (w *Whisper) HasIdentity(pubKey string) bool

HasIdentity checks if the the whisper node is configured with the private key of the specified public pair.

func (*Whisper) HasSymKey 

func (w *Whisper) HasSymKey(name string) bool

func (*Whisper) MarkPeerTrusted 

func (w *Whisper) MarkPeerTrusted(peerID []byte) error

MarkPeerTrusted marks specific peer trusted, which will allow it to send historic (expired) messages.

func (*Whisper) Messages 

func (w *Whisper) Messages(id string) []*ReceivedMessage

Messages retrieves all the decrypted messages matching a filter id.

func (*Whisper) NewIdentity 

func (w *Whisper) NewIdentity() *ecdsa.PrivateKey

NewIdentity generates a new cryptographic identity for the client, and injects it into the known identities for message decryption.

func (*Whisper) Protocols 

func (w *Whisper) Protocols() []p2p.Protocol

Protocols returns the whisper sub-protocols ran by this particular client.

func (*Whisper) RegisterServer 

func (w *Whisper) RegisterServer(server MailServer)

func (*Whisper) RequestHistoricMessages 

func (w *Whisper) RequestHistoricMessages(peerID []byte, envelope *Envelope) error

func (*Whisper) Send 

func (w *Whisper) Send(envelope *Envelope) error

Send injects a message into the whisper send queue, to be distributed in the network in the coming cycles.

func (*Whisper) SendP2PDirect 

func (w *Whisper) SendP2PDirect(peer *Peer, envelope *Envelope) error

func (*Whisper) SendP2PMessage 

func (w *Whisper) SendP2PMessage(peerID []byte, envelope *Envelope) error

func (*Whisper) Start 

func (w *Whisper) Start(*p2p.Server) error

Start implements node.Service, starting the background data propagation thread of the Whisper protocol.

func (*Whisper) Stats 

func (w *Whisper) Stats() string

func (*Whisper) Stop 

func (w *Whisper) Stop() error

Stop implements node.Service, stopping the background data propagation thread of the Whisper protocol.

func (*Whisper) Unwatch 

func (w *Whisper) Unwatch(id string)

Unwatch removes an installed message handler.

func (*Whisper) Version 

func (w *Whisper) Version() uint

Version returns the whisper sub-protocols version number.

func (*Whisper) Watch 

func (w *Whisper) Watch(f *Filter) (string, error)

Watch installs a new message handler to run in case a matching packet arrives from the whisper network.

type WhisperFilterArgs 

type WhisperFilterArgs struct {
	To        string      `json:"to"`
	From      string      `json:"from"`
	KeyName   string      `json:"keyname"`
	PoW       float64     `json:"pow"`
	Topics    []TopicType `json:"topics"`
	AcceptP2P bool        `json:"p2p"`
}

func (*WhisperFilterArgs) UnmarshalJSON 

func (args *WhisperFilterArgs) UnmarshalJSON(b []byte) (err error)

UnmarshalJSON implements the json.Unmarshaler interface, invoked to convert a JSON message blob into a WhisperFilterArgs structure.

type WhisperMessage 

type WhisperMessage struct {
	Topic   string  `json:"topic"`
	Payload string  `json:"payload"`
	Padding string  `json:"padding"`
	From    string  `json:"from"`
	To      string  `json:"to"`
	Sent    uint32  `json:"sent"`
	TTL     uint32  `json:"ttl"`
	PoW     float64 `json:"pow"`
	Hash    string  `json:"hash"`
}

WhisperMessage is the RPC representation of a whisper message.

func NewWhisperMessage 

func NewWhisperMessage(message *ReceivedMessage) *WhisperMessage

NewWhisperMessage converts an internal message into an API version.

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.