blob: 2633f848edeeeda0b8fbd330a074db1d54fcd852 [file] [log] [blame]
Matteo Scandoloa6a3aee2019-11-26 13:30:14 -07001// 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
7package gopacket
8
9import (
10 "errors"
11)
12
13// DecodeFeedback is used by DecodingLayer layers to provide decoding metadata.
14type 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
21type nilDecodeFeedback struct{}
22
23func (nilDecodeFeedback) SetTruncated() {}
24
25// NilDecodeFeedback implements DecodeFeedback by doing nothing.
26var 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// }
41type 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.
74type 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.
82type DecodeFunc func([]byte, PacketBuilder) error
83
84// Decode implements Decoder by calling itself.
85func (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.
92var 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.
97var DecodeUnknown Decoder = DecodeFunc(decodeUnknown)
98
99// DecodeFragment is a Decoder that returns a Fragment layer containing all
100// remaining bytes.
101var 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.
105var LayerTypeZero = RegisterLayerType(0, LayerTypeMetadata{Name: "Unknown", Decoder: DecodeUnknown})
106
107// LayerTypeDecodeFailure is the layer type for the default error layer.
108var 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.
112var 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.
116var 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.
122type DecodeFailure struct {
123 data []byte
124 err error
125 stack []byte
126}
127
128// Error returns the error encountered during decoding.
129func (d *DecodeFailure) Error() error { return d.err }
130
131// LayerContents implements Layer.
132func (d *DecodeFailure) LayerContents() []byte { return d.data }
133
134// LayerPayload implements Layer.
135func (d *DecodeFailure) LayerPayload() []byte { return nil }
136
137// String implements fmt.Stringer.
138func (d *DecodeFailure) String() string {
139 return "Packet decoding error: " + d.Error().Error()
140}
141
142// Dump implements Dumper.
143func (d *DecodeFailure) Dump() (s string) {
144 if d.stack != nil {
145 s = string(d.stack)
146 }
147 return
148}
149
150// LayerType returns LayerTypeDecodeFailure
151func (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.
155func decodeUnknown(data []byte, p PacketBuilder) error {
156 return errors.New("Layer type not currently supported")
157}