From 3fc15ebb45216c62a917d8baf3335951c3658c07 Mon Sep 17 00:00:00 2001 From: "Franklin \"Snaipe\" Mathieu" Date: Tue, 1 Nov 2016 21:41:06 +0100 Subject: [PATCH] docs: Added initial docs --- doc/conf.py | 294 +++++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 10 ++ doc/setup.rst | 45 +++++++ doc/specifiers.rst | 130 ++++++++++++++++++++ doc/starter.rst | 60 +++++++++ 5 files changed, 539 insertions(+) create mode 100644 doc/conf.py create mode 100644 doc/index.rst create mode 100644 doc/setup.rst create mode 100644 doc/specifiers.rst create mode 100644 doc/starter.rst diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..640d947 --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,294 @@ +# -*- coding: utf-8 -*- +import sys +import os +import re + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) +sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), "_ext"))) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', +] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'wssdl' +copyright = u'2016, Franklin "Snaipe" Mathieu' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The full version, including alpha/beta/rc tags. +release = '0.1.1' +# The short X.Y version. +version = re.search(r'\d+\.\d+', release).group(0) + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build', 'html', 'doctrees'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'wssdl_doc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'wssdl.tex', u'wssdl documentation', + u'Franklin "Snaipe" Mathieu', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'wssdl', u'wssdl documentation', + [u'Franklin "Snaipe" Mathieu'], 3) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'wssdl', u'wssdl documentation', + u'wssdl', 'wssdl', '', + ''), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + + +# -- Options for Epub output --------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = u'wssdl' +epub_author = u'Franklin "Snaipe" Mathieu' +epub_publisher = u'Franklin "Snaipe" Mathieu' +epub_copyright = copyright + +# The language of the text. It defaults to the language option +# or en if the language is not set. +#epub_language = '' + +# The scheme of the identifier. Typical schemes are ISBN or URL. +#epub_scheme = '' + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +#epub_identifier = '' + +# A unique identification for the text. +#epub_uid = '' + +# A tuple containing the cover image and cover page html template filenames. +#epub_cover = () + +# HTML files that should be inserted before the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_pre_files = [] + +# HTML files shat should be inserted after the pages created by sphinx. +# The format is a list of tuples containing the path and title. +#epub_post_files = [] + +# A list of files that should not be packed into the epub file. +#epub_exclude_files = [] + +# The depth of the table of contents in toc.ncx. +#epub_tocdepth = 3 + +# Allow duplicate toc entries. +#epub_tocdup = True + +# Highlight PHP without starting `_, +and put it in one of Wireshark's plugin paths. + +.. note:: + + Usually, Wireshark loads plugins from ``~/.config/wireshark/plugins`` and + ``/usr/lib/wireshark/plugins/``. You can check what directories + Wireshark checks by going into Help -> About -> Folders. + +From source +~~~~~~~~~~~ + +Building from source requires as an additional prerequisite luarocks and the +luafilesystem module to be installed. + +To boostrap the library in one coalesced file, and install it to +``~/.config/wireshark/plugins``, run from the project directory: + +.. code-block:: bash + + $ make install + +If you prefer to install it in another location, set the variable ``WS_PLUGIN_DIR``. +For instance, to install wssdl in the system plugin path for Wireshark 2.2.0: + +.. code-block:: bash + + $ sudo make WS_PLUGIN_DIR=/usr/lib/wireshark/plugins/2.2.0 install diff --git a/doc/specifiers.rst b/doc/specifiers.rst new file mode 100644 index 0000000..7087c1b --- /dev/null +++ b/doc/specifiers.rst @@ -0,0 +1,130 @@ +.. _specifiers: + +Specifier reference +=================== + +Primitive Field Types +--------------------- + +=========== ==================================================================== +Type Description +=========== ==================================================================== +u8() Unsigned 8-bit integer. +----------- -------------------------------------------------------------------- +u16() Unsigned 16-bit integer. +----------- -------------------------------------------------------------------- +u24() Unsigned 24-bit integer. +----------- -------------------------------------------------------------------- +u32() Unsigned 32-bit integer. +----------- -------------------------------------------------------------------- +u64() Unsigned 64-bit integer. +----------- -------------------------------------------------------------------- +i8() Signed 8-bit integer. +----------- -------------------------------------------------------------------- +i16() Signed 16-bit integer. +----------- -------------------------------------------------------------------- +i24() Signed 24-bit integer. +----------- -------------------------------------------------------------------- +i32() Signed 32-bit integer. +----------- -------------------------------------------------------------------- +i64() Signed 64-bit integer. +----------- -------------------------------------------------------------------- +int(N) Unsigned ``N``-bit integer. If ``N`` isn't specified, the size of + the field becomes the remaining payload size. + ``N`` cannot be larger than 64-bits. +----------- -------------------------------------------------------------------- +uint(N) Unsigned ``N``-bit integer. If ``N`` isn't specified, the size of + the field becomes the remaining payload size. + ``N`` cannot be larger than 64-bits. +----------- -------------------------------------------------------------------- +f32() 32-bit floating-point value. +----------- -------------------------------------------------------------------- +f64() 64-bit floating-point value. +----------- -------------------------------------------------------------------- +utf8(N) UTF8-encoded string w/ a length of ``N`` code units. If ``N`` + isn't specified, the size of the field becomes the remaining + payload size. + If used, the field must be aligned on an octet boundary. +----------- -------------------------------------------------------------------- +utf8z() Null-terminated UTF8-encoded string. + If used, the field must be aligned on an octet boundary. +----------- -------------------------------------------------------------------- +utf16(N) UTF16-encoded string w/ a length of ``N`` code units. If ``N`` + isn't specified, the size of the field becomes the remaining + payload size. + If used, the field must be aligned on an octet boundary. +----------- -------------------------------------------------------------------- +utf16z() Null-terminated UTF16-encoded string. + If used, the field must be aligned on an octet boundary. +----------- -------------------------------------------------------------------- +bytes(N) Byte buffer with a size of ``N`` octets. If ``N`` isn't specified, + the size of the field becomes the remaining payload size. + If used, the field must be aligned on an octet boundary. +----------- -------------------------------------------------------------------- +bits(N) Bits buffer with a size of ``N`` bits. + ``N`` cannot be larger than 64-bits. +----------- -------------------------------------------------------------------- +bool(N) Boolean value with a size of ``N`` bits. If ``N`` isn't specified + the size of this field is 1 bit. + A field value of zero means False, while non-zero means True. +----------- -------------------------------------------------------------------- +bit() A single bit. +----------- -------------------------------------------------------------------- +ipv4() IPv4 address. + If used, the field must be aligned on an octet boundary. +----------- -------------------------------------------------------------------- +ipv6() IPv6 address. + If used, the field must be aligned on an octet boundary. +=========== ==================================================================== + +Special Field Types +------------------- + +User Types +~~~~~~~~~~ + +Any variable declared with ``wssdl.packet`` can be used as a field type. + +Payload Type +~~~~~~~~~~~~ + +The special payload type is used for packets that contains data that needs to +be subdissected by another registered dissector. The specifier comes in three +prototypes: + +* ``payload { }`` + +* ``payload { , }`` + +* ``payload { , , }`` + +Where ```` is the field that should be used as the value to lookup the +dissector table entry, ```` is the dissector table identifier, and +```` is the size of the field in octets. + +If ```` is nil or unspecified, then the dissector table identifier becomes +``.``. + +If ```` is nil or unspecified, then the size of the field becomes the +remaining packet size. + +Other specifiers +---------------- + +================== ============================================================= +Type Description +================== ============================================================= +le() Parse the field as little-endian. The following types + support little-endian: u8, u16, u24, u32, u64, i8, i16, i24, + i32, i64, int, uint, f32, f64, utf16, utf16z, ipv4. +------------------ ------------------------------------------------------------- +dec() Use a decimal format for the integer field (default) +------------------ ------------------------------------------------------------- +hex() Use a hexadecimal format for the integer field +------------------ ------------------------------------------------------------- +oct() Use an octal format for the integer field +------------------ ------------------------------------------------------------- +name(str) Set the display name of the field to ``str``. +------------------ ------------------------------------------------------------- +description(str) Set the description of the field to ``str``. +================== ============================================================= diff --git a/doc/starter.rst b/doc/starter.rst new file mode 100644 index 0000000..b192258 --- /dev/null +++ b/doc/starter.rst @@ -0,0 +1,60 @@ +Getting started +=============== + +Packet definition +----------------- + +The ``packet`` function is used to define the structure of your packet. + +This function takes a sequence of comma/semicolon-separated fields, with each +field using the `` : (params) ... : specifierN(params)`` +syntax, where ```` is an lua identifier for the field that is unique +in the current definition scope; and where each ```` is a wssdl +specifier, one of which must be a field type. + +See :ref:`specifiers` for a complete list of specifiers. + +.. code-block:: lua + :name: Example + + local wssdl = require 'wssdl' + + my_pkt = wssdl.packet { + foo : u8(); + bar : i32(); + baz : utf8(256); + } + +Creating a protocol +------------------- + +A ``Proto`` object can be created by calling the ``proto(name, description)`` +method on the created packet type: + +.. code-block:: lua + + my_pkt = wssdl.packet { ... } + + proto = my_pkt:proto('proto_id', 'Some protocol') + +The protocol name and description are passed verbatim to wireshark and as such +**must** both be unique. + +Registering a dissector +----------------------- + +The ``dissect`` function can be used to register one or more protocols in their +relevant dissector tables. + +This function takes a sequence of dissector table mappings. Each mapping +follows the following syntax: ``: { }``, where +```` is the identifier of the desired dissector table, ```` is either ``set`` or ``add`` (which holds the semantics of ``DissectorTable:set`` and ``DissectorTable:add`` respectively), and ```` are key/value entries where the key is the first parameter of ``set/add`` and the value is the proto object passed as second parameter. + +.. code-block:: lua + :name: Registering a TCP protocol on port 1234 + + wssdl.dissect { + tcp.proto:add { + [1234] = my_pkt:proto('proto_id', 'Some protocol') + } + }