github.com/gopacket/gopacket@v1.1.0/layers/doc.go (about)

     1  // Copyright 2012 Google, Inc. All rights reserved.
     2  //
     3  // Use of this source code is governed by a BSD-style license
     4  // that can be found in the LICENSE file in the root of the source
     5  // tree.
     6  
     7  /*
     8  Package layers provides decoding layers for many common protocols.
     9  
    10  The layers package contains decode implementations for a number of different
    11  types of packet layers.  Users of gopacket will almost always want to also use
    12  layers to actually decode packet data into useful pieces. To see the set of
    13  protocols that gopacket/layers is currently able to decode,
    14  look at the set of LayerTypes defined in the Variables sections. The
    15  layers package also defines endpoints for many of the common packet layers
    16  that have source/destination addresses associated with them, for example IPv4/6
    17  (IPs) and TCP/UDP (ports).
    18  Finally, layers contains a number of useful enumerations (IPProtocol,
    19  EthernetType, LinkType, PPPType, etc...).  Many of these implement the
    20  gopacket.Decoder interface, so they can be passed into gopacket as decoders.
    21  
    22  Most common protocol layers are named using acronyms or other industry-common
    23  names (IPv4, TCP, PPP).  Some of the less common ones have their names expanded
    24  (CiscoDiscoveryProtocol).
    25  For certain protocols, sub-parts of the protocol are split out into their own
    26  layers (SCTP, for example).  This is done mostly in cases where portions of the
    27  protocol may fulfill the capabilities of interesting layers (SCTPData implements
    28  ApplicationLayer, while base SCTP implements TransportLayer), or possibly
    29  because splitting a protocol into a few layers makes decoding easier.
    30  
    31  This package is meant to be used with its parent,
    32  http://github.com/gopacket/gopacket.
    33  
    34  # Port Types
    35  
    36  Instead of using raw uint16 or uint8 values for ports, we use a different port
    37  type for every protocol, for example TCPPort and UDPPort.  This allows us to
    38  override string behavior for each port, which we do by setting up port name
    39  maps (TCPPortNames, UDPPortNames, etc...).  Well-known ports are annotated with
    40  their protocol names, and their String function displays these names:
    41  
    42  	p := TCPPort(80)
    43  	fmt.Printf("Number: %d  String: %v", p, p)
    44  	// Prints: "Number: 80  String: 80(http)"
    45  
    46  # Modifying Decode Behavior
    47  
    48  layers links together decoding through its enumerations.  For example, after
    49  decoding layer type Ethernet, it uses Ethernet.EthernetType as its next decoder.
    50  All enumerations that act as decoders, like EthernetType, can be modified by
    51  users depending on their preferences.  For example, if you have a spiffy new
    52  IPv4 decoder that works way better than the one built into layers, you can do
    53  this:
    54  
    55  	var mySpiffyIPv4Decoder gopacket.Decoder = ...
    56  	layers.EthernetTypeMetadata[EthernetTypeIPv4].DecodeWith = mySpiffyIPv4Decoder
    57  
    58  This will make all future ethernet packets use your new decoder to decode IPv4
    59  packets, instead of the built-in decoder used by gopacket.
    60  */
    61  package layers