A DNP3 parser implementation in Hammer
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
include
samples
src
test
.gitignore
CMakeLists.txt
README
TODO
crc.c
dissect.c
leakcheck-suppressions

README

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.