273 lines
9.0 KiB
Plaintext
273 lines
9.0 KiB
Plaintext
/******************************************************************************
|
|
* Copyright (C) 2009-2010 Sourcefire, Inc.
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License Version 2 as
|
|
* published by the Free Software Foundation. You may not use, modify or
|
|
* distribute this program under any other version of the GNU General
|
|
* Public License.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this program; if not, write to the Free Software
|
|
* Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
|
|
*
|
|
******************************************************************************/
|
|
|
|
#ifndef __OBFUSCATION_H__
|
|
#define __OBFUSCATION_H__
|
|
|
|
#include "sf_types.h"
|
|
#include "decode.h"
|
|
#include <pcap.h>
|
|
|
|
|
|
/*******************************************************************************
|
|
* Macros
|
|
******************************************************************************/
|
|
/* This should be defined to be greater than or equal to the maximum
|
|
* amount of data expected to be obfuscated */
|
|
#define OB_LENGTH_MAX UINT16_MAX
|
|
|
|
|
|
/*******************************************************************************
|
|
* Types
|
|
******************************************************************************/
|
|
typedef uint8_t ob_char_t;
|
|
typedef uint16_t ob_size_t;
|
|
|
|
typedef enum _ObRet
|
|
{
|
|
OB_RET_SUCCESS,
|
|
OB_RET_ERROR,
|
|
OB_RET_OVERFLOW
|
|
|
|
} ObRet;
|
|
|
|
|
|
/*******************************************************************************
|
|
* Callback to use for obfuscating payload or stream segments - see API below.
|
|
*
|
|
* The first chunk of a payload or stream segment whether needing obfuscation
|
|
* or not will pass a valid pcap_pkthdr struct. Subsequent calls will pass NULL
|
|
* for this structure. This is useful, especially for the stream segment API
|
|
* call to know when a new segment begins. Any new "payload" will have a valid
|
|
* pcap_pkthdr struct.
|
|
*
|
|
* If the slice sent in has a non-NULL packet data pointer, the data should *NOT*
|
|
* be obfuscated.
|
|
*
|
|
* If the chunk sent in has a NULL packet data pointer, then that chunk of data
|
|
* should be obfuscated with the obfuscation character.
|
|
*
|
|
* The length passed in is the amount of data that should be copied from the
|
|
* packet data pointer or the amount of data that should be written with the
|
|
* obfuscation character.
|
|
*
|
|
* Arguments
|
|
* struct pcap_pkthdr *pkth
|
|
* The pcap header that contains the packet caplen and timestamps
|
|
* uint8_t *packet_data
|
|
* A pointer to the current offset into the packet data. NULL if
|
|
* obfuscation of the payload slice is required.
|
|
* ob_char_t ob_char
|
|
* The obfuscation character to use if packet_data is NULL.
|
|
* ob_size_t length
|
|
* The amount of data to be logged or obfuscated.
|
|
* void *user_data
|
|
* The user data passed in to the API functions obfuscatePayload() or
|
|
* obfuscateStreamSegments below.
|
|
*
|
|
* Returns
|
|
* OB_RET_SUCCESS if all is good
|
|
* OB_RET_ERROR if the rest of the obfuscation should not be done
|
|
*
|
|
******************************************************************************/
|
|
typedef ObRet (*ObfuscationCallback)
|
|
(
|
|
const struct pcap_pkthdr *pkth,
|
|
const uint8_t *packet_data,
|
|
ob_size_t length,
|
|
ob_char_t ob_char,
|
|
void *user_data
|
|
);
|
|
|
|
|
|
/*******************************************************************************
|
|
* Obfuscation API
|
|
******************************************************************************/
|
|
typedef struct _ObfuscationApi
|
|
{
|
|
/*
|
|
* Resets/clears any entries that have been added
|
|
* Should be done per packet aquisition
|
|
*
|
|
* Arguments
|
|
* None
|
|
*
|
|
* Returns
|
|
* None
|
|
*/
|
|
|
|
void (*resetObfuscationEntries)(void);
|
|
|
|
|
|
/*
|
|
* Adds an obfuscation entry to the queue
|
|
*
|
|
* Arguments
|
|
* Packet *p
|
|
* The Packet struct that has the payload data that should be obfuscated
|
|
* ob_size_t offset
|
|
* The offset from the beginning of the payload to start obfuscation
|
|
* ob_size_t length
|
|
* The amount of data to obfuscate
|
|
* ob_char_t ob_char
|
|
* The character to use when obfuscating
|
|
*
|
|
* There are two types of entries that can be added. A slice entry that
|
|
* has an offset and length less than OB_LENGTH_MAX and an entry with
|
|
* length OB_LENGTH_MAX that implies obfuscating from offset to the end
|
|
* of the packet data.
|
|
*
|
|
* NOTE --
|
|
* There is a fixed size of slice entries and OB_LENGTH_MAX entries.
|
|
* If OB_RET_OVERFLOW is returned when attempting to add a slice entry,
|
|
* a second call can be made to add an OB_LENGTH_MAX entry. Only one
|
|
* OB_LENGTH_MAX entry can be associated with each Packet. If there is
|
|
* already an OB_LENGTH_MAX entry for the packet, the lower of the two
|
|
* offsets will be used. Although you should check for OB_RET_OVERFLOW
|
|
* when attempting to add an OB_LENGTH_MAX entry, the fixed size should
|
|
* be more than enough space to store an entry for each possible packet
|
|
* that could be in the system at the time.
|
|
*
|
|
* Returns
|
|
* OB_RET_SUCCESS on sucess
|
|
* OB_RET_ERROR on error
|
|
* OB_RET_OVERFLOW if there is no space left to add an entry
|
|
*/
|
|
|
|
ObRet (*addObfuscationEntry)(Packet *p, ob_size_t offset,
|
|
ob_size_t length, ob_char_t ob_char);
|
|
|
|
|
|
/*
|
|
* Determines if there are any obfuscation entries associated with
|
|
* the given Packet
|
|
*
|
|
* Arguments
|
|
* Packet *
|
|
* The Packet to check
|
|
*
|
|
* Returns
|
|
* 1 if the packet requires obfuscation
|
|
* 0 if it doesn't
|
|
*/
|
|
|
|
int (*payloadObfuscationRequired)(Packet *p);
|
|
|
|
|
|
/*
|
|
* Obfuscate the payload associated with the Packet. Mainly for use by the
|
|
* output system to print or log an obfuscated payload. The callback will
|
|
* be called for both payload segments that need obfuscation and those that
|
|
* don't. See comment on ObfuscationCallback above.
|
|
*
|
|
* Arguments
|
|
* Packet *
|
|
* The Packet whose payload should be obfuscated
|
|
* ObfuscationCallback
|
|
* The function that will be called for each obfuscated and
|
|
* non-obfuscated segment in the payload
|
|
* void *
|
|
* User data that will be passed to the callback
|
|
*
|
|
* Returns
|
|
* OB_RET_SUCCESS on sucess
|
|
* OB_RET_ERROR on error
|
|
*/
|
|
|
|
ObRet (*obfuscatePacket)(Packet *p,
|
|
ObfuscationCallback callback, void *user_data);
|
|
|
|
|
|
/*
|
|
* Obfuscate the stream segments associated with the Packet. Mainly for use
|
|
* by the output system to print or log the stream segments associated with
|
|
* a Packet that have been marked as needing obfuscation. The callback will
|
|
* be called for both stream segments that need obfuscation and those that
|
|
* don't. It will be called for all stream segments. See comment on
|
|
* ObfuscationCallback above.
|
|
*
|
|
* Arguments
|
|
* Packet *
|
|
* The Packet whose stream segments should be obfuscated
|
|
* ObfuscationCallback
|
|
* The function that will be called for each obfuscated and
|
|
* non-obfuscated part of the stream segments.
|
|
* void *
|
|
* User data that will be passed to the callback
|
|
*
|
|
* Returns
|
|
* OB_RET_SUCCESS on sucess
|
|
* OB_RET_ERROR on error
|
|
*/
|
|
|
|
ObRet (*obfuscatePacketStreamSegments)(Packet *p,
|
|
ObfuscationCallback callback, void *user_data);
|
|
|
|
|
|
/*
|
|
* Obfuscates the Packet payload and returns payload and payload length
|
|
* in parameters
|
|
*
|
|
* NOTE
|
|
* *payload will be set to NULL, so don't pass in an already
|
|
* allocated pointer.
|
|
* *payload_len will be zeroed.
|
|
*
|
|
* The payload returned is dynamically allocated and MUST be free'd.
|
|
*
|
|
* Arguments
|
|
* Packet *
|
|
* The Packet whose payload should be obfuscated
|
|
* uint8_t **payload
|
|
* A pointer to a payload pointer so it can be allocated, returned
|
|
* and accessed.
|
|
* ob_size_t *payload_len
|
|
* A pointer to an ob_size_t so the length can be returned.
|
|
*
|
|
* Returns
|
|
* OB_RET_ERROR if the payload could not be obfuscated
|
|
* the pointers to payload and payload_len will not be valid
|
|
* OB_RET_SUCCESS if the payload was obfuscated
|
|
* the pointers to payload and payload_len will be valid
|
|
*/
|
|
|
|
ObRet (*getObfuscatedPayload)(Packet *p, uint8_t **payload,
|
|
ob_size_t *payload_len);
|
|
|
|
/*
|
|
* Prints the current obfuscation entries.
|
|
*
|
|
* Arguments
|
|
* int sorted
|
|
* Print the sorted entries and sort if necessary.
|
|
*
|
|
* Returns
|
|
* None
|
|
*/
|
|
|
|
void (*printObfuscationEntries)(int sorted);
|
|
|
|
} ObfuscationApi;
|
|
|
|
/* For access when including header */
|
|
extern ObfuscationApi *obApi;
|
|
|
|
#endif /* __OBFUSCATION_H__ */
|