1a2,7
> .\" Copyright (c) 2010 The FreeBSD Foundation
> .\" All rights reserved.
> .\"
> .\" Portions of this documentation were written by Shteryana Sotirova Shopova
> .\" under sponsorship from the FreeBSD Foundation.
> .\"
34c40
< .Dd October 4, 2005
---
> .Dd September 9, 2010
42,43c48,52
< .Nm snmp_code snmp_pdu_decode ,
< .Nm snmp_code snmp_pdu_encode ,
---
> .Nm snmp_pdu_decode ,
> .Nm snmp_pdu_encode ,
> .Nm snmp_pdu_decode_header ,
> .Nm snmp_pdu_decode_scoped ,
> .Nm snmp_pdu_decode_secmode ,
44a54,56
> .Nm snmp_passwd_to_keys ,
> .Nm snmp_get_local_keys ,
> .Nm snmp_calc_keychange ,
66a79,84
> .Ft enum snmp_code
> .Fn snmp_pdu_decode_header "struct snmp_pdu *pdu" "struct asn_buf *buf"
> .Ft enum snmp_code
> .Fn snmp_pdu_decode_scoped "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip"
> .Ft enum snmp_code
> .Fn snmp_pdu_decode_secmode "struct asn_buf *buf" "struct snmp_pdu *pdu"
68a87,92
> .Ft enum snmp_code
> .Fn snmp_passwd_to_keys "struct snmp_user *user" "char *passwd"
> .Ft enum snmp_code
> .Fn snmp_get_local_keys "struct snmp_user *user" "uint8_t *eid" "uint32_t elen"
> .Ft enum snmp_code
> .Fn snmp_calc_keychange "struct snmp_user *user" "uint8_t *keychange"
76,77c100,101
< The SNMP library contains routines to handle SNMP version 1 and 2 PDUs.
< There are two basic structures used throughout the library:
---
> The SNMP library contains routines to handle SNMP version 1, 2 and 3 PDUs.
> There are several basic structures used throughout the library:
136a161
> .Pp
138,139c163
< #define SNMP_COMMUNITY_MAXLEN 128
< #define SNMP_MAX_BINDINGS 100
---
> #define SNMP_ENGINE_ID_SIZ 32
140a165,234
> struct snmp_engine {
> uint8_t engine_id[SNMP_ENGINE_ID_SIZ];
> uint32_t engine_len;
> int32_t engine_boots;
> int32_t engine_time;
> int32_t max_msg_size;
> };
> .Ed
> .Pp
> This structure represents an SNMP engine as specified by the SNMP Management
> Architecture described in RFC 3411.
> .Pp
> .Bd -literal -offset indent
> #define SNMP_USM_NAME_SIZ (32 + 1)
> #define SNMP_AUTH_KEY_SIZ 40
> #define SNMP_PRIV_KEY_SIZ 32
>
> struct snmp_user {
> char sec_name[SNMP_USM_NAME_SIZ];
> enum snmp_authentication auth_proto;
> enum snmp_privacy priv_proto;
> uint8_t auth_key[SNMP_AUTH_KEY_SIZ];
> uint8_t priv_key[SNMP_PRIV_KEY_SIZ];
> };
> .Ed
> .Pp
> This structure represents an SNMPv3 user as specified by the User-based
> Security Model (USM) described in RFC 3414. The field
> .Fa sec_name
> is a human readable string containing the security user name.
> .Fa auth_proto
> contains the id of the authentication protocol in use by the user and may be one
> of:
> .Bd -literal -offset indent
> enum snmp_authentication {
> SNMP_AUTH_NOAUTH = 0,
> SNMP_AUTH_HMAC_MD5,
> SNMP_AUTH_HMAC_SHA
> };
> .Ed
> .Fa priv_proto
> contains the id of the privacy protocol in use by the user and may be one
> of:
> .Bd -literal -offset indent
> enum snmp_privacy {
> SNMP_PRIV_NOPRIV = 0,
> SNMP_PRIV_DES = 1,
> SNMP_PRIV_AES
> };
> .Ed
> .Fa auth_key
> and
> .Fa priv_key
> contain the authentication and privacy keys for the user.
> .Pp
> .Bd -literal -offset indent
> #define SNMP_COMMUNITY_MAXLEN 128
> #define SNMP_MAX_BINDINGS 100
> #define SNMP_CONTEXT_NAME_SIZ (32 + 1)
> #define SNMP_TIME_WINDOW 150
>
> #define SNMP_USM_AUTH_SIZE 12
> #define SNMP_USM_PRIV_SIZE 8
>
> #define SNMP_MSG_AUTH_FLAG 0x1
> #define SNMP_MSG_PRIV_FLAG 0x2
> #define SNMP_MSG_REPORT_FLAG 0x4
>
> #define SNMP_SECMODEL_USM 3
>
142,144c236,238
< char community[SNMP_COMMUNITY_MAXLEN + 1];
< enum snmp_version version;
< u_int type;
---
> char community[SNMP_COMMUNITY_MAXLEN + 1];
> enum snmp_version version;
> u_int type;
145a240,255
> /* SNMPv3 PDU header fields */
> int32_t identifier;
> uint8_t flags;
> int32_t security_model;
> struct snmp_engine engine;
>
> /* Associated USM user parameters */
> struct snmp_user user;
> uint8_t msg_digest[SNMP_USM_AUTH_SIZE];
> uint8_t msg_salt[SNMP_USM_PRIV_SIZE];
>
> /* View-based Access Model */
> uint32_t context_engine_len;
> uint8_t context_engine[SNMP_ENGINE_ID_SIZ];
> char context_name[SNMP_CONTEXT_NAME_SIZ];
>
147,151c257,261
< struct asn_oid enterprise;
< u_char agent_addr[4];
< int32_t generic_trap;
< int32_t specific_trap;
< u_int32_t time_stamp;
---
> struct asn_oid enterprise;
> u_char agent_addr[4];
> int32_t generic_trap;
> int32_t specific_trap;
> uint32_t time_stamp;
154,156c264,266
< int32_t request_id;
< int32_t error_status;
< int32_t error_index;
---
> int32_t request_id;
> int32_t error_status;
> int32_t error_index;
159,161c269,276
< u_char *outer_ptr;
< u_char *pdu_ptr;
< u_char *vars_ptr;
---
> size_t outer_len;
> size_t scoped_len;
> u_char *outer_ptr;
> u_char *digest_ptr;
> u_char *encrypted_ptr;
> u_char *scoped_ptr;
> u_char *pdu_ptr;
> u_char *vars_ptr;
163,164c278,280
< struct snmp_value bindings[SNMP_MAX_BINDINGS];
< u_int nbindings;
---
>
> struct snmp_value bindings[SNMP_MAX_BINDINGS];
> u_int nbindings;
174a291
> SNMP_V3
179a297,299
> .Fa security_model
> is the security model used for SNMPv3 PDUs. The only supported
> value currently is 3 (User-based Security Model).
226c346,347
< into the an octetstring in buffer
---
> into the an octetstring in buffer, and if authentication and privacy are used,
> calculates a message digest and encrypts the PDU data in the buffer
229a351,368
> .Fn snmp_pdu_decode_header
> decodes the header of the PDU pointed to by
> .Fa buf .
> The uncoded PDU contents remain in the buffer.
> .Pp
> The function
> .Fn snmp_pdu_decode_scoped
> decodes the scoped PDU pointed to by
> .Fa buf .
> .Pp
> The function
> .Fn snmp_pdu_decode_secmode
> verifies the authentication parameter contained in the PDU (if present) and
> if the PDU is encrypted, decrypts the PDU contents pointed to by
> .Fa buf .
> If successfull, a plain text scoped PDU is stored in the buffer.
> .Pp
> The function
234a374,399
> .Fn snmp_passwd_to_keys
> calculates a binary private authentication key corresponding to a plain text human
> readable password string. The calculated key is placed in the
> .Fa auth_key
> field of the
> .Fa user .
> .Pp
> The function
> .Fn snmp_get_local_keys
> calculates a localazied authentication and privacy keys for a specified SNMPv3
> engine. The calculateds keys are placed in the
> .Fa auth_key
> and
> .Fa priv_key
> fields of the
> .Fa user .
> .Pp
> The function
> .Fn snmp_calc_keychange
> calculates a binary key change octet string based on the contents of an old and
> a new binary localized key. The rezult is placed in the buffer pointer to by
> .Fa keychange
> and may be used by an SNMPv3 user who wishes to change his/her password
> or localized key.
> .Pp
> The function
283a449,455
> .It Bq Er SNMP_CODE_BADSECLEVEL
> The requested securityLevel contained in the PDU is not supported.
> .It Bq Er SNMP_CODE_BADDIGEST
> The PDU authentication parameter received in the PDU did not match the
> calculated message digest.
> .It Bq Er SNMP_CODE_EDECRYPT
> Error occured while trying to decrypt the PDU.
299a472,479
> .Sh CAVEAT
> The SNMPv3 message digests, encryption and decryption, and key routines use
> the cryptographic functions from
> .Xr crypto 3 .
> The library may optionally be built without references to the
> .Xr crypto 3
> library. In such case only plain text SNMPv3 PDUs without message digests
> may be proccessed correctly.
303a484
> The Begemot SNMP library was originally written by
304a486,489
> .Pp
> .An Shteryana Shopova Aq syrinx@FreeBSD.org
> added support for the SNMPv3 message proccessing and User-Based
> Security model message authentication and privacy.