snmp_core.h

00001 /**
00002  * @file
00003  * SNMP core API for implementing MIBs
00004  */
00005 
00006 /*
00007  * Copyright (c) 2006 Axon Digital Design B.V., The Netherlands.
00008  * All rights reserved.
00009  *
00010  * Redistribution and use in source and binary forms, with or without modification,
00011  * are permitted provided that the following conditions are met:
00012  *
00013  * 1. Redistributions of source code must retain the above copyright notice,
00014  *    this list of conditions and the following disclaimer.
00015  * 2. Redistributions in binary form must reproduce the above copyright notice,
00016  *    this list of conditions and the following disclaimer in the documentation
00017  *    and/or other materials provided with the distribution.
00018  * 3. The name of the author may not be used to endorse or promote products
00019  *    derived from this software without specific prior written permission.
00020  *
00021  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
00022  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
00023  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
00024  * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00025  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
00026  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00027  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00028  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
00029  * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
00030  * OF SUCH DAMAGE.
00031  *
00032  * Author: Christiaan Simons <christiaan.simons@axon.tv>
00033  *         Martin Hentschel <info@cl-soft.de>
00034  */
00035 
00036 #ifndef LWIP_HDR_APPS_SNMP_CORE_H
00037 #define LWIP_HDR_APPS_SNMP_CORE_H
00038 
00039 #include "lwip/apps/snmp_opts.h"
00040 
00041 #if LWIP_SNMP /* don't build if not configured for use in lwipopts.h */
00042 
00043 #include "lwip/ip_addr.h"
00044 #include "lwip/err.h"
00045 
00046 #ifdef __cplusplus
00047 extern "C" {
00048 #endif
00049 
00050 /* basic ASN1 defines */
00051 #define SNMP_ASN1_CLASS_UNIVERSAL   0x00
00052 #define SNMP_ASN1_CLASS_APPLICATION 0x40
00053 #define SNMP_ASN1_CLASS_CONTEXT     0x80
00054 #define SNMP_ASN1_CLASS_PRIVATE     0xC0
00055 
00056 #define SNMP_ASN1_CONTENTTYPE_PRIMITIVE   0x00
00057 #define SNMP_ASN1_CONTENTTYPE_CONSTRUCTED 0x20
00058 
00059 /* universal tags (from ASN.1 spec.) */
00060 #define SNMP_ASN1_UNIVERSAL_END_OF_CONTENT  0
00061 #define SNMP_ASN1_UNIVERSAL_INTEGER         2
00062 #define SNMP_ASN1_UNIVERSAL_OCTET_STRING    4
00063 #define SNMP_ASN1_UNIVERSAL_NULL            5
00064 #define SNMP_ASN1_UNIVERSAL_OBJECT_ID       6
00065 #define SNMP_ASN1_UNIVERSAL_SEQUENCE_OF    16
00066 
00067 /* application specific (SNMP) tags (from SNMPv2-SMI) */
00068 #define SNMP_ASN1_APPLICATION_IPADDR    0  /* [APPLICATION 0] IMPLICIT OCTET STRING (SIZE (4)) */
00069 #define SNMP_ASN1_APPLICATION_COUNTER   1  /* [APPLICATION 1] IMPLICIT INTEGER (0..4294967295) => u32_t */
00070 #define SNMP_ASN1_APPLICATION_GAUGE     2  /* [APPLICATION 2] IMPLICIT INTEGER (0..4294967295) => u32_t */
00071 #define SNMP_ASN1_APPLICATION_TIMETICKS 3  /* [APPLICATION 3] IMPLICIT INTEGER (0..4294967295) => u32_t */
00072 #define SNMP_ASN1_APPLICATION_OPAQUE    4  /* [APPLICATION 4] IMPLICIT OCTET STRING */
00073 #define SNMP_ASN1_APPLICATION_COUNTER64 6  /* [APPLICATION 6] IMPLICIT INTEGER (0..18446744073709551615) */
00074 
00075 /* context specific (SNMP) tags (from RFC 1905) */
00076 #define SNMP_ASN1_CONTEXT_VARBIND_NO_SUCH_INSTANCE 1
00077 
00078 /* full ASN1 type defines */
00079 #define SNMP_ASN1_TYPE_END_OF_CONTENT (SNMP_ASN1_CLASS_UNIVERSAL | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_UNIVERSAL_END_OF_CONTENT)
00080 #define SNMP_ASN1_TYPE_INTEGER        (SNMP_ASN1_CLASS_UNIVERSAL | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_UNIVERSAL_INTEGER)
00081 #define SNMP_ASN1_TYPE_OCTET_STRING   (SNMP_ASN1_CLASS_UNIVERSAL | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_UNIVERSAL_OCTET_STRING)
00082 #define SNMP_ASN1_TYPE_NULL           (SNMP_ASN1_CLASS_UNIVERSAL | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_UNIVERSAL_NULL)
00083 #define SNMP_ASN1_TYPE_OBJECT_ID      (SNMP_ASN1_CLASS_UNIVERSAL | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_UNIVERSAL_OBJECT_ID)
00084 #define SNMP_ASN1_TYPE_SEQUENCE       (SNMP_ASN1_CLASS_UNIVERSAL | SNMP_ASN1_CONTENTTYPE_CONSTRUCTED | SNMP_ASN1_UNIVERSAL_SEQUENCE_OF)
00085 #define SNMP_ASN1_TYPE_IPADDR         (SNMP_ASN1_CLASS_APPLICATION | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_APPLICATION_IPADDR)
00086 #define SNMP_ASN1_TYPE_IPADDRESS      SNMP_ASN1_TYPE_IPADDR
00087 #define SNMP_ASN1_TYPE_COUNTER        (SNMP_ASN1_CLASS_APPLICATION | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_APPLICATION_COUNTER)
00088 #define SNMP_ASN1_TYPE_COUNTER32      SNMP_ASN1_TYPE_COUNTER
00089 #define SNMP_ASN1_TYPE_GAUGE          (SNMP_ASN1_CLASS_APPLICATION | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_APPLICATION_GAUGE)
00090 #define SNMP_ASN1_TYPE_GAUGE32        SNMP_ASN1_TYPE_GAUGE
00091 #define SNMP_ASN1_TYPE_UNSIGNED32     SNMP_ASN1_TYPE_GAUGE
00092 #define SNMP_ASN1_TYPE_TIMETICKS      (SNMP_ASN1_CLASS_APPLICATION | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_APPLICATION_TIMETICKS)
00093 #define SNMP_ASN1_TYPE_OPAQUE         (SNMP_ASN1_CLASS_APPLICATION | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_APPLICATION_OPAQUE)
00094 #if LWIP_HAVE_INT64
00095 #define SNMP_ASN1_TYPE_COUNTER64      (SNMP_ASN1_CLASS_APPLICATION | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_APPLICATION_COUNTER64)
00096 #endif
00097 
00098 #define SNMP_VARBIND_EXCEPTION_OFFSET 0xF0
00099 #define SNMP_VARBIND_EXCEPTION_MASK   0x0F
00100 
00101 /** error codes predefined by SNMP prot. */
00102 typedef enum {
00103   SNMP_ERR_NOERROR             = 0,
00104 /* 
00105 outdated v1 error codes. do not use anmore!
00106 #define SNMP_ERR_NOSUCHNAME 2  use SNMP_ERR_NOSUCHINSTANCE instead
00107 #define SNMP_ERR_BADVALUE   3  use SNMP_ERR_WRONGTYPE,SNMP_ERR_WRONGLENGTH,SNMP_ERR_WRONGENCODING or SNMP_ERR_WRONGVALUE instead
00108 #define SNMP_ERR_READONLY   4  use SNMP_ERR_NOTWRITABLE instead
00109 */
00110   SNMP_ERR_GENERROR            = 5,
00111   SNMP_ERR_NOACCESS            = 6,
00112   SNMP_ERR_WRONGTYPE           = 7,
00113   SNMP_ERR_WRONGLENGTH         = 8,
00114   SNMP_ERR_WRONGENCODING       = 9,
00115   SNMP_ERR_WRONGVALUE          = 10,
00116   SNMP_ERR_NOCREATION          = 11,
00117   SNMP_ERR_INCONSISTENTVALUE   = 12,
00118   SNMP_ERR_RESOURCEUNAVAILABLE = 13,
00119   SNMP_ERR_COMMITFAILED        = 14,
00120   SNMP_ERR_UNDOFAILED          = 15,
00121   SNMP_ERR_NOTWRITABLE         = 17,
00122   SNMP_ERR_INCONSISTENTNAME    = 18,
00123 
00124   SNMP_ERR_NOSUCHINSTANCE      = SNMP_VARBIND_EXCEPTION_OFFSET + SNMP_ASN1_CONTEXT_VARBIND_NO_SUCH_INSTANCE
00125 } snmp_err_t;
00126 
00127 /** internal object identifier representation */
00128 struct snmp_obj_id
00129 {
00130   u8_t len;
00131   u32_t id[SNMP_MAX_OBJ_ID_LEN];
00132 };
00133 
00134 struct snmp_obj_id_const_ref
00135 {
00136   u8_t len;
00137   const u32_t* id;
00138 };
00139 
00140 extern const struct snmp_obj_id_const_ref snmp_zero_dot_zero; /* administrative identifier from SNMPv2-SMI */
00141 
00142 /** SNMP variant value, used as reference in struct snmp_node_instance and table implementation */
00143 union snmp_variant_value
00144 {
00145   void* ptr;
00146   const void* const_ptr;
00147   u32_t u32;
00148   s32_t s32;
00149 #if LWIP_HAVE_INT64
00150   u64_t u64;
00151 #endif
00152 };
00153 
00154 
00155 /**
00156 SNMP MIB node types
00157  tree node is the only node the stack can process in order to walk the tree,
00158  all other nodes are assumed to be leaf nodes.
00159  This cannot be an enum because users may want to define their own node types.
00160 */
00161 #define SNMP_NODE_TREE         0x00
00162 /* predefined leaf node types */
00163 #define SNMP_NODE_SCALAR       0x01
00164 #define SNMP_NODE_SCALAR_ARRAY 0x02
00165 #define SNMP_NODE_TABLE        0x03
00166 #define SNMP_NODE_THREADSYNC   0x04
00167 
00168 /** node "base class" layout, the mandatory fields for a node  */
00169 struct snmp_node
00170 {
00171   /** one out of SNMP_NODE_TREE or any leaf node type (like SNMP_NODE_SCALAR) */
00172   u8_t node_type;
00173   /** the number assigned to this node which used as part of the full OID */
00174   u32_t oid;
00175 };
00176 
00177 /** SNMP node instance access types */
00178 typedef enum {
00179   SNMP_NODE_INSTANCE_ACCESS_READ    = 1,
00180   SNMP_NODE_INSTANCE_ACCESS_WRITE   = 2,
00181   SNMP_NODE_INSTANCE_READ_ONLY      = SNMP_NODE_INSTANCE_ACCESS_READ,
00182   SNMP_NODE_INSTANCE_READ_WRITE     = (SNMP_NODE_INSTANCE_ACCESS_READ | SNMP_NODE_INSTANCE_ACCESS_WRITE),
00183   SNMP_NODE_INSTANCE_WRITE_ONLY     = SNMP_NODE_INSTANCE_ACCESS_WRITE,
00184   SNMP_NODE_INSTANCE_NOT_ACCESSIBLE = 0
00185 } snmp_access_t;
00186 
00187 struct snmp_node_instance;
00188 
00189 typedef s16_t (*node_instance_get_value_method)(struct snmp_node_instance*, void*);
00190 typedef snmp_err_t (*node_instance_set_test_method)(struct snmp_node_instance*, u16_t, void*);
00191 typedef snmp_err_t (*node_instance_set_value_method)(struct snmp_node_instance*, u16_t, void*);
00192 typedef void (*node_instance_release_method)(struct snmp_node_instance*);
00193 
00194 #define SNMP_GET_VALUE_RAW_DATA 0x4000  /* do not use 0x8000 because return value of node_instance_get_value_method is signed16 and 0x8000 would be the signed bit */
00195 
00196 /** SNMP node instance */
00197 struct snmp_node_instance
00198 {
00199   /** prefilled with the node, get_instance() is called on; may be changed by user to any value to pass an arbitrary node between calls to get_instance() and get_value/test_value/set_value */
00200   const struct snmp_node* node;
00201   /** prefilled with the instance id requested; for get_instance() this is the exact oid requested; for get_next_instance() this is the relative starting point, stack expects relative oid of next node here */
00202   struct snmp_obj_id instance_oid;
00203 
00204   /** ASN type for this object (see snmp_asn1.h for definitions) */
00205   u8_t asn1_type;
00206   /** one out of instance access types defined above (SNMP_NODE_INSTANCE_READ_ONLY,...) */
00207   snmp_access_t access;
00208 
00209   /** returns object value for the given object identifier. Return values <0 to indicate an error */
00210   node_instance_get_value_method get_value;
00211   /** tests length and/or range BEFORE setting */
00212   node_instance_set_test_method set_test;
00213   /** sets object value, only called when set_test() was successful */
00214   node_instance_set_value_method set_value;
00215   /** called in any case when the instance is not required anymore by stack (useful for freeing memory allocated in get_instance/get_next_instance methods) */
00216   node_instance_release_method release_instance;
00217 
00218   /** reference to pass arbitrary value between calls to get_instance() and get_value/test_value/set_value */
00219   union snmp_variant_value reference;
00220   /** see reference (if reference is a pointer, the length of underlying data may be stored here or anything else) */
00221   u32_t reference_len;
00222 };
00223 
00224 
00225 /** SNMP tree node */
00226 struct snmp_tree_node
00227 {
00228   /** inherited "base class" members */
00229   struct snmp_node node;
00230   u16_t subnode_count;
00231   const struct snmp_node* const *subnodes;
00232 };
00233 
00234 #define SNMP_CREATE_TREE_NODE(oid, subnodes) \
00235   {{ SNMP_NODE_TREE, (oid) }, \
00236   (u16_t)LWIP_ARRAYSIZE(subnodes), (subnodes) }
00237 
00238 #define SNMP_CREATE_EMPTY_TREE_NODE(oid) \
00239   {{ SNMP_NODE_TREE, (oid) }, \
00240   0, NULL }
00241 
00242 /** SNMP leaf node */
00243 struct snmp_leaf_node
00244 {
00245   /** inherited "base class" members */
00246   struct snmp_node node;
00247   snmp_err_t (*get_instance)(const u32_t *root_oid, u8_t root_oid_len, struct snmp_node_instance* instance);
00248   snmp_err_t (*get_next_instance)(const u32_t *root_oid, u8_t root_oid_len, struct snmp_node_instance* instance);
00249 };
00250 
00251 /** represents a single mib with its base oid and root node */
00252 struct snmp_mib
00253 {
00254   const u32_t *base_oid;
00255   u8_t base_oid_len;
00256   const struct snmp_node *root_node;
00257 };
00258 
00259 #define SNMP_MIB_CREATE(oid_list, root_node) { (oid_list), (u8_t)LWIP_ARRAYSIZE(oid_list), root_node }
00260 
00261 /** OID range structure */
00262 struct snmp_oid_range
00263 {
00264   u32_t min;
00265   u32_t max;
00266 };
00267 
00268 /** checks if incoming OID length and values are in allowed ranges */
00269 u8_t snmp_oid_in_range(const u32_t *oid_in, u8_t oid_len, const struct snmp_oid_range *oid_ranges, u8_t oid_ranges_len);
00270 
00271 typedef enum {
00272   SNMP_NEXT_OID_STATUS_SUCCESS,
00273   SNMP_NEXT_OID_STATUS_NO_MATCH,
00274   SNMP_NEXT_OID_STATUS_BUF_TO_SMALL
00275 } snmp_next_oid_status_t;
00276 
00277 /** state for next_oid_init / next_oid_check functions */
00278 struct snmp_next_oid_state
00279 {
00280   const u32_t* start_oid;
00281   u8_t start_oid_len;
00282 
00283   u32_t* next_oid;
00284   u8_t next_oid_len;
00285   u8_t next_oid_max_len;
00286 
00287   snmp_next_oid_status_t status;
00288   void* reference;
00289 };
00290 
00291 void snmp_next_oid_init(struct snmp_next_oid_state *state,
00292   const u32_t *start_oid, u8_t start_oid_len,
00293   u32_t *next_oid_buf, u8_t next_oid_max_len);
00294 u8_t snmp_next_oid_precheck(struct snmp_next_oid_state *state, const u32_t *oid, u8_t oid_len);
00295 u8_t snmp_next_oid_check(struct snmp_next_oid_state *state, const u32_t *oid, u8_t oid_len, void* reference);
00296 
00297 void snmp_oid_assign(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len);
00298 void snmp_oid_combine(struct snmp_obj_id* target, const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len);
00299 void snmp_oid_prefix(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len);
00300 void snmp_oid_append(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len);
00301 u8_t snmp_oid_equal(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len);
00302 s8_t snmp_oid_compare(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len);
00303 
00304 #if LWIP_IPV4
00305 u8_t snmp_oid_to_ip4(const u32_t *oid, ip4_addr_t *ip);
00306 void snmp_ip4_to_oid(const ip4_addr_t *ip, u32_t *oid);
00307 #endif /* LWIP_IPV4 */
00308 #if LWIP_IPV6
00309 u8_t snmp_oid_to_ip6(const u32_t *oid, ip6_addr_t *ip);
00310 void snmp_ip6_to_oid(const ip6_addr_t *ip, u32_t *oid);
00311 #endif /* LWIP_IPV6 */
00312 #if LWIP_IPV4 || LWIP_IPV6
00313 u8_t snmp_ip_to_oid(const ip_addr_t *ip, u32_t *oid);
00314 u8_t snmp_ip_port_to_oid(const ip_addr_t *ip, u16_t port, u32_t *oid);
00315 
00316 u8_t snmp_oid_to_ip(const u32_t *oid, u8_t oid_len, ip_addr_t *ip);
00317 u8_t snmp_oid_to_ip_port(const u32_t *oid, u8_t oid_len, ip_addr_t *ip, u16_t *port);
00318 #endif /* LWIP_IPV4 || LWIP_IPV6 */
00319 
00320 struct netif;
00321 u8_t netif_to_num(const struct netif *netif);
00322 
00323 snmp_err_t snmp_set_test_ok(struct snmp_node_instance* instance, u16_t value_len, void* value); /* generic function which can be used if test is always successful */
00324 
00325 err_t snmp_decode_bits(const u8_t *buf, u32_t buf_len, u32_t *bit_value);
00326 err_t snmp_decode_truthvalue(const s32_t *asn1_value, u8_t *bool_value);
00327 u8_t  snmp_encode_bits(u8_t *buf, u32_t buf_len, u32_t bit_value, u8_t bit_count);
00328 u8_t  snmp_encode_truthvalue(s32_t *asn1_value, u32_t bool_value);
00329 
00330 struct snmp_statistics
00331 {
00332   u32_t inpkts;
00333   u32_t outpkts;
00334   u32_t inbadversions;
00335   u32_t inbadcommunitynames;
00336   u32_t inbadcommunityuses;
00337   u32_t inasnparseerrs;
00338   u32_t intoobigs;
00339   u32_t innosuchnames;
00340   u32_t inbadvalues;
00341   u32_t inreadonlys;
00342   u32_t ingenerrs;
00343   u32_t intotalreqvars;
00344   u32_t intotalsetvars;
00345   u32_t ingetrequests;
00346   u32_t ingetnexts;
00347   u32_t insetrequests;
00348   u32_t ingetresponses;
00349   u32_t intraps;
00350   u32_t outtoobigs;
00351   u32_t outnosuchnames;
00352   u32_t outbadvalues;
00353   u32_t outgenerrs;
00354   u32_t outgetrequests;
00355   u32_t outgetnexts;
00356   u32_t outsetrequests;
00357   u32_t outgetresponses;
00358   u32_t outtraps;
00359 #if LWIP_SNMP_V3
00360   u32_t unsupportedseclevels;
00361   u32_t notintimewindows;
00362   u32_t unknownusernames;
00363   u32_t unknownengineids;
00364   u32_t wrongdigests;
00365   u32_t decryptionerrors;
00366 #endif
00367 };
00368 
00369 extern struct snmp_statistics snmp_stats;
00370 
00371 #ifdef __cplusplus
00372 }
00373 #endif
00374 
00375 #endif /* LWIP_SNMP */
00376 
00377 #endif /* LWIP_HDR_APPS_SNMP_CORE_H */