Assignment Quick Links

  1. Overview
  2. Build It
  3. Break It
    1. Infer details
  4. Fix It
  5. Oracle
  6. Program specifications
    1. logappend
    2. logread
  7. Grading
  8. Scoring
  9. Rules

Build It

Getting Started

All implementations must be written in C. You will find some starter code in the Canvas Files. Feel free to make whatever changes you feel are necessary, as long as you stay within the rules. You don’t need to feel obliged to keep the starter code the way we gave it to you; it’s just there as one suggested way of organizing your code.

Program Specifications

Your team will design a log format and implement both logappend and logread to use it. Each program’s description is linked below (and in the Table of Contents).

Look at the page of examples for examples of using the logappend and logread tools together. Both tools must function correctly without Internet access. Both must operate on their original thread, meaning you cannot use functions like fork or execv. Similarly, you must not use the system call to run commands in the shell.

As with most English-level specifications, you may find ambiguities or underspecified corner cases in the specs above. In all such cases, the Oracle reference implementation (described below) is the definitive authority. In other words, your implementation is expected to match the Oracle’s behavior in every particular.

Oracle

An oracle reference implementation is provided to demonstrate the expected output of a series of commands run on logread and logappend. You may run the reference implementation by submitting a query to the “Oracle” assignment in AutoLab. This is not a real assignment and will not be graded. It is only there to provide easy access to the reference implementation.

The oracle assignment expects you to submit a JSON file. Please check the formatting of your JSON file before submitting (for instance, by using https://jsonlint.com/ to ensure that your submission is a valid JSON file). The contents should be an array for commands (written as strings), along with an optional batch file. Here is an example:

{
  "commands": [
    {
      "program": "logappend",
      "args": ["-K", "secret", "-T", "1", "-G", "GERDA", "-A", "log"]
    },
    {
      "program": "logappend",
      "args": ["-K", "secret", "-T", "2", "-G", "GERDA", "-A", "-R", "16", "log"]
    },
    {
      "program": "logread",
      "args": [ "-K", "secret", "-R", "-G", "GERDA", "log"]
    }
  ],
  "batch": "LUsgc2VjcmV0IC1FIGVtcGwgLUEgbG9nCg=="
}

If you include the “batch” key, the value must be a base64 encoded batch file. To encode a file, most Unix/Linux/Mac systems include the base64 command, which you can run as:

base64 -i input_file -o output_file

The value of the “batch” key will be base64 decoded and placed in a file called batch when tests are executed. To run this batch file, you still need to specify a logappend command referring to the file using the -B flag, when specifying your list of command entries.

After submitting your query, you can then look at AutoLab’s output to see what the oracle produces.

Oracle Bugs If you believe you have found a genuine bug in the oracle’s implementation, do not exploit it to gain points in the Break It phase. This will anger the course staff, which is always unwise. Instead, please report the bug via Piazza to the course staff. Each confirmed report will be worth an additional 25 contest points.

Security Model

The system as a whole must guarantee the privacy and integrity of the log in the presence of an adversary who does not know the authentication token. This token is used by both the logappend and logread tools, specified on the command line. Without knowledge of the token an attacker should not be able to:

Deliverables

The Build It assignment on AutoLab expects you to upload a tar archive of your implementation files (please do not upload any binaries or other intermediate files). To create such a submission, if you have used the Makefile provided with the starter code, in the directory containing your implementation’s files, simply run:

make handin

To score a submission, AutoLab will run tar xf handin.tar followed by make. The only requirements on make are that it must function without internet connectivity, and it must build from source (committing binaries is not acceptable).

Once make finishes, logread and logappend should be executable files within the build directory. An automated system will invoke them with a variety of options and measure their responses. The executables must be able to be run from any working directory.

Each test must complete within at most 60 seconds, and the entire build plus test process must take less than 7 minutes or your submission will time out, so try to avoid any obvious inefficiencies in your build and implementation.

Your code will be run within a Docker container on the server. To help test your code (to ensure that you have the right versions of libraries etc.), you can use this Dockerfile. Instructions for how to use it are within the same file. Docker CE can be installed on your system by following the instructions here.

Checkpoint

To ensure you’re making progress on the assignment, we will have a checkpoint deadline. By this deadline, your team must pass at least one test in AutoLab. We recommend the first test, which closely resembles the example given above for the Oracle. You can then continue to refine your system until it’s time for the final submission described below.

Final Submission

In addition to submitting your code via AutoLab, you should submit a design document (PDF) to Gradescope. In the design document you should:

Grading

Build It will be worth 100 points