vendor/github.com/google/gopacket/decode.go

   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 package gopacket
   8
   9 import (
  10         "errors"
  11 )
  12
  13 // DecodeFeedback is used by DecodingLayer layers to provide decoding metadata.
  14 type DecodeFeedback interface {
  15         // SetTruncated should be called if during decoding you notice that a packet
  16         // is shorter than internal layer variables (HeaderLength, or the like) say it
  17         // should be.  It sets packet.Metadata().Truncated.
  18         SetTruncated()
  19 }
  20
  21 type nilDecodeFeedback struct{}
  22
  23 func (nilDecodeFeedback) SetTruncated() {}
  24
  25 // NilDecodeFeedback implements DecodeFeedback by doing nothing.
  26 var NilDecodeFeedback DecodeFeedback = nilDecodeFeedback{}
  27
  28 // PacketBuilder is used by layer decoders to store the layers they've decoded,
  29 // and to defer future decoding via NextDecoder.
  30 // Typically, the pattern for use is:
  31 //  func (m *myDecoder) Decode(data []byte, p PacketBuilder) error {
  32 //    if myLayer, err := myDecodingLogic(data); err != nil {
  33 //      return err
  34 //    } else {
  35 //      p.AddLayer(myLayer)
  36 //    }
  37 //    // maybe do this, if myLayer is a LinkLayer
  38 //    p.SetLinkLayer(myLayer)
  39 //    return p.NextDecoder(nextDecoder)
  40 //  }
  41 type PacketBuilder interface {
  42         DecodeFeedback
  43         // AddLayer should be called by a decoder immediately upon successful
  44         // decoding of a layer.
  45         AddLayer(l Layer)
  46         // The following functions set the various specific layers in the final
  47         // packet.  Note that if many layers call SetX, the first call is kept and all
  48         // other calls are ignored.
  49         SetLinkLayer(LinkLayer)
  50         SetNetworkLayer(NetworkLayer)
  51         SetTransportLayer(TransportLayer)
  52         SetApplicationLayer(ApplicationLayer)
  53         SetErrorLayer(ErrorLayer)
  54         // NextDecoder should be called by a decoder when they're done decoding a
  55         // packet layer but not done with decoding the entire packet.  The next
  56         // decoder will be called to decode the last AddLayer's LayerPayload.
  57         // Because of this, NextDecoder must only be called once all other
  58         // PacketBuilder calls have been made.  Set*Layer and AddLayer calls after
  59         // NextDecoder calls will behave incorrectly.
  60         NextDecoder(next Decoder) error
  61         // DumpPacketData is used solely for decoding.  If you come across an error
  62         // you need to diagnose while processing a packet, call this and your packet's
  63         // data will be dumped to stderr so you can create a test.  This should never
  64         // be called from a production decoder.
  65         DumpPacketData()
  66         // DecodeOptions returns the decode options
  67         DecodeOptions() *DecodeOptions
  68 }
  69
  70 // Decoder is an interface for logic to decode a packet layer.  Users may
  71 // implement a Decoder to handle their own strange packet types, or may use one
  72 // of the many decoders available in the 'layers' subpackage to decode things
  73 // for them.
  74 type Decoder interface {
  75         // Decode decodes the bytes of a packet, sending decoded values and other
  76         // information to PacketBuilder, and returning an error if unsuccessful.  See
  77         // the PacketBuilder documentation for more details.
  78         Decode([]byte, PacketBuilder) error
  79 }
  80
  81 // DecodeFunc wraps a function to make it a Decoder.
  82 type DecodeFunc func([]byte, PacketBuilder) error
  83
  84 // Decode implements Decoder by calling itself.
  85 func (d DecodeFunc) Decode(data []byte, p PacketBuilder) error {
  86         // function, call thyself.
  87         return d(data, p)
  88 }
  89
  90 // DecodePayload is a Decoder that returns a Payload layer containing all
  91 // remaining bytes.
  92 var DecodePayload Decoder = DecodeFunc(decodePayload)
  93
  94 // DecodeUnknown is a Decoder that returns an Unknown layer containing all
  95 // remaining bytes, useful if you run up against a layer that you're unable to
  96 // decode yet.  This layer is considered an ErrorLayer.
  97 var DecodeUnknown Decoder = DecodeFunc(decodeUnknown)
  98
  99 // DecodeFragment is a Decoder that returns a Fragment layer containing all
 100 // remaining bytes.
 101 var DecodeFragment Decoder = DecodeFunc(decodeFragment)
 102
 103 // LayerTypeZero is an invalid layer type, but can be used to determine whether
 104 // layer type has actually been set correctly.
 105 var LayerTypeZero = RegisterLayerType(0, LayerTypeMetadata{Name: "Unknown", Decoder: DecodeUnknown})
 106
 107 // LayerTypeDecodeFailure is the layer type for the default error layer.
 108 var LayerTypeDecodeFailure = RegisterLayerType(1, LayerTypeMetadata{Name: "DecodeFailure", Decoder: DecodeUnknown})
 109
 110 // LayerTypePayload is the layer type for a payload that we don't try to decode
 111 // but treat as a success, IE: an application-level payload.
 112 var LayerTypePayload = RegisterLayerType(2, LayerTypeMetadata{Name: "Payload", Decoder: DecodePayload})
 113
 114 // LayerTypeFragment is the layer type for a fragment of a layer transported
 115 // by an underlying layer that supports fragmentation.
 116 var LayerTypeFragment = RegisterLayerType(3, LayerTypeMetadata{Name: "Fragment", Decoder: DecodeFragment})
 117
 118 // DecodeFailure is a packet layer created if decoding of the packet data failed
 119 // for some reason.  It implements ErrorLayer.  LayerContents will be the entire
 120 // set of bytes that failed to parse, and Error will return the reason parsing
 121 // failed.
 122 type DecodeFailure struct {
 123         data  []byte
 124         err   error
 125         stack []byte
 126 }
 127
 128 // Error returns the error encountered during decoding.
 129 func (d *DecodeFailure) Error() error { return d.err }
 130
 131 // LayerContents implements Layer.
 132 func (d *DecodeFailure) LayerContents() []byte { return d.data }
 133
 134 // LayerPayload implements Layer.
 135 func (d *DecodeFailure) LayerPayload() []byte { return nil }
 136
 137 // String implements fmt.Stringer.
 138 func (d *DecodeFailure) String() string {
 139         return "Packet decoding error: " + d.Error().Error()
 140 }
 141
 142 // Dump implements Dumper.
 143 func (d *DecodeFailure) Dump() (s string) {
 144         if d.stack != nil {
 145                 s = string(d.stack)
 146         }
 147         return
 148 }
 149
 150 // LayerType returns LayerTypeDecodeFailure
 151 func (d *DecodeFailure) LayerType() LayerType { return LayerTypeDecodeFailure }
 152
 153 // decodeUnknown "decodes" unsupported data types by returning an error.
 154 // This decoder will thus always return a DecodeFailure layer.
 155 func decodeUnknown(data []byte, p PacketBuilder) error {
 156         return errors.New("Layer type not currently supported")
 157 }