gommunityid

README

gommunityid

gommunityid is a Golang implementation of the Community ID flow hashing algorithm. Its API design was clearly and obviously inspired by the Python reference implementation.

Usage

package main

import (
	"fmt"
	"net"

	"github.com/satta/gommunityid"
)

func main() {
	// Get instance for version 1, seed 0
	cid, _ := gommunityid.GetCommunityIDByVersion(1, 0)

	// Obtain flow tuple. This can be done any way you like.
	ft := gommunityid.MakeFlowTuple(net.IPv4(1, 2, 3, 4), net.IPv4(5, 6, 7, 8), 9, 10, 1)

	// Calculate Base64-encoded value
	communityid := cid.CalcBase64(ft)
	fmt.Printf("%s\n", communityid)

	// Calculate hex-encoded value
	communityid = cid.CalcHex(ft)
	fmt.Printf("%s\n", communityid)

	// Calculate byte slice
	communityidByte := cid.Calc(ft)
	fmt.Printf("%v\n", communityidByte)
}

There is also a convenience function for parsing pcap files and automated FlowTuple generation for all supported protocols.

Command line interface

This package builds a simple command line tool to calculate IDs for pcaps:

$ ./gommunityid pcap
Usage: gommunityid pcap [options] <pcap-file>
  -seed uint
    	seed value (default 0)
  -version uint
    	Community ID version (default 1)
$ gommunityid pcap testdata/tcp.pcap
1071580904.891921 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80
1071580905.035577 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855
1071580905.035724 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80
1071580905.037333 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80
1071580905.181581 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855
1071580905.184528 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855
1071580905.184844 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80
1071580905.184698 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855
1071580905.184920 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80
1071580905.184736 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855
1071580905.203025 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 128.232.110.120 66.35.250.204 6 34855 80
1071580905.346457 | 1:LQU9qZlK+B5F3KDmev6m5PMibrg= | 66.35.250.204 128.232.110.120 6 80 34855

and explicit tuples:

$ gommunityid tuple
Usage: gommunityid tuple [options] <proto> <srcip> <dstip> <srcport> <dstport>
  -seed uint
    	seed value (default 0)
  -version uint
    	Community ID version (default 1)
$ gommunityid tuple 6 66.35.250.204 128.232.110.120 80 34855
1:LQU9qZlK+B5F3KDmev6m5PMibrg=

Author/Contact

Sascha Steinbiss

License

MIT

Documentation

Index

• Constants
• func GetICMPv4PortEquivalents(p1, p2 uint8) (uint16, uint16, bool)
• func GetICMPv6PortEquivalents(p1, p2 uint8) (uint16, uint16, bool)
• func PcapFlowTupleSource(file string) (<-chan PcapFlowTuple, error)
• type CommunityID
  • func GetCommunityIDByVersion(version uint, seed uint16) (CommunityID, error)
• type CommunityIDv1
  • func (cid CommunityIDv1) Calc(ft FlowTuple) []byte
  • func (cid CommunityIDv1) CalcBase64(ft FlowTuple) string
  • func (cid CommunityIDv1) CalcHex(ft FlowTuple) string
  • func (cid CommunityIDv1) Hash(ft FlowTuple) hash.Hash
  • func (cid CommunityIDv1) Render(h hash.Hash) []byte
  • func (cid CommunityIDv1) RenderBase64(h hash.Hash) string
  • func (cid CommunityIDv1) RenderHex(h hash.Hash) string
• type FlowTuple
  • func MakeFlowTuple(srcip, dstip net.IP, srcport, dstport uint16, proto uint8) FlowTuple
  • func MakeFlowTupleICMP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple
  • func MakeFlowTupleICMP6(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple
  • func MakeFlowTupleSCTP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple
  • func MakeFlowTupleTCP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple
  • func MakeFlowTupleUDP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple
  • func (ft FlowTuple) InOrder() FlowTuple
  • func (ft FlowTuple) IsOrdered() bool
• type PcapFlowTuple

Constants

const (
	ProtoICMP  = 1
	ProtoTCP   = 6
	ProtoUDP   = 17
	ProtoICMP6 = 58
	ProtoSCTP  = 132
)

Define protocol number constants.

Functions

func GetICMPv4PortEquivalents

func GetICMPv4PortEquivalents(p1, p2 uint8) (uint16, uint16, bool)

GetICMPv4PortEquivalents returns ICMPv4 codes mapped back to pseudo port numbers, as well as a bool indicating whether a communication is one-way.

func GetICMPv6PortEquivalents

func GetICMPv6PortEquivalents(p1, p2 uint8) (uint16, uint16, bool)

GetICMPv6PortEquivalents returns ICMPv6 codes mapped back to pseudo port numbers, as well as a bool indicating whether a communication is one-way.

func PcapFlowTupleSource

func PcapFlowTupleSource(file string) (<-chan PcapFlowTuple, error)

PcapFlowTupleSource returns, for a given pcap file name, a channel delivering PcapFlowTuples for each packet in the file. If the file cannot be read for some reason, an error is returned as well accordingly.

Types

type CommunityID

type CommunityID interface {
	Calc(FlowTuple) []byte
	CalcHex(FlowTuple) string
	CalcBase64(FlowTuple) string
	Hash(FlowTuple) hash.Hash
	Render(hash.Hash) []byte
	RenderHex(hash.Hash) string
	RenderBase64(hash.Hash) string
}

CommunityID is an interface defining the supported operations on a component calculating a specific community ID version.

func GetCommunityIDByVersion

func GetCommunityIDByVersion(version uint, seed uint16) (CommunityID, error)

GetCommunityIDByVersion returns, for a given version number and seed, an object implementing the CommunityID interface for the specified version. This will be preconfigured with the given seed.

type CommunityIDv1

type CommunityIDv1 struct {
	Seed uint16
}

CommunityIDv1 encapsulates the calculation code for version 1 of the Community ID flow hashing algorithm.

func (CommunityIDv1) Calc

func (cid CommunityIDv1) Calc(ft FlowTuple) []byte

Calc returns the community id value for a given FlowTuple, as an unformatted byte slice.

func (CommunityIDv1) CalcBase64

func (cid CommunityIDv1) CalcBase64(ft FlowTuple) string

CalcBase64 returns the community id value for a given FlowTuple, as an Base64-encoded string.

func (CommunityIDv1) CalcHex

func (cid CommunityIDv1) CalcHex(ft FlowTuple) string

CalcHex returns the community id value for a given FlowTuple, as an hex-encoded string.

func (CommunityIDv1) Hash

func (cid CommunityIDv1) Hash(ft FlowTuple) hash.Hash

Hash returns a hash.Hash instance (SHA1) in a state corresponding to all input value already dealt with in the hash.

func (CommunityIDv1) Render

func (cid CommunityIDv1) Render(h hash.Hash) []byte

Render returns the value of the given hash, as an unformatted byte slice.

func (CommunityIDv1) RenderBase64

func (cid CommunityIDv1) RenderBase64(h hash.Hash) string

RenderBase64 returns the value of the given hash, as Base64-encoded string.

func (CommunityIDv1) RenderHex

func (cid CommunityIDv1) RenderHex(h hash.Hash) string

RenderHex returns the value of the given hash, as hex-encoded string.

type FlowTuple

type FlowTuple struct {
	Srcip    net.IP
	Dstip    net.IP
	Srcport  uint16
	Dstport  uint16
	Proto    uint8
	IsOneWay bool
}

FlowTuple is a collection of all values required for ID calculation.

func MakeFlowTuple

func MakeFlowTuple(srcip, dstip net.IP, srcport, dstport uint16, proto uint8) FlowTuple

MakeFlowTuple returns a FlowTuple for the given set of communication details: protocol, IPs (source, destination) and ports (source, destination).

func MakeFlowTupleICMP

func MakeFlowTupleICMP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple

MakeFlowTupleICMP returns a FlowTuple with the ICMPv4 protocol preconfigured.

func MakeFlowTupleICMP6

func MakeFlowTupleICMP6(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple

MakeFlowTupleICMP6 returns a FlowTuple with the ICMPv6 protocol preconfigured.

func MakeFlowTupleSCTP

func MakeFlowTupleSCTP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple

MakeFlowTupleSCTP returns a FlowTuple with the SCTP protocol preconfigured.

func MakeFlowTupleTCP

func MakeFlowTupleTCP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple

MakeFlowTupleTCP returns a FlowTuple with the TCP protocol preconfigured.

func MakeFlowTupleUDP

func MakeFlowTupleUDP(srcip, dstip net.IP, srcport, dstport uint16) FlowTuple

MakeFlowTupleUDP returns a FlowTuple with the UDP protocol preconfigured.

func (FlowTuple) InOrder

func (ft FlowTuple) InOrder() FlowTuple

InOrder returns a new copy of the flow tuple, with guaranteed IsOrdered() property.

func (FlowTuple) IsOrdered

func (ft FlowTuple) IsOrdered() bool

IsOrdered returns true if the flow tuple direction is ordered.

type PcapFlowTuple

type PcapFlowTuple struct {
	FlowTuple FlowTuple
	Metadata  *gopacket.PacketMetadata
}

PcapFlowTuple represents a pair of the FlowTuple for a packet as well as its packet metadata (e.g. timestamp).