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
165 .Bd -literal -offset indent
166 #define SNMP_ENGINE_ID_SIZ 32
169 uint8_t engine_id[SNMP_ENGINE_ID_SIZ];
171 int32_t engine_boots;
173 int32_t max_msg_size;
177 This structure represents an SNMP engine as specified by the SNMP Management
178 Architecture described in RFC 3411.
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
185 enum snmp_usm_level {
186 SNMP_noAuthNoPriv = 1,
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];
200 This structure represents an SNMPv3 user as specified by the User-based
201 Security Model (USM) described in RFC 3414. The field
203 is a human readable string containing the security user name.
205 contains the id of the authentication protocol in use by the user and may be one
207 .Bd -literal -offset indent
208 enum snmp_authentication {
209 SNMP_AUTH_NOAUTH = 0,
215 contains the id of the privacy protocol in use by the user and may be one
217 .Bd -literal -offset indent
219 SNMP_PRIV_NOPRIV = 0,
227 contain the authentication and privacy keys for the user.
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
235 #define SNMP_USM_AUTH_SIZE 12
236 #define SNMP_USM_PRIV_SIZE 8
238 #define SNMP_MSG_AUTH_FLAG 0x1
239 #define SNMP_MSG_PRIV_FLAG 0x2
240 #define SNMP_MSG_REPORT_FLAG 0x4
242 #define SNMP_MPM_SNMP_V1 0
243 #define SNMP_MPM_SNMP_V2c 1
244 #define SNMP_MPM_SNMP_V3 3
247 char community[SNMP_COMMUNITY_MAXLEN + 1];
248 enum snmp_version version;
251 /* SNMPv3 PDU header fields */
254 int32_t security_model;
255 struct snmp_engine engine;
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];
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];
268 struct asn_oid enterprise;
269 u_char agent_addr[4];
270 int32_t generic_trap;
271 int32_t specific_trap;
276 int32_t error_status;
279 /* fixes for encoding */
284 u_char *encrypted_ptr;
290 struct snmp_value bindings[SNMP_MAX_BINDINGS];
294 This structure contains a decoded SNMP PDU.
297 .Bd -literal -offset indent
307 is the type of the PDU.
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
314 SNMP_SECMODEL_ANY = 0,
315 SNMP_SECMODEL_SNMPv1 = 1,
316 SNMP_SECMODEL_SNMPv2c = 2,
317 SNMP_SECMODEL_USM = 3,
318 SNMP_SECMODEL_UNKNOWN
324 is used to free all the dynamic allocated contents of an SNMP value.
325 It does not free the structure pointed to by
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
337 makes a deep copy of the value pointed to by
339 to the structure pointed to by
343 is uninitialized and will overwrite its previous contents.
344 It does not itself allocate the structure pointed to by
349 frees all the dynamically allocated components of the PDU.
350 It does not itself free the structure pointed to by
355 decodes the PDU pointed to by
357 and stores the result into
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
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
372 .Fn snmp_pdu_decode_header
373 decodes the header of the PDU pointed to by
375 The uncoded PDU contents remain in the buffer.
378 .Fn snmp_pdu_decode_scoped
379 decodes the scoped PDU pointed to by
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
387 If successfull, a plain text scoped PDU is stored in the buffer.
390 .Fn snmp_pdu_init_secparams
391 calculates the initialization vector for the privacy protocol in use before
392 the PDU pointed to by
394 may be encrypted or decrypted.
398 dumps the PDU in a human readable form by calling
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
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
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
424 and may be used by an SNMPv3 user who wishes to change his/her password
429 takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
432 takes an SNMP truth value and makes a C truth value (0 or 1).
435 checks, whether its argument is a legal SNMP truth value.
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 *, ...);
446 There is a default error handler in the library that prints a message
449 followed by the error message to standard error.
451 The function pointed to by
452 .Bd -literal -offset indent
453 extern void (*snmp_printf)(const char *, ...);
459 The default handler is
463 will return one of the following return codes:
465 .It Bq Er SNMP_CODE_OK
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.
487 will return one of the following return codes:
489 .It Bq Er SNMP_CODE_OK
491 .It Bq Er SNMP_CODE_FAILED
501 The SNMPv3 message digests, encryption and decryption, and key routines use
502 the cryptographic functions from
504 The library may optionally be built without references to the
506 library. In such case only plain text SNMPv3 PDUs without message digests
507 may be proccessed correctly.
509 This implementation conforms to the applicable IETF RFCs and ITU-T
512 The Begemot SNMP library was originally written by
513 .An Hartmut Brandt Aq harti@FreeBSD.org
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.