session

package
v4.7.4 Latest Latest
Warning

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

 Go to latest Published: Jul 12, 2024 License: BSD-2-Clause, BSD-2-Clause Imports: 26 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateE2ESessionBaseKey 

func GenerateE2ESessionBaseKey(myDHPrivKey, theirDHPubKey *cyclic.Int,
	dhGrp *cyclic.Group, mySIDHPrivKey *sidh.PrivateKey,
	theirSIDHPubKey *sidh.PublicKey) *cyclic.Int

GenerateE2ESessionBaseKey returns the baseKey symmetric encryption key root. The baseKey is created by hashing the results of the Diffie-Hellman (DH) key exchange with the post-quantum secure Supersingular Isogeny DH exchange results.

func MakeSessionPrefix 

func MakeSessionPrefix(sid SessionID) string

MakeSessionPrefix builds the prefix

Types

type Cypher 

type Cypher interface {

	// GetSession return pointers to higher level management structures.
	GetSession() *Session

	// Fingerprint returns the Cypher key fingerprint, if it has it. Otherwise,
	// it generates and returns a new one.
	Fingerprint() format.Fingerprint

	// Encrypt uses the E2E key to encrypt the message to its intended
	// recipient. It also properly populates the associated data, including the
	// MAC, fingerprint, and encrypted timestamp. It generates a residue of the
	// key used to encrypt the contents.
	Encrypt(contents []byte) (ecrContents, mac []byte, residue e2eCrypto.KeyResidue)

	// Decrypt uses the E2E key to decrypt the message. It returns an error in
	// case of HMAC verification failure or in case of a decryption error
	// (related to padding). It generates a residue of the
	// key used to encrypt the contents.
	Decrypt(msg format.Message) (decryptedPayload []byte, residue e2eCrypto.KeyResidue, err error)

	// Use sets the key as used. It cannot be used again.
	Use()
}

Cypher manages the cryptographic material for E2E messages and provides methods to encrypt and decrypt them.

type CypherHandler 

type CypherHandler interface {
	AddKey(cy Cypher)
	DeleteKey(cy Cypher)
}

type Negotiation 

type Negotiation uint8

Fix-me: this solution is incompatible with offline sending, when that is added, a session which has not been confirmed will never partnerSource the creation of new session, the Unconfirmed->Confirmed and Confirmed->NewSessionCreated most likely need to be two separate enums tracked separately 

const (
	Unconfirmed Negotiation = iota
	Sending
	Sent
	Confirmed
	NewSessionTriggered
	NewSessionCreated
)

func (Negotiation) String 

func (c Negotiation) String() string

Adherence to stringer interface

type Params 

type Params struct {
	// using the DH as a seed, both sides finalizeKeyNegotation a number
	// of keys to use before they must rekey because
	// there are no keys to use.
	MinKeys uint16
	MaxKeys uint16
	// the percent of keys before a rekey is attempted. must be <0
	RekeyThreshold float64
	// extra keys generated and reserved for rekey attempts. This
	// many keys are not allowed to be used for sending messages
	// in order to ensure there are extras for rekeying.
	NumRekeys uint16
	// Number from 0 to 1, denotes how often when in the unconfirmed state the
	// system will automatically resend the rekey request on any message send
	// from the partner the session is associated with
	UnconfirmedRetryRatio float64
}

func GetDefaultParams 

func GetDefaultParams() Params

GetDefaultParams returns a default set of Params.

func GetParameters 

func GetParameters(params string) (Params, error)

GetParameters returns the default Params, or override with given parameters, if set.

func (Params) MarshalJSON 

func (p Params) MarshalJSON() ([]byte, error)

MarshalJSON adheres to the json.Marshaler interface.

func (Params) String 

func (p Params) String() string

func (*Params) UnmarshalJSON 

func (p *Params) UnmarshalJSON(data []byte) error

UnmarshalJSON adheres to the json.Unmarshaler interface.

type RelationshipType 

type RelationshipType uint
const (
	Send RelationshipType = iota
	Receive
)

func (RelationshipType) Prefix 

func (rt RelationshipType) Prefix() string

func (RelationshipType) String 

func (rt RelationshipType) String() string

type Session 

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

func CreateTestSession 

func CreateTestSession(numKeys, keysAvailable, rekeyThreshold uint32, status Negotiation, t *testing.T) (*Session, versioned.KV)

func LoadSession 

func LoadSession(kv versioned.KV, sessionID SessionID,
	relationshipFingerprint []byte, cyHandler CypherHandler,
	grp *cyclic.Group, rng *fastRNG.StreamGenerator) (*Session, error)

LoadSession and state vector from kv and populate runtime fields

func NewSession 

func NewSession(kv versioned.KV, t RelationshipType, partner *id.ID, myPrivKey,
	partnerPubKey, baseKey *cyclic.Int, mySIDHPrivKey *sidh.PrivateKey,
	partnerSIDHPubKey *sidh.PublicKey, trigger SessionID,
	relationshipFingerprint []byte, negotiationStatus Negotiation,
	e2eParams Params, cyHandler CypherHandler, grp *cyclic.Group,
	rng *fastRNG.StreamGenerator) *Session

NewSession - Generator which creates all keys and structures

func (*Session) Delete 

func (s *Session) Delete()

Delete removes this session and its key states from the storage

func (*Session) GetBaseKey 

func (s *Session) GetBaseKey() *cyclic.Int

GetBaseKey retrieves the base key.

func (*Session) GetID 

func (s *Session) GetID() SessionID

GetID Blake2B hash of base key used for storage

func (*Session) GetMyPrivKey 

func (s *Session) GetMyPrivKey() *cyclic.Int

func (*Session) GetMySIDHPrivKey 

func (s *Session) GetMySIDHPrivKey() *sidh.PrivateKey

func (*Session) GetPartner 

func (s *Session) GetPartner() *id.ID

GetPartner returns the ID of the partner for this session

func (*Session) GetPartnerPubKey 

func (s *Session) GetPartnerPubKey() *cyclic.Int

func (*Session) GetPartnerSIDHPubKey 

func (s *Session) GetPartnerSIDHPubKey() *sidh.PublicKey

func (*Session) GetRelationshipFingerprint 

func (s *Session) GetRelationshipFingerprint() []byte

todo - doscstring

func (*Session) GetSource 

func (s *Session) GetSource() SessionID

func (*Session) IsConfirmed 

func (s *Session) IsConfirmed() bool

IsConfirmed checks if the session has been confirmed

func (*Session) NegotiationStatus 

func (s *Session) NegotiationStatus() Negotiation

NegotiationStatus checks if the session has been confirmed

func (*Session) PopKey 

func (s *Session) PopKey() (Cypher, error)

PopKey Pops the first unused key, skipping any which are denoted as used. will return if the remaining keys are designated as rekeys

func (*Session) PopReKey 

func (s *Session) PopReKey() (Cypher, error)

PopReKey Pops the first unused key, skipping any which are denoted as used, including keys designated for rekeys

func (*Session) Save 

func (s *Session) Save() error

todo - doscstring

func (*Session) SetNegotiationStatus 

func (s *Session) SetNegotiationStatus(status Negotiation)

todo - doscstring

func (*Session) Status 

func (s *Session) Status() Status

returns the state of the session, which denotes if the Session is active, functional but in need of a rekey, empty of Send key, or empty of rekeys

func (*Session) String 

func (s *Session) String() string

todo - doscstring

func (*Session) TriggerNegotiation 

func (s *Session) TriggerNegotiation() bool

TriggerNegotiation in a mostly thread safe manner, checks if the session needs a negotiation, returns if it does while updating the session to denote the negotiation was triggered WARNING: This function relies on proper action by the caller for data safety. When triggering the creation of a new session (the first case) it does not store to disk the fact that it has triggered the session. This is because every session should only partnerSource one other session and in the event that session partnerSource does not resolve before a crash, by not storing it the partnerSource will automatically happen again when reloading after the crash. In order to ensure the session creation is not triggered again after the reload, it is the responsibility of the caller to call Session.SetConfirmationStatus(NewSessionCreated) .

func (*Session) TrySetNegotiationStatus 

func (s *Session) TrySetNegotiationStatus(status Negotiation) error

todo - doscstring

type SessionDisk 

type SessionDisk struct {
	E2EParams Params

	//session type
	Type uint8

	// Underlying key
	BaseKey []byte
	// Own Private Key
	MyPrivKey []byte
	// Partner Public Key
	PartnerPubKey []byte
	// Own SIDH Private Key
	MySIDHPrivKey []byte
	// Note: only 3 bit patterns: 001, 010, 100
	MySIDHVariant byte
	// Partner SIDH Public Key
	PartnerSIDHPubKey []byte
	// Note: only 3 bit patterns: 001, 010, 100
	PartnerSIDHVariant byte

	// ID of the session which triggered this sessions creation.
	Trigger []byte
	// relationship fp
	RelationshipFingerprint []byte

	//denotes if the other party has confirmed this key
	Confirmation uint8

	// Number of keys usable before rekey
	RekeyThreshold uint32

	Partner []byte
}

SessionDisk is a utility struct to write part of session data to disk. As this is serialized by json, any field that should be serialized must be exported

type SessionID 

type SessionID [sessionIDLen]byte

func GetSessionIDFromBaseKey 

func GetSessionIDFromBaseKey(baseKey *cyclic.Int) SessionID

underlying definition of session id

func GetSessionIDFromBaseKeyForTesting 

func GetSessionIDFromBaseKeyForTesting(baseKey *cyclic.Int, i interface{}) SessionID

underlying definition of session id FOR TESTING PURPOSES ONLY

func (SessionID) Marshal 

func (sid SessionID) Marshal() []byte

func (SessionID) String 

func (sid SessionID) String() string

func (*SessionID) Unmarshal 

func (sid *SessionID) Unmarshal(b []byte) error

type Status 

type Status uint8
const (
	// Active sessions have keys remaining that can be used for messages
	Active Status = iota
	// RekeyNeeded sessions have keys remaining for messages, but should be rekeyed immediately
	RekeyNeeded
	// Empty sessions can't be used for more messages, but can be used for rekeys
	Empty
	// RekeyEmpty sessions are totally empty and no longer have enough keys left for a rekey, much less messages
	RekeyEmpty
)

func (Status) String 

func (a Status) String() string

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.