contrib/bsnmp/lib/bsnmplib.3

   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
  63 Begemot 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
 103 The SNMP library contains routines to handle SNMP version 1, 2 and 3 PDUs.
 104 There are several basic structures used throughout the library:
 105 .Bd -literal -offset indent
 106 struct 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
 124 This structure represents one variable binding from an SNMP PDU.
 125 The field
 126 .Fa var
 127 is the ASN.1 of the variable that is bound.
 128 .Fa syntax
 129 contains either the syntax code of the value or an exception code for SNMPv2
 130 and may be one of:
 131 .Bd -literal -offset indent
 132 enum 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
 150 The field
 151 .Fa v
 152 holds the actual value depending on
 153 .Fa syntax .
 154 Note, that if
 155 .Fa syntax
 156 is
 157 .Li SNMP_SYNTAX_OCTETSTRING
 158 and
 159 .Fa v.octetstring.len
 160 is not zero,
 161 .Fa v.octetstring.octets
 162 points to a string allocated by
 163 .Xr malloc 3 .
 164 .Pp
 165 .Bd -literal -offset indent
 166 #define SNMP_ENGINE_ID_SIZ              32
 167
 168 struct 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
 177 This structure represents an SNMP engine as specified by the SNMP Management
 178 Architecture 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
 185 enum snmp_usm_level {
 186         SNMP_noAuthNoPriv = 1,
 187         SNMP_authNoPriv = 2,
 188         SNMP_authPriv = 3
 189 };
 190
 191 struct 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
 200 This structure represents an SNMPv3 user as specified by the User-based
 201 Security Model (USM) described in RFC 3414. The field
 202 .Fa sec_name
 203 is a human readable string containing the security user name.
 204 .Fa auth_proto
 205 contains the id of the authentication protocol in use by the user and may be one
 206 of:
 207 .Bd -literal -offset indent
 208 enum snmp_authentication {
 209         SNMP_AUTH_NOAUTH = 0,
 210         SNMP_AUTH_HMAC_MD5,
 211         SNMP_AUTH_HMAC_SHA
 212 };
 213 .Ed
 214 .Fa priv_proto
 215 contains the id of the privacy protocol in use by the user and may be one
 216 of:
 217 .Bd -literal -offset indent
 218 enum snmp_privacy {
 219         SNMP_PRIV_NOPRIV = 0,
 220         SNMP_PRIV_DES = 1,
 221         SNMP_PRIV_AES
 222 };
 223 .Ed
 224 .Fa auth_key
 225 and
 226 .Fa priv_key
 227 contain 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
 246 struct 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
 294 This structure contains a decoded SNMP PDU.
 295 .Fa version
 296 is one of
 297 .Bd -literal -offset indent
 298 enum snmp_version {
 299         SNMP_Verr = 0,
 300         SNMP_V1 = 1,
 301         SNMP_V2c,
 302         SNMP_V3
 303 };
 304 .Ed
 305 and
 306 .Fa type
 307 is the type of the PDU.
 308 .Fa security_model
 309 is the security model used for SNMPv3 PDUs. The only supported
 310 value currently is 3 (User-based Security Model). Additional values for any,
 311 unknown, SNMPv1 and SNMPv2c security models are also enumerated
 312 .Bd -literal -offset indent
 313 enum 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
 322 The function
 323 .Fn snmp_value_free
 324 is used to free all the dynamic allocated contents of an SNMP value.
 325 It does not free the structure pointed to by
 326 .Fa value
 327 itself.
 328 .Pp
 329 The function
 330 .Fn snmp_value_parse
 331 parses the ASCII representation of an SNMP value into its binary form.
 332 This function is mainly used by the configuration file reader of
 333 .Xr bsnmpd 1 .
 334 .Pp
 335 The function
 336 .Fn snmp_value_copy
 337 makes a deep copy of the value pointed to by
 338 .Fa from
 339 to the structure pointed to by
 340 .Fa to .
 341 It assumes that
 342 .Fa to
 343 is uninitialized and will overwrite its previous contents.
 344 It does not itself allocate the structure pointed to by
 345 .Fa to .
 346 .Pp
 347 The function
 348 .Fn snmp_pdu_free
 349 frees all the dynamically allocated components of the PDU.
 350 It does not itself free the structure pointed to by
 351 .Fa pdu .
 352 .Pp
 353 The function
 354 .Fn snmp_pdu_decode
 355 decodes the PDU pointed to by
 356 .Fa buf
 357 and stores the result into
 358 .Fa pdu .
 359 If an error occurs in a variable binding the (1 based) index of this binding
 360 is stored in the variable pointed to by
 361 .Fa ip .
 362 .Pp
 363 The function
 364 .Fn snmp_pdu_encode
 365 encodes the PDU
 366 .Fa pdu
 367 into the an octetstring in buffer, and if authentication and privacy are used,
 368 calculates a message digest and encrypts the PDU data in the buffer
 369 .Fa buf .
 370 .Pp
 371 The function
 372 .Fn snmp_pdu_decode_header
 373 decodes the header of the PDU pointed to by
 374 .Fa buf .
 375 The uncoded PDU contents remain in the buffer.
 376 .Pp
 377 The function
 378 .Fn snmp_pdu_decode_scoped
 379 decodes the scoped PDU pointed to by
 380 .Fa buf .
 381 .Pp
 382 The function
 383 .Fn snmp_pdu_decode_secmode
 384 verifies the authentication parameter contained in the PDU (if present) and
 385 if the PDU is encrypted, decrypts the PDU contents pointed to by
 386 .Fa buf .
 387 If successfull, a plain text scoped PDU is stored in the buffer.
 388 .Pp
 389 The function
 390 .Fn snmp_pdu_init_secparams
 391 calculates the initialization vector for the privacy protocol in use before
 392 the PDU pointed to by
 393 .Fa pdu
 394 may be encrypted or decrypted.
 395 .Pp
 396 The function
 397 .Fn snmp_pdu_dump
 398 dumps the PDU in a human readable form by calling
 399 .Fn snmp_printf .
 400 .Pp
 401 The function
 402 .Fn snmp_passwd_to_keys
 403 calculates a binary private authentication key corresponding to a plain text human
 404 readable password string. The calculated key is placed in the
 405 .Fa auth_key
 406 field of the
 407 .Fa user .
 408 .Pp
 409 The function
 410 .Fn snmp_get_local_keys
 411 calculates a localazied authentication and privacy keys for a specified SNMPv3
 412 engine. The calculateds keys are placed in the
 413 .Fa auth_key
 414 and
 415 .Fa priv_key
 416 fields of the
 417 .Fa user .
 418 .Pp
 419 The function
 420 .Fn snmp_calc_keychange
 421 calculates a binary key change octet string based on the contents of an old and
 422 a new binary localized key. The rezult is placed in the buffer pointer to by
 423 .Fa keychange
 424 and may be used by an SNMPv3 user who wishes to change his/her password
 425 or localized key.
 426 .Pp
 427 The function
 428 .Fn TRUTH_MK
 429 takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
 430 The function
 431 .Fn TRUTH_GET
 432 takes an SNMP truth value and makes a C truth value (0 or 1).
 433 The function
 434 .Fn TRUTH_OK
 435 checks, whether its argument is a legal SNMP truth value.
 436 .Sh DIAGNOSTICS
 437 When an error occurs in any of the function the function pointed to
 438 by the global pointer
 439 .Bd -literal -offset indent
 440 extern void (*snmp_error)(const char *, ...);
 441 .Ed
 442 .Pp
 443 with a
 444 .Xr printf 3
 445 style format string.
 446 There is a default error handler in the library that prints a message
 447 starting with
 448 .Sq SNMP:
 449 followed by the error message to standard error.
 450 .Pp
 451 The function pointed to by
 452 .Bd -literal -offset indent
 453 extern void (*snmp_printf)(const char *, ...);
 454 .Ed
 455 .Pp
 456 is called by the
 457 .Fn snmp_pdu_dump
 458 function.
 459 The default handler is
 460 .Xr printf 3 .
 461 .Sh ERRORS
 462 .Fn snmp_pdu_decode
 463 will return one of the following return codes:
 464 .Bl -tag -width Er
 465 .It Bq Er SNMP_CODE_OK
 466 Success.
 467 .It Bq Er SNMP_CODE_FAILED
 468 The ASN.1 coding was wrong.
 469 .It Bq Er SNMP_CODE_BADLEN
 470 A variable binding value had a wrong length field.
 471 .It Bq Er SNMP_CODE_OORANGE
 472 A variable binding value was out of the allowed range.
 473 .It Bq Er SNMP_CODE_BADVERS
 474 The PDU is of an unsupported version.
 475 .It Bq Er SNMP_CODE_BADENQ
 476 There was an ASN.1 value with an unsupported tag.
 477 .It Bq Er SNMP_CODE_BADSECLEVEL
 478 The requested securityLevel contained in the PDU is not supported.
 479 .It Bq Er SNMP_CODE_BADDIGEST
 480 The PDU authentication parameter received in the PDU did not match the
 481 calculated message digest.
 482 .It Bq Er SNMP_CODE_EDECRYPT
 483 Error occured while trying to decrypt the PDU.
 484 .El
 485 .Pp
 486 .Fn snmp_pdu_encode
 487 will return one of the following return codes:
 488 .Bl -tag -width Er
 489 .It Bq Er SNMP_CODE_OK
 490 Success.
 491 .It Bq Er SNMP_CODE_FAILED
 492 Encoding 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
 501 The SNMPv3 message digests, encryption and decryption, and key routines use
 502 the cryptographic functions from
 503 .Xr crypto 3 .
 504 The library may optionally be built without references to the
 505 .Xr crypto 3
 506 library. In such case only plain text SNMPv3 PDUs without message digests
 507 may be proccessed correctly.
 508 .Sh STANDARDS
 509 This implementation conforms to the applicable IETF RFCs and ITU-T
 510 recommendations.
 511 .Sh AUTHORS
 512 The 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
 516 added support for the SNMPv3 message proccessing and User-Based
 517 Security model message authentication and privacy.