A Simple Protocol

Submission Deadline:

The goals of this assignment are to:

  1. Enroll in the course project server
  2. Implement a simple network protocol

Project Server Account

Assignment solutions will be submitted to a git repository hosted on a course project server. To obtain access to this server, post an SSH public key in a DM to @wkr on slack. You will use this keypair to authenticate when submitting solutions.

Points will be deducted from your grade if you lose access to your account! Don’t lose your keys!

Network Security Transport Protocol (NSTP)

To get your feet wet, you will be implementing a simple binary protocol for a key-value store. The protocol begins with an initialization phase where the client and server exchange “Hello” messages. Then, request/response message pairs can be exchanged. An overview of this protocol is shown below.

ClientServerInitialization phaseClientHelloServerHelloSession initialized, any of the following message pairs are legalLoadRequestLoadResponseStoreRequestStoreResponsePingRequestPingResponseAny message can be responded to with an error messageStoreRequestErrorMessage

ClientHello

0   1   2   3      5     L(U)+5
+---+---+---+------+---~---+
| T | M | N | L(U) |   U   |
+---+---+---+------+---~---+
T u8 message tag = 0
M u8 major version = 1
N u8 minor version
L(U) u16 length of user agent string
U UTF-8 user agent string

A ClientHello message indicates the protocol version and identifies the user agent to the server. Compliant servers must reject clients that do not report their version as 1.x.

ServerHello

0   1   2   3      5     L(U)+5
+---+---+---+------+---~---+
| T | M | N | L(U) |   U   |
+---+---+---+------+---~---+
T u8 message tag = 1
M u8 major version = 1
N u8 minor version
L(U) u16 length of user agent string
U UTF-8 user agent string

A ServerHello message identifies the server to the client. Compliant clients must reject servers that do not report their version as 1.x.

ErrorMessage

0   1      3     L(M)+3
+---+------+---~---+
| T | L(M) |   M   |
+---+------+---~---+
T u8 message tag = 2
L(U) u16 length of message
U UTF-8 error message

Error messages can be returned from any request and immediately terminate a session.

PingRequest

0   1      3   L(D)+3  L(D)+4
+---+------+---~---+---+
| T | L(D) |   D   | A |
+---+------+---~---+---+
T u8 message tag = 3
L(D) u16 length of data
D [u8] data
A u8 hash algorithm (0=identity, 1=SHA256, 2=SHA512)

A PingRequest includes a data payload and hash algorithm identifier. Compliant servers are expected to return a PingResponse message that contains the requested hash of the provided data.

PingResponse

0   1      3    L(H)+3
+---+------+---~---+
| T | L(H) |   H   |
+---+------+---~---+
T u8 message tag = 4
L(H) u16 length of hash
H [u8] hash

A PingResponse returns a requested hash value to a client.

LoadRequest

0   1      3    L(K)+3
+---+------+---~---+
| T | L(K) |   K   |
+---+------+---~---+
T u8 message tag = 5
L(K) u16 length of key
K UTF-8 key

A LoadRequest message contains a UTF-8-encoded key for a resource assumed to exist on the server.

LoadResponse

0   1      3    L(V)+3
+---+------+---~---+
| T | L(V) |   V   |
+---+------+---~---+
T u8 message tag = 6
L(V) u16 length of value
V [u8] value

A LoadResponse message contains a value corresponding to a requested key. If the key does not exist, a compliant server must return a zero-length value.

StoreRequest

0   1      3    L(K)+3  L(K)+5  L(K)+L(V)+5
+---+------+---~---+------+---~---+
| T | L(K) |   K   | L(V) |   V   |
+---+------+---~---+------+---~---+
T u8 message tag = 7
L(K) u16 length of key
K UTF-8 key
L(V) u16 length of value
V [u8] value

A StoreRequest message contains a UTF-8-encoded key and value to store on the server.

StoreResponse

0   1      3   L(H)+3 L(H)+4
+---+------+---~---+---+
| T | L(H) |   H   | A |
+---+------+---~---+---+
T u8 message tag = 8
L(H) u16 length of hash
H [u8] hash
A u8 hash algorithm (0=identity, 1=SHA256, 2=SHA512)

A StoreResponse message contains a hash of the value stored along with the algorithm used to compute the hash.

Evaluation Criteria

Your protocol implementation must consist of a NSTP server that will be evaluated on its adherence to the protocol specification outlined above. In addition, your server implementation:

  • must be able to concurrently service clients up to the resources available to it
  • must be resistant to application-level DoS due to unresponsive clients by dropping connections that are inactive for more than 10 seconds

An image containing a partial test suite can be pulled from gcr.io/netsec/assignments/00-simple_protocol-tests. Running this image with a target host and port as arugments will execute the test suite, the results of which will be printed to stdout. For example, to test a server running on localhost port 22300, run the image like so:

$ docker run -it --rm gcr.io/netsec/assignments/00-simple_protocol-tests localhost 22300

Your submission must contain a Dockerfile in the repository root that builds a container containing your server when the following sequence of commands is performed:

$ git clone ${your_repo_url} submission
$ cd submission
$ docker build -t submission .

Your server should be invoked by default when running the resulting container image (use one of the CMD or ENTRYPOINT Dockerfile directives). It should service clients on 0.0.0.0:22300. Grading of your solution will take place using an automated test suite that will expect your server to be reachable on that port when running your image as follows:

$ docker run -d -p 22300:22300 submission

Submission Instructions

Push the source code for your server to a git repository on the project server at ~/assignments/00-simple_protocol. For example:

# On the project server
$ mkdir -p ~/assignments/00-simple_protocol
$ cd ~/assignments/00-simple_protocol
$ git init --bare

# On your development machine
$ cd ${repo_path}
$ git remote add submission ${user}@netsec.seclab.ccs.neu.edu:assignments/00-simple_protocol
$ git push -u submission --all
$ git push -u submission --tags

You may tag the commit you wish to be considered for grading with the tag solution; otherwise, the latest commit on master will be treated as such.