Skip to content

Home

Jump to bottom
Mark Bednarczyk edited this page Oct 10, 2024 · 7 revisions

Welcome to the core-protocols module's user guide!

The core-protocols module provides protocol level support to jNetWorks SDK and jNetPcap SDK libraries.

Table of Contents

  • 1. Home
    • Table Of Contents
    • Introduction
      • About Runtime API
      • About Protocol API
  • 2. Getting Started
    • Installation
      • Prerequisites
  • 3. Working with Protocol API
    • What are protocols packs?
    • Core protocol pack
    • Packet and Header API
      • Builtin Frame and Payload headers
    • Extended protocol services and APIs
    • Descriptor types
  • 3.1 Ethernet Protocol
  • 3.2 IEEE802.2 LLC/SNAP Protocol

Introduction

The core-protocols module is a prerequisite for all other modules that use protocol level APIs such as jnetpcap and jnetworks Java libraries. The central part of the protocol level API are these primitives such as Packet, Header, MetaPacket, MetaHeader and MetaField objects which are provided by this module. These primitives encapsulate low level state that is generated by various dissectors and reassemblers through a variety of most efficient methods available. Some of this low level protocol level state can be provided by hardware or native C library implementation. The default however is that all of the publically exported API functionality, is always availble in pure Java implementation, not requiring any specialized hardware or native libraries.

Native C module

Modlue: core-protocols-native

The native module core-protocols-native provides C library and headers that loosely mimics that Java core-protocols module's API. The C library is standalone and does not require the Java counterpart to function and visa versa.

The Java library discovers, at runtime, if native C counter part is available and by default will utilize native implementation for certain parts of performing API work. The API can be configured to work in pure java, pure native or hybrid mode which is the default.

About Runtime API

There are two important parts to the runtime API. There is a publically visible API that provides some useful and common classes and constants such as MemoryUnit for working memory storage or TimestampUnit for various native timestamps encodings (think TimeUnit enum table).

For the other part there is a large private API exported to other modules that provides vital support for native memory bindigns, binary layouts which are more fine granular that JDK's MemoryLayout in foreign function API and many more. Large part of the API is exported as private due to the fact that its not really part of protocol pack mission but more of current implementation of the public protocol API.

About Protocol API

Package: com.slytechs.jnet.protocol

The protocol API in core-protocols module provides base classes, interfaces and thousands of various protocol related constants that are utilized by all protocol level modules every where.

About Protocol Packs

Package: com.slytechs.jnet.protocol.pack

A protocol pack concept is introduced to break up groups of protocols into separate modules, but Packs provide APIs for managing those separate modules by providing services such as query, loading of protocol packs, unique IDs accross packs, extendable dissectors exported to other packs and lastly high level protocol services.

Try System.out.println(Pack.listAllDeclaredPacks()) to see a list of all defined protocol packs and their current discovery status.

Pack [name="core"           ( 0/0x000), loaded=71 definitions]
Pack [name="options"        ( 1/0x040), loaded=46 definitions]
Pack [name="media"          ( 2/0x080), <pack not loaded>]
Pack [name="web"            ( 3/0x0C0), loaded= 3 definitions]
Pack [name="telco"          ( 4/0x100), <pack not loaded>]
Pack [name="lte"            ( 5/0x140), <pack not loaded>]
Pack [name="database"       ( 6/0x180), <pack not loaded>]
Pack [name="microsoft"      ( 7/0x1C0), <pack not loaded>]
Pack [name="authentication" ( 8/0x200), <pack not loaded>]

Note! the "options" protocol pack is "virtual" and its values are actually defined within individual protocols (ie. Ip4Option class). It is however treated like a normal protocol pack from pack management API point of view.

About protocol package

Package: com.slytechs.jnet.protocol

The protocol package provides high level base classes and interface for protocol support.

When packets are captured, or read from capture files they are presented to the library in raw form which typically is made up of a memory segment which contains a low level descriptor which describes the contents of another memory segment which contains the packet data. The Packet classes encapsulates the raw state and provides a high level API for working with captured packets.

Since packets are made up of encapsulating protocol layers, each headed by a header containing specific protocol data, a Header class is introduced to provide access to the contents within the packet. The extra data for the high level Header object to operate is provided in extended descriptors provided by this and other modules. Fruther more Header is just a base class for more specific protocol level headers such as Ethernet which exposes ethernet header's values such as destination/source mac addresses and type fields and so on.

There are other concept level interfaces and classes provided for working with data streams, datagram fragmentation, analysis and so on.

Core protocol API

Package: com.slytechs.jnet.protocol.pack.core

The actual header definitions for core-protocol module reside in this package. There is long list of protocol headers, constants and supporting interfaces for these protocols.

The most important of these header definitions are Ethernet, Ip4, Ip6, Tcp and Udp classes. There are many more protocol header's defined such as Stp, Vlan and so on, so that you may properly work most network traffic captured.

The core protocol pack also provides interfaces and classes for IPF (ip fragmentation). The core pack does not actually implement the IPF functionality itself only the common API for using the IPF generated or tracked packets. The implementation is provided by jnetpcap and jnetworks libraries and is system configuration dependent. For example jNetWorks when paired with hardware accelerator cards will use a vastly different implementation to perform IPF than lets say a libpcap based one. As before, all discoverable at runtime and the best implementation is utilized by default or configured through the public API.

Clone this wiki locally