Coverage Report

Created: 2025-07-11 06:47

/src/PcapPlusPlus/Packet++/header/TLVData.h
Line
Count
Source (jump to first uncovered line)
1
#pragma once
2
3
#include "Layer.h"
4
#include "IpAddress.h"
5
#include <string.h>
6
7
/// @file
8
9
/// @namespace pcpp
10
/// @brief The main namespace for the PcapPlusPlus lib
11
namespace pcpp
12
{
13
  /// @class TLVRecord
14
  /// A wrapper class for a Type-Length-Value (TLV) record. This class does not create or modify TLV records, but
15
  /// rather serves as a wrapper and provides useful methods for retrieving data from them. This class has several
16
  /// abstract methods that should be implemented in derived classes. These methods are for record length value
17
  /// calculation (the 'L' in TLV) which is implemented differently in different protocols
18
  template <typename TRecType, typename TRecLen> class TLVRecord
19
  {
20
  protected:
21
    /// A struct representing the TLV construct
22
#pragma pack(push, 1)
23
    struct TLVRawData
24
    {
25
      /// Record type
26
      TRecType recordType;
27
      /// Record length in bytes
28
      TRecLen recordLen;
29
      /// Record value (variable size)
30
      uint8_t recordValue[];
31
    };
32
#pragma pack(pop)
33
34
    TLVRawData* m_Data;
35
36
  public:
37
    /// A c'tor for this class that gets a pointer to the TLV record raw data (byte array)
38
    /// @param[in] recordRawData A pointer to the TLV record raw data
39
    TLVRecord(uint8_t* recordRawData)
40
    {
41
      assign(recordRawData);
42
    }
43
44
    /// A copy c'tor for this class. This copy c'tor doesn't copy the TLV data, but only the pointer to it,
45
    /// which means that after calling it both the old and the new instance will point to the same TLV raw data
46
    /// @param[in] other The TLVRecord instance to copy from
47
    TLVRecord(const TLVRecord& other)
48
    {
49
      m_Data = other.m_Data;
50
    }
51
52
    /// A d'tor for this class, currently does nothing
53
    virtual ~TLVRecord() = default;
54
55
    /// Assign a pointer to the TLV record raw data (byte array)
56
    /// @param[in] recordRawData A pointer to the TLV record raw data
57
    void assign(uint8_t* recordRawData)
58
0
    {
59
0
      m_Data = reinterpret_cast<TLVRawData*>(recordRawData);
60
0
    }
61
62
    /// Check if a pointer can be assigned to the TLV record data
63
    /// @param[in] recordRawData A pointer to the TLV record raw data
64
    /// @param[in] tlvDataLen The size of the TLV record raw data
65
    /// @return True if data is valid and can be assigned
66
    static bool canAssign(const uint8_t* recordRawData, size_t tlvDataLen)
67
0
    {
68
0
      return recordRawData != nullptr &&
69
0
             tlvDataLen >= (sizeof(TLVRawData::recordType) + sizeof(TLVRawData::recordLen));
70
0
    }
71
72
    /// Overload of the assignment operator. This operator doesn't copy the TLV data, but rather copies the pointer
73
    /// to it, which means that after calling it both the old and the new instance will point to the same TLV raw
74
    /// data
75
    /// @param[in] other The TLVRecord instance to assign
76
    TLVRecord& operator=(const TLVRecord& other)
77
    {
78
      m_Data = other.m_Data;
79
      return *this;
80
    }
81
82
    /// Overload of the equality operator. Two record are equal if both of them point to the same data, or if they
83
    /// point to different data but their total size is equal and the raw data they both contain is similar.
84
    /// @param[in] rhs The object to compare to
85
    /// @return True if both objects are equal, false otherwise
86
    bool operator==(const TLVRecord& rhs) const
87
    {
88
      if (m_Data == rhs.m_Data)
89
        return true;
90
91
      if (getTotalSize() != rhs.getTotalSize())
92
        return false;
93
94
      if (isNull() || ((TLVRecord&)rhs).isNull())
95
        return false;
96
97
      return (memcmp(m_Data, rhs.m_Data, getTotalSize()) == 0);
98
    }
99
100
    /// Overload of the not equal operator.
101
    /// @param[in] rhs The object to compare to
102
    /// @return True if objects are not equal, false otherwise
103
    bool operator!=(const TLVRecord& rhs) const
104
    {
105
      return !operator==(rhs);
106
    }
107
108
    /// @return The type field of the record (the 'T' in __Type__-Length-Value)
109
    TRecType getType() const
110
    {
111
      if (m_Data == nullptr)
112
        return 0;
113
114
      return m_Data->recordType;
115
    }
116
117
    /// @return A pointer to the value of the record as byte array (the 'V' in Type-Length- __Value__)
118
    uint8_t* getValue() const
119
    {
120
      if (m_Data == nullptr)
121
        return nullptr;
122
123
      return m_Data->recordValue;
124
    }
125
126
    /// @return True if the TLV record raw data is nullptr, false otherwise
127
    bool isNull() const
128
    {
129
      return (m_Data == nullptr);
130
    }
131
132
    /// @return True if the TLV record raw data is not nullptr, false otherwise
133
    bool isNotNull() const
134
    {
135
      return (m_Data != nullptr);
136
    }
137
138
    /// @return A pointer to the TLV record raw data byte stream
139
    uint8_t* getRecordBasePtr() const
140
    {
141
      return reinterpret_cast<uint8_t*>(m_Data);
142
    }
143
144
    /// Free the memory of the TLV record raw data
145
    void purgeRecordData()
146
    {
147
      if (!isNull())
148
      {
149
        delete[] m_Data;
150
        m_Data = nullptr;
151
      }
152
    }
153
154
    /// A templated method to retrieve the record data as a certain type T. For example, if record data is 4B long
155
    /// (integer) then this method should be used as getValueAs<int>() and it will return the record data as an
156
    /// integer.<BR> Notice this return value is a copy of the data, not a pointer to the actual data
157
    /// @param[in] offset The offset in the record data to start reading the value from. Useful for cases when you
158
    /// want to read some of the data that doesn't start at offset 0. This is an optional parameter and the default
159
    /// value is 0, meaning start reading the value at the beginning of the record data
160
    /// @return The record data as type T
161
    template <typename T> T getValueAs(size_t offset = 0) const
162
    {
163
      if (getDataSize() - offset < sizeof(T))
164
        return 0;
165
166
      T result;
167
      memcpy(&result, m_Data->recordValue + getValueOffset() + offset, sizeof(T));
168
      return result;
169
    }
170
171
    /// A templated method to copy data of type T into the TLV record data. For example: if record data is 4[Bytes]
172
    /// long use this method with \<int\> to set an integer value into the record data: setValue<int>(num)
173
    /// @param[in] newValue The value of type T to copy to the record data
174
    /// @param[in] valueOffset An optional parameter that specifies where to start setting the record data (default
175
    /// set to 0). For example: if record data is 20 bytes long and you only need to set the 4 last bytes as integer
176
    /// then use this method like this: setValue<int>(num, 16)
177
    /// @return True if value was set successfully or false if the size of T is larger than the record data size
178
    template <typename T> bool setValue(T newValue, int valueOffset = 0)
179
    {
180
      if (getDataSize() < sizeof(T))
181
        return false;
182
183
      memcpy(m_Data->recordValue + getValueOffset() + valueOffset, &newValue, sizeof(T));
184
      return true;
185
    }
186
187
    /// @return The total size of the TLV record (in bytes)
188
    virtual size_t getTotalSize() const = 0;
189
190
    /// @return The size of the record value (meaning the size of the 'V' part in TLV)
191
    virtual size_t getDataSize() const = 0;
192
193
  protected:
194
    virtual size_t getValueOffset() const
195
0
    {
196
0
      return 0;
197
0
    }
198
  };
199
200
  /// @class TLVRecordReader
201
  /// A class for reading TLV records data out of a byte stream. This class contains helper methods for retrieving and
202
  /// counting TLV records. This is a template class that expects template argument class derived from TLVRecord.
203
  template <typename TLVRecordType> class TLVRecordReader
204
  {
205
  private:
206
    mutable size_t m_RecordCount;
207
208
  public:
209
    /// A default c'tor for this class
210
    TLVRecordReader()
211
    {
212
      m_RecordCount = static_cast<size_t>(-1);
213
    }
214
215
    /// A default copy c'tor for this class
216
    TLVRecordReader(const TLVRecordReader& other)
217
    {
218
      m_RecordCount = other.m_RecordCount;
219
    }
220
221
    /// A d'tor for this class which currently does nothing
222
    virtual ~TLVRecordReader() = default;
223
224
    /// Overload of the assignment operator for this class
225
    /// @param[in] other The TLVRecordReader instance to assign
226
    TLVRecordReader& operator=(const TLVRecordReader& other)
227
    {
228
      m_RecordCount = other.m_RecordCount;
229
      return *this;
230
    }
231
232
    /// Get the first TLV record out of a byte stream
233
    /// @param[in] tlvDataBasePtr A pointer to the TLV data byte stream
234
    /// @param[in] tlvDataLen The TLV data byte stream length
235
    /// @return An instance of type TLVRecordType that contains the first TLV record. If tlvDataBasePtr is nullptr
236
    /// or tlvDataLen is zero the returned TLVRecordType instance will be logically null, meaning
237
    /// TLVRecordType.isNull() will return true
238
    TLVRecordType getFirstTLVRecord(uint8_t* tlvDataBasePtr, size_t tlvDataLen) const
239
    {
240
      TLVRecordType resRec(nullptr);  // for NRVO optimization
241
      if (!TLVRecordType::canAssign(tlvDataBasePtr, tlvDataLen))
242
        return resRec;
243
244
      resRec.assign(tlvDataBasePtr);
245
      // resRec pointer is out-bounds of the TLV records memory
246
      if (resRec.getRecordBasePtr() + resRec.getTotalSize() > tlvDataBasePtr + tlvDataLen)
247
        resRec.assign(nullptr);
248
249
      // check if there are records at all and the total size is not zero
250
      if (!resRec.isNull() && (tlvDataLen == 0 || resRec.getTotalSize() == 0))
251
        resRec.assign(nullptr);
252
253
      return resRec;
254
    }
255
256
    /// Get a TLV record that follows a given TLV record in a byte stream
257
    /// @param[in] record A given TLV record
258
    /// @param[in] tlvDataBasePtr A pointer to the TLV data byte stream
259
    /// @param[in] tlvDataLen The TLV data byte stream length
260
    /// @return An instance of type TLVRecordType that wraps the record following the record given as input. If the
261
    /// input record.isNull() is true or if the next record is out of bounds of the byte stream, a logical null
262
    /// instance of TLVRecordType will be returned, meaning TLVRecordType.isNull() will return true
263
    TLVRecordType getNextTLVRecord(TLVRecordType& record, const uint8_t* tlvDataBasePtr, size_t tlvDataLen) const
264
    {
265
      TLVRecordType resRec(nullptr);  // for NRVO optimization
266
267
      if (record.isNull())
268
        return resRec;
269
270
      if (!TLVRecordType::canAssign(record.getRecordBasePtr() + record.getTotalSize(),
271
                                    tlvDataBasePtr - record.getRecordBasePtr() + tlvDataLen -
272
                                        record.getTotalSize()))
273
        return resRec;
274
275
      resRec.assign(record.getRecordBasePtr() + record.getTotalSize());
276
277
      if (resRec.getTotalSize() == 0)
278
        resRec.assign(nullptr);
279
280
      // resRec pointer is out-bounds of the TLV records memory
281
      if ((resRec.getRecordBasePtr() - tlvDataBasePtr) < 0)
282
        resRec.assign(nullptr);
283
284
      // resRec pointer is out-bounds of the TLV records memory
285
      if (!resRec.isNull() && resRec.getRecordBasePtr() + resRec.getTotalSize() > tlvDataBasePtr + tlvDataLen)
286
        resRec.assign(nullptr);
287
288
      return resRec;
289
    }
290
291
    /// Search for the first TLV record that corresponds to a given record type (the 'T' in __Type__-Length-Value)
292
    /// @param[in] recordType The record type to search for
293
    /// @param[in] tlvDataBasePtr A pointer to the TLV data byte stream
294
    /// @param[in] tlvDataLen The TLV data byte stream length
295
    /// @return An instance of type TLVRecordType that contains the result record. If record was not found a logical
296
    /// null instance of TLVRecordType will be returned, meaning TLVRecordType.isNull() will return true
297
    TLVRecordType getTLVRecord(uint32_t recordType, uint8_t* tlvDataBasePtr, size_t tlvDataLen) const
298
    {
299
      TLVRecordType curRec = getFirstTLVRecord(tlvDataBasePtr, tlvDataLen);
300
      while (!curRec.isNull())
301
      {
302
        if (curRec.getType() == recordType)
303
        {
304
          return curRec;
305
        }
306
307
        curRec = getNextTLVRecord(curRec, tlvDataBasePtr, tlvDataLen);
308
      }
309
310
      curRec.assign(nullptr);
311
      return curRec;  // for NRVO optimization
312
    }
313
314
    /// Get the TLV record count in a given TLV data byte stream. For efficiency purposes the count is being cached
315
    /// so only the first call to this method will go over all the TLV records, while all consequent calls will
316
    /// return the cached number. This implies that if there is a change in the number of records, it's the user's
317
    /// responsibility to call changeTLVRecordCount() with the record count change
318
    /// @param[in] tlvDataBasePtr A pointer to the TLV data byte stream
319
    /// @param[in] tlvDataLen The TLV data byte stream length
320
    /// @return The TLV record count
321
    size_t getTLVRecordCount(uint8_t* tlvDataBasePtr, size_t tlvDataLen) const
322
    {
323
      if (m_RecordCount != static_cast<size_t>(-1))
324
        return m_RecordCount;
325
326
      m_RecordCount = 0;
327
      TLVRecordType curRec = getFirstTLVRecord(tlvDataBasePtr, tlvDataLen);
328
      while (!curRec.isNull())
329
      {
330
        m_RecordCount++;
331
        curRec = getNextTLVRecord(curRec, tlvDataBasePtr, tlvDataLen);
332
      }
333
334
      return m_RecordCount;
335
    }
336
337
    /// As described in getTLVRecordCount(), the TLV record count is being cached for efficiency purposes. So if the
338
    /// number of TLV records change, it's the user's responsibility to call this method with the number of TLV
339
    /// records being added or removed. If records were added the change should be a positive number, or a negative
340
    /// number if records were removed
341
    /// @param[in] changedBy Number of records that were added or removed
342
    void changeTLVRecordCount(int changedBy)
343
    {
344
      if (m_RecordCount != static_cast<size_t>(-1))
345
        m_RecordCount += changedBy;
346
    }
347
  };
348
349
  /// @class TLVRecordBuilder
350
  /// A base class for building Type-Length-Value (TLV) records. This builder receives the record parameters in its
351
  /// c'tor, builds the record raw buffer and provides a method to build a TLVRecord object out of it. Please notice
352
  /// this is a base class that lacks the capability of actually building TLVRecord objects and also cannot be
353
  /// instantiated. The reason for that is that different protocols build TLV records in different ways, so these
354
  /// missing capabilities will be implemented by the derived classes which are specific to each protocol. This class
355
  /// only provides the common infrastructure that will be used by them
356
  class TLVRecordBuilder
357
  {
358
  protected:
359
    TLVRecordBuilder();
360
361
    TLVRecordBuilder(uint32_t recType, const uint8_t* recValue, uint8_t recValueLen);
362
363
    TLVRecordBuilder(uint32_t recType, uint8_t recValue);
364
365
    TLVRecordBuilder(uint32_t recType, uint16_t recValue);
366
367
    TLVRecordBuilder(uint32_t recType, uint32_t recValue);
368
369
    TLVRecordBuilder(uint32_t recType, const IPv4Address& recValue);
370
371
    TLVRecordBuilder(uint32_t recType, const std::string& recValue, bool valueIsHexString = false);
372
373
    TLVRecordBuilder(const TLVRecordBuilder& other);
374
375
    TLVRecordBuilder& operator=(const TLVRecordBuilder& other);
376
377
    virtual ~TLVRecordBuilder();
378
379
    void init(uint32_t recType, const uint8_t* recValue, size_t recValueLen);
380
381
    uint8_t* m_RecValue;
382
    size_t m_RecValueLen;
383
    uint32_t m_RecType;
384
385
  private:
386
    void copyData(const TLVRecordBuilder& other);
387
  };
388
}  // namespace pcpp