Index: head/contrib/bsnmp/lib/bsnmpclient.3 =================================================================== --- head/contrib/bsnmp/lib/bsnmpclient.3 (revision 237192) +++ head/contrib/bsnmp/lib/bsnmpclient.3 (revision 237193) @@ -1,703 +1,703 @@ .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmpclient.3,v 1.12 2005/10/04 08:46:50 brandt_h Exp $ .\" .Dd September 9, 2010 .Dt BSNMPCLIENT 3 .Os .Sh NAME .Nm snmp_client , .Nm snmp_send_cb_f , .Nm snmp_timeout_cb_f , .Nm snmp_timeout_start_f , .Nm snmp_timeout_stop_f , .Nm snmp_open , .Nm snmp_close , .Nm snmp_pdu_create , .Nm snmp_add_binding , .Nm snmp_pdu_check , .Nm snmp_pdu_send , .Nm snmp_oid_append , .Nm snmp_parse_server , .Nm snmp_receive , .Nm snmp_table_cb_f , .Nm snmp_table_fetch , .Nm snmp_table_fetch_async , .Nm snmp_dialog , .Nm snmp_discover_engine .Nd "SNMP client library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In asn1.h .In snmp.h .In snmpclient.h .Ft typedef void .Fn (*snmp_send_cb_f) "struct snmp_pdu *req" "struct snmp_pdu *resp" "void *uarg" .Ft typedef void .Fn (*snmp_timeout_cb_f) "void *uarg" .Ft typedef void * .Fn (*snmp_timeout_start_f) "struct timeval *timeout" "snmp_timeout_cb_f callback" "void *uarg" .Ft typedef void .Fn (*snmp_timeout_stop_f) "void *timeout_id" .Vt extern struct snmp_client snmp_client ; .Ft void .Fn snmp_client_init "struct snmp_client *client" .Ft int .Fn snmp_client_set_host "struct snmp_client *client" "const char *host" .Ft int .Fn snmp_client_set_port "struct snmp_client *client" "const char *port" .Ft int .Fn snmp_open "const char *host" "const char *port" "const char *read_community" "const char *write_community" .Ft void .Fn snmp_close "void" .Ft void .Fn snmp_pdu_create "struct snmp_pdu *pdu" "u_int op" .Ft int .Fn snmp_add_binding "struct snmp_pdu *pdu" "..." .Ft int .Fn snmp_pdu_check "const struct snmp_pdu *req" "const struct snmp_pdu *resp" .Ft int32_t .Fn snmp_pdu_send "struct snmp_pdu *pdu" "snmp_send_cb_f func" "void *uarg" .Ft int .Fn snmp_oid_append "struct asn_oid *oid" "const char *fmt" "..." .Ft int .Fn snmp_parse_server "struct snmp_client *sc" "const char *str" .Ft int .Fn snmp_receive "int blocking" .Ft typedef void .Fn (*snmp_table_cb_f) "void *list" "void *arg" "int res" .Ft int .Fn snmp_table_fetch "const struct snmp_table *descr" "void *list" .Ft int .Fn snmp_table_fetch_async "const struct snmp_table *descr" "void *list" "snmp_table_cb_f callback" "void *uarg" .Ft int .Fn snmp_dialog "struct snmp_pdu *req" "struct snmp_pdu *resp" .Ft int .Fn snmp_discover_engine "void" .Sh DESCRIPTION The SNMP library contains routines to easily build SNMP client applications that use SNMP versions 1, 2 or 3. Most of the routines use a .Vt struct snmp_client : .Bd -literal -offset indent struct snmp_client { enum snmp_version version; int trans; /* which transport to use */ /* these two are read-only for the application */ char *cport; /* port number as string */ char *chost; /* host name or IP address as string */ char read_community[SNMP_COMMUNITY_MAXLEN + 1]; char write_community[SNMP_COMMUNITY_MAXLEN + 1]; /* SNMPv3 specific fields */ int32_t identifier; int32_t security_model; struct snmp_engine engine; struct snmp_user user; /* SNMPv3 Access control - VACM*/ uint32_t clen; uint8_t cengine[SNMP_ENGINE_ID_SIZ]; char cname[SNMP_CONTEXT_NAME_SIZ]; struct timeval timeout; u_int retries; int dump_pdus; size_t txbuflen; size_t rxbuflen; int fd; int32_t next_reqid; int32_t max_reqid; int32_t min_reqid; char error[SNMP_STRERROR_LEN]; snmp_timeout_start_f timeout_start; snmp_timeout_stop_f timeout_stop; char local_path[sizeof(SNMP_LOCAL_PATH)]; }; .Ed .Pp The fields of this structure are described below. .Bl -tag -width "timeout_start" .It Va version This is the version of SNMP to use. See .Xr bsnmplib 3 for applicable values. The default version is .Li SNMP_V2c . .It Va trans If this is .Dv SNMP_TRANS_LOC_DGRAM a local datagram socket is used. If it is .Dv SNMP_TRANS_LOC_STREAM a local stream socket is used. For .Dv SNMP_TRANS_UDP a UDP socket is created. It uses the .Va chost field as the path to the server's socket for local sockets. .It Va cport The SNMP agent's UDP port number. This may be a symbolic port number (from .Pa /etc/services ) or a numeric port number. If this field is .Li NULL (the default) the standard SNMP port is used. This field should not be changed directly but rather by calling .Fn snmp_client_set_port . .It Va chost The SNMP agent's host name, IP address or .Ux domain socket path name. If this is .Li NULL (the default) .Li localhost is assumed. This field should not be changed directly but rather through calling .Fn snmp_client_set_host . .It Va read_community This is the community name to be used for all requests except SET requests. The default is .Sq public . .It Va write_community The community name to be used for SET requests. The default is .Sq private . .It Va identifier The message indentifier value to be used with SNMPv3 PDUs. Incremented with each transmitted PDU. .It Va security_model The security model to be used with SNMPv3 PDUs. Currently only User-Based Security model specified by RFC 3414 (value 3) is supported. .It Va engine The authorative SNMP engine parameters to be used with SNMPv3 PDUs. .It Va user The USM SNMP user credentials to be used with SNMPv3 PDUs. .It Va clen The length of the context engine id to be used with SNMPv3 PDUs. .It Va cengine The context engine id to be used with SNMPv3 PDUs. Default is empty. .It Va cname The context name to be used with SNMPv3 PDUs. Default is .Sq "" . .It Va timeout The maximum time to wait for responses to requests. If the time elapses, the request is resent up to .Va retries times. The default is 3 seconds. .It Va retries Number of times a request PDU is to be resent. If set to 0, the request is sent only once. The default is 3 retransmissions. .It Va dump_pdus If set to a non-zero value all received and sent PDUs are dumped via .Xr snmp_pdu_dump 3 . The default is not to dump PDUs. .It Va txbuflen The encoding buffer size to be allocated for transmitted PDUs. The default is 10000 octets. .It Va rxbuflen The decoding buffer size to be allocated for received PDUs. This is the size of the maximum PDU that can be received. The default is 10000 octets. .It Va fd After calling .Fn snmp_open this is the file socket file descriptor used for sending and receiving PDUs. .It Va next_reqid The request id of the next PDU to send. Used internal by the library. .It Va max_reqid The maximum request id to use for outgoing PDUs. The default is .Li INT32_MAX . .It Va min_reqid The minimum request id to use for outgoing PDUs. Request ids are allocated linearily starting at .Va min_reqid up to .Va max_reqid . .It Va error If an error happens, this field is set to a printable string describing the error. .It Va timeout_start This field must point to a function setting up a one shot timeout. After the timeout has elapsed, the given callback function must be called with the user argument. The .Fn timeout_start function must return a .Vt void * identifying the timeout. .It Va timeout_stop This field must be set to a function that stops a running timeout. The function will be called with the return value of the corresponding .Fn timeout_start function. .It Va local_path If in local socket mode, the name of the clients socket. Not needed by the application. .El .Pp In the current implementation there is a global variable .Pp .D1 Vt extern struct snmp_client snmp_client ; .Pp that is used by all the library functions. The first call into the library must be a call to .Fn snmp_client_init to initialize this global variable to the default values. After this call and before calling .Fn snmp_open the fields of the variable may be modified by the user. The modification of the .Va chost and .Va cport fields should be done only via the functions .Fn snmp_client_set_host and .Fn snmp_client_set_port . .Pp The function .Fn snmp_open creates a UDP or .Ux domain socket and connects it to the agent's IP address and port. If any of the arguments of the call is not .Li NULL the corresponding field in the global .Va snmp_client is set from the argument. Otherwise the values that are already in that variable are used. The function .Fn snmp_close closes the socket, stops all timeouts and frees all dynamically allocated resources. .Pp The next three functions are used to create request PDUs. The function .Fn snmp_pdu_create initializes a PDU of type .Va op . It does not allocate space for the PDU itself. This is the responsibility of the caller. .Fn snmp_add_binding adds bindings to the PDU and returns the (zero based) index of the first new binding. The arguments are pairs of pointer to the OIDs and syntax constants, terminated by a NULL. The call .Bd -literal -offset indent snmp_add_binding(&pdu, &oid1, SNMP_SYNTAX_INTEGER, &oid2, SNMP_SYNTAX_OCTETSTRING, NULL); .Ed .Pp adds two new bindings to the PDU and returns the index of the first one. It is the responsibility of the caller to set the value part of the binding if necessary. The functions returns -1 if the maximum number of bindings is exhausted. The function .Fn snmp_oid_append can be used to construct variable OIDs for requests. It takes a pointer to an .Vt struct asn_oid that is to be constructed, a format string, and a number of arguments the type of which depends on the format string. The format string is interpreted character by character in the following way: .Bl -tag -width ".It Li ( Va N Ns Li )" .It Li i This format expects an argument of type .Vt asn_subid_t and appends this as a single integer to the OID. .It Li a This format expects an argument of type .Vt struct in_addr and appends to four parts of the IP address to the OID. .It Li s This format expects an argument of type .Vt const char * and appends the length of the string (as computed by .Xr strlen 3 ) and each of the characters in the string to the OID. -.It Li ( Va N Ns Li ) +.It ( Va N Ns ) This format expects no argument. .Va N must be a decimal number and is stored into an internal variable .Va size . .It Li b This format expects an argument of type .Vt const char * and appends .Va size characters from the string to the OID. The string may contain .Li NUL characters. .It Li c This format expects two arguments: one of type .Vt size_t and one of type .Vt const u_char * . The first argument gives the number of bytes to append to the OID from the string pointed to by the second argument. .El .Pp The function .Fn snmp_pdu_check may be used to check a response PDU. A number of checks are performed (error code, equal number of bindings, syntaxes and values for SET PDUs). The function returns +1 if everything is ok, 0 if a NOSUCHNAME or similar error was detected, -1 if the response PDU had fatal errors and -2 if .Fa resp is .Li NULL (a timeout occurred). .Pp The function .Fn snmp_pdu_send encodes and sends the given PDU. It records the PDU together with the callback and user pointers in an internal list and arranges for retransmission if no response is received. When a response is received or the retransmission count is exceeded the callback .Fa func is called with the orignal request PDU, the response PDU and the user argument .Fa uarg . If the retransmit count is exceeded, .Fa func is called with the original request PDU, the response pointer set to .Li NULL and the user argument .Fa uarg . The caller should not free the request PDU until the callback function is called. The callback function must free the request PDU and the response PDU (if not .Li NULL ). .Pp The function .Fn snmp_receive tries to receive a PDU. If the argument is zero, the function polls to see whether a packet is available, if the argument is non-zero, the function blocks until the next packet is received. The packet is delivered via the usual callback mechanism (non-response packets are silently dropped). The function returns 0, if a packet was received and successfully dispatched, -1 if an error occurred or no packet was available (in polling mode). .Pp The next two functions are used to retrieve tables from SNMP agents. They use the following input structure, that describes the table: .Bd -literal -offset indent struct snmp_table { struct asn_oid table; struct asn_oid last_change; u_int max_iter; size_t entry_size; u_int index_size; uint64_t req_mask; struct snmp_table_entry { asn_subid_t subid; enum snmp_syntax syntax; off_t offset; } entries[]; }; .Ed .Pp The fields of this structure have the following meaning: .Bl -tag -width "last_change" .It Va table This is the base OID of the table. .It Va last_change Some tables have a scalar variable of type TIMETICKS attached to them, that holds the time when the table was last changed. This OID should be the OID of this variable (without the \&.0 index). When the table is retrieved with multiple GET requests, and the variable changes between two request, the table fetch is restarted. .It Va max_iter Maximum number of tries to fetch the table. .It Va entry_size The table fetching routines return a list of structures one for each table row. This variable is the size of one structure and used to .Xr malloc 3 the structure. .It Va index_size This is the number of index columns in the table. .It Va req_mask This is a bit mask with a 1 for each table column that is required. Bit 0 corresponds to the first element (index 0) in the array .Va entries , bit 1 to the second (index 1) and so on. SNMP tables may be sparse. For sparse columns the bit should not be set. If the bit for a given column is set and the column value cannot be retrieved for a given row, the table fetch is restarted assuming that the table is currently being modified by the agent. The bits for the index columns are ignored. .It Va entries This is a variable sized array of column descriptors. This array is terminated by an element with syntax .Li SNMP_SYNTAX_NULL . The first .Va index_size elements describe all the index columns of the table, the rest are normal columns. If for the column at .Ql entries[N] the expression .Ql req_mask & (1 << N) yields true, the column is considered a required column. The fields of this the array elements have the following meaning: .Bl -tag -width "syntax" .It Va subid This is the OID subid of the column. This is ignored for index entries. Index entries are decoded according to the .Va syntax field. .It Va syntax This is the syntax of the column or index. A syntax of .Li SNMP_SYNTAX_NULL terminates the array. .It Va offset This is the starting offset of the value of the column in the return structures. This field can be set with the ISO-C .Fn offsetof macro. .El .El .Pp Both table fetching functions return TAILQ (see .Xr queue 3 ) of structures--one for each table row. These structures must start with a .Fn TAILQ_ENTRY and a .Vt uint64_t and are allocated via .Xr malloc 3 . The .Fa list argument of the table functions must point to a .Fn TAILQ_HEAD . The .Vt uint64_t fields, usually called .Va found is used to indicate which of the columns have been found for the given row. It is encoded like the .Fa req_mask field. .Pp The function .Fn snmp_table_fetch synchronously fetches the given table. If everything is ok 0 is returned. Otherwise the function returns -1 and sets an appropriate error string. The function .Fn snmp_table_fetch_async fetches the tables asynchronously. If either the entire table is fetch, or an error occurs the callback function .Fa callback is called with the callers arguments .Fa list and .Fa uarg and a parameter that is either 0 if the table was fetched, or -1 if there was an error. The function itself returns -1 if it could not initialize fetching of the table. .Pp The following table description is used to fetch the ATM interface table: .Bd -literal -offset indent /* * ATM interface table */ struct atmif { TAILQ_ENTRY(atmif) link; uint64_t found; int32_t index; u_char *ifname; size_t ifnamelen; uint32_t node_id; uint32_t pcr; int32_t media; uint32_t vpi_bits; uint32_t vci_bits; uint32_t max_vpcs; uint32_t max_vccs; u_char *esi; size_t esilen; int32_t carrier; }; TAILQ_HEAD(atmif_list, atmif); /* list of all ATM interfaces */ struct atmif_list atmif_list; static const struct snmp_table atmif_table = { OIDX_begemotAtmIfTable, OIDX_begemotAtmIfTableLastChange, 2, sizeof(struct atmif), 1, 0x7ffULL, { { 0, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, index) }, { 1, SNMP_SYNTAX_OCTETSTRING, offsetof(struct atmif, ifname) }, { 2, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, node_id) }, { 3, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, pcr) }, { 4, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, media) }, { 5, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, vpi_bits) }, { 6, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, vci_bits) }, { 7, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, max_vpcs) }, { 8, SNMP_SYNTAX_GAUGE, offsetof(struct atmif, max_vccs) }, { 9, SNMP_SYNTAX_OCTETSTRING, offsetof(struct atmif, esi) }, { 10, SNMP_SYNTAX_INTEGER, offsetof(struct atmif, carrier) }, { 0, SNMP_SYNTAX_NULL, 0 } } }; \&... if (snmp_table_fetch(&atmif_table, &atmif_list) != 0) errx(1, "AtmIf table: %s", snmp_client.error); \&... .Ed .Pp The function .Fn snmp_dialog is used to execute a synchonuous dialog with the agent. The request PDU .Fa req is sent and the function blocks until the response PDU is received. Note, that asynchonuous receives are handled (i.e. callback functions of other send calls or table fetches may be called while in the function). The response PDU is returned in .Fa resp . If no response could be received after all timeouts and retries, the function returns -1. If a response was received 0 is returned. .Pp The function .Fn snmp_discover_engine is used to discover the authorative snmpEngineId of a remote SNMPv3 agent. A request PDU with empty USM user name is sent and the client's engine parameters are set according to the snmpEngine parameters received in the response PDU. If the client is configured to use authentication and/or privacy and the snmpEngineBoots and/or snmpEngineTime in the response had zero values, an additional request (possibly encrypted) with the appropriate user credentials is sent to fetch the missing values. Note, that the function blocks until the discovery proccess is completed. If no response could be received after all timeouts and retries, or the response contained errors the function returns -1. If the discovery proccess was completed 0 is returned. .Pp The function .Fn snmp_parse_server is used to parse an SNMP server specification string and fill in the fields of a .Vt struct snmp_client . The syntax of a server specification is .Pp .D1 [trans::][community@][server][:port] .Pp where .Va trans is the transport name (one of udp, stream or dgram), .Va community is the string to be used for both the read and the write community, .Va server is the server's host name in case of UDP and the path name in case of a local socket, and .Va port is the port in case of UDP transport. The function returns 0 in the case of success and return -1 and sets the error string in case of an error. .Sh DIAGNOSTICS If an error occurs in any of the function an error indication as described above is returned. Additionally the function sets a printable error string in the .Va error filed of .Va snmp_client . .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmplib 3 .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS .An Hartmut Brandt Aq harti@FreeBSD.org .An Kendy Kutzner Aq kutzner@fokus.gmd.de Index: head/contrib/bsnmp/lib/bsnmplib.3 =================================================================== --- head/contrib/bsnmp/lib/bsnmplib.3 (revision 237192) +++ head/contrib/bsnmp/lib/bsnmplib.3 (revision 237193) @@ -1,517 +1,514 @@ .\" .\" 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. .\" .\" Copyright (c) 2004-2005 .\" Hartmut Brandt. .\" All rights reserved. .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $Begemot: bsnmp/lib/bsnmplib.3,v 1.9 2005/10/04 08:46:51 brandt_h Exp $ .\" .Dd December 19, 2010 .Dt BSNMPLIB 3 .Os .Sh NAME .Nm snmp_value_free , .Nm snmp_value_parse , .Nm snmp_value_copy , .Nm snmp_pdu_free , .Nm snmp_pdu_decode , .Nm snmp_pdu_encode , .Nm snmp_pdu_decode_header , .Nm snmp_pdu_decode_scoped , .Nm snmp_pdu_decode_secmode , .Nm snmp_pdu_init_secparams , .Nm snmp_pdu_dump , .Nm snmp_passwd_to_keys , .Nm snmp_get_local_keys , .Nm snmp_calc_keychange , .Nm TRUTH_MK , .Nm TRUTH_GET , .Nm TRUTH_OK .Nd "SNMP decoding and encoding library" .Sh LIBRARY Begemot SNMP library .Pq libbsnmp, -lbsnmp .Sh SYNOPSIS .In bsnmp/asn1.h .In bsnmp/snmp.h .Ft void .Fn snmp_value_free "struct snmp_value *value" .Ft int .Fn snmp_value_parse "const char *buf" "enum snmp_syntax" "union snmp_values *value" .Ft int .Fn snmp_value_copy "struct snmp_value *to" "const struct snmp_value *from" .Ft void .Fn snmp_pdu_free "struct snmp_pdu *value" .Ft enum snmp_code .Fn snmp_pdu_decode "struct asn_buf *buf" "struct snmp_pdu *pdu" "int32_t *ip" .Ft enum snmp_code .Fn snmp_pdu_encode "struct snmp_pdu *pdu" "struct asn_buf *buf" .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" .Ft void .Fn snmp_pdu_init_secparams "struct snmp_pdu *pdu" .Ft void .Fn snmp_pdu_dump "const struct snmp_pdu *pdu" .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" .Ft int .Fn TRUTH_MK "F" .Ft int .Fn TRUTH_GET "T" .Ft int .Fn TRUTH_OK "T" .Sh DESCRIPTION The SNMP library contains routines to handle SNMP version 1, 2 and 3 PDUs. There are several basic structures used throughout the library: .Bd -literal -offset indent struct snmp_value { struct asn_oid var; enum snmp_syntax syntax; union snmp_values { int32_t integer;/* also integer32 */ struct { u_int len; u_char *octets; } octetstring; struct asn_oid oid; u_char ipaddress[4]; uint32_t uint32; /* also gauge32, counter32, unsigned32, timeticks */ uint64_t counter64; } v; }; .Ed .Pp This structure represents one variable binding from an SNMP PDU. The field .Fa var is the ASN.1 of the variable that is bound. .Fa syntax contains either the syntax code of the value or an exception code for SNMPv2 and may be one of: .Bd -literal -offset indent enum snmp_syntax { SNMP_SYNTAX_NULL = 0, SNMP_SYNTAX_INTEGER, /* == INTEGER32 */ SNMP_SYNTAX_OCTETSTRING, SNMP_SYNTAX_OID, SNMP_SYNTAX_IPADDRESS, SNMP_SYNTAX_COUNTER, SNMP_SYNTAX_GAUGE, /* == UNSIGNED32 */ SNMP_SYNTAX_TIMETICKS, /* v2 additions */ SNMP_SYNTAX_COUNTER64, /* exceptions */ SNMP_SYNTAX_NOSUCHOBJECT, SNMP_SYNTAX_NOSUCHINSTANCE, SNMP_SYNTAX_ENDOFMIBVIEW, }; .Ed The field .Fa v holds the actual value depending on .Fa syntax . Note, that if .Fa syntax is .Li SNMP_SYNTAX_OCTETSTRING and .Fa v.octetstring.len is not zero, .Fa v.octetstring.octets points to a string allocated by .Xr malloc 3 . -.Pp .Bd -literal -offset indent #define SNMP_ENGINE_ID_SIZ 32 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_ADM_STR32_SIZ (32 + 1) #define SNMP_AUTH_KEY_SIZ 40 #define SNMP_PRIV_KEY_SIZ 32 enum snmp_usm_level { SNMP_noAuthNoPriv = 1, SNMP_authNoPriv = 2, SNMP_authPriv = 3 }; struct snmp_user { char sec_name[SNMP_ADM_STR32_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_MPM_SNMP_V1 0 #define SNMP_MPM_SNMP_V2c 1 #define SNMP_MPM_SNMP_V3 3 struct snmp_pdu { char community[SNMP_COMMUNITY_MAXLEN + 1]; enum snmp_version version; u_int type; /* 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]; /* trap only */ struct asn_oid enterprise; u_char agent_addr[4]; int32_t generic_trap; int32_t specific_trap; uint32_t time_stamp; /* others */ int32_t request_id; int32_t error_status; int32_t error_index; /* fixes for encoding */ 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; struct snmp_value bindings[SNMP_MAX_BINDINGS]; u_int nbindings; }; .Ed This structure contains a decoded SNMP PDU. .Fa version is one of .Bd -literal -offset indent enum snmp_version { SNMP_Verr = 0, SNMP_V1 = 1, SNMP_V2c, SNMP_V3 }; .Ed and .Fa type is the type of the PDU. .Fa security_model is the security model used for SNMPv3 PDUs. The only supported value currently is 3 (User-based Security Model). Additional values for any, unknown, SNMPv1 and SNMPv2c security models are also enumerated .Bd -literal -offset indent enum snmp_secmodel { SNMP_SECMODEL_ANY = 0, SNMP_SECMODEL_SNMPv1 = 1, SNMP_SECMODEL_SNMPv2c = 2, SNMP_SECMODEL_USM = 3, SNMP_SECMODEL_UNKNOWN }; .Ed .Pp The function .Fn snmp_value_free is used to free all the dynamic allocated contents of an SNMP value. It does not free the structure pointed to by .Fa value itself. .Pp The function .Fn snmp_value_parse parses the ASCII representation of an SNMP value into its binary form. This function is mainly used by the configuration file reader of .Xr bsnmpd 1 . .Pp The function .Fn snmp_value_copy makes a deep copy of the value pointed to by .Fa from to the structure pointed to by .Fa to . It assumes that .Fa to is uninitialized and will overwrite its previous contents. It does not itself allocate the structure pointed to by .Fa to . .Pp The function .Fn snmp_pdu_free frees all the dynamically allocated components of the PDU. It does not itself free the structure pointed to by .Fa pdu . .Pp The function .Fn snmp_pdu_decode decodes the PDU pointed to by .Fa buf and stores the result into .Fa pdu . If an error occurs in a variable binding the (1 based) index of this binding is stored in the variable pointed to by .Fa ip . .Pp The function .Fn snmp_pdu_encode encodes the PDU .Fa pdu 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 .Fa buf . .Pp The function .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 .Fn snmp_pdu_init_secparams calculates the initialization vector for the privacy protocol in use before the PDU pointed to by .Fa pdu may be encrypted or decrypted. .Pp The function .Fn snmp_pdu_dump dumps the PDU in a human readable form by calling .Fn snmp_printf . .Pp The function .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 .Fn TRUTH_MK takes a C truth value (zero or non-zero) and makes an SNMP truth value (2 or 1). The function .Fn TRUTH_GET takes an SNMP truth value and makes a C truth value (0 or 1). The function .Fn TRUTH_OK checks, whether its argument is a legal SNMP truth value. .Sh DIAGNOSTICS When an error occurs in any of the function the function pointed to by the global pointer .Bd -literal -offset indent extern void (*snmp_error)(const char *, ...); .Ed .Pp with a .Xr printf 3 style format string. There is a default error handler in the library that prints a message starting with .Sq SNMP: followed by the error message to standard error. .Pp The function pointed to by .Bd -literal -offset indent extern void (*snmp_printf)(const char *, ...); .Ed .Pp is called by the .Fn snmp_pdu_dump function. The default handler is .Xr printf 3 . .Sh ERRORS .Fn snmp_pdu_decode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED The ASN.1 coding was wrong. .It Bq Er SNMP_CODE_BADLEN A variable binding value had a wrong length field. .It Bq Er SNMP_CODE_OORANGE A variable binding value was out of the allowed range. .It Bq Er SNMP_CODE_BADVERS The PDU is of an unsupported version. .It Bq Er SNMP_CODE_BADENQ There was an ASN.1 value with an unsupported tag. .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. .El .Pp .Fn snmp_pdu_encode will return one of the following return codes: .Bl -tag -width Er .It Bq Er SNMP_CODE_OK Success. .It Bq Er SNMP_CODE_FAILED Encoding failed. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr bsnmpd 1 , .Xr bsnmpagent 3 , .Xr bsnmpclient 3 , .Xr bsnmplib 3 .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. .Sh STANDARDS This implementation conforms to the applicable IETF RFCs and ITU-T recommendations. .Sh AUTHORS The Begemot SNMP library was originally written by .An Hartmut Brandt Aq harti@FreeBSD.org .Pp .An Shteryana Shopova Aq syrinx@FreeBSD.org added support for the SNMPv3 message proccessing and User-Based Security model message authentication and privacy. Index: head/contrib/bsnmp/snmp_target/snmp_target.3 =================================================================== --- head/contrib/bsnmp/snmp_target/snmp_target.3 (revision 237192) +++ head/contrib/bsnmp/snmp_target/snmp_target.3 (revision 237193) @@ -1,204 +1,204 @@ .\"- .\" Copyright (C) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by Shteryana Sotirova Shopova under .\" sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 16, 2010 .Dt SNMP_TARGET 3 .Os .Sh NAME .Nm snmp_target -.Nd "Target addresses and notifications module for +.Nd "Target addresses and notifications module for" .Xr bsnmpd 1 .Sh LIBRARY .Pq begemotSnmpdModulePath."target" = "/usr/lib/snmp_target.so" .Sh DESCRIPTION The .Nm snmp_target module implements SNMPv3 Management Target MIB and basic functionality from Notification MIB as defined in RFC 3413. The module is used to manage the internal list of SNMPv3 notification target addresses in .Nm bsnmpd and their associated transport and encapsulation parameters. The module must be loaded for .Nm bsnmpd to send SNMPv3 Trap-PDUs to the configured notification target addresses. .Sh IMPLEMENTATION NOTES A short description of the objects implemented in the module follows. .Bl -tag -width "XXXXXXXXX" .It Va snmpTargetSpinLock An advisory lock used to coordinate several Command Generator Applications when altering the SNMP Target addresses and their associated parameters. .It Va snmpTargetAddrTable The table contains the transport addresses to be used in generation of SNMP messages. The table contains the following objects .Bl -tag -width ".It Va snmpTargetAddrName" .It Va snmpTargetAddrName A unique local identifier used as entry key. Not accessible for GET or SET operations. .It Va snmpTargetAddrTDomain The transport domain of the target address. Currently only UDP over IPv4 is supported and any attempt to SET the value of this object will return an "inconsistentValue" error. Additional transport domains will be supported in future via the object definitions in TRANSPORT-ADDRESS-MIB (RFC 3419). .It Va snmpTargetAddrTAddress The transport address of this entry interpreted within the context of the value of .Va snmpTargetAddrTDomain . For UDP over IPv4, this is a 6-byte long octetstring, with the first 4 bytes representing the IPv4 address and the last 2 bytes the UDP port number in network-byte order. .It Va snmpTargetAddrTimeout The value of this object is only relevant when the receiver of the SNMP message is to send an acknowledgment that the message was received, i.e for SNMP notifications it is relevant if the notification is SNMP Inform rather than SNMP Trap. Currently .Nm bsnmpd supports only SNMP Trap notifications, so the value of this object is meaningless. .It Va snmpTargetAddrRetryCount As with .Va snmpTargetAddrTimeout the value of this object currently is meaningless. .It Va snmpTargetAddrTagList A list of human-readable tag values used to select target addresses for a particular operation. Recognized ASCII delimiting characters between tags are space (0x20), tab (0x20), carriage return (0xOD) and line feed (0x0A). .It Va snmpTargetAddrParams The value of this object contains the value of a key in snmpTargetParamsTable containing SNMP parameters used when generating messages to this transport address. .It Va snmpTargetAddrStorageType This column always has either of two values. Entries created via .Nm bsnmpd's configuration file always have this column set to readOnly (5) and it is not possible to modify those entries. Entries created by Command Generator Applications always have this column set to volatile(2) and such entries are lost when the module is restarted. A SET operation on this column is not allowed. .It Va snmpTargetAddrRowStatus This column is used to create new target address entries or delete existing ones from the table. .El .It Va snmpTargetParamsTable The table contains the target information to be used in generation of SNMP messages. The table contains the following objects .Bl -tag -width ".It Va snmpTargetParamsName" .It Va snmpTargetParamsName A unique local identifier used as entry key. Not accessible for GET or SET operations. .It Va snmpTargetParamsMPModel The Message Processing Model to be used when generating SNMP PDUs using this entry. Supported values are 0 for SNMPv1, 1 for SNMPv2c and 3 for SNMPv3. .It Va snmpTargetParamsSecurityModel The Security Model to be used when generating SNMP PDUs using this entry. Supported values are 1 for SNMPv1, 2 for SNMPv2c and 3 for SNMPv3 User-Based Security Model. .It Va snmpTargetParamsSecurityName The securityName which identifies the Principal on whose behalf SNMP PDUs will be generated using this entry. For SNMPv1 and SNMPv2c this is the name of a community configured in .Nm bsnmpd , and for SNMPv3 USM, this is the name of an existing user configured via the .Nm snmp_usm module. .It Va snmpTargetParamsSecurityLevel The Security Level to be used when generating SNMP PDUs using this entry. Supported values are noAuthNoPriv(1) for plain-text PDUs with no authentication, authNoPriv(2) for authenticated plain-text PDUs and authPriv(3) for encrypted PDUs. .It Va snmpTargetParamsStorageType As with .Va snmpTargetAddrStorageType this column always has either of two values. Entries created via .Nm bsnmpd's configuration file always have this column set to readOnly (5), while entries created by Command Generator Applications always have this column set to volatile(2). A SET operation on this column is not allowed. .It Va snmpTargetParamsRowStatus This column is used to create new target address parameters entries or delete existing ones from the table. .El .It Va snmpNotifyTable The table is used to select the management targets which should receive SNMP notifications. The table contains the following objects .Bl -tag -width ".It Va snmpNotifyName" .It Va snmpNotifyName A unique local identifier used as entry key. Not accessible for GET or SET operations. .It Va snmpNotifyTag This object contains a single tag value used to select target addresses from the .Va snmpTargetAddrTable to which the notifications will be send. .It Va snmpNotifyType The type of SNMP notifications that will be send to the target addresses matching the corresponding .Va snmpNotifyTag . Possible values are Trap (1) or Inform (2). Currently only SNMP Traps are supported and any attempt to SET the value of this object will return an "inconsistentValue" error. .It Va snmpNotifyStorageType Again this column always has either of two values. Entries created via .Nm bsnmpd's configuration file always have this column set to readOnly (5), while entries created by Command Generator Applications always have this column set to volatile(2). A SET operation on this column is not allowed. .It Va snmpNotifyRowStatus This column is used to create new notification target entries or delete existing ones from the table. .El .El .Pp The .Va snmpNotifyFilterProfileTable and .Va snmpNotifyFilterTable tables from the SNMP-NOTIFICATION-MIB are not supported by the module. Notification filtering is supported via the .Xr snmp_vacm 3 module instead. .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/snmp/defs/target_tree.def The description of the MIB tree implemented by .Nm . .El .Sh SEE ALSO .Xr bsnmpd 1 , .Xr gensnmptree 1 , .Xr snmpmod 3 , .Xr snmp_usm 3 , .Xr snmp_vacm 3 .Sh STANDARDS IETF RFC 3413 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org Index: head/contrib/bsnmp/snmp_usm/snmp_usm.3 =================================================================== --- head/contrib/bsnmp/snmp_usm/snmp_usm.3 (revision 237192) +++ head/contrib/bsnmp/snmp_usm/snmp_usm.3 (revision 237193) @@ -1,132 +1,132 @@ .\"- .\" Copyright (C) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by Shteryana Sotirova Shopova under .\" sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 9, 2010 .Dt SNMP_USM 3 .Os .Sh NAME .Nm snmp_usm -.Nd "user-based security module for +.Nd "user-based security module for" .Xr bsnmpd 1 .Sh LIBRARY .Pq begemotSnmpdModulePath."usm" = "/usr/lib/snmp_usm.so" .Sh DESCRIPTION The .Nm snmp_usm module implements SNMPv3 User-Based Security Model MIB as defined in RFC 3414. The module is used to manage the internal list of SNMPv3 USM active users in .Nm bsnmpd . The module must be loaded for .Nm bsnmpd to receive and process SNMPv3 USM PDUs correctly. .Sh IMPLEMENTATION NOTES A short description of the objects in the MIB follows. .Bl -tag -width "XXXXXXXXX" .It Va usmStats The subtree contains statistics for the User-based Security Model PDU processing. The statistics are reset each time the module is loaded. .It Va usmUserSpinLock An advisory lock used to coordinate several Command Generator Applications when altering the SNMP USM users. .It Va usmUserTable The table contains all SNMP USM users configured in .Nm bsnmpd . The table contains the following objects .Bl -tag -width ".It Va usmUserEngineID" .It Va usmUserEngineID An SNMP engine's administratively-unique identifier. Must be set to the same Engine ID as .Nm bsnmpd so that the user will actually be allowed to communicate with the daemon. The column is used as entry key and is not accessible for GET or SET operations. .It Va usmUserName The USM user name. The second entry key, again not accessible for GET or SET operations. .It Va usmUserSecurityName The column has the exact same value as the .Va usmUserName column, however is accessible for GET operations. .It Va usmUserCloneFrom A GET on this column will return an empty OID. SET operations are currently not supported. .It Va usmUserAuthProtocol The value of this column contains the OID corresponding to the authentication protocol used by the USM user. The following protocols and their OIDs are known to .Nm module .Bl -tag -width ".It Va NoAuthProtocol" .It NoAuthProtocol 1.3.6.1.6.3.10.1.1.1 .It HMACMD5AuthProtocol 1.3.6.1.6.3.10.1.1.2 .It HMACSHAAuthProtocol 1.3.6.1.6.3.10.1.1.3 .El .It Va usmUserAuthKeyChange , Va usmUserOwnAuthKeyChange These columns may be used to change the user's authentication key. .It Va usmUserPrivProtocol The value of this column contains the OID corresponding to the privacy protocol used by the USM user. The following protocols and their OIDs are known to .Nm module .Bl -tag -width ".It Va NoPrivProtocol" .It NoPrivProtocol 1.3.6.1.6.3.10.1.2.1 .It DESPrivProtoco 1.3.6.1.6.3.10.1.2.2 .It AesCfb128Protocol 1.3.6.1.6.3.10.1.2.4 .El .It Va usmUserPrivKeyChange , Va usmUserOwnPrivKeyChange These columns may be used to change the user's privacy key. .It Va usmUserPublic An arbitrary octet string that may be modified to confirm a SET operation on any of the columns was successful. .It Va usmUserStorageType This column always has either of two values. Entries created via .Nm bsnmpd's configuration file always have this column set to readOnly (5) and it is not possible to modify those entries. Entries created by Command Generator Applications always have this column set to volatile(2) and such entries are lost when the module is restarted. A SET operation on this column is not allowed. .It Va usmUserStatus This column is used to create new USM user entries or delete existing ones from the table. .El .El .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/snmp/defs/usm_tree.def The description of the MIB tree implemented by .Nm . .El .Sh SEE ALSO .Xr bsnmpd 1 , .Xr gensnmptree 1 , .Xr snmpmod 3 .Sh STANDARDS IETF RFC 3414 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org Index: head/contrib/bsnmp/snmp_vacm/snmp_vacm.3 =================================================================== --- head/contrib/bsnmp/snmp_vacm/snmp_vacm.3 (revision 237192) +++ head/contrib/bsnmp/snmp_vacm/snmp_vacm.3 (revision 237193) @@ -1,94 +1,94 @@ .\"- .\" Copyright (C) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" This documentation was written by Shteryana Sotirova Shopova under .\" sponsorship from the FreeBSD Foundation. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd October 7, 2010 .Dt SNMP_VACM 3 .Os .Sh NAME .Nm snmp_vacm -.Nd "View-based Access Control module for +.Nd "View-based Access Control module for" .Xr bsnmpd 1 .Sh LIBRARY .Pq begemotSnmpdModulePath."vacm" = "/usr/lib/snmp_vacm.so" .Sh DESCRIPTION The .Nm snmp_vacm module implements SNMPv3 View-based Access Control Model MIB as defined in RFC 3415. The module is used to manage the internal lists of SNMPv1, v2c and v3 user names and groups and their access rights to fetch or modify the values of the MIB objects maintained by .Nm bsnmpd and the modules loaded in the daemon. The module must be loaded for .Nm bsnmpd to implement proper view-based access control. If the module is not loaded, access is granted to all configured SNMPv1 & SNMPv2c communities and SNMPv3 USM users. .Sh IMPLEMENTATION NOTES An entry in any table implemented by this MIB may be created by setting the relevant RowStatus column to createAndGo (4) - in fact, any other value for those columns in a SET operation will cause an error. When an entry is created, any of its columns that is not used as index, is set to the default value as specified in the SNMP-VIEW-BASED-ACM-MIB. All entries maintained by the module are persistent after reboot if created via .Nm bsnmpd 's config file, otherwise entries created via SNMP are lost after reboot. A short description of the objects in the MIB follows. .Bl -tag -width "XXXXXXXXX" .It Va vacmContextTable A read-only table that consists of a list of SNMP contexts available in .Nm bsnmpd . .It Va vacmSecurityToGroupTable The table contains a list of SNMPv1, v2c and v3 user names and the groups they belong to. .It Va vacmAccessTable The table contains a list of SNMP contexts to groups mappings and respectively the names of the SNMP views under those contexts, to which users in the group are granted read-only, read-write access or receive notifications for the objects under the subtree in the relevant view. .It Va vacmViewTreeFamilyTable The table contains a list of SNMP views, i.e. entries specifying the OID of a MIB subtree and whether access to the objects under this subtree is to be allowed or forbidden. .El .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/snmp/defs/vacm_tree.def The description of the MIB tree implemented by .Nm . .El .Sh SEE ALSO .Xr bsnmpd 1 , .Xr gensnmptree 1 , .Xr snmpmod 3 .Sh STANDARDS IETF RFC 3415 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org