A DNP3 parser implementation in Hammer

• Uses the Hammer parser combinator library. https://github.com/UpstandingHackers/hammer

• Currently requires a custom version of Hammer: https://github.com/pesco/hammer/ (master branch)

  This includes:

  • 'h_aligned', to check for byte-alignment (from branch 'h_aligned')
  • A temporary patch to 'h_put_value' allowing it to overwrite a previously-stored value. This is a stop-gap workaround until we get symbol scoping.

• Uses cmake[https://cmake.org/] to build. The 'build' directory is in '.gitignore'.

  mkdir build; cd build cmake .. make

• Run './dnp3-tests' to execute the unit tests (uses the GLib test framework).

• The './dissect' utility is an example application that accepts DNP3 traffic (as a stream of raw link-layer frames) on stdin and prints it in human- readable form. The 'samples/' directory contains some sample inputs in hexadecimal notation. Example usage:

  xxd -r -p ../samples/read.hex | ./dissect

  The '-f' option uses the same traffic recognizer to sanitize its input:

  cat ../samples/*.hex | xxd -r -p | ./dissect -f | ./dissect

NOTES:

Z) A couple of bigger and a lot of smaller things are still TODO.

A) This implementation is based on IEEE Std. 1815-2012 and notably AN2013-004b.

B) This is an application-oriented implementation of DNP3. Nonconforming input is discarded immediately and not processed. The focus is on recognizing expected input as opposed to inspecting erroneous input.

In the same vein, semantic representation is relatively high-level and does
not insist on mirroring packet structure where details are irrelevant to a
user of the protocol.

C) Reserved bits are required to be 0 unless the standard explicitly allows them to be ignored.

D) Deprecated and obsolete parts of the protocol are not supported unless required. Specifically:

 - The INITIALIZE_DATA function code is rejected with a FUNC_NOT_SUPP
   parse error.
 - The SAVE_CONFIG function code is rejected with FUNC_NOT_SUPP.
 - The 'rollover' flag on counter objects is ignored and its value not
   exposed to the user.
 - Delta counters are rejected with an OBJ_UNKNOWN parse error.

 - The 'queue' flag on CROB objects _is_ accepted so an implementation
   can reject only the offending object in a request containing multiple
   commands.

E) Although not explicitly disallowed by the specification, there is never a case where a header with a count of 0 objects is semantically meaningful. Therefore, such messages are rejected.

LICENSE:

Copyright (c) 2014-2016 Sven M. Hallberg and contributors

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.