Software Engineering Institute | Carnegie Mellon©
CERT NetSA Security Suite
Monitoring for Large-Scale Networks

fixbuf

Documentation

fixbuf

  • Documentation
  • Downloads
  • Main Page
  • Data Structures
  • Files
  • File List
  • Globals

public.h

Go to the documentation of this file.
00001 /*
00002  ** public.h
00003  ** fixbuf IPFIX Implementation Public Interface
00004  **
00005  ** ------------------------------------------------------------------------
00006  ** Copyright (C) 2006-2008 Carnegie Mellon University. All Rights Reserved.
00007  ** ------------------------------------------------------------------------
00008  ** Authors: Brian Trammell <bht@cert.org>
00009  ** ------------------------------------------------------------------------
00010  ** @OPENSOURCE_HEADER_START@
00011  ** Use of the libfixbuf system and related source code is subject to the terms 
00012  ** of the following licenses:
00013  ** 
00014  ** GNU Public License (GPL) Rights pursuant to Version 2, June 1991
00015  ** Government Purpose License Rights (GPLR) pursuant to DFARS 252.227.7013
00016  ** 
00017  ** NO WARRANTY
00018  ** 
00019  ** ANY INFORMATION, MATERIALS, SERVICES, INTELLECTUAL PROPERTY OR OTHER 
00020  ** PROPERTY OR RIGHTS GRANTED OR PROVIDED BY CARNEGIE MELLON UNIVERSITY 
00021  ** PURSUANT TO THIS LICENSE (HEREINAFTER THE "DELIVERABLES") ARE ON AN 
00022  ** "AS-IS" BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY 
00023  ** KIND, EITHER EXPRESS OR IMPLIED AS TO ANY MATTER INCLUDING, BUT NOT 
00024  ** LIMITED TO, WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE, 
00025  ** MERCHANTABILITY, INFORMATIONAL CONTENT, NONINFRINGEMENT, OR ERROR-FREE 
00026  ** OPERATION. CARNEGIE MELLON UNIVERSITY SHALL NOT BE LIABLE FOR INDIRECT, 
00027  ** SPECIAL OR CONSEQUENTIAL DAMAGES, SUCH AS LOSS OF PROFITS OR INABILITY 
00028  ** TO USE SAID INTELLECTUAL PROPERTY, UNDER THIS LICENSE, REGARDLESS OF 
00029  ** WHETHER SUCH PARTY WAS AWARE OF THE POSSIBILITY OF SUCH DAMAGES. 
00030  ** LICENSEE AGREES THAT IT WILL NOT MAKE ANY WARRANTY ON BEHALF OF 
00031  ** CARNEGIE MELLON UNIVERSITY, EXPRESS OR IMPLIED, TO ANY PERSON 
00032  ** CONCERNING THE APPLICATION OF OR THE RESULTS TO BE OBTAINED WITH THE 
00033  ** DELIVERABLES UNDER THIS LICENSE.
00034  ** 
00035  ** Licensee hereby agrees to defend, indemnify, and hold harmless Carnegie 
00036  ** Mellon University, its trustees, officers, employees, and agents from 
00037  ** all claims or demands made against them (and any related losses, 
00038  ** expenses, or attorney's fees) arising out of, or relating to Licensee's 
00039  ** and/or its sub licensees' negligent use or willful misuse of or 
00040  ** negligent conduct or willful misconduct regarding the Software, 
00041  ** facilities, or other rights or assistance granted by Carnegie Mellon 
00042  ** University under this License, including, but not limited to, any 
00043  ** claims of product liability, personal injury, death, damage to 
00044  ** property, or violation of any laws or regulations.
00045  ** 
00046  ** Carnegie Mellon University Software Engineering Institute authored 
00047  ** documents are sponsored by the U.S. Department of Defense under 
00048  ** Contract F19628-00-C-0003. Carnegie Mellon University retains 
00049  ** copyrights in all material produced under this contract. The U.S. 
00050  ** Government retains a non-exclusive, royalty-free license to publish or 
00051  ** reproduce these documents, or allow others to do so, for U.S. 
00052  ** Government purposes only pursuant to the copyright license under the 
00053  ** contract clause at 252.227.7013.
00054  ** 
00055  ** @OPENSOURCE_HEADER_END@ 
00056  ** ------------------------------------------------------------------------
00057  */
00058 
00299 #ifndef _FB_PUBLIC_H_
00300 #define _FB_PUBLIC_H_
00301 #include <fixbuf/autoinc.h>
00302 
00303 #ifdef __cplusplus
00304 extern "C" {
00305 #endif
00306 
00307 #ident "$Id: public.h 16097 2010-07-28 20:37:45Z ecoff_svn $"
00308 
00309 /* 
00310  * Error Handling Definitions
00311  */
00312 
00314 #define FB_ERROR_DOMAIN             g_quark_from_string("fixbufError")
00315 
00316 #define FB_ERROR_TMPL               1
00317 
00321 #define FB_ERROR_EOM                2
00322 
00327 #define FB_ERROR_EOF                3
00328 
00332 #define FB_ERROR_IPFIX              4
00333 
00338 #define FB_ERROR_BUFSZ              5
00339 
00340 #define FB_ERROR_IMPL               6
00341 
00342 #define FB_ERROR_IO                 7
00343 
00347 #define FB_ERROR_NLREAD             8
00348 
00353 #define FB_ERROR_NLWRITE            9
00354 
00357 #define FB_ERROR_NOELEMENT          10
00358 
00361 #define FB_ERROR_CONN               11
00362 
00366 #define FB_ERROR_NETFLOWV9          12
00367 
00370 #define FB_ERROR_TRANSMISC          13
00371 
00372 /*
00373  * Public Datatypes and Constants
00374  */
00375  
00376 struct fBuf_st;
00382 typedef struct fBuf_st fBuf_t;
00383 
00390 typedef struct fbVarfield_st {
00392     size_t      len;
00399     uint8_t     *buf;
00400 } fbVarfield_t;
00401 
00402 struct fbInfoModel_st;
00407 typedef struct fbInfoModel_st fbInfoModel_t;
00408 
00414 #define FB_IE_INIT(_name_, _ent_, _num_, _len_, _flags_) \
00415     { {.name = _name_}, 0, _ent_, _num_, _len_, _flags_ }
00416 
00422 #define FB_IE_NULL \
00423     { {.name = NULL}, 0, 0, 0, 0, 0 }
00424 
00429 #define FB_IE_F_NONE                            0x00000000
00430 
00435 #define FB_IE_F_ENDIAN                          0x00000001
00436 
00446 #define FB_IE_F_REVERSIBLE                      0x00000040
00447 
00455 #define FB_IE_F_ALIEN                           0x00000080
00456 
00460 #define FB_IE_VARLEN                            65535
00461 
00469 #define FB_IE_PEN_REVERSE                       29305
00470 
00479 #define FB_IE_VENDOR_BIT_REVERSE                0x4000
00480 
00486 #define FB_IE_REVERSE_STR                       "reverse"
00487 
00489 #define FB_IE_REVERSE_STRLEN                    7
00490 
00499 typedef struct fbInfoElement_st {
00501     union {
00507         const struct fbInfoElement_st *canon;
00512         char                    *name;
00513     } 
00514                         ref;
00515 
00521     uint32_t            midx;
00523     uint32_t            ent;
00528     uint16_t            num;
00530     uint16_t            len;
00532     uint32_t            flags;
00533 } fbInfoElement_t;
00534 
00539 #define FB_TID_AUTO         0
00540 
00544 #define FB_TID_TS           2
00545 
00549 #define FB_TID_OTS          3
00550 
00554 #define FB_TID_MIN_DATA     256
00555 
00556 struct fbTemplate_st;
00562 typedef struct fbTemplate_st fbTemplate_t;
00563 
00569 #define FB_IESPEC_NULL { NULL, 0, 0 }
00570 
00576 typedef struct fbInfoElementSpec_st {
00578     char                *name;
00583     uint16_t            len_override;
00590     uint32_t            flags;
00591 } fbInfoElementSpec_t;
00592 
00593 struct fbSession_st;
00600 typedef struct fbSession_st fbSession_t;
00601 
00603 typedef enum fbTransport_en {
00608     FB_SCTP,
00610     FB_TCP,
00612     FB_UDP,
00618     FB_DTLS_SCTP,
00623     FB_TLS_TCP,
00629     FB_DTLS_UDP,
00630 } fbTransport_t;
00631 
00636 typedef struct fbConnSpec_st {
00638     fbTransport_t       transport;
00640     char                *host;
00642     char                *svc;
00644     char                *ssl_ca_file;
00646     char                *ssl_cert_file;
00648     char                *ssl_key_file;
00650     char                *ssl_key_pass;
00655     void                *vai;
00660     void                *vssl_ctx;
00661 } fbConnSpec_t;
00662 
00666 #define FB_CONNSPEC_INIT { FB_SCTP, NULL, NULL,         \
00667                            NULL, NULL, NULL, NULL,      \
00668                            NULL, NULL }
00669 
00670 #if HAVE_SPREAD
00671 
00676 #define FB_SPREADPARAMS_INIT { 0, 0, 0 }
00677 
00678 typedef struct fbSpreadParams_st {
00681     fbSession_t *   session;
00684     char *          daemon;
00687     char **         groups;
00688 } fbSpreadParams_t;
00689 
00690 #endif /* HAVE_SPREAD */
00691 
00692 struct fbExporter_st;
00698 typedef struct fbExporter_st fbExporter_t;
00699 
00700 struct fbCollector_st;
00708 typedef struct fbCollector_st fbCollector_t;
00709 
00710 struct fbListener_st;
00717 typedef struct fbListener_st fbListener_t;
00718  
00728 typedef gboolean        (*fbListenerAppInit_fn) (
00729     fbListener_t                *listener,
00730     void                        **ctx,
00731     int                         fd,
00732     struct sockaddr             *peer,
00733     size_t                      peerlen,
00734     GError                      **err);
00735 
00740 typedef void            (*fbListenerAppFree_fn) (
00741     void                        *ctx);
00742 
00743 /*
00744  * Public Function Calls. These calls will remain available and retain 
00745  * their functionality in all subsequent versions of libfixbuf.
00746  */
00747 
00748 
00765 gboolean            fBufSetInternalTemplate(
00766     fBuf_t              *fbuf,
00767     uint16_t            int_tid,
00768     GError              **err);
00769 
00787 gboolean            fBufSetExportTemplate(
00788     fBuf_t              *fbuf,
00789     uint16_t            ext_tid,
00790     GError              **err);
00791 
00806 void                fBufSetAutomaticMode(
00807     fBuf_t              *fbuf,
00808     gboolean            automatic);
00809 
00817 fbSession_t         *fBufGetSession(
00818     fBuf_t              *fbuf);
00819 
00828 void                fBufFree(
00829     fBuf_t              *fbuf);
00830 
00842 fBuf_t              *fBufAllocForExport(
00843     fbSession_t         *session,
00844     fbExporter_t        *exporter);
00845 
00855 fbExporter_t        *fBufGetExporter(
00856     fBuf_t              *fbuf);
00857 
00868 void                fBufSetExporter(
00869     fBuf_t              *fbuf,
00870     fbExporter_t        *exporter);
00871 
00895 gboolean            fBufAppend(
00896     fBuf_t              *fbuf,
00897     uint8_t             *recbase,
00898     size_t              recsize,
00899     GError              **err);
00900 
00910 gboolean            fBufEmit(
00911     fBuf_t              *fbuf,
00912     GError              **err);
00913 
00925 void                fBufSetExportTime(
00926     fBuf_t              *fbuf,
00927     uint32_t            extime);
00928 
00940 fBuf_t              *fBufAllocForCollection(
00941     fbSession_t         *session,
00942     fbCollector_t       *collector);
00943     
00953 fbCollector_t       *fBufGetCollector(
00954     fBuf_t              *fbuf);
00955 
00966 void                fBufSetCollector(
00967     fBuf_t              *fbuf,
00968     fbCollector_t       *collector);
00969 
00999 gboolean            fBufNext(
01000     fBuf_t              *fbuf,
01001     uint8_t             *recbase,
01002     size_t              *recsize,
01003     GError              **err);
01004 
01018 gboolean            fBufNextMessage(
01019     fBuf_t              *fbuf,
01020     GError              **err);
01021     
01029 uint32_t            fBufGetExportTime(
01030     fBuf_t              *fbuf);
01031 
01051 fbTemplate_t    *fBufGetCollectionTemplate(
01052     fBuf_t          *fbuf,
01053     uint16_t        *ext_tid);
01054 
01073 fbTemplate_t    *fBufNextCollectionTemplate(
01074     fBuf_t          *fbuf,
01075     uint16_t        *ext_tid,
01076     GError          **err);
01077 
01089 fbInfoModel_t       *fbInfoModelAlloc();
01090 
01099 void                fbInfoModelFree(
01100     fbInfoModel_t       *model);
01101 
01116 void                fbInfoModelAddElement(
01117     fbInfoModel_t       *model,
01118     fbInfoElement_t     *ie);
01119 
01134 void                fbInfoModelAddElementArray(
01135     fbInfoModel_t       *model,
01136     fbInfoElement_t     *ie);
01137 
01149 const fbInfoElement_t     *fbInfoModelGetElementByName(
01150     fbInfoModel_t       *model,
01151     const char          *name);
01152 
01153 
01171 fbTemplate_t        *fbTemplateAlloc(
01172     fbInfoModel_t       *model);
01173 
01190 gboolean            fbTemplateAppend(
01191     fbTemplate_t        *tmpl,
01192     fbInfoElement_t     *ex_ie,
01193     GError              **err);
01194 
01210 gboolean            fbTemplateAppendSpec(
01211     fbTemplate_t        *tmpl,
01212     fbInfoElementSpec_t *spec,
01213     uint32_t            flags,
01214     GError              **err);
01215 
01233 gboolean            fbTemplateAppendSpecArray(
01234     fbTemplate_t        *tmpl,
01235     fbInfoElementSpec_t *spec,
01236     uint32_t            flags,
01237     GError              **err);
01238 
01246 uint32_t            fbTemplateCountElements(
01247     fbTemplate_t        *tmpl);
01248 
01258 void                fbTemplateSetOptionsScope(
01259     fbTemplate_t        *tmpl,
01260     uint16_t            scope_count);
01261 
01269 uint32_t            fbTemplateGetOptionsScope(
01270     fbTemplate_t        *tmpl);
01271 
01283 gboolean           fbTemplateContainsElement(
01284     fbTemplate_t            *tmpl,
01285     const fbInfoElement_t   *ex_ie);
01286 
01296 gboolean           fbTemplateContainsElementByName(
01297     fbTemplate_t        *tmpl,
01298     fbInfoElementSpec_t *spec);
01299 
01309 gboolean           fbTemplateContainsAllElementsByName(
01310     fbTemplate_t        *tmpl,
01311     fbInfoElementSpec_t *spec);
01312 
01320 void                fbTemplateFreeUnused(
01321     fbTemplate_t        *tmpl);
01322 
01335 fbSession_t         *fbSessionAlloc(
01336     fbInfoModel_t       *model);
01337 
01347 void                fbSessionFree(
01348     fbSession_t         *session);
01349 
01362 void                fbSessionResetExternal(
01363     fbSession_t         *session);
01364 
01380 void                fbSessionSetDomain(
01381     fbSession_t         *session,
01382     uint32_t            domain);
01383 
01391 uint32_t            fbSessionGetDomain(
01392     fbSession_t         *session);
01393 
01406 gboolean            fbSessionExportTemplate(
01407     fbSession_t         *session,
01408     uint16_t            tid,
01409     GError              **err);
01410 
01422 gboolean            fbSessionExportTemplates(
01423     fbSession_t         *session,
01424     GError              **err);
01425 
01441 uint16_t            fbSessionAddTemplate(
01442     fbSession_t         *session,
01443     gboolean            internal,
01444     uint16_t            tid,
01445     fbTemplate_t        *tmpl,
01446     GError              **err);
01447 
01460 gboolean            fbSessionRemoveTemplate(
01461     fbSession_t         *session,
01462     gboolean            internal,
01463     uint16_t            tid,
01464     GError              **err);
01465 
01477 fbTemplate_t        *fbSessionGetTemplate(
01478     fbSession_t         *session,
01479     gboolean            internal,
01480     uint16_t            tid,
01481     GError              **err);
01482 
01493 fbExporter_t        *fbExporterAllocNet(
01494     fbConnSpec_t        *spec);
01495 
01496 #if HAVE_SPREAD
01497 
01512 fbExporter_t        *fbExporterAllocSpread(
01513     fbSpreadParams_t      *params );
01514 
01515 #endif /* HAVE_SPREAD */
01516 
01527 fbExporter_t        *fbExporterAllocFile(
01528     const char          *path);
01529 
01537 fbExporter_t        *fbExporterAllocFP(
01538     FILE                *fp);
01539     
01552 void                fbExporterSetStream(
01553     fbExporter_t        *exporter,
01554     int                 sctp_stream);
01555 
01568 void                fbExporterAutoStream(
01569     fbExporter_t        *exporter);
01570 
01578 void                fbExporterClose(
01579     fbExporter_t       *exporter);
01580 
01592 fbCollector_t       *fbCollectorAllocFile(
01593     void                *ctx,
01594     const char          *path,
01595     GError              **err);
01596 
01606 fbCollector_t       *fbCollectorAllocFP(
01607     void                *ctx,
01608     FILE                *fp);
01609 
01610 
01611 #ifdef HAVE_SPREAD
01612 
01613 /*
01614 *   Allocate a collecting process endpoint for the Spread transport.
01615 *
01616 *   @param ctx      application context
01617 *   @param params   point to fbSpreadSpec_t containing Spread params
01618 *   @param err      error description, set on failure
01619 *
01620 *   @return         a collecting endpoint, or null on failure
01621 */
01622 
01623 fbCollector_t       *fbCollectorAllocSpread (
01624     void                *ctx,
01625     fbSpreadParams_t    *params,
01626     GError              **err );
01627 
01628 #endif /* HAVE_SPREAD */
01629 
01640 void                *fbCollectorGetContext(
01641     fbCollector_t       *collector);
01642 
01653 void                fbCollectorClose(
01654     fbCollector_t       *collector);
01655 
01656 
01657 
01680 fbListener_t        *fbListenerAlloc(
01681     fbConnSpec_t            *spec,
01682     fbSession_t             *session,
01683     fbListenerAppInit_fn    appinit,
01684     fbListenerAppFree_fn    appfree,
01685     GError                  **err);
01686 
01694 void                fbListenerFree(
01695     fbListener_t            *listener);
01696 
01718 fBuf_t              *fbListenerWait(
01719     fbListener_t            *listener,
01720     GError                  **err);
01721 
01729 void                fbListenerInterrupt(
01730     fbListener_t            *listener);
01731 
01732 
01748 gboolean            fbListenerGetCollector(
01749     fbListener_t        *listener,
01750     fbCollector_t       **collector,
01751     GError              **err);
01752 
01753 
01754 
01755 
01771 gboolean    fbCollectorClearTranslator(
01772     fbCollector_t   *collector,
01773     GError          **err);
01774 
01775 
01791 gboolean    fbCollectorSetNetflowV9Translator(
01792     fbCollector_t               *collector,
01793     GError                      **err);
01794 
01795 #ifdef __cplusplus
01796 } /* extern "C" */
01797 #endif
01798 
01799 #endif
© 2006-2010 Carnegie Mellon University