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 #define SNMP_ASN1_TYPE_COUNTER64      (SNMP_ASN1_CLASS_APPLICATION | SNMP_ASN1_CONTENTTYPE_PRIMITIVE | SNMP_ASN1_APPLICATION_COUNTER64)
00095 
00096 #define SNMP_VARBIND_EXCEPTION_OFFSET 0xF0
00097 #define SNMP_VARBIND_EXCEPTION_MASK   0x0F
00098 
00099 /** error codes predefined by SNMP prot. */
00100 typedef enum {
00101   SNMP_ERR_NOERROR             = 0,
00102 /* 
00103 outdated v1 error codes. do not use anmore!
00104 #define SNMP_ERR_NOSUCHNAME 2  use SNMP_ERR_NOSUCHINSTANCE instead
00105 #define SNMP_ERR_BADVALUE   3  use SNMP_ERR_WRONGTYPE,SNMP_ERR_WRONGLENGTH,SNMP_ERR_WRONGENCODING or SNMP_ERR_WRONGVALUE instead
00106 #define SNMP_ERR_READONLY   4  use SNMP_ERR_NOTWRITABLE instead
00107 */
00108   SNMP_ERR_GENERROR            = 5,
00109   SNMP_ERR_NOACCESS            = 6,
00110   SNMP_ERR_WRONGTYPE           = 7,
00111   SNMP_ERR_WRONGLENGTH         = 8,
00112   SNMP_ERR_WRONGENCODING       = 9,
00113   SNMP_ERR_WRONGVALUE          = 10,
00114   SNMP_ERR_NOCREATION          = 11,
00115   SNMP_ERR_INCONSISTENTVALUE   = 12,
00116   SNMP_ERR_RESOURCEUNAVAILABLE = 13,
00117   SNMP_ERR_COMMITFAILED        = 14,
00118   SNMP_ERR_UNDOFAILED          = 15,
00119   SNMP_ERR_NOTWRITABLE         = 17,
00120   SNMP_ERR_INCONSISTENTNAME    = 18,
00121 
00122   SNMP_ERR_NOSUCHINSTANCE      = SNMP_VARBIND_EXCEPTION_OFFSET + SNMP_ASN1_CONTEXT_VARBIND_NO_SUCH_INSTANCE
00123 } snmp_err_t;
00124 
00125 /** internal object identifier representation */
00126 struct snmp_obj_id
00127 {
00128   u8_t len;
00129   u32_t id[SNMP_MAX_OBJ_ID_LEN];
00130 };
00131 
00132 struct snmp_obj_id_const_ref
00133 {
00134   u8_t len;
00135   const u32_t* id;
00136 };
00137 
00138 extern const struct snmp_obj_id_const_ref snmp_zero_dot_zero; /* administrative identifier from SNMPv2-SMI */
00139 
00140 /** SNMP variant value, used as reference in struct snmp_node_instance and table implementation */
00141 union snmp_variant_value
00142 {
00143   void* ptr;
00144   const void* const_ptr;
00145   u32_t u32;
00146   s32_t s32;
00147 };
00148 
00149 
00150 /**
00151 SNMP MIB node types
00152  tree node is the only node the stack can process in order to walk the tree,
00153  all other nodes are assumed to be leaf nodes.
00154  This cannot be an enum because users may want to define their own node types.
00155 */
00156 #define SNMP_NODE_TREE         0x00
00157 /* predefined leaf node types */
00158 #define SNMP_NODE_SCALAR       0x01
00159 #define SNMP_NODE_SCALAR_ARRAY 0x02
00160 #define SNMP_NODE_TABLE        0x03
00161 #define SNMP_NODE_THREADSYNC   0x04
00162 
00163 /** node "base class" layout, the mandatory fields for a node  */
00164 struct snmp_node
00165 {
00166   /** one out of SNMP_NODE_TREE or any leaf node type (like SNMP_NODE_SCALAR) */
00167   u8_t node_type;
00168   /** the number assigned to this node which used as part of the full OID */
00169   u32_t oid;
00170 };
00171 
00172 /** SNMP node instance access types */
00173 typedef enum {
00174   SNMP_NODE_INSTANCE_ACCESS_READ    = 1,
00175   SNMP_NODE_INSTANCE_ACCESS_WRITE   = 2,
00176   SNMP_NODE_INSTANCE_READ_ONLY      = SNMP_NODE_INSTANCE_ACCESS_READ,
00177   SNMP_NODE_INSTANCE_READ_WRITE     = (SNMP_NODE_INSTANCE_ACCESS_READ | SNMP_NODE_INSTANCE_ACCESS_WRITE),
00178   SNMP_NODE_INSTANCE_WRITE_ONLY     = SNMP_NODE_INSTANCE_ACCESS_WRITE,
00179   SNMP_NODE_INSTANCE_NOT_ACCESSIBLE = 0
00180 } snmp_access_t;
00181 
00182 struct snmp_node_instance;
00183 
00184 typedef s16_t (*node_instance_get_value_method)(struct snmp_node_instance*, void*);
00185 typedef snmp_err_t (*node_instance_set_test_method)(struct snmp_node_instance*, u16_t, void*);
00186 typedef snmp_err_t (*node_instance_set_value_method)(struct snmp_node_instance*, u16_t, void*);
00187 typedef void (*node_instance_release_method)(struct snmp_node_instance*);
00188 
00189 #define SNMP_GET_VALUE_RAW_DATA 0x8000
00190 
00191 /** SNMP node instance */
00192 struct snmp_node_instance
00193 {
00194   /** 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 */
00195   const struct snmp_node* node;
00196   /** 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 */
00197   struct snmp_obj_id instance_oid;
00198 
00199   /** ASN type for this object (see snmp_asn1.h for definitions) */
00200   u8_t asn1_type;
00201   /** one out of instance access types defined above (SNMP_NODE_INSTANCE_READ_ONLY,...) */
00202   snmp_access_t access;
00203 
00204   /** returns object value for the given object identifier. Return values <0 to indicate an error */
00205   node_instance_get_value_method get_value;
00206   /** tests length and/or range BEFORE setting */
00207   node_instance_set_test_method set_test;
00208   /** sets object value, only called when set_test() was successful */
00209   node_instance_set_value_method set_value;
00210   /** 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) */
00211   node_instance_release_method release_instance;
00212 
00213   /** reference to pass arbitrary value between calls to get_instance() and get_value/test_value/set_value */
00214   union snmp_variant_value reference;
00215   /** see reference (if reference is a pointer, the length of underlying data may be stored here or anything else) */
00216   u32_t reference_len;
00217 };
00218 
00219 
00220 /** SNMP tree node */
00221 struct snmp_tree_node
00222 {
00223   /** inherited "base class" members */
00224   struct snmp_node node;
00225   u16_t subnode_count;
00226   const struct snmp_node* const *subnodes;
00227 };
00228 
00229 #define SNMP_CREATE_TREE_NODE(oid, subnodes) \
00230   {{ SNMP_NODE_TREE, (oid) }, \
00231   (u16_t)LWIP_ARRAYSIZE(subnodes), (subnodes) }
00232 
00233 #define SNMP_CREATE_EMPTY_TREE_NODE(oid) \
00234   {{ SNMP_NODE_TREE, (oid) }, \
00235   0, NULL }
00236 
00237 /** SNMP leaf node */
00238 struct snmp_leaf_node
00239 {
00240   /** inherited "base class" members */
00241   struct snmp_node node;
00242   snmp_err_t (*get_instance)(const u32_t *root_oid, u8_t root_oid_len, struct snmp_node_instance* instance);
00243   snmp_err_t (*get_next_instance)(const u32_t *root_oid, u8_t root_oid_len, struct snmp_node_instance* instance);
00244 };
00245 
00246 /** represents a single mib with its base oid and root node */
00247 struct snmp_mib
00248 {
00249   const u32_t *base_oid;
00250   u8_t base_oid_len;
00251   const struct snmp_node *root_node;
00252 };
00253 
00254 #define SNMP_MIB_CREATE(oid_list, root_node) { (oid_list), (u8_t)LWIP_ARRAYSIZE(oid_list), root_node }
00255 
00256 /** OID range structure */
00257 struct snmp_oid_range
00258 {
00259   u32_t min;
00260   u32_t max;
00261 };
00262 
00263 /** checks if incoming OID length and values are in allowed ranges */
00264 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);
00265 
00266 typedef enum {
00267   SNMP_NEXT_OID_STATUS_SUCCESS,
00268   SNMP_NEXT_OID_STATUS_NO_MATCH,
00269   SNMP_NEXT_OID_STATUS_BUF_TO_SMALL
00270 } snmp_next_oid_status_t;
00271 
00272 /** state for next_oid_init / next_oid_check functions */
00273 struct snmp_next_oid_state
00274 {
00275   const u32_t* start_oid;
00276   u8_t start_oid_len;
00277 
00278   u32_t* next_oid;
00279   u8_t next_oid_len;
00280   u8_t next_oid_max_len;
00281 
00282   snmp_next_oid_status_t status;
00283   void* reference;
00284 };
00285 
00286 void snmp_next_oid_init(struct snmp_next_oid_state *state,
00287   const u32_t *start_oid, u8_t start_oid_len,
00288   u32_t *next_oid_buf, u8_t next_oid_max_len);
00289 u8_t snmp_next_oid_precheck(struct snmp_next_oid_state *state, const u32_t *oid, const u8_t oid_len);
00290 u8_t snmp_next_oid_check(struct snmp_next_oid_state *state, const u32_t *oid, const u8_t oid_len, void* reference);
00291 
00292 void snmp_oid_assign(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len);
00293 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);
00294 void snmp_oid_prefix(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len);
00295 void snmp_oid_append(struct snmp_obj_id* target, const u32_t *oid, u8_t oid_len);
00296 u8_t snmp_oid_equal(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len);
00297 s8_t snmp_oid_compare(const u32_t *oid1, u8_t oid1_len, const u32_t *oid2, u8_t oid2_len);
00298 
00299 #if LWIP_IPV4
00300 u8_t snmp_oid_to_ip4(const u32_t *oid, ip4_addr_t *ip);
00301 void snmp_ip4_to_oid(const ip4_addr_t *ip, u32_t *oid);
00302 #endif /* LWIP_IPV4 */
00303 #if LWIP_IPV6
00304 u8_t snmp_oid_to_ip6(const u32_t *oid, ip6_addr_t *ip);
00305 void snmp_ip6_to_oid(const ip6_addr_t *ip, u32_t *oid);
00306 #endif /* LWIP_IPV6 */
00307 #if LWIP_IPV4 || LWIP_IPV6
00308 u8_t snmp_ip_to_oid(const ip_addr_t *ip, u32_t *oid);
00309 u8_t snmp_ip_port_to_oid(const ip_addr_t *ip, u16_t port, u32_t *oid);
00310 
00311 u8_t snmp_oid_to_ip(const u32_t *oid, u8_t oid_len, ip_addr_t *ip);
00312 u8_t snmp_oid_to_ip_port(const u32_t *oid, u8_t oid_len, ip_addr_t *ip, u16_t *port);
00313 #endif /* LWIP_IPV4 || LWIP_IPV6 */
00314 
00315 struct netif;
00316 u8_t netif_to_num(const struct netif *netif);
00317 
00318 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 */
00319 
00320 err_t snmp_decode_bits(const u8_t *buf, u32_t buf_len, u32_t *bit_value);
00321 err_t snmp_decode_truthvalue(const s32_t *asn1_value, u8_t *bool_value);
00322 u8_t  snmp_encode_bits(u8_t *buf, u32_t buf_len, u32_t bit_value, u8_t bit_count);
00323 u8_t  snmp_encode_truthvalue(s32_t *asn1_value, u32_t bool_value);
00324 
00325 struct snmp_statistics
00326 {
00327   u32_t inpkts;
00328   u32_t outpkts;
00329   u32_t inbadversions;
00330   u32_t inbadcommunitynames;
00331   u32_t inbadcommunityuses;
00332   u32_t inasnparseerrs;
00333   u32_t intoobigs;
00334   u32_t innosuchnames;
00335   u32_t inbadvalues;
00336   u32_t inreadonlys;
00337   u32_t ingenerrs;
00338   u32_t intotalreqvars;
00339   u32_t intotalsetvars;
00340   u32_t ingetrequests;
00341   u32_t ingetnexts;
00342   u32_t insetrequests;
00343   u32_t ingetresponses;
00344   u32_t intraps;
00345   u32_t outtoobigs;
00346   u32_t outnosuchnames;
00347   u32_t outbadvalues;
00348   u32_t outgenerrs;
00349   u32_t outgetrequests;
00350   u32_t outgetnexts;
00351   u32_t outsetrequests;
00352   u32_t outgetresponses;
00353   u32_t outtraps;
00354 };
00355 
00356 extern struct snmp_statistics snmp_stats;
00357 
00358 #ifdef __cplusplus
00359 }
00360 #endif
00361 
00362 #endif /* LWIP_SNMP */
00363 
00364 #endif /* LWIP_HDR_APPS_SNMP_CORE_H */