chore: add initial protocol structs

go.mod

@@ -3,8 +3,9 @@ module dev.l1qu1d.net/wraith-labs/wraith-module-pinecomms
 go 1.19
 
 require (
-	dev.l1qu1d.net/wraith-labs/wraith/wraith v0.0.0-20230108044209-a3d333e966c0
+	dev.l1qu1d.net/wraith-labs/wraith/wraith v0.0.0-20230108053804-2017758710bb
 	github.com/cristalhq/jwt/v4 v4.0.2
+	github.com/fxamacker/cbor/v2 v2.4.0
 	github.com/google/uuid v1.3.0
 	github.com/gorilla/mux v1.8.0
 	github.com/gorilla/websocket v1.5.0
@@ -21,6 +22,7 @@ require (
 	github.com/marten-seemann/qtls-go1-18 v0.1.4 // indirect
 	github.com/marten-seemann/qtls-go1-19 v0.1.2 // indirect
 	github.com/onsi/ginkgo/v2 v2.6.1 // indirect
+	github.com/x448/float16 v0.8.4 // indirect
 	go.uber.org/atomic v1.10.0 // indirect
 	golang.org/x/crypto v0.5.0 // indirect
 	golang.org/x/exp v0.0.0-20230105202349-8879d0199aa3 // indirect

go.sum

@@ -1,5 +1,5 @@
-dev.l1qu1d.net/wraith-labs/wraith/wraith v0.0.0-20230108044209-a3d333e966c0 h1:osK0txrQoYK9yqC/rtiVcCjH9ZtiSQWlYCV43NiCvok=
-dev.l1qu1d.net/wraith-labs/wraith/wraith v0.0.0-20230108044209-a3d333e966c0/go.mod h1:tGS7U98Lv1UDSAEmdfEz2rDy4N7oz7i6GTZ5hkpNdxM=
+dev.l1qu1d.net/wraith-labs/wraith/wraith v0.0.0-20230108053804-2017758710bb h1:0uPcJmG4XOdBKPHF1dumKaYewe37NcuHYKkvh0US4+M=
+dev.l1qu1d.net/wraith-labs/wraith/wraith v0.0.0-20230108053804-2017758710bb/go.mod h1:atDu4/L057CdEw2ufSxijPU+6Yq2FnC9coRYS6l4Pks=
 github.com/Arceliar/phony v0.0.0-20210209235338-dde1a8dca979 h1:WndgpSW13S32VLQ3ugUxx2EnnWmgba1kCqPkd4Gk1yQ=
 github.com/Arceliar/phony v0.0.0-20210209235338-dde1a8dca979/go.mod h1:6Lkn+/zJilRMsKmbmG1RPoamiArC6HS73xbwRyp3UyI=
 github.com/cristalhq/jwt/v4 v4.0.2 h1:g/AD3h0VicDamtlM70GWGElp8kssQEv+5wYd7L9WOhU=
@@ -7,6 +7,8 @@ github.com/cristalhq/jwt/v4 v4.0.2/go.mod h1:HnYraSNKDRag1DZP92rYHyrjyQHnVEHPNqe
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fxamacker/cbor/v2 v2.4.0 h1:ri0ArlOR+5XunOP8CRUowT0pSJOwhW098ZCUyskZD88=
+github.com/fxamacker/cbor/v2 v2.4.0/go.mod h1:TA1xS00nchWmaBnEIxPSE5oHLuJBAVvqrtAnWBwBCVo=
 github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO8GZSjAhjMsSuLt29uWRFHdHYUb5lYOV9qE=
 github.com/gin-contrib/sse v0.1.0/go.mod h1:RHrZQHXnP2xjPF+u1gW/2HnVO7nvIa9PG3Gm+fLHvGI=
 github.com/gin-gonic/gin v1.6.3 h1:ahKqKTFpO5KTPHxWZjEdPScmYaGtLo8Y4DMHoEsnp14=
@@ -79,6 +81,8 @@ github.com/ugorji/go v1.1.7 h1:/68gy2h+1mWMrwZFeD1kQialdSzAb432dtpeJ42ovdo=
 github.com/ugorji/go v1.1.7/go.mod h1:kZn38zHttfInRq0xu/PH0az30d+z6vm202qpg1oXVMw=
 github.com/ugorji/go/codec v1.1.7 h1:2SvQaVZ1ouYrrKKwoSk2pzd4A9evlKJb9oTL+OaLUSs=
 github.com/ugorji/go/codec v1.1.7/go.mod h1:Ax+UKWsSmolVDwsd+7N3ZtXu+yMGCf907BLYF3GoBXY=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
 github.com/yuin/goldmark v1.3.5/go.mod h1:mwnBkeHKe2W/ZEtQ+71ViKU8L12m81fl3OWwC1Zlc8k=
 go.uber.org/atomic v1.10.0 h1:9qC72Qh0+3MqyJbAn8YU5xVq1frD8bn3JtD2oXtafVQ=
 go.uber.org/atomic v1.10.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0=

internal/proto/heartbeat.go

@@ -0,0 +1,17 @@
+package proto
+
+// The structure of heartbeats which Wraiths send to c2 to register
+// their status and presence.
+type Heartbeat struct {
+	// The operating system Wraith is running on.
+	HostOS string
+
+	// The CPU architecture of the host.
+	HostArch string
+
+	// The system hostname.
+	Hostname string
+
+	// A list of errors the Wraith has encountered.
+	Errors []error
+}

internal/proto/helpers.go

@@ -0,0 +1,56 @@
+package proto
+
+import (
+	"crypto/ed25519"
+	"crypto/sha512"
+	"errors"
+
+	"github.com/fxamacker/cbor/v2"
+)
+
+type packet interface {
+	Heartbeat | Req | Res
+}
+
+// Converts a packet into a byte array ready for transmission.
+func Marshal[P packet](p *P, signingKey ed25519.PrivateKey) ([]byte, error) {
+	// Get the CBOR representation of the data.
+	dataBytes, err := cbor.Marshal(p)
+	if err != nil {
+		return dataBytes, err
+	}
+
+	// Calculate the checksum of the data for the signature.
+	checksum := sha512.Sum384(dataBytes)
+
+	// Create the signature for verification purposes.
+	signatureBytes := ed25519.Sign(signingKey, checksum[:])
+
+	// Return a byte array of the signature followed by the data.
+	return append(signatureBytes, dataBytes...), nil
+}
+
+// Converts a byte array into a packet so that it can be processed.
+func Unmarshal[P packet](p *P, verificationKey ed25519.PublicKey, data []byte) error {
+	// Make sure the data is correctly formatted (at least 64 bytes)
+	if len(data) < 64 {
+		return errors.New("provided data was too short")
+	}
+
+	// Split the byte array into the signature and data parts.
+	signatureBytes := data[0:64]
+	dataBytes := data[64:]
+
+	// Calculate the checksum of the data for verification.
+	checksum := sha512.Sum384(dataBytes)
+
+	// Verify the signature.
+	verified := ed25519.Verify(verificationKey, checksum[:], signatureBytes)
+	if !verified {
+		return errors.New("data failed signature verification")
+	}
+
+	// If verification was successful, unmarshal the data into the
+	// current struct and return whether this was successful.
+	return cbor.Unmarshal(dataBytes, p)
+}

internal/proto/req.go

@@ -0,0 +1,24 @@
+package proto
+
+// The structure of requests pc3 makes to Wraiths running the
+// pinecomms module.
+type Req struct {
+	// The actual payload which tells the module what to do.
+	Payload struct {
+		// Which shm fields should be read and returned.
+		Read []string
+
+		// Which shm fields should be written to and the
+		// values that should be written.
+		Write map[string]interface{}
+
+		// Whether to return a list of all active memory cells
+		// in the response. Runs after Req.Payload.Write.
+		ListMem bool
+	}
+
+	// Conditions which must be satisfied for Wraith to consider
+	// the payload. If the conditions are not met, the payload
+	// is dropped.
+	Conditions struct{}
+}

internal/proto/res.go

@@ -0,0 +1,22 @@
+package proto
+
+// The structure of responses Wraiths running the pinecomms module
+// make to pc3.
+type Res struct {
+	// The main body of the response.
+	Payload struct {
+		// A map of all read cells and their contents.
+		Read map[string]interface{}
+
+		// An array of all cells which were successfully written.
+		Written []string
+
+		// An array of all cells present in the shm if it was
+		// requested.
+		MemList []string
+	}
+
+	// A signature verifying that the request came from the Wraith. Allows
+	// for store-and-forward functionality.
+	Signature []byte
+}