renterhost

Documentation

Overview

Package renterhost implements the handshake and transport for the Sia renter-host protocol.

Index

• Constants
• Variables
• func HashRevision(rev types.FileContractRevision) crypto.Hash
• type HashSigner
• type HashVerifier
• type ProtocolObject
• type RPCError
  • func (e *RPCError) Error() string
• type RPCFormContractAdditions
• type RPCFormContractRequest
• type RPCFormContractSignatures
• type RPCLockRequest
• type RPCLockResponse
• type RPCReadRequest
• type RPCReadRequestSection
• type RPCReadResponse
• type RPCSectorRootsRequest
• type RPCSectorRootsResponse
• type RPCSettingsResponse
• type RPCWriteAction
• type RPCWriteMerkleProof
• type RPCWriteRequest
• type RPCWriteResponse
• type Session
  • func NewHostSession(conn io.ReadWriteCloser, hs HashSigner) (_ *Session, err error)
  • func NewRenterSession(conn io.ReadWriteCloser, hv HashVerifier) (_ *Session, err error)
  • func (s *Session) Close() (err error)
  • func (s *Session) ReadID() (rpcID Specifier, err error)
  • func (s *Session) ReadRequest(req ProtocolObject, maxLen uint64) (err error)
  • func (s *Session) ReadResponse(resp ProtocolObject, maxLen uint64) (err error)
  • func (s *Session) SetChallenge(challenge [16]byte)
  • func (s *Session) SignChallenge(hs HashSigner) []byte
  • func (s *Session) VerifyChallenge(sig []byte, hv HashVerifier) bool
  • func (s *Session) WriteRequest(rpcID Specifier, req ProtocolObject) (err error)
  • func (s *Session) WriteResponse(resp ProtocolObject, err error) (e error)
• type Specifier
  • func (s Specifier) String() string

Constants

const MinMessageSize = 4096

MinMessageSize is the minimum size of an RPC message. If an encoded message would be smaller than MinMessageSize, the sender MAY pad it with random data. This hinders traffic analysis by obscuring the true sizes of messages.

const SectorSize = 1 << 22 // 4 MiB

SectorSize is the size of one sector in bytes.

Variables

var (
	RPCFormContractID  = newSpecifier("LoopFormContract")
	RPCLockID          = newSpecifier("LoopLock")
	RPCReadID          = newSpecifier("LoopRead")
	RPCRenewContractID = newSpecifier("LoopRenew")
	RPCSectorRootsID   = newSpecifier("LoopSectorRoots")
	RPCSettingsID      = newSpecifier("LoopSettings")
	RPCUnlockID        = newSpecifier("LoopUnlock")
	RPCWriteID         = newSpecifier("LoopWrite")
)

RPC IDs

var (
	RPCWriteActionAppend = newSpecifier("Append")
	RPCWriteActionTrim   = newSpecifier("Trim")
	RPCWriteActionSwap   = newSpecifier("Swap")
	RPCWriteActionUpdate = newSpecifier("Update")

	RPCReadStop = newSpecifier("ReadStop")
)

Read/Write actions

var ErrRenterClosed = errors.New("renter has terminated session")

ErrRenterClosed is returned by (*Session).ReadID when the renter sends the session termination signal.

Functions

func HashRevision

func HashRevision(rev types.FileContractRevision) crypto.Hash

HashRevision hashes a FileContractRevision. This is the hash signed by the renter and host during revision negotiation.

Types

type HashSigner

type HashSigner interface {
	SignHash(hash crypto.Hash) []byte
}

A HashSigner signs hashes with a secret key.

type HashVerifier

type HashVerifier interface {
	VerifyHash(hash crypto.Hash, sig []byte) bool
}

A HashVerifier verifies that a hash was signed with a secret key.

type ProtocolObject

type ProtocolObject interface {
	// contains filtered or unexported methods
}

A ProtocolObject is an object that can be serialized for transport in the renter-host protocol.

type RPCError

type RPCError struct {
	Type        Specifier
	Data        []byte // structure depends on Type
	Description string // human-readable error string
}

An RPCError may be sent instead of a response object to any RPC.

func (*RPCError) Error

func (e *RPCError) Error() string

Error implements the error interface.

type RPCFormContractAdditions

type RPCFormContractAdditions struct {
	Parents []types.Transaction
	Inputs  []types.SiacoinInput
	Outputs []types.SiacoinOutput
}

RPCFormContractAdditions contains the parent transaction, inputs, and outputs added by the host when negotiating a file contract.

type RPCFormContractRequest

type RPCFormContractRequest struct {
	Transactions []types.Transaction
	RenterKey    types.SiaPublicKey
}

RPCFormContractRequest contains the request parameters for the FormContract RPC.

type RPCFormContractSignatures

type RPCFormContractSignatures struct {
	ContractSignatures []types.TransactionSignature
	RevisionSignature  types.TransactionSignature
}

RPCFormContractSignatures contains the signatures for a contract transaction and initial revision. These signatures are sent by both the renter and host during contract formation and renewal.

type RPCLockRequest

type RPCLockRequest struct {
	ContractID types.FileContractID
	Signature  []byte
	Timeout    uint64
}

RPCLockRequest contains the request parameters for the Lock RPC.

type RPCLockResponse

type RPCLockResponse struct {
	Acquired     bool
	NewChallenge [16]byte
	Revision     types.FileContractRevision
	Signatures   []types.TransactionSignature
}

RPCLockResponse contains the response data for the Lock RPC.

type RPCReadRequest

type RPCReadRequest struct {
	Sections    []RPCReadRequestSection
	MerkleProof bool

	NewRevisionNumber    uint64
	NewValidProofValues  []types.Currency
	NewMissedProofValues []types.Currency
	Signature            []byte
}

RPCReadRequest contains the request parameters for the Read RPC.

type RPCReadRequestSection

type RPCReadRequestSection struct {
	MerkleRoot crypto.Hash
	Offset     uint32
	Length     uint32
}

RPCReadRequestSection is a section requested in RPCReadRequest.

type RPCReadResponse

type RPCReadResponse struct {
	Signature   []byte
	Data        []byte
	MerkleProof []crypto.Hash
}

RPCReadResponse contains the response data for the Read RPC.

type RPCSectorRootsRequest

type RPCSectorRootsRequest struct {
	RootOffset uint64
	NumRoots   uint64

	NewRevisionNumber    uint64
	NewValidProofValues  []types.Currency
	NewMissedProofValues []types.Currency
	Signature            []byte
}

RPCSectorRootsRequest contains the request parameters for the SectorRoots RPC.

type RPCSectorRootsResponse

type RPCSectorRootsResponse struct {
	Signature   []byte
	SectorRoots []crypto.Hash
	MerkleProof []crypto.Hash
}

RPCSectorRootsResponse contains the response data for the SectorRoots RPC.

type RPCSettingsResponse

type RPCSettingsResponse struct {
	Settings []byte // JSON-encoded hostdb.HostSettings
}

RPCSettingsResponse contains the response data for the SettingsResponse RPC.

type RPCWriteAction

type RPCWriteAction struct {
	Type Specifier
	A, B uint64
	Data []byte
}

RPCWriteAction is a generic Write action. The meaning of each field depends on the Type of the action.

type RPCWriteMerkleProof

type RPCWriteMerkleProof struct {
	OldSubtreeHashes []crypto.Hash
	OldLeafHashes    []crypto.Hash
	NewMerkleRoot    crypto.Hash
}

RPCWriteMerkleProof contains the optional Merkle proof for response data for the Write RPC.

type RPCWriteRequest

type RPCWriteRequest struct {
	Actions     []RPCWriteAction
	MerkleProof bool

	NewRevisionNumber    uint64
	NewValidProofValues  []types.Currency
	NewMissedProofValues []types.Currency
}

RPCWriteRequest contains the request parameters for the Write RPC.

type RPCWriteResponse

type RPCWriteResponse struct {
	Signature []byte
}

RPCWriteResponse contains the response data for the Write RPC.

type Session

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

A Session is an ongoing exchange of RPCs via the renter-host protocol.

func NewHostSession

func NewHostSession(conn io.ReadWriteCloser, hs HashSigner) (_ *Session, err error)

NewHostSession conducts the hosts's half of the renter-host protocol handshake, returning a Session that can be used to handle RPC requests.

func NewRenterSession

func NewRenterSession(conn io.ReadWriteCloser, hv HashVerifier) (_ *Session, err error)

NewRenterSession conducts the renter's half of the renter-host protocol handshake, returning a Session that can be used to make RPC requests.

Note that hostdb.HostPublicKey implements the HashVerifier interface.

func (*Session) Close

func (s *Session) Close() (err error)

Close gracefully terminates the RPC loop and closes the connection.

func (*Session) ReadID

func (s *Session) ReadID() (rpcID Specifier, err error)

ReadID reads an RPC request ID. If the renter sends the session termination signal, ReadID returns ErrRenterClosed.

func (*Session) ReadRequest

func (s *Session) ReadRequest(req ProtocolObject, maxLen uint64) (err error)

ReadRequest reads an RPC request using the new loop protocol.

func (*Session) ReadResponse

func (s *Session) ReadResponse(resp ProtocolObject, maxLen uint64) (err error)

ReadResponse reads an RPC response. If the response is an error, it is returned directly.

func (*Session) SetChallenge

func (s *Session) SetChallenge(challenge [16]byte)

SetChallenge sets the current session challenge.

func (*Session) SignChallenge

func (s *Session) SignChallenge(hs HashSigner) []byte

SignChallenge signs the current session challenge.

func (*Session) VerifyChallenge

func (s *Session) VerifyChallenge(sig []byte, hv HashVerifier) bool

VerifyChallenge verifies a signature of the current session challenge.

func (*Session) WriteRequest

func (s *Session) WriteRequest(rpcID Specifier, req ProtocolObject) (err error)

WriteRequest sends an encrypted RPC request, comprising an RPC ID and a request object.

func (*Session) WriteResponse

func (s *Session) WriteResponse(resp ProtocolObject, err error) (e error)

WriteResponse writes an RPC response object or error. Either resp or err must be nil. If err is an *RPCError, it is sent directly; otherwise, a generic RPCError is created from err's Error string.

type Specifier

type Specifier [16]byte

A Specifier is a generic identification tag.

func (Specifier) String

func (s Specifier) String() string