messages

Documentation

Overview

Package messages implements the basic messaging system usable for chatting in the 3nigm4 framework. It defines basic exchanged strutures and the basic flow.

Index

• type EnrollmentRes
• type HandshakeReq
• type HandshakeRes
• type Message
• type RecipientKeys
• type ServerKey
• type ServerMsg
• type SessionKeys
  • func NewSessionKeys(creatorId string, preshared []byte, recipients []string) (*SessionKeys, error)
  • func SessionFromEncryptedMsg(data []byte, recipientk openpgp.EntityList, preshared []byte) (*SessionKeys, error)
  • func (sk *SessionKeys) DecryptMessage(chipered []byte, participants openpgp.EntityList, signed bool) (*Message, error)
  • func (sk *SessionKeys) EncryptForRecipientsHandshake(recipients openpgp.EntityList, signer *openpgp.Entity) ([]byte, error)
  • func (sk *SessionKeys) EncryptForServerHandshake(recipients openpgp.EntityList, signer *openpgp.Entity, ttl uint64) ([]byte, error)
  • func (sk *SessionKeys) EncryptMessage(message []byte, signer *openpgp.Entity) ([]byte, error)
• type SignedMessage
• type StandardResponse

Types

type EnrollmentRes

type EnrollmentRes struct {
	SessionId            []byte `json:"session" xml:"session"`   // the id of the session;
	EncryptedSessionKeys []byte `json:"sessionk" xml:"sessionk"` // encrypted SessionKeys json encoded struct.
}

EnrollmentRes is passed by the server to clients when they require pending messages to the service.

type HandshakeReq

type HandshakeReq struct {
	TimeStamp      time.Time       `json:"timestamp" xml:"timestamp"`     // handshake op timestamp;
	RecipientsKeys []RecipientKeys `json:"recipientsk" xml:"recipientsk"` // recipient completed with pgp encrypted messages;
	ServerKey      ServerKey       `json:"serverk" xml:"serverk"`         // key that'll be used by the server to encrypt a random generated key;
}

HandshakeReq request to require a new session to the server All the request will be encoded and encrypted using server pgp public key.

type HandshakeRes

type HandshakeRes struct {
	SessionId []byte `json:"session" xml:"session"` // the id of the session.
}

HandshakeRes successful server response returns all needed informations to start exchanging messages with required recipients.

type Message

type Message struct {
	SessionId         []byte    `json:"session" xml:"session"`     // the id of the session;
	SenderId          string    `json:"-" xml:"-"`                 // plain text message sender (in memory);
	EncryptedSenderId []byte    `json:"esenderid" xml:"esenderid"` // encrypted sender id;
	Body              []byte    `json:"-" xml:"-"`                 // plaintext body (in memory);
	EncryptedBody     []byte    `json:"body" xml:"body"`           // the actual encrypted message;
	TimeStamp         time.Time `json:"timestamp" xml:"timestamp"` // message op timestamp;
	Counter           uint64    `json:"counter" xml:"counter"`     // message idx.
}

Message request for an encrypted message using pre-sared keys.

type RecipientKeys

type RecipientKeys struct {
	Id                   string `json:"id" xml:"id"`             // recipient id;
	EncryptedSessionKeys []byte `json:"sessionk" xml:"sessionk"` // encrypted SessionKeys json encoded struct.
}

RecipientKeys is replicated for each recipient and used in handshake flow to exchange, in encrypted form, all required symmetric keys.

type ServerKey

type ServerKey struct {
	ServerSymmetricKey []byte `json:"serverk" xml:"serverk"` // symmetric key to be used to encrypt server random key;
	TimeToLive         uint64 `json:"ttl" xml:"ttl"`         // time to live in seconds.
}

ServerKey is passed to the server will be used to encrypt a second random key to be used in symmetric algorithm assigning a time to live.

type ServerMsg

type ServerMsg struct {
	ServerSymmetricKey []byte   `json:"serverk" xml:"serverk"`             // symmetric key to be used to encrypt server random key;
	RecipientsIds      []string `json:"recipientsids" xml:"recipientsids"` // resipients ids;
	TimeToLive         uint64   `json:"ttl" xml:"ttl"`                     // time to live in seconds.
}

ServerMsg contain the exchange structure used to pass the server symmetric key to the server.

type SessionKeys

type SessionKeys struct {
	CreatorId          string    `json:"creatorid" xml:"creatorid"`        // id of the session creator;
	MainSymmetricKey   []byte    `json:"maink" xml:"maink"`                // main random generated symmetric key;
	ServerSymmetricKey []byte    `json:"serverk" xml:"serverk"`            // server symmetric key;
	PreSharedFlag      bool      `json:"presharedf" xml:"presharedf"`      // is there also a pre-shared key in use;
	RecipientsIds      []string  `json:"recipientsids" xml:"recipientsid"` // slice of id of recipients and senender (all involved entities);
	PreSharedKey       []byte    `json:"-" xml:"-"`                        // pre shared key (only available in the client);
	SessionId          []byte    `json:"-" xml:"-"`                        // session id returned by the server after creating the session;
	IncrementalCounter uint64    `json:"-" xml:"-"`                        // incremental counter of exchanged messages;
	UserId             string    `json:"-" xml:"-"`                        // the user that is interacting with the session;
	ServerTmpKey       []byte    `json:"-" xml:"-"`                        // server generated in memory key (shoul never be stored anywhere);
	Messages           []Message `json:"-" xml:"-"`                        // in memory plain text messages list associated with the session.
}

SessionKeys contains all required keys to participate to a chat session. This structure will be encrypted using pgp before being inserted in a Recipient keys struct for being sent to the server.

func NewSessionKeys

func NewSessionKeys(creatorId string, preshared []byte, recipients []string) (*SessionKeys, error)

NewSessionKeys creates a new session struct assigning random keys and required configurations.

func SessionFromEncryptedMsg

func SessionFromEncryptedMsg(data []byte, recipientk openpgp.EntityList, preshared []byte) (*SessionKeys, error)

SessionFromEncryptedMsg create a new session from an encrypted message. Pre-shared key have to be inserted manually.

func (*SessionKeys) DecryptMessage

func (sk *SessionKeys) DecryptMessage(chipered []byte, participants openpgp.EntityList, signed bool) (*Message, error)

DecryptMessage decrypt messages using symmetric keys and verifying the signature (if enabled), it returns the plaintext message, the message time stamp and the message count.

func (*SessionKeys) EncryptForRecipientsHandshake

func (sk *SessionKeys) EncryptForRecipientsHandshake(recipients openpgp.EntityList, signer *openpgp.Entity) ([]byte, error)

EncryptForRecipientsHandshake creates an encrypted message to pass session keys to one or more of recipients.

func (*SessionKeys) EncryptForServerHandshake

func (sk *SessionKeys) EncryptForServerHandshake(recipients openpgp.EntityList, signer *openpgp.Entity, ttl uint64) ([]byte, error)

EncryptForServerHandshake create an encrypted packet to exchange server encryption key with the server. This function will use as recipient the public keys exposed by the server entity and will sign the message using the sender key. A time to live can be specified to define how many time the key should be maintained by the server.

func (*SessionKeys) EncryptMessage

func (sk *SessionKeys) EncryptMessage(message []byte, signer *openpgp.Entity) ([]byte, error)

EncryptMessage derive all required keys and encrypt a message using pre-shared keys. Notice that server maintained key has been already retrieved and is stored in volatile RAM for usage.

type SignedMessage

type SignedMessage struct {
	Message   Message `json:"message" xml:"message"`     // the message;
	Signature []byte  `json:"signature" xml:"signature"` // signature on json coded message.
}

SignedMessage wrapping message containing message signature.

type StandardResponse

type StandardResponse struct {
	Status string `json:"status"` // Status string
	Error  string `json:"error"`  // Error description
}

StandardResponse is a generic response message used to pass non specific messages like everything is OK or an error occurred.