1.\" 2.\" Copyright (c) 2010 The FreeBSD Foundation 3.\" All rights reserved. 4.\" 5.\" Portions of this documentation were written by Shteryana Sotirova Shopova 6.\" under sponsorship from the FreeBSD Foundation. 7.\" 8.\" Copyright (c) 2004-2005 9.\" Hartmut Brandt. 10.\" All rights reserved. 11.\" Copyright (c) 2001-2003 12.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). 13.\" All rights reserved. 14.\" 15.\" Author: Harti Brandt <harti@FreeBSD.org> 16.\" 17.\" Redistribution and use in source and binary forms, with or without 18.\" modification, are permitted provided that the following conditions 19.\" are met: 20.\" 1. Redistributions of source code must retain the above copyright 21.\" notice, this list of conditions and the following disclaimer. 22.\" 2. Redistributions in binary form must reproduce the above copyright 23.\" notice, this list of conditions and the following disclaimer in the 24.\" documentation and/or other materials provided with the distribution. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $ 39.\" 40.Dd December 19, 2010 41.Dt BSNMPLIB 3 42.Os 43.Sh NAME 44.Nm snmp_value_free , 45.Nm snmp_value_parse , 46.Nm snmp_value_copy , 47.Nm snmp_pdu_free , 48.Nm snmp_pdu_decode , 49.Nm snmp_pdu_encode , 50.Nm snmp_pdu_decode_header , 51.Nm snmp_pdu_decode_scoped , 52.Nm snmp_pdu_decode_secmode , 53.Nm snmp_pdu_init_secparams , 54.Nm snmp_pdu_dump , 55.Nm snmp_passwd_to_keys , 56.Nm snmp_get_local_keys , 57.Nm snmp_calc_keychange , 58.Nm TRUTH_MK , 59.Nm TRUTH_GET , 60.Nm TRUTH_OK 61.Nd "SNMP decoding and encoding library" 62.Sh LIBRARY 63Begemot SNMP library 64.Pq libbsnmp, -lbsnmp 65.Sh SYNOPSIS 66.In bsnmp/asn1.h 67.In bsnmp/snmp.h 68.Ft void 69.Fn snmp_value_free "struct snmp_value *value" 70.Ft int 71.Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value" 72.Ft int 73.Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from" 74.Ft void 75.Fn snmp_pdu_free "struct snmp_pdu *value" 76.Ft enum snmp_code 77.Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip" 78.Ft enum snmp_code 79.Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf" 80.Ft enum snmp_code 81.Fn snmp_pdu_decode_header "struct snmp_pdu *pdu" "struct asn_buf *buf" 82.Ft enum snmp_code 83.Fn snmp_pdu_decode_scoped "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip" 84.Ft enum snmp_code 85.Fn snmp_pdu_decode_secmode "struct asn_buf *buf" "struct snmp_pdu *pdu" 86.Ft void 87.Fn snmp_pdu_init_secparams "struct snmp_pdu *pdu" 88.Ft void 89.Fn snmp_pdu_dump "const struct snmp_pdu *pdu" 90.Ft enum snmp_code 91.Fn snmp_passwd_to_keys "struct snmp_user *user" "char *passwd" 92.Ft enum snmp_code 93.Fn snmp_get_local_keys "struct snmp_user *user" "uint8_t *eid" "uint32_t elen" 94.Ft enum snmp_code 95.Fn snmp_calc_keychange "struct snmp_user *user" "uint8_t *keychange" 96.Ft int 97.Fn TRUTH_MK "F" 98.Ft int 99.Fn TRUTH_GET "T" 100.Ft int 101.Fn TRUTH_OK "T" 102.Sh DESCRIPTION 103The SNMP library contains routines to handle SNMP version 1, 2 and 3 PDUs. 104There are several basic structures used throughout the library: 105.Bd -literal -offset indent 106struct snmp_value { 107 struct asn_oid var; 108 enum snmp_syntax syntax; 109 union snmp_values { 110 int32_t integer;/* also integer32 */ 111 struct { 112 u_int len; 113 u_char *octets; 114 } octetstring; 115 struct asn_oid oid; 116 u_char ipaddress[4]; 117 uint32_t uint32; /* also gauge32, counter32, 118 unsigned32, timeticks */ 119 uint64_t counter64; 120 } v; 121}; 122.Ed 123.Pp 124This structure represents one variable binding from an SNMP PDU. 125The field 126.Fa var 127is the ASN.1 of the variable that is bound. 128.Fa syntax 129contains either the syntax code of the value or an exception code for SNMPv2 130and may be one of: 131.Bd -literal -offset indent 132enum snmp_syntax { 133 SNMP_SYNTAX_NULL = 0, 134 SNMP_SYNTAX_INTEGER, /* == INTEGER32 */ 135 SNMP_SYNTAX_OCTETSTRING, 136 SNMP_SYNTAX_OID, 137 SNMP_SYNTAX_IPADDRESS, 138 SNMP_SYNTAX_COUNTER, 139 SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */ 140 SNMP_SYNTAX_TIMETICKS, 141 142 /* v2 additions */ 143 SNMP_SYNTAX_COUNTER64, 144 /* exceptions */ 145 SNMP_SYNTAX_NOSUCHOBJECT, 146 SNMP_SYNTAX_NOSUCHINSTANCE, 147 SNMP_SYNTAX_ENDOFMIBVIEW, 148}; 149.Ed 150The field 151.Fa v 152holds the actual value depending on 153.Fa syntax . 154Note, that if 155.Fa syntax 156is 157.Li SNMP_SYNTAX_OCTETSTRING 158and 159.Fa v.octetstring.len 160is not zero, 161.Fa v.octetstring.octets 162points to a string allocated by 163.Xr malloc 3 . 164.Pp 165.Bd -literal -offset indent 166#define SNMP_ENGINE_ID_SIZ 32 167 168struct snmp_engine { 169 uint8_t engine_id[SNMP_ENGINE_ID_SIZ]; 170 uint32_t engine_len; 171 int32_t engine_boots; 172 int32_t engine_time; 173 int32_t max_msg_size; 174}; 175.Ed 176.Pp 177This structure represents an SNMP engine as specified by the SNMP Management 178Architecture described in RFC 3411. 179.Pp 180.Bd -literal -offset indent 181#define SNMP_ADM_STR32_SIZ (32 + 1) 182#define SNMP_AUTH_KEY_SIZ 40 183#define SNMP_PRIV_KEY_SIZ 32 184 185enum snmp_usm_level { 186 SNMP_noAuthNoPriv = 1, 187 SNMP_authNoPriv = 2, 188 SNMP_authPriv = 3 189}; 190 191struct snmp_user { 192 char sec_name[SNMP_ADM_STR32_SIZ]; 193 enum snmp_authentication auth_proto; 194 enum snmp_privacy priv_proto; 195 uint8_t auth_key[SNMP_AUTH_KEY_SIZ]; 196 uint8_t priv_key[SNMP_PRIV_KEY_SIZ]; 197}; 198.Ed 199.Pp 200This structure represents an SNMPv3 user as specified by the User-based 201Security Model (USM) described in RFC 3414. The field 202.Fa sec_name 203is a human readable string containing the security user name. 204.Fa auth_proto 205contains the id of the authentication protocol in use by the user and may be one 206of: 207.Bd -literal -offset indent 208enum snmp_authentication { 209 SNMP_AUTH_NOAUTH = 0, 210 SNMP_AUTH_HMAC_MD5, 211 SNMP_AUTH_HMAC_SHA 212}; 213.Ed 214.Fa priv_proto 215contains the id of the privacy protocol in use by the user and may be one 216of: 217.Bd -literal -offset indent 218enum snmp_privacy { 219 SNMP_PRIV_NOPRIV = 0, 220 SNMP_PRIV_DES = 1, 221 SNMP_PRIV_AES 222}; 223.Ed 224.Fa auth_key 225and 226.Fa priv_key 227contain the authentication and privacy keys for the user. 228.Pp 229.Bd -literal -offset indent 230#define SNMP_COMMUNITY_MAXLEN 128 231#define SNMP_MAX_BINDINGS 100 232#define SNMP_CONTEXT_NAME_SIZ (32 + 1) 233#define SNMP_TIME_WINDOW 150 234 235#define SNMP_USM_AUTH_SIZE 12 236#define SNMP_USM_PRIV_SIZE 8 237 238#define SNMP_MSG_AUTH_FLAG 0x1 239#define SNMP_MSG_PRIV_FLAG 0x2 240#define SNMP_MSG_REPORT_FLAG 0x4 241 242#define SNMP_MPM_SNMP_V1 0 243#define SNMP_MPM_SNMP_V2c 1 244#define SNMP_MPM_SNMP_V3 3 245 246struct snmp_pdu { 247 char community[SNMP_COMMUNITY_MAXLEN + 1]; 248 enum snmp_version version; 249 u_int type; 250 251 /* SNMPv3 PDU header fields */ 252 int32_t identifier; 253 uint8_t flags; 254 int32_t security_model; 255 struct snmp_engine engine; 256 257 /* Associated USM user parameters */ 258 struct snmp_user user; 259 uint8_t msg_digest[SNMP_USM_AUTH_SIZE]; 260 uint8_t msg_salt[SNMP_USM_PRIV_SIZE]; 261 262 /* View-based Access Model */ 263 uint32_t context_engine_len; 264 uint8_t context_engine[SNMP_ENGINE_ID_SIZ]; 265 char context_name[SNMP_CONTEXT_NAME_SIZ]; 266 267 /* trap only */ 268 struct asn_oid enterprise; 269 u_char agent_addr[4]; 270 int32_t generic_trap; 271 int32_t specific_trap; 272 uint32_t time_stamp; 273 274 /* others */ 275 int32_t request_id; 276 int32_t error_status; 277 int32_t error_index; 278 279 /* fixes for encoding */ 280 size_t outer_len; 281 size_t scoped_len; 282 u_char *outer_ptr; 283 u_char *digest_ptr; 284 u_char *encrypted_ptr; 285 u_char *scoped_ptr; 286 u_char *pdu_ptr; 287 u_char *vars_ptr; 288 289 290 struct snmp_value bindings[SNMP_MAX_BINDINGS]; 291 u_int nbindings; 292}; 293.Ed 294This structure contains a decoded SNMP PDU. 295.Fa version 296is one of 297.Bd -literal -offset indent 298enum snmp_version { 299 SNMP_Verr = 0, 300 SNMP_V1 = 1, 301 SNMP_V2c, 302 SNMP_V3 303}; 304.Ed 305and 306.Fa type 307is the type of the PDU. 308.Fa security_model 309is the security model used for SNMPv3 PDUs. The only supported 310value currently is 3 (User-based Security Model). Additional values for any, 311unknown, SNMPv1 and SNMPv2c security models are also enumerated 312.Bd -literal -offset indent 313enum snmp_secmodel { 314 SNMP_SECMODEL_ANY = 0, 315 SNMP_SECMODEL_SNMPv1 = 1, 316 SNMP_SECMODEL_SNMPv2c = 2, 317 SNMP_SECMODEL_USM = 3, 318 SNMP_SECMODEL_UNKNOWN 319}; 320.Ed 321.Pp 322The function 323.Fn snmp_value_free 324is used to free all the dynamic allocated contents of an SNMP value. 325It does not free the structure pointed to by 326.Fa value 327itself. 328.Pp 329The function 330.Fn snmp_value_parse 331parses the ASCII representation of an SNMP value into its binary form. 332This function is mainly used by the configuration file reader of 333.Xr bsnmpd 1 . 334.Pp 335The function 336.Fn snmp_value_copy 337makes a deep copy of the value pointed to by 338.Fa from 339to the structure pointed to by 340.Fa to . 341It assumes that 342.Fa to 343is uninitialized and will overwrite its previous contents. 344It does not itself allocate the structure pointed to by 345.Fa to . 346.Pp 347The function 348.Fn snmp_pdu_free 349frees all the dynamically allocated components of the PDU. 350It does not itself free the structure pointed to by 351.Fa pdu . 352.Pp 353The function 354.Fn snmp_pdu_decode 355decodes the PDU pointed to by 356.Fa buf 357and stores the result into 358.Fa pdu . 359If an error occurs in a variable binding the (1 based) index of this binding 360is stored in the variable pointed to by 361.Fa ip . 362.Pp 363The function 364.Fn snmp_pdu_encode 365encodes the PDU 366.Fa pdu 367into the an octetstring in buffer, and if authentication and privacy are used, 368calculates a message digest and encrypts the PDU data in the buffer 369.Fa buf . 370.Pp 371The function 372.Fn snmp_pdu_decode_header 373decodes the header of the PDU pointed to by 374.Fa buf . 375The uncoded PDU contents remain in the buffer. 376.Pp 377The function 378.Fn snmp_pdu_decode_scoped 379decodes the scoped PDU pointed to by 380.Fa buf . 381.Pp 382The function 383.Fn snmp_pdu_decode_secmode 384verifies the authentication parameter contained in the PDU (if present) and 385if the PDU is encrypted, decrypts the PDU contents pointed to by 386.Fa buf . 387If successfull, a plain text scoped PDU is stored in the buffer. 388.Pp 389The function 390.Fn snmp_pdu_init_secparams 391calculates the initialization vector for the privacy protocol in use before 392the PDU pointed to by 393.Fa pdu 394may be encrypted or decrypted. 395.Pp 396The function 397.Fn snmp_pdu_dump 398dumps the PDU in a human readable form by calling 399.Fn snmp_printf . 400.Pp 401The function 402.Fn snmp_passwd_to_keys 403calculates a binary private authentication key corresponding to a plain text human 404readable password string. The calculated key is placed in the 405.Fa auth_key 406field of the 407.Fa user . 408.Pp 409The function 410.Fn snmp_get_local_keys 411calculates a localazied authentication and privacy keys for a specified SNMPv3 412engine. The calculateds keys are placed in the 413.Fa auth_key 414and 415.Fa priv_key 416fields of the 417.Fa user . 418.Pp 419The function 420.Fn snmp_calc_keychange 421calculates a binary key change octet string based on the contents of an old and 422a new binary localized key. The rezult is placed in the buffer pointer to by 423.Fa keychange 424and may be used by an SNMPv3 user who wishes to change his/her password 425or localized key. 426.Pp 427The function 428.Fn TRUTH_MK 429takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1). 430The function 431.Fn TRUTH_GET 432takes an SNMP truth value and makes a C truth value (0 or 1). 433The function 434.Fn TRUTH_OK 435checks, whether its argument is a legal SNMP truth value. 436.Sh DIAGNOSTICS 437When an error occurs in any of the function the function pointed to 438by the global pointer 439.Bd -literal -offset indent 440extern void (*snmp_error)(const char *, ...); 441.Ed 442.Pp 443with a 444.Xr printf 3 445style format string. 446There is a default error handler in the library that prints a message 447starting with 448.Sq SNMP: 449followed by the error message to standard error. 450.Pp 451The function pointed to by 452.Bd -literal -offset indent 453extern void (*snmp_printf)(const char *, ...); 454.Ed 455.Pp 456is called by the 457.Fn snmp_pdu_dump 458function. 459The default handler is 460.Xr printf 3 . 461.Sh ERRORS 462.Fn snmp_pdu_decode 463will return one of the following return codes: 464.Bl -tag -width Er 465.It Bq Er SNMP_CODE_OK 466Success. 467.It Bq Er SNMP_CODE_FAILED 468The ASN.1 coding was wrong. 469.It Bq Er SNMP_CODE_BADLEN 470A variable binding value had a wrong length field. 471.It Bq Er SNMP_CODE_OORANGE 472A variable binding value was out of the allowed range. 473.It Bq Er SNMP_CODE_BADVERS 474The PDU is of an unsupported version. 475.It Bq Er SNMP_CODE_BADENQ 476There was an ASN.1 value with an unsupported tag. 477.It Bq Er SNMP_CODE_BADSECLEVEL 478The requested securityLevel contained in the PDU is not supported. 479.It Bq Er SNMP_CODE_BADDIGEST 480The PDU authentication parameter received in the PDU did not match the 481calculated message digest. 482.It Bq Er SNMP_CODE_EDECRYPT 483Error occured while trying to decrypt the PDU. 484.El 485.Pp 486.Fn snmp_pdu_encode 487will return one of the following return codes: 488.Bl -tag -width Er 489.It Bq Er SNMP_CODE_OK 490Success. 491.It Bq Er SNMP_CODE_FAILED 492Encoding failed. 493.El 494.Sh SEE ALSO 495.Xr gensnmptree 1 , 496.Xr bsnmpd 1 , 497.Xr bsnmpagent 3 , 498.Xr bsnmpclient 3 , 499.Xr bsnmplib 3 500.Sh CAVEAT 501The SNMPv3 message digests, encryption and decryption, and key routines use 502the cryptographic functions from 503.Xr crypto 3 . 504The library may optionally be built without references to the 505.Xr crypto 3 506library. In such case only plain text SNMPv3 PDUs without message digests 507may be proccessed correctly. 508.Sh STANDARDS 509This implementation conforms to the applicable IETF RFCs and ITU-T 510recommendations. 511.Sh AUTHORS 512The Begemot SNMP library was originally written by 513.An Hartmut Brandt Aq harti@FreeBSD.org 514.Pp 515.An Shteryana Shopova Aq syrinx@FreeBSD.org 516added support for the SNMPv3 message proccessing and User-Based 517Security model message authentication and privacy. 518