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 unchanged lines hidden (view full) ---
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 September 9, 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_dump ,
54.Nm snmp_passwd_to_keys ,
55.Nm snmp_get_local_keys ,
56.Nm snmp_calc_keychange ,
57.Nm TRUTH_MK ,
58.Nm TRUTH_GET ,
59.Nm TRUTH_OK
60.Nd "SNMP decoding and encoding library"
61.Sh LIBRARY
62Begemot SNMP library
63.Pq libbsnmp, -lbsnmp
64.Sh SYNOPSIS
--- 6 unchanged lines hidden (view full) ---
71.Ft int
72.Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from"
73.Ft void
74.Fn snmp_pdu_free "struct snmp_pdu *value"
75.Ft enum snmp_code
76.Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
77.Ft enum snmp_code
78.Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf"
79.Ft enum snmp_code
80.Fn snmp_pdu_decode_header "struct snmp_pdu *pdu" "struct asn_buf *buf"
81.Ft enum snmp_code
82.Fn snmp_pdu_decode_scoped "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
83.Ft enum snmp_code
84.Fn snmp_pdu_decode_secmode "struct asn_buf *buf" "struct snmp_pdu *pdu"
85.Ft void
86.Fn snmp_pdu_dump "const struct snmp_pdu *pdu"
87.Ft enum snmp_code
88.Fn snmp_passwd_to_keys "struct snmp_user *user" "char *passwd"
89.Ft enum snmp_code
90.Fn snmp_get_local_keys "struct snmp_user *user" "uint8_t *eid" "uint32_t elen"
91.Ft enum snmp_code
92.Fn snmp_calc_keychange "struct snmp_user *user" "uint8_t *keychange"
93.Ft int
94.Fn TRUTH_MK "F"
95.Ft int
96.Fn TRUTH_GET "T"
97.Ft int
98.Fn TRUTH_OK "T"
99.Sh DESCRIPTION
100The SNMP library contains routines to handle SNMP version 1, 2 and 3 PDUs.
101There are several basic structures used throughout the library:
102.Bd -literal -offset indent
103struct snmp_value {
104 struct asn_oid var;
105 enum snmp_syntax syntax;
106 union snmp_values {
107 int32_t integer;/* also integer32 */
108 struct {
109 u_int len;
--- 43 unchanged lines hidden (view full) ---
153is
154.Li SNMP_SYNTAX_OCTETSTRING
155and
156.Fa v.octetstring.len
157is not zero,
158.Fa v.octetstring.octets
159points to a string allocated by
160.Xr malloc 3 .
161.Pp
162.Bd -literal -offset indent
163#define SNMP_ENGINE_ID_SIZ 32
164
165struct snmp_engine {
166 uint8_t engine_id[SNMP_ENGINE_ID_SIZ];
167 uint32_t engine_len;
168 int32_t engine_boots;
169 int32_t engine_time;
170 int32_t max_msg_size;
171};
172.Ed
173.Pp
174This structure represents an SNMP engine as specified by the SNMP Management
175Architecture described in RFC 3411.
176.Pp
177.Bd -literal -offset indent
178#define SNMP_USM_NAME_SIZ (32 + 1)
179#define SNMP_AUTH_KEY_SIZ 40
180#define SNMP_PRIV_KEY_SIZ 32
181
182struct snmp_user {
183 char sec_name[SNMP_USM_NAME_SIZ];
184 enum snmp_authentication auth_proto;
185 enum snmp_privacy priv_proto;
186 uint8_t auth_key[SNMP_AUTH_KEY_SIZ];
187 uint8_t priv_key[SNMP_PRIV_KEY_SIZ];
188};
189.Ed
190.Pp
191This structure represents an SNMPv3 user as specified by the User-based
192Security Model (USM) described in RFC 3414. The field
193.Fa sec_name
194is a human readable string containing the security user name.
195.Fa auth_proto
196contains the id of the authentication protocol in use by the user and may be one
197of:
198.Bd -literal -offset indent
199enum snmp_authentication {
200 SNMP_AUTH_NOAUTH = 0,
201 SNMP_AUTH_HMAC_MD5,
202 SNMP_AUTH_HMAC_SHA
203};
204.Ed
205.Fa priv_proto
206contains the id of the privacy protocol in use by the user and may be one
207of:
208.Bd -literal -offset indent
209enum snmp_privacy {
210 SNMP_PRIV_NOPRIV = 0,
211 SNMP_PRIV_DES = 1,
212 SNMP_PRIV_AES
213};
214.Ed
215.Fa auth_key
216and
217.Fa priv_key
218contain the authentication and privacy keys for the user.
219.Pp
220.Bd -literal -offset indent
221#define SNMP_COMMUNITY_MAXLEN 128
222#define SNMP_MAX_BINDINGS 100
223#define SNMP_CONTEXT_NAME_SIZ (32 + 1)
224#define SNMP_TIME_WINDOW 150
225
226#define SNMP_USM_AUTH_SIZE 12
227#define SNMP_USM_PRIV_SIZE 8
228
229#define SNMP_MSG_AUTH_FLAG 0x1
230#define SNMP_MSG_PRIV_FLAG 0x2
231#define SNMP_MSG_REPORT_FLAG 0x4
232
233#define SNMP_SECMODEL_USM 3
234
235struct snmp_pdu {
236 char community[SNMP_COMMUNITY_MAXLEN + 1];
237 enum snmp_version version;
238 u_int type;
239
240 /* SNMPv3 PDU header fields */
241 int32_t identifier;
242 uint8_t flags;
243 int32_t security_model;
244 struct snmp_engine engine;
245
246 /* Associated USM user parameters */
247 struct snmp_user user;
248 uint8_t msg_digest[SNMP_USM_AUTH_SIZE];
249 uint8_t msg_salt[SNMP_USM_PRIV_SIZE];
250
251 /* View-based Access Model */
252 uint32_t context_engine_len;
253 uint8_t context_engine[SNMP_ENGINE_ID_SIZ];
254 char context_name[SNMP_CONTEXT_NAME_SIZ];
255
256 /* trap only */
257 struct asn_oid enterprise;
258 u_char agent_addr[4];
259 int32_t generic_trap;
260 int32_t specific_trap;
261 uint32_t time_stamp;
262
263 /* others */
264 int32_t request_id;
265 int32_t error_status;
266 int32_t error_index;
267
268 /* fixes for encoding */
269 size_t outer_len;
270 size_t scoped_len;
271 u_char *outer_ptr;
272 u_char *digest_ptr;
273 u_char *encrypted_ptr;
274 u_char *scoped_ptr;
275 u_char *pdu_ptr;
276 u_char *vars_ptr;
277
278
279 struct snmp_value bindings[SNMP_MAX_BINDINGS];
280 u_int nbindings;
281};
282.Ed
283This structure contains a decoded SNMP PDU.
284.Fa version
285is one of
286.Bd -literal -offset indent
287enum snmp_version {
288 SNMP_Verr = 0,
289 SNMP_V1 = 1,
290 SNMP_V2c,
291 SNMP_V3
292};
293.Ed
294and
295.Fa type
296is the type of the PDU.
297.Fa security_model
298is the security model used for SNMPv3 PDUs. The only supported
299value currently is 3 (User-based Security Model).
300.Pp
301The function
302.Fn snmp_value_free
303is used to free all the dynamic allocated contents of an SNMP value.
304It does not free the structure pointed to by
305.Fa value
306itself.
307.Pp
--- 30 unchanged lines hidden (view full) ---
338If an error occurs in a variable binding the (1 based) index of this binding
339is stored in the variable pointed to by
340.Fa ip .
341.Pp
342The function
343.Fn snmp_pdu_encode
344encodes the PDU
345.Fa pdu
346into the an octetstring in buffer, and if authentication and privacy are used,
347calculates a message digest and encrypts the PDU data in the buffer
348.Fa buf .
349.Pp
350The function
351.Fn snmp_pdu_decode_header
352decodes the header of the PDU pointed to by
353.Fa buf .
354The uncoded PDU contents remain in the buffer.
355.Pp
356The function
357.Fn snmp_pdu_decode_scoped
358decodes the scoped PDU pointed to by
359.Fa buf .
360.Pp
361The function
362.Fn snmp_pdu_decode_secmode
363verifies the authentication parameter contained in the PDU (if present) and
364if the PDU is encrypted, decrypts the PDU contents pointed to by
365.Fa buf .
366If successfull, a plain text scoped PDU is stored in the buffer.
367.Pp
368The function
369.Fn snmp_pdu_dump
370dumps the PDU in a human readable form by calling
371.Fn snmp_printf .
372.Pp
373The function
374.Fn snmp_passwd_to_keys
375calculates a binary private authentication key corresponding to a plain text human
376readable password string. The calculated key is placed in the
377.Fa auth_key
378field of the
379.Fa user .
380.Pp
381The function
382.Fn snmp_get_local_keys
383calculates a localazied authentication and privacy keys for a specified SNMPv3
384engine. The calculateds keys are placed in the
385.Fa auth_key
386and
387.Fa priv_key
388fields of the
389.Fa user .
390.Pp
391The function
392.Fn snmp_calc_keychange
393calculates a binary key change octet string based on the contents of an old and
394a new binary localized key. The rezult is placed in the buffer pointer to by
395.Fa keychange
396and may be used by an SNMPv3 user who wishes to change his/her password
397or localized key.
398.Pp
399The function
400.Fn TRUTH_MK
401takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
402The function
403.Fn TRUTH_GET
404takes an SNMP truth value and makes a C truth value (0 or 1).
405The function
406.Fn TRUTH_OK
407checks, whether its argument is a legal SNMP truth value.
--- 33 unchanged lines hidden (view full) ---
441.It Bq Er SNMP_CODE_BADLEN
442A variable binding value had a wrong length field.
443.It Bq Er SNMP_CODE_OORANGE
444A variable binding value was out of the allowed range.
445.It Bq Er SNMP_CODE_BADVERS
446The PDU is of an unsupported version.
447.It Bq Er SNMP_CODE_BADENQ
448There was an ASN.1 value with an unsupported tag.
449.It Bq Er SNMP_CODE_BADSECLEVEL
450The requested securityLevel contained in the PDU is not supported.
451.It Bq Er SNMP_CODE_BADDIGEST
452The PDU authentication parameter received in the PDU did not match the
453calculated message digest.
454.It Bq Er SNMP_CODE_EDECRYPT
455Error occured while trying to decrypt the PDU.
456.El
457.Pp
458.Fn snmp_pdu_encode
459will return one of the following return codes:
460.Bl -tag -width Er
461.It Bq Er SNMP_CODE_OK
462Success.
463.It Bq Er SNMP_CODE_FAILED
464Encoding failed.
465.El
466.Sh SEE ALSO
467.Xr gensnmptree 1 ,
468.Xr bsnmpd 1 ,
469.Xr bsnmpagent 3 ,
470.Xr bsnmpclient 3 ,
471.Xr bsnmplib 3
472.Sh CAVEAT
473The SNMPv3 message digests, encryption and decryption, and key routines use
474the cryptographic functions from
475.Xr crypto 3 .
476The library may optionally be built without references to the
477.Xr crypto 3
478library. In such case only plain text SNMPv3 PDUs without message digests
479may be proccessed correctly.
480.Sh STANDARDS
481This implementation conforms to the applicable IETF RFCs and ITU-T
482recommendations.
483.Sh AUTHORS
484The Begemot SNMP library was originally written by
485.An Hartmut Brandt Aq harti@FreeBSD.org
486.Pp
487.An Shteryana Shopova Aq syrinx@FreeBSD.org
488added support for the SNMPv3 message proccessing and User-Based
489Security model message authentication and privacy.
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 unchanged lines hidden (view full) ---
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 September 9, 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_dump ,
54.Nm snmp_passwd_to_keys ,
55.Nm snmp_get_local_keys ,
56.Nm snmp_calc_keychange ,
57.Nm TRUTH_MK ,
58.Nm TRUTH_GET ,
59.Nm TRUTH_OK
60.Nd "SNMP decoding and encoding library"
61.Sh LIBRARY
62Begemot SNMP library
63.Pq libbsnmp, -lbsnmp
64.Sh SYNOPSIS
--- 6 unchanged lines hidden (view full) ---
71.Ft int
72.Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from"
73.Ft void
74.Fn snmp_pdu_free "struct snmp_pdu *value"
75.Ft enum snmp_code
76.Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
77.Ft enum snmp_code
78.Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf"
79.Ft enum snmp_code
80.Fn snmp_pdu_decode_header "struct snmp_pdu *pdu" "struct asn_buf *buf"
81.Ft enum snmp_code
82.Fn snmp_pdu_decode_scoped "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
83.Ft enum snmp_code
84.Fn snmp_pdu_decode_secmode "struct asn_buf *buf" "struct snmp_pdu *pdu"
85.Ft void
86.Fn snmp_pdu_dump "const struct snmp_pdu *pdu"
87.Ft enum snmp_code
88.Fn snmp_passwd_to_keys "struct snmp_user *user" "char *passwd"
89.Ft enum snmp_code
90.Fn snmp_get_local_keys "struct snmp_user *user" "uint8_t *eid" "uint32_t elen"
91.Ft enum snmp_code
92.Fn snmp_calc_keychange "struct snmp_user *user" "uint8_t *keychange"
93.Ft int
94.Fn TRUTH_MK "F"
95.Ft int
96.Fn TRUTH_GET "T"
97.Ft int
98.Fn TRUTH_OK "T"
99.Sh DESCRIPTION
100The SNMP library contains routines to handle SNMP version 1, 2 and 3 PDUs.
101There are several basic structures used throughout the library:
102.Bd -literal -offset indent
103struct snmp_value {
104 struct asn_oid var;
105 enum snmp_syntax syntax;
106 union snmp_values {
107 int32_t integer;/* also integer32 */
108 struct {
109 u_int len;
--- 43 unchanged lines hidden (view full) ---
153is
154.Li SNMP_SYNTAX_OCTETSTRING
155and
156.Fa v.octetstring.len
157is not zero,
158.Fa v.octetstring.octets
159points to a string allocated by
160.Xr malloc 3 .
161.Pp
162.Bd -literal -offset indent
163#define SNMP_ENGINE_ID_SIZ 32
164
165struct snmp_engine {
166 uint8_t engine_id[SNMP_ENGINE_ID_SIZ];
167 uint32_t engine_len;
168 int32_t engine_boots;
169 int32_t engine_time;
170 int32_t max_msg_size;
171};
172.Ed
173.Pp
174This structure represents an SNMP engine as specified by the SNMP Management
175Architecture described in RFC 3411.
176.Pp
177.Bd -literal -offset indent
178#define SNMP_USM_NAME_SIZ (32 + 1)
179#define SNMP_AUTH_KEY_SIZ 40
180#define SNMP_PRIV_KEY_SIZ 32
181
182struct snmp_user {
183 char sec_name[SNMP_USM_NAME_SIZ];
184 enum snmp_authentication auth_proto;
185 enum snmp_privacy priv_proto;
186 uint8_t auth_key[SNMP_AUTH_KEY_SIZ];
187 uint8_t priv_key[SNMP_PRIV_KEY_SIZ];
188};
189.Ed
190.Pp
191This structure represents an SNMPv3 user as specified by the User-based
192Security Model (USM) described in RFC 3414. The field
193.Fa sec_name
194is a human readable string containing the security user name.
195.Fa auth_proto
196contains the id of the authentication protocol in use by the user and may be one
197of:
198.Bd -literal -offset indent
199enum snmp_authentication {
200 SNMP_AUTH_NOAUTH = 0,
201 SNMP_AUTH_HMAC_MD5,
202 SNMP_AUTH_HMAC_SHA
203};
204.Ed
205.Fa priv_proto
206contains the id of the privacy protocol in use by the user and may be one
207of:
208.Bd -literal -offset indent
209enum snmp_privacy {
210 SNMP_PRIV_NOPRIV = 0,
211 SNMP_PRIV_DES = 1,
212 SNMP_PRIV_AES
213};
214.Ed
215.Fa auth_key
216and
217.Fa priv_key
218contain the authentication and privacy keys for the user.
219.Pp
220.Bd -literal -offset indent
221#define SNMP_COMMUNITY_MAXLEN 128
222#define SNMP_MAX_BINDINGS 100
223#define SNMP_CONTEXT_NAME_SIZ (32 + 1)
224#define SNMP_TIME_WINDOW 150
225
226#define SNMP_USM_AUTH_SIZE 12
227#define SNMP_USM_PRIV_SIZE 8
228
229#define SNMP_MSG_AUTH_FLAG 0x1
230#define SNMP_MSG_PRIV_FLAG 0x2
231#define SNMP_MSG_REPORT_FLAG 0x4
232
233#define SNMP_SECMODEL_USM 3
234
235struct snmp_pdu {
236 char community[SNMP_COMMUNITY_MAXLEN + 1];
237 enum snmp_version version;
238 u_int type;
239
240 /* SNMPv3 PDU header fields */
241 int32_t identifier;
242 uint8_t flags;
243 int32_t security_model;
244 struct snmp_engine engine;
245
246 /* Associated USM user parameters */
247 struct snmp_user user;
248 uint8_t msg_digest[SNMP_USM_AUTH_SIZE];
249 uint8_t msg_salt[SNMP_USM_PRIV_SIZE];
250
251 /* View-based Access Model */
252 uint32_t context_engine_len;
253 uint8_t context_engine[SNMP_ENGINE_ID_SIZ];
254 char context_name[SNMP_CONTEXT_NAME_SIZ];
255
256 /* trap only */
257 struct asn_oid enterprise;
258 u_char agent_addr[4];
259 int32_t generic_trap;
260 int32_t specific_trap;
261 uint32_t time_stamp;
262
263 /* others */
264 int32_t request_id;
265 int32_t error_status;
266 int32_t error_index;
267
268 /* fixes for encoding */
269 size_t outer_len;
270 size_t scoped_len;
271 u_char *outer_ptr;
272 u_char *digest_ptr;
273 u_char *encrypted_ptr;
274 u_char *scoped_ptr;
275 u_char *pdu_ptr;
276 u_char *vars_ptr;
277
278
279 struct snmp_value bindings[SNMP_MAX_BINDINGS];
280 u_int nbindings;
281};
282.Ed
283This structure contains a decoded SNMP PDU.
284.Fa version
285is one of
286.Bd -literal -offset indent
287enum snmp_version {
288 SNMP_Verr = 0,
289 SNMP_V1 = 1,
290 SNMP_V2c,
291 SNMP_V3
292};
293.Ed
294and
295.Fa type
296is the type of the PDU.
297.Fa security_model
298is the security model used for SNMPv3 PDUs. The only supported
299value currently is 3 (User-based Security Model).
300.Pp
301The function
302.Fn snmp_value_free
303is used to free all the dynamic allocated contents of an SNMP value.
304It does not free the structure pointed to by
305.Fa value
306itself.
307.Pp
--- 30 unchanged lines hidden (view full) ---
338If an error occurs in a variable binding the (1 based) index of this binding
339is stored in the variable pointed to by
340.Fa ip .
341.Pp
342The function
343.Fn snmp_pdu_encode
344encodes the PDU
345.Fa pdu
346into the an octetstring in buffer, and if authentication and privacy are used,
347calculates a message digest and encrypts the PDU data in the buffer
348.Fa buf .
349.Pp
350The function
351.Fn snmp_pdu_decode_header
352decodes the header of the PDU pointed to by
353.Fa buf .
354The uncoded PDU contents remain in the buffer.
355.Pp
356The function
357.Fn snmp_pdu_decode_scoped
358decodes the scoped PDU pointed to by
359.Fa buf .
360.Pp
361The function
362.Fn snmp_pdu_decode_secmode
363verifies the authentication parameter contained in the PDU (if present) and
364if the PDU is encrypted, decrypts the PDU contents pointed to by
365.Fa buf .
366If successfull, a plain text scoped PDU is stored in the buffer.
367.Pp
368The function
369.Fn snmp_pdu_dump
370dumps the PDU in a human readable form by calling
371.Fn snmp_printf .
372.Pp
373The function
374.Fn snmp_passwd_to_keys
375calculates a binary private authentication key corresponding to a plain text human
376readable password string. The calculated key is placed in the
377.Fa auth_key
378field of the
379.Fa user .
380.Pp
381The function
382.Fn snmp_get_local_keys
383calculates a localazied authentication and privacy keys for a specified SNMPv3
384engine. The calculateds keys are placed in the
385.Fa auth_key
386and
387.Fa priv_key
388fields of the
389.Fa user .
390.Pp
391The function
392.Fn snmp_calc_keychange
393calculates a binary key change octet string based on the contents of an old and
394a new binary localized key. The rezult is placed in the buffer pointer to by
395.Fa keychange
396and may be used by an SNMPv3 user who wishes to change his/her password
397or localized key.
398.Pp
399The function
400.Fn TRUTH_MK
401takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1).
402The function
403.Fn TRUTH_GET
404takes an SNMP truth value and makes a C truth value (0 or 1).
405The function
406.Fn TRUTH_OK
407checks, whether its argument is a legal SNMP truth value.
--- 33 unchanged lines hidden (view full) ---
441.It Bq Er SNMP_CODE_BADLEN
442A variable binding value had a wrong length field.
443.It Bq Er SNMP_CODE_OORANGE
444A variable binding value was out of the allowed range.
445.It Bq Er SNMP_CODE_BADVERS
446The PDU is of an unsupported version.
447.It Bq Er SNMP_CODE_BADENQ
448There was an ASN.1 value with an unsupported tag.
449.It Bq Er SNMP_CODE_BADSECLEVEL
450The requested securityLevel contained in the PDU is not supported.
451.It Bq Er SNMP_CODE_BADDIGEST
452The PDU authentication parameter received in the PDU did not match the
453calculated message digest.
454.It Bq Er SNMP_CODE_EDECRYPT
455Error occured while trying to decrypt the PDU.
456.El
457.Pp
458.Fn snmp_pdu_encode
459will return one of the following return codes:
460.Bl -tag -width Er
461.It Bq Er SNMP_CODE_OK
462Success.
463.It Bq Er SNMP_CODE_FAILED
464Encoding failed.
465.El
466.Sh SEE ALSO
467.Xr gensnmptree 1 ,
468.Xr bsnmpd 1 ,
469.Xr bsnmpagent 3 ,
470.Xr bsnmpclient 3 ,
471.Xr bsnmplib 3
472.Sh CAVEAT
473The SNMPv3 message digests, encryption and decryption, and key routines use
474the cryptographic functions from
475.Xr crypto 3 .
476The library may optionally be built without references to the
477.Xr crypto 3
478library. In such case only plain text SNMPv3 PDUs without message digests
479may be proccessed correctly.
480.Sh STANDARDS
481This implementation conforms to the applicable IETF RFCs and ITU-T
482recommendations.
483.Sh AUTHORS
484The Begemot SNMP library was originally written by
485.An Hartmut Brandt Aq harti@FreeBSD.org
486.Pp
487.An Shteryana Shopova Aq syrinx@FreeBSD.org
488added support for the SNMPv3 message proccessing and User-Based
489Security model message authentication and privacy.