net-snmp 5.7
snmp_secmod.h
00001 #ifndef SNMPSECMOD_H
00002 #define SNMPSECMOD_H
00003 
00004 #ifdef __cplusplus
00005 extern          "C" {
00006 #endif
00007 
00008 #include <net-snmp/library/snmp_transport.h>
00009 
00010 /* Locally defined security models.
00011  * (Net-SNMP enterprise number = 8072)*256 + local_num
00012  */
00013 #define NETSNMP_SEC_MODEL_KSM     2066432
00014 #define NETSNMP_KSM_SECURITY_MODEL     NETSNMP_SEC_MODEL_KSM
00015 #define NETSNMP_TSM_SECURITY_MODEL     SNMP_SEC_MODEL_TSM
00016 
00017 struct snmp_secmod_def;
00018 
00019 /*
00020  * parameter information passed to security model routines
00021  */
00022 struct snmp_secmod_outgoing_params {
00023     int             msgProcModel;
00024     u_char         *globalData;
00025     size_t          globalDataLen;
00026     int             maxMsgSize;
00027     int             secModel;
00028     u_char         *secEngineID;
00029     size_t          secEngineIDLen;
00030     char           *secName;
00031     size_t          secNameLen;
00032     int             secLevel;
00033     u_char         *scopedPdu;
00034     size_t          scopedPduLen;
00035     void           *secStateRef;
00036     u_char         *secParams;
00037     size_t         *secParamsLen;
00038     u_char        **wholeMsg;
00039     size_t         *wholeMsgLen;
00040     size_t         *wholeMsgOffset;
00041     netsnmp_pdu    *pdu;        /* IN - the pdu getting encoded            */
00042     netsnmp_session *session;   /* IN - session sending the message        */
00043 };
00044 
00045 struct snmp_secmod_incoming_params {
00046     int             msgProcModel;       /* IN */
00047     size_t          maxMsgSize; /* IN     - Used to calc maxSizeResponse.  */
00048 
00049     u_char         *secParams;  /* IN     - BER encoded securityParameters. */
00050     int             secModel;   /* IN */
00051     int             secLevel;   /* IN     - AuthNoPriv; authPriv etc.      */
00052 
00053     u_char         *wholeMsg;   /* IN     - Original v3 message.           */
00054     size_t          wholeMsgLen;        /* IN     - Msg length.                    */
00055 
00056     u_char         *secEngineID;        /* OUT    - Pointer snmpEngineID.          */
00057     size_t         *secEngineIDLen;     /* IN/OUT - Len available; len returned.   */
00058     /*
00059      * NOTE: Memory provided by caller.      
00060      */
00061 
00062     char           *secName;    /* OUT    - Pointer to securityName.       */
00063     size_t         *secNameLen; /* IN/OUT - Len available; len returned.   */
00064 
00065     u_char        **scopedPdu;  /* OUT    - Pointer to plaintext scopedPdu. */
00066     size_t         *scopedPduLen;       /* IN/OUT - Len available; len returned.   */
00067 
00068     size_t         *maxSizeResponse;    /* OUT    - Max size of Response PDU.      */
00069     void          **secStateRef;        /* OUT    - Ref to security state.         */
00070     netsnmp_session *sess;      /* IN     - session which got the message  */
00071     netsnmp_pdu    *pdu;        /* IN     - the pdu getting parsed         */
00072     u_char          msg_flags;  /* IN     - v3 Message flags.              */
00073 };
00074 
00075 
00076 /*
00077  * function pointers:
00078  */
00079 
00080 /*
00081  * free's a given security module's data; called at unregistration time 
00082  */
00083 typedef int     (SecmodSessionCallback) (netsnmp_session *);
00084 typedef int     (SecmodPduCallback) (netsnmp_pdu *);
00085 typedef int     (Secmod2PduCallback) (netsnmp_pdu *, netsnmp_pdu *);
00086 typedef int     (SecmodOutMsg) (struct snmp_secmod_outgoing_params *);
00087 typedef int     (SecmodInMsg) (struct snmp_secmod_incoming_params *);
00088 typedef void    (SecmodFreeState) (void *);
00089 typedef void    (SecmodHandleReport) (void *sessp,
00090                                       netsnmp_transport *transport,
00091                                       netsnmp_session *,
00092                                       int result,
00093                                       netsnmp_pdu *origpdu);
00094 typedef int     (SecmodDiscoveryMethod) (void *slp, netsnmp_session *session);
00095 typedef int     (SecmodPostDiscovery) (void *slp, netsnmp_session *session);
00096 
00097 typedef int     (SecmodSessionSetup) (netsnmp_session *in_session,
00098                                       netsnmp_session *out_session);
00099 /*
00100  * definition of a security module
00101  */
00102 
00103 /*
00104  * all of these callback functions except the encoding and decoding
00105  * routines are optional.  The rest of them are available if need.  
00106  */
00107 struct snmp_secmod_def {
00108     /*
00109      * session maniplation functions 
00110      */
00111     SecmodSessionCallback *session_open;        /* called in snmp_sess_open()  */
00112     SecmodSessionCallback *session_close;       /* called in snmp_sess_close() */
00113     SecmodSessionSetup    *session_setup;
00114 
00115     /*
00116      * pdu manipulation routines 
00117      */
00118     SecmodPduCallback *pdu_free;        /* called in free_pdu() */
00119     Secmod2PduCallback *pdu_clone;      /* called in snmp_clone_pdu() */
00120     SecmodPduCallback *pdu_timeout;     /* called when request timesout */
00121     SecmodFreeState *pdu_free_state_ref;        /* frees pdu->securityStateRef */
00122 
00123     /*
00124      * de/encoding routines: mandatory 
00125      */
00126     SecmodOutMsg   *encode_reverse;     /* encode packet back to front */
00127     SecmodOutMsg   *encode_forward;     /* encode packet forward */
00128     SecmodInMsg    *decode;     /* decode & validate incoming */
00129 
00130    /*
00131     * error and report handling
00132     */
00133    SecmodHandleReport *handle_report;
00134 
00135    /*
00136     * default engineID discovery mechanism
00137     */
00138    SecmodDiscoveryMethod *probe_engineid;
00139    SecmodPostDiscovery   *post_probe_engineid;
00140 };
00141 
00142 
00143 /*
00144  * internal list
00145  */
00146 struct snmp_secmod_list {
00147     int             securityModel;
00148     struct snmp_secmod_def *secDef;
00149     struct snmp_secmod_list *next;
00150 };
00151 
00152 
00153 /*
00154  * register a security service 
00155  */
00156 int             register_sec_mod(int, const char *,
00157                                  struct snmp_secmod_def *);
00158 /*
00159  * find a security service definition 
00160  */
00161 NETSNMP_IMPORT
00162 struct snmp_secmod_def *find_sec_mod(int);
00163 /*
00164  * register a security service 
00165  */
00166 int             unregister_sec_mod(int);        /* register a security service */
00167 void            init_secmod(void);
00168 NETSNMP_IMPORT
00169 void            shutdown_secmod(void);
00170 
00171 /*
00172  * clears the sec_mod list
00173  */
00174 NETSNMP_IMPORT
00175 void            clear_sec_mod(void);
00176 
00177 #ifdef __cplusplus
00178 }
00179 #endif
00180 #endif                          /* SNMPSECMOD_H */