xref: /freebsd/contrib/bsnmp/lib/bsnmplib.3 (revision bb15ca603fa442c72dde3f3cb8b46db6970e3950)
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