{"id":42104360,"url":"https://github.com/navaz-alani/concord","last_synced_at":"2026-01-26T13:11:30.272Z","repository":{"id":56194632,"uuid":"314376574","full_name":"navaz-alani/concord","owner":"navaz-alani","description":"A secure-by-default packet-based application layer (L7) protocol specification, with UDP \u0026 TCP implementations in Golang.","archived":false,"fork":false,"pushed_at":"2020-12-23T14:17:29.000Z","size":3566,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-06-19T05:46:07.392Z","etag":null,"topics":["application-layer-protocol","concord","concord-packet-protocol","golang-library","packets","udp"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/navaz-alani/concord","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navaz-alani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-19T21:40:52.000Z","updated_at":"2021-01-08T18:37:12.000Z","dependencies_parsed_at":"2022-08-15T14:30:51.379Z","dependency_job_id":null,"html_url":"https://github.com/navaz-alani/concord","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/navaz-alani/concord","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navaz-alani%2Fconcord","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navaz-alani%2Fconcord/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navaz-alani%2Fconcord/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navaz-alani%2Fconcord/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navaz-alani","download_url":"https://codeload.github.com/navaz-alani/concord/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navaz-alani%2Fconcord/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28779010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T11:46:04.308Z","status":"ssl_error","status_checked_at":"2026-01-26T11:46:02.664Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-layer-protocol","concord","concord-packet-protocol","golang-library","packets","udp"],"created_at":"2026-01-26T13:11:29.520Z","updated_at":"2026-01-26T13:11:30.266Z","avatar_url":"https://github.com/navaz-alani.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Concord Packet Protocol (CPP)\n\nThis document provides the definition of the Concord Packet Protocol (henceforth\nreferred to as CPP, or \"the Protocol\").\n\n__NOTE__: [This GitHub Repository](https://github.com/navaz-alani/concord)\nprovides an implementation of the Protocol, currently only for Golang. However,\nthe protocol is language agnostic and can therefore be implemented in multiple\nlanguages. The Protocol attempts to be relatively simple and easily\nimplementable in multiple languages. Furthermore, CPP's definition is such that\napplications may easily create their own packet types, for example for\nefficiency purposes.\n\n## Introduction\n\nCPP is an application layer protocol, with an interface similar to HTTP. CPP,\nlike HTTP, is a client-server protocol and it defines a Packet entity and how\nservers should process these packets.\n\n## Packets\n\nThe centerpiece of CPP is the Packet entity. It is the object which is\ntransmitted between clients and servers. Packets have two main sections/parts:\n\n* Metadata - this is (not exclusively) Protocol-related data. Metadata\n  exists in a \"map\" form i.e. in string key-value pairs. The Protocol defines\n  certain metadata keys which are useful.\n* Data - this is the section of the packet which is for use by the application.\n  There is no specification on the structure of this data section and\n  applications may use this section in any way.\n\nHere are the Protocol specified packet metadata keys:\n\n* `KeyTarget` is the string `\"_tgt\"`. It specifies the server target invoked by\n  the packet (explained in the next section).\n* `KeySvrStatus` is the string `\"_stat\"`. This is on response packets from a\n  server, indicating the status of the request. If this metadata key is defined,\n  it possibly has the value \"-1\", which indicates a server side processing\n  error.\n* `KeySvrMsg` is the string `\"_msg\"`. It holds an server error message, when\n  defined.\n* `KeyRef` is the string `\"_ref\"`. It is a unique identifier sent by a client.\n  When this key is defined on a packet by a client, the server ensures that it\n  is present on the response packet.\n\nThere is also a server function called \"relay\" which is used to send packets to\nother addresses. This requires metadata keys and they are:\n\n* `KeyRelayFrom` is the string `\"_relay_src\"`. It specifies the relayer's\n  address.\n* `KeyRelayTo` is the string `\"_relay_dst\"`. It specifies the address to which\n  the packet is to be relayed.\n\n## Servers\n\nServers are the next key component in CPP. A CPP server does two things:\nprocesses packets sent by clients and (possibly) sends responses to these\npackets. Servers in CPP define \"targets\" to which clients can direct packets\nfor processing (this is somewhat analogous to HTTP endpoints). Formally, a\n\"target\" is a sequence of callbacks which operate on a packet under a shared\ncontext. This will be exponded on more in the next subsection.\n\nWe now focus on how servers process packets.\n\n### Server Side Processing\n\nThere are two stages of server side packet processing: the data and the packet\nstages. In each of these stages, processing is similar and is based on the idea\nof pipelines. The data stage uses \"Data Pipelines\" while the packet stage uses\n\"Packet Pipelines\", both of which are conceptually exactly the same. A\nData/Packet pipeline is a series of callbacks which operate on a particular\npiece of data (binary/packet respectively) under a shared context. The \"shared\ncontext\" for processing mentioned here is used by the pipeline to modify the\nbehaviour of the server through status codes. Here are the currently defined\ncontext status codes:\n\n* `CodeContinue` means \"continue pipeline execution\". It indicates that the\n  current pipeline stage succeeded.\n* `CodeStopError` means \"stop pipeline execution and return error\". It indicates\n  that the current pipeline stage encountered an irrecoverable error and the\n  processing cannot continue. The server should then respond with an error\n  message (which is also contained in the context).\n* `CodeStopCloseSend` means \"stop pipeline execution and continue with\n  processing\". It indicates that the current pipeline should be prematurely\n  stopped, but not due to an error.\n* `CodeStopNoop` means \"stop pipeline execution and do nothing\". It indicates\n  that the current pipeline should be prematurely stopped (possibly due to an\n  error) and server should not do anything else related to the data/packet being\n  processed. So if the pipeline is a Packet Pipeline, this code would force the\n  server to stop processing the packet without sending a response to the sender.\n* `CodeRelay` means \"stop pipeline execution and send the response to another\n  address\". It indicates that pipeline execution should be stopped and the\n  response should be sent to another address, specified in the response packet's\n  metadata (under the server relay keys).\n\nThe notion of these Data/Packet pipelines is what makes CPP servers easily\nextensible. An example of this is the Cryptographic extension which easily\nprovides the ability to secure client-server communication by installing key\nexchange targets on the server and encryption/decryption stages in the Data\npipeline.\n\n#### Data Processing Stage\n\n__NOTE__: In the following, \"the wire\" refers to the underlying connection, for\nexample a UDP socket/TCP connection.\n\nThe data stage is more low-level and allows for operations on the binary\nrepresentation of a packet. This stage occurs at two points: when the packet's\nbinary data is read off the wire and before it is written to the wire.\n\nA great application of this is transport layer encryption (analogous to TLS, but\nadmittedly much simpler). The Cryptographic extension, which is part of the\nProtocol specification does exactly this - it will be discussed after server\nsize processing stages have been discussed.\n\nA server has exactly two Data pipelines, `DATA_IN` and `DATA_OUT`, which are\nused for all data read and written to the wire respectively (note that these\nnames do not matter in server implementations as they will be defined as\nconstants). Data pipelines operate on the binary data and return a modified form\nof that data for the next stage in the pipeline to operate on. After the Data\npipeline execution has been compelted, the final binary data will be decoded\ninto a packet (in the case of the `DATA_IN` pipeline) or written to the wire (in\nthe case of the `DATA_OUT` pipeline). Of course, the context status codes can be\nused to modify the server's behaviour.\n\n#### Packet Processing Stage\n\nAfter the `DATA_IN` pipeline execution has completed successfully, the server\nthen decodes the binary data from the pipeline into a packet, which will be\noperated on under a Packet pipeline. However, there are cases where this\npipeline execution may not succeeed:\n\n* If the decoding of the binary data into a packet fails\n* If the target specified by the packet is invalid\n\nThe second of these points is important. Every decoded packet needs to specify\nthe Packet pipeline which operates on it. This is where server targets come in.\nA packet's metadata contains the server target that it invokes - this is under\nthe `KeyTarget` metadata key. A server contains Packet pipelines mapped to\ntargets and when a packet has been decoded, it is operated on by the pipeine\ncorresponding to its target. The Packet pipeline is a bit different from the\nData pipeline in that each packet pipeline stage appends data/sets metadata on\nthe response packet, rather than returning a response packet. After the Packet\npipeline is executed, the response packet is then converted to binary, passed\nthrough the `DATA_OUT` pipeline and sent over the wire. The recipient of the\nresponse packet is not always the sender of the packet. If the application\ndecides that the response should be sent to another address, it can specify so\nin the Packet pipeline context status using `CodeRelay` and then supply the\nrelay address in the response packet's `KeyRelayTo` metadata key (if `CodeRelay`\nis supplied and no address is provided in `KeyRelayTo`, the behaviour of the\nserver is indistinguishable from the case where the context code `CodeStopNoop`\nis supplied).\n\n\n### Extending Server Capabilities (and the `Crypto` Extension)\n\nUsing the Data/Packet pipeline architecture, extensions to servers are easy to\ncraft. For example, the `Crypto` extension is a Protocol specified server\nextension (which also has client handles). It aims to make two things possible -\ntransport layer encryption and end-to-end packet data encryption (which makes\nsense in packet relay cases).\n\n__Crypto Specs__: Currently, the `Crypto` extension uses Elliptic Curve Diffie\nHellman (ECDH) for secret key generation, using the NIST-P256 elliptic curve\nparameters. Encryption is then performed using the secret key and AES.\n\nThe `Crypto` extension firstly maintains a list of public keys of clients which\nhave performed a key-exchange with the server. To make the key-exchange\npossible, the extension installs two key-exchange targets onto the server:\n\n* Firstly, there is the `TargetKeyExchangeServer` target (which is the string\n  `\"crypto.kex-cs\"`). This target expects the client's public key in JSON\n  format (conatining only the `(x,y)` point on the NIST-P256 curve). Here is the\n  format for the public key used by the `Crypto` extension:\n  ```JSON\n  { X: \"\u003cx-point\u003e\", Y: \"\u003cy-point\u003e\" }\n  ```\n  The server will then respond with its public key in the same format. A shared\n  key is then established using ECDH and all further communication is AES\n  encrypted using that shared key.\n* Secondly, there is a `TargetKeyExchangeClient` target (which is the string\n  `\"crypto.kex-cc\"`). This target expects the IP address of the client whose key\n  to obtain, in JSON format. Here is the format for the request:\n  ```JSON\n  { ip: \"\u003cother-ip\u003e\" }\n  ```\n  If the other client has not performed a key-exchange with the server or the\n  packet data failed to decode, the response packet contains an error message\n  specifying this. Otherwise, the response packet contains the public key (in\n  the previously specified format) of the other client. This key is used to\n  generate a secret shared key with the other client using ECDH. The `Crypto`\n  extension provides clients functions for end-to-end encrypting packet data for\n  packets destined to the other client, using this shared key. Then other client\n  also needs to obtain the public key of the client before they can decode\n  end-to-end encrypted packets relayed by the client.\n\nOn the server, the `Crypto` extension installs callbacks onto the `DATA_IN` and\n`DATA_OUT` pipelines to perform transport layer encryption/decryption\nrespectively if the sender/recipient respectively has been key-exchanged with.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavaz-alani%2Fconcord","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavaz-alani%2Fconcord","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavaz-alani%2Fconcord/lists"}