{"@context":"https://w3id.org/codemeta/3.0","@type":"SoftwareSourceCode","identifier":"pkg:golang/github.com/google/go%21packet","name":"github.com/google/goPacket","description":"Package gopacket provides packet decoding for the Go language.\n\ngopacket contains many sub-packages with additional functionality you may find\nuseful, including:\n\nAlso, if you're looking to dive right into code, see the examples subdirectory\nfor numerous simple binaries built using gopacket libraries.\n\nMinimum go version required is 1.5.\n\ngopacket takes in packet data as a []byte and decodes it into a packet with\na non-zero number of \"layers\".  Each layer corresponds to a protocol\nwithin the bytes.  Once a packet has been decoded, the layers of the packet\ncan be requested from the packet.\n\nPackets can be decoded from a number of starting points.  Many of our base\ntypes implement Decoder, which allow us to decode packets for which\nwe don't have full data.\n\nMost of the time, you won't just have a []byte of packet data lying around.\nInstead, you'll want to read packets in from somewhere (file, interface, etc)\nand process them.  To do that, you'll want to build a PacketSource.\n\nFirst, you'll need to construct an object that implements the PacketDataSource\ninterface.  There are implementations of this interface bundled with gopacket\nin the gopacket/pcap and gopacket/pfring subpackages... see their documentation\nfor more information on their usage.  Once you have a PacketDataSource, you can\npass it into NewPacketSource, along with a Decoder of your choice, to create\na PacketSource.\n\nOnce you have a PacketSource, you can read packets from it in multiple ways.\nSee the docs for PacketSource for more details.  The easiest method is the\nPackets function, which returns a channel, then asynchronously writes new\npackets into that channel, closing the channel if the packetSource hits an\nend-of-file.\n\nYou can change the decoding options of the packetSource by setting fields in\npacketSource.DecodeOptions... see the following sections for more details.\n\ngopacket optionally decodes packet data lazily, meaning it\nonly decodes a packet layer when it needs to handle a function call.\n\nLazily-decoded packets are not concurrency-safe.  Since layers have not all been\ndecoded, each call to Layer() or Layers() has the potential to mutate the packet\nin order to decode the next layer.  If a packet is used\nin multiple goroutines concurrently, don't use gopacket.Lazy.  Then gopacket\nwill decode the packet fully, and all future function calls won't mutate the\nobject.\n\nBy default, gopacket will copy the slice passed to NewPacket and store the\ncopy within the packet, so future mutations to the bytes underlying the slice\ndon't affect the packet and its layers.  If you can guarantee that the\nunderlying slice bytes won't be changed, you can use NoCopy to tell\ngopacket.NewPacket, and it'll use the passed-in slice itself.\n\nThe fastest method of decoding is to use both Lazy and NoCopy, but note from\nthe many caveats above that for some implementations either or both may be\ndangerous.\n\nDuring decoding, certain layers are stored in the packet as well-known\nlayer types.  For example, IPv4 and IPv6 are both considered NetworkLayer\nlayers, while TCP and UDP are both TransportLayer layers.  We support 4\nlayers, corresponding to the 4 layers of the TCP/IP layering scheme (roughly\nanagalous to layers 2, 3, 4, and 7 of the OSI model).  To access these,\nyou can use the packet.LinkLayer, packet.NetworkLayer,\npacket.TransportLayer, and packet.ApplicationLayer functions.  Each of\nthese functions returns a corresponding interface\n(gopacket.{Link,Network,Transport,Application}Layer).  The first three\nprovide methods for getting src/dst addresses for that particular layer,\nwhile the final layer provides a Payload function to get payload data.\nThis is helpful, for example, to get payloads for all packets regardless\nof their underlying data type:\n\nA particularly useful layer is ErrorLayer, which is set whenever there's\nan error parsing part of the packet.\n\nNote that we don't return an error from NewPacket because we may have decoded\na number of layers successfully before running into our erroneous layer.  You\nmay still be able to get your Ethernet and IPv4 layers correctly, even if\nyour TCP layer is malformed.\n\ngopacket has two useful objects, Flow and Endpoint, for communicating in a protocol\nindependent manner the fact that a packet is coming from A and going to B.\nThe general layer types LinkLayer, NetworkLayer, and TransportLayer all provide\nmethods for extracting their flow information, without worrying about the type\nof the underlying Layer.\n\nA Flow is a simple object made up of a set of two Endpoints, one source and one\ndestination.  It details the sender and receiver of the Layer of the Packet.\n\nAn Endpoint is a hashable representation of a source or destination.  For\nexample, for LayerTypeIPv4, an Endpoint contains the IP address bytes for a v4\nIP packet.  A Flow can be broken into Endpoints, and Endpoints can be combined\ninto Flows:\n\nBoth Endpoint and Flow objects can be used as map keys, and the equality\noperator can compare them, so you can easily group together all packets\nbased on endpoint criteria:\n\nFor load-balancing purposes, both Flow and Endpoint have FastHash() functions,\nwhich provide quick, non-cryptographic hashes of their contents.  Of particular\nimportance is the fact that Flow FastHash() is symmetric: A-\u003eB will have the same\nhash as B-\u003eA.  An example usage could be:\n\nThis allows us to split up a packet stream while still making sure that each\nstream sees all packets for a flow (and its bidirectional opposite).\n\nIf your network has some strange encapsulation, you can implement your own\ndecoder.  In this example, we handle Ethernet packets which are encapsulated\nin a 4-byte header.\n\nSee the docs for Decoder and PacketBuilder for more details on how coding\ndecoders works, or look at RegisterLayerType and RegisterEndpointType to see how\nto add layer/endpoint types to gopacket.\n\nTLDR:  DecodingLayerParser takes about 10% of the time as NewPacket to decode\npacket data, but only for known packet stacks.\n\nBasic decoding using gopacket.NewPacket or PacketSource.Packets is somewhat slow\ndue to its need to allocate a new packet and every respective layer.  It's very\nversatile and can handle all known layer types, but sometimes you really only\ncare about a specific set of layers regardless, so that versatility is wasted.\n\nDecodingLayerParser avoids memory allocation altogether by decoding packet\nlayers directly into preallocated objects, which you can then reference to get\nthe packet's information.  A quick example:\n\nThe important thing to note here is that the parser is modifying the passed in\nlayers (eth, ip4, ip6, tcp) instead of allocating new ones, thus greatly\nspeeding up the decoding process.  It's even branching based on layer type...\nit'll handle an (eth, ip4, tcp) or (eth, ip6, tcp) stack.  However, it won't\nhandle any other type... since no other decoders were passed in, an (eth, ip4,\nudp) stack will stop decoding after ip4, and only pass back [LayerTypeEthernet,\nLayerTypeIPv4] through the 'decoded' slice (along with an error saying it can't\ndecode a UDP packet).\n\nUnfortunately, not all layers can be used by DecodingLayerParser... only those\nimplementing the DecodingLayer interface are usable.  Also, it's possible to\ncreate DecodingLayers that are not themselves Layers... see\nlayers.IPv6ExtensionSkipper for an example of this.\n\nAs well as offering the ability to decode packet data, gopacket will allow you\nto create packets from scratch, as well.  A number of gopacket layers implement\nthe SerializableLayer interface; these layers can be serialized to a []byte in\nthe following manner:\n\nSerializeTo PREPENDS the given layer onto the SerializeBuffer, and they treat\nthe current buffer's Bytes() slice as the payload of the serializing layer.\nTherefore, you can serialize an entire packet by serializing a set of layers in\nreverse order (Payload, then TCP, then IP, then Ethernet, for example).  The\nSerializeBuffer's SerializeLayers function is a helper that does exactly that.\n\nTo generate a (empty and useless, because no fields are set)\nEthernet(IPv4(TCP(Payload))) packet, for example, you can run:\n\nIf you use gopacket, you'll almost definitely want to make sure gopacket/layers\nis imported, since when imported it sets all the LayerType variables and fills\nin a lot of interesting variables/maps (DecodersByLayerName, etc).  Therefore,\nit's recommended that even if you don't use any layers functions directly, you still import with:","version":"v1.1.19","softwareVersion":"v1.1.19","license":"https://spdx.org/licenses/BSD-3-Clause","codeRepository":"https://github.com/google/goPacket","issueTracker":"https://github.com/google/gopacket/issues","url":"https://github.com/google/goPacket","programmingLanguage":{"@type":"ComputerLanguage","name":"Go"},"dateCreated":"2013-10-04","dateModified":"2020-10-19","datePublished":"2020-10-19","copyrightYear":2013,"downloadUrl":"https://proxy.golang.org/github.com/google/go!packet/@v/v1.1.19.zip","softwareHelp":{"@type":"WebSite","url":"https://pkg.go.dev/github.com/google/goPacket#section-documentation"},"applicationCategory":"go","runtimePlatform":"go","developmentStatus":"active","sameAs":["https://pkg.go.dev/github.com/google/goPacket"],"https://www.w3.org/ns/activitystreams#likes":6646,"https://forgefed.org/ns#forks":1151}