2 .\" Copyright (c) 2010 The FreeBSD Foundation
3 .\" All rights reserved.
5 .\" Portions of this documentation were written by Shteryana Sotirova Shopova
6 .\" under sponsorship from the FreeBSD Foundation.
8 .\" Copyright (c) 2004-2005
10 .\" All rights reserved.
11 .\" Copyright (c) 2001-2003
12 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
13 .\" All rights reserved.
15 .\" Author: Harti Brandt <harti@FreeBSD.org>
17 .\" Redistribution and use in source and binary forms, with or without
18 .\" modification, are permitted provided that the following conditions
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.
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
38 .\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $
45 .Nm snmp_value_parse ,
50 .Nm snmp_pdu_decode_header ,
51 .Nm snmp_pdu_decode_scoped ,
52 .Nm snmp_pdu_decode_secmode ,
53 .Nm snmp_pdu_init_secparams ,
55 .Nm snmp_passwd_to_keys ,
56 .Nm snmp_get_local_keys ,
57 .Nm snmp_calc_keychange ,
61 .Nd "SNMP decoding and encoding library"
69 .Fn snmp_value_free "struct snmp_value *value"
71 .Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value"
73 .Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from"
75 .Fn snmp_pdu_free "struct snmp_pdu *value"
77 .Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
79 .Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf"
81 .Fn snmp_pdu_decode_header "struct snmp_pdu *pdu" "struct asn_buf *buf"
83 .Fn snmp_pdu_decode_scoped "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
85 .Fn snmp_pdu_decode_secmode "struct asn_buf *buf" "struct snmp_pdu *pdu"
87 .Fn snmp_pdu_init_secparams "struct snmp_pdu *pdu"
89 .Fn snmp_pdu_dump "const struct snmp_pdu *pdu"
91 .Fn snmp_passwd_to_keys "struct snmp_user *user" "char *passwd"
93 .Fn snmp_get_local_keys "struct snmp_user *user" "uint8_t *eid" "uint32_t elen"
95 .Fn snmp_calc_keychange "struct snmp_user *user" "uint8_t *keychange"
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
108 enum snmp_syntax syntax;
110 int32_t integer;/* also integer32 */
117 uint32_t uint32; /* also gauge32, counter32,
118 unsigned32, timeticks */
124 This structure represents one variable binding from an SNMP PDU.
127 is the ASN.1 of the variable that is bound.
129 contains either the syntax code of the value or an exception code for SNMPv2
131 .Bd -literal -offset indent
133 SNMP_SYNTAX_NULL = 0,
134 SNMP_SYNTAX_INTEGER, /* == INTEGER32 */
135 SNMP_SYNTAX_OCTETSTRING,
137 SNMP_SYNTAX_IPADDRESS,
139 SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */
140 SNMP_SYNTAX_TIMETICKS,
143 SNMP_SYNTAX_COUNTER64,
145 SNMP_SYNTAX_NOSUCHOBJECT,
146 SNMP_SYNTAX_NOSUCHINSTANCE,
147 SNMP_SYNTAX_ENDOFMIBVIEW,
152 holds the actual value depending on
157 .Li SNMP_SYNTAX_OCTETSTRING
159 .Fa v.octetstring.len
161 .Fa v.octetstring.octets
162 points to a string allocated by
164 .Bd -literal -offset indent
165 #define SNMP_ENGINE_ID_SIZ 32
168 uint8_t engine_id[SNMP_ENGINE_ID_SIZ];
170 int32_t engine_boots;
172 int32_t max_msg_size;
176 This structure represents an SNMP engine as specified by the SNMP Management
177 Architecture described in RFC 3411.
178 .Bd -literal -offset indent
179 #define SNMP_ADM_STR32_SIZ (32 + 1)
180 #define SNMP_AUTH_KEY_SIZ 40
181 #define SNMP_PRIV_KEY_SIZ 32
183 enum snmp_usm_level {
184 SNMP_noAuthNoPriv = 1,
190 char sec_name[SNMP_ADM_STR32_SIZ];
191 enum snmp_authentication auth_proto;
192 enum snmp_privacy priv_proto;
193 uint8_t auth_key[SNMP_AUTH_KEY_SIZ];
194 uint8_t priv_key[SNMP_PRIV_KEY_SIZ];
198 This structure represents an SNMPv3 user as specified by the User-based
199 Security Model (USM) described in RFC 3414. The field
201 is a human readable string containing the security user name.
203 contains the id of the authentication protocol in use by the user and may be one
205 .Bd -literal -offset indent
206 enum snmp_authentication {
207 SNMP_AUTH_NOAUTH = 0,
213 contains the id of the privacy protocol in use by the user and may be one
215 .Bd -literal -offset indent
217 SNMP_PRIV_NOPRIV = 0,
225 contain the authentication and privacy keys for the user.
226 .Bd -literal -offset indent
227 #define SNMP_COMMUNITY_MAXLEN 128
228 #define SNMP_MAX_BINDINGS 100
229 #define SNMP_CONTEXT_NAME_SIZ (32 + 1)
230 #define SNMP_TIME_WINDOW 150
232 #define SNMP_USM_AUTH_SIZE 12
233 #define SNMP_USM_PRIV_SIZE 8
235 #define SNMP_MSG_AUTH_FLAG 0x1
236 #define SNMP_MSG_PRIV_FLAG 0x2
237 #define SNMP_MSG_REPORT_FLAG 0x4
239 #define SNMP_MPM_SNMP_V1 0
240 #define SNMP_MPM_SNMP_V2c 1
241 #define SNMP_MPM_SNMP_V3 3
244 char community[SNMP_COMMUNITY_MAXLEN + 1];
245 enum snmp_version version;
248 /* SNMPv3 PDU header fields */
251 int32_t security_model;
252 struct snmp_engine engine;
254 /* Associated USM user parameters */
255 struct snmp_user user;
256 uint8_t msg_digest[SNMP_USM_AUTH_SIZE];
257 uint8_t msg_salt[SNMP_USM_PRIV_SIZE];
259 /* View-based Access Model */
260 uint32_t context_engine_len;
261 uint8_t context_engine[SNMP_ENGINE_ID_SIZ];
262 char context_name[SNMP_CONTEXT_NAME_SIZ];
265 struct asn_oid enterprise;
266 u_char agent_addr[4];
267 int32_t generic_trap;
268 int32_t specific_trap;
273 int32_t error_status;
276 /* fixes for encoding */
281 u_char *encrypted_ptr;
287 struct snmp_value bindings[SNMP_MAX_BINDINGS];
291 This structure contains a decoded SNMP PDU.
294 .Bd -literal -offset indent
304 is the type of the PDU.
306 is the security model used for SNMPv3 PDUs. The only supported
307 value currently is 3 (User-based Security Model). Additional values for any,
308 unknown, SNMPv1 and SNMPv2c security models are also enumerated
309 .Bd -literal -offset indent
311 SNMP_SECMODEL_ANY = 0,
312 SNMP_SECMODEL_SNMPv1 = 1,
313 SNMP_SECMODEL_SNMPv2c = 2,
314 SNMP_SECMODEL_USM = 3,
315 SNMP_SECMODEL_UNKNOWN
321 is used to free all the dynamic allocated contents of an SNMP value.
322 It does not free the structure pointed to by
328 parses the ASCII representation of an SNMP value into its binary form.
329 This function is mainly used by the configuration file reader of
334 makes a deep copy of the value pointed to by
336 to the structure pointed to by
340 is uninitialized and will overwrite its previous contents.
341 It does not itself allocate the structure pointed to by
346 frees all the dynamically allocated components of the PDU.
347 It does not itself free the structure pointed to by
352 decodes the PDU pointed to by
354 and stores the result into
356 If an error occurs in a variable binding the (1 based) index of this binding
357 is stored in the variable pointed to by
364 into the an octetstring in buffer, and if authentication and privacy are used,
365 calculates a message digest and encrypts the PDU data in the buffer
369 .Fn snmp_pdu_decode_header
370 decodes the header of the PDU pointed to by
372 The uncoded PDU contents remain in the buffer.
375 .Fn snmp_pdu_decode_scoped
376 decodes the scoped PDU pointed to by
380 .Fn snmp_pdu_decode_secmode
381 verifies the authentication parameter contained in the PDU (if present) and
382 if the PDU is encrypted, decrypts the PDU contents pointed to by
384 If successfull, a plain text scoped PDU is stored in the buffer.
387 .Fn snmp_pdu_init_secparams
388 calculates the initialization vector for the privacy protocol in use before
389 the PDU pointed to by
391 may be encrypted or decrypted.
395 dumps the PDU in a human readable form by calling
399 .Fn snmp_passwd_to_keys
400 calculates a binary private authentication key corresponding to a plain text human
401 readable password string. The calculated key is placed in the
407 .Fn snmp_get_local_keys
408 calculates a localazied authentication and privacy keys for a specified SNMPv3
409 engine. The calculateds keys are placed in the
417 .Fn snmp_calc_keychange
418 calculates a binary key change octet string based on the contents of an old and
419 a new binary localized key. The rezult is placed in the buffer pointer to by
421 and may be used by an SNMPv3 user who wishes to change his/her password
426 takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
429 takes an SNMP truth value and makes a C truth value (0 or 1).
432 checks, whether its argument is a legal SNMP truth value.
434 When an error occurs in any of the function the function pointed to
435 by the global pointer
436 .Bd -literal -offset indent
437 extern void (*snmp_error)(const char *, ...);
443 There is a default error handler in the library that prints a message
446 followed by the error message to standard error.
448 The function pointed to by
449 .Bd -literal -offset indent
450 extern void (*snmp_printf)(const char *, ...);
456 The default handler is
460 will return one of the following return codes:
462 .It Bq Er SNMP_CODE_OK
464 .It Bq Er SNMP_CODE_FAILED
465 The ASN.1 coding was wrong.
466 .It Bq Er SNMP_CODE_BADLEN
467 A variable binding value had a wrong length field.
468 .It Bq Er SNMP_CODE_OORANGE
469 A variable binding value was out of the allowed range.
470 .It Bq Er SNMP_CODE_BADVERS
471 The PDU is of an unsupported version.
472 .It Bq Er SNMP_CODE_BADENQ
473 There was an ASN.1 value with an unsupported tag.
474 .It Bq Er SNMP_CODE_BADSECLEVEL
475 The requested securityLevel contained in the PDU is not supported.
476 .It Bq Er SNMP_CODE_BADDIGEST
477 The PDU authentication parameter received in the PDU did not match the
478 calculated message digest.
479 .It Bq Er SNMP_CODE_EDECRYPT
480 Error occured while trying to decrypt the PDU.
484 will return one of the following return codes:
486 .It Bq Er SNMP_CODE_OK
488 .It Bq Er SNMP_CODE_FAILED
498 The SNMPv3 message digests, encryption and decryption, and key routines use
499 the cryptographic functions from
501 The library may optionally be built without references to the
503 library. In such case only plain text SNMPv3 PDUs without message digests
504 may be proccessed correctly.
506 This implementation conforms to the applicable IETF RFCs and ITU-T
509 The Begemot SNMP library was originally written by
510 .An Hartmut Brandt Aq harti@FreeBSD.org
512 .An Shteryana Shopova Aq syrinx@FreeBSD.org
513 added support for the SNMPv3 message proccessing and User-Based
514 Security model message authentication and privacy.