Skip to content

Home

Jump to bottom
jchan005 edited this page Oct 21, 2017 · 15 revisions

Goal

Aker is an experimental module for selectively blocking MAC addresses based on a succinct schedule in MsgPack.

The primary goal for Aker is to accept a weekly schedule with the optional exceptions added to the schedule so that there is very little interaction between Aker and it's controlling agent. Aker will ultimately call another program (passed by command line arguments) with a list of MAC addresses to block at the time they should be blocked - replacing any previously existing schedule.

Ultimately Aker will choose either the weekly-schedule or the absolute-schedule to apply for any defined times. If both define a window that overlap, the absolute-schedule is chosen. Aker is designed to do what it's told & not to try to merge schedules.

Schedule Schema

Update coming with shorter names

Below is an example schema represented in JSON for clarity, then MsgPack for accuracy.

  • weekly-schedule - optional - This is the section of the document that describes the recurring weekly schedule.
  • time - required - The number of seconds since the most recent Sunday midnight defining the starting time to block this list of MAC addresses. 12:00:01 AM is time = 1.
  • indexes - required - The list of indexes into the macs array to apply during this window of time.
  • macs - optional - The array with the full list of MAC addresses that can be blocked.
  • absolute-schedule - optional - This is the section of the document that describes the window of time that replaces the normal weekly schedule. All times in the absolute schedule are considered contiguous and are required to fully express the schedule. At the point in time where the latest unix-time entry is encountered, this entry is applied and is in effect until the next scheduled event in the absolute-schedule will be triggered.
  • unix-time - required - The unix time (number of seconds since January 1, 1970) defining the starting time to block this list of MAC addresses. Additionally, the special value of 0 is allowed to indicate a time that has passed in order to accommodate slight clock differences between client and server.
{
    "weekly-schedule": [
        { "time": 10, "indexes": [0, 1, 3] },
        { "time": 20, "indexes": [0] },
        { "time": 30, "indexes": [] }
    ],

    "macs": [
        "11:22:33:44:55:aa",
        "22:33:44:55:66:bb",
        "33:44:55:66:77:cc",
        "44:55:66:77:88:dd"
    ],

    "absolute-schedule": [
        { "unix-time": 1508213527, "indexes": [0, 2] }
    ]
}

Hex MsgPack:

0x83, 0xAF, 0x77, 0x65,   0x65, 0x6B, 0x6C, 0x79,   0x2D, 0x73, 0x63, 0x68,
0x65, 0x64, 0x75, 0x6C,   0x65, 0x93, 0x82, 0xA4,   0x74, 0x69, 0x6D, 0x65,
0x0A, 0xA7, 0x69, 0x6E,   0x64, 0x65, 0x78, 0x65,   0x73, 0x93, 0x00, 0x01,
0x03, 0x82, 0xA4, 0x74,   0x69, 0x6D, 0x65, 0x14,   0xA7, 0x69, 0x6E, 0x64,
0x65, 0x78, 0x65, 0x73,   0x91, 0x00, 0x82, 0xA4,   0x74, 0x69, 0x6D, 0x65,
0x1E, 0xA7, 0x69, 0x6E,   0x64, 0x65, 0x78, 0x65,   0x73, 0x90, 0xA4, 0x6D,
0x61, 0x63, 0x73, 0x94,   0xB1, 0x31, 0x31, 0x3A,   0x32, 0x32, 0x3A, 0x33,
0x33, 0x3A, 0x34, 0x34,   0x3A, 0x35, 0x35, 0x3A,   0x61, 0x61, 0xB1, 0x32,
0x32, 0x3A, 0x33, 0x33,   0x3A, 0x34, 0x34, 0x3A,   0x35, 0x35, 0x3A, 0x36,
0x36, 0x3A, 0x62, 0x62,   0xB1, 0x33, 0x33, 0x3A,   0x34, 0x34, 0x3A, 0x35,
0x35, 0x3A, 0x36, 0x36,   0x3A, 0x37, 0x37, 0x3A,   0x63, 0x63, 0xB1, 0x34,
0x34, 0x3A, 0x35, 0x35,   0x3A, 0x36, 0x36, 0x3A,   0x37, 0x37, 0x3A, 0x38,
0x38, 0x3A, 0x64, 0x64,   0xB1, 0x61, 0x62, 0x73,   0x6F, 0x6C, 0x75, 0x74,
0x65, 0x2D, 0x73, 0x63,   0x68, 0x65, 0x64, 0x75,   0x6C, 0x65, 0x91, 0x82,
0xA9, 0x75, 0x6E, 0x69,   0x78, 0x2D, 0x74, 0x69,   0x6D, 0x65, 0xCE, 0x59,
0xE5, 0x83, 0x17, 0xA7,   0x69, 0x6E, 0x64, 0x65,   0x78, 0x65, 0x73, 0x92,
0x00, 0x02

Example Use Cases

A simple schedule on an account with two devices, the first of which is blocked on school nights from 9:00 PM to 9:00 AM.

{
    "macs": [
        "11:22:33:44:55:aa",
        "66:77:88:99:ee:ff"
    ],
    "weekly-schedule": [
        { "time" = 75600, "indexes" = [0] },
        { "time" = 118800, "indexes" = null },
        { "time" = 162000, "indexes" = [0] },
        { "time" = 205200, "indexes" = null },
        { "time" = 248400, "indexes" = [0] },
        { "time" = 291600, "indexes" = null },
        { "time" = 334800, "indexes" = [0] },
        { "time" = 378000, "indexes" = null },
        { "time" = 421200, "indexes" = [0] },
        { "time" = 464400, "indexes" = null }
    ]
}

A modification on the above account, with the intention of blocking access from now (January 1st, 2020, 6:00PM) for the duration of one hour. This occurs outside of the normal blocked window.

    // ...
    "absolute-schedule": [
        { "unix-time" = 1577901600, "indexes" = [0]},
        { "unix-time" = 1577905200, "indexes" = null}
    ]

A modification of the first example, with the intention of cancelling the blockage of any devices for the duration of the rest of the evening (January 1st, 2020, 6:00PM). This occurs outside of the normal blocked window. Note this simply replaces the next regularly scheduled event.

    // ...
    "absolute-schedule": [
        { "unix-time" = 1577912400, "indexes" = null}
    ]

A modification of the first example, with the intention of cancelling the blockage of any devices for the duration of the rest of the evening starting now (January 1st, 2020, 10:00PM). This occurs during an active block window. Note the ending event is required and coincides with a regularly scheduled event. This is necessary to determine the natural expiration of the absolute schedule when a value of 0 is used to indicate the immediate start of this schedule.

    // ...
    "absolute-schedule": [
        { "unix-time" = 0, "indexes" = null},
        { "unix-time" = 1577955600, "indexes" = null}
    ]

Helpful Things

If the weekly-schedule is not present, the default semantics are to not block any MAC addresses.

If the absolute-schedule is not present, there is no affect on the lists of blocked MAC addresses.

Don't want to hand encode from JSON to Msgpack? Neither do we! This tool makes the process simple & painless:

http://kawanet.github.io/msgpack-lite/

Clone this wiki locally