contrib/bsnmp/snmp_usm/snmp_usm.3

   1 .\"-
   2 .\" Copyright (C) 2010 The FreeBSD Foundation
   3 .\" All rights reserved.
   4 .\"
   5 .\" This documentation was written by Shteryana Sotirova Shopova under
   6 .\" sponsorship from the FreeBSD Foundation.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 9, 2010
  32 .Dt SNMP_USM 3
  33 .Os
  34 .Sh NAME
  35 .Nm snmp_usm
  36 .Nd "user-based security module for"
  37 .Xr bsnmpd 1
  38 .Sh LIBRARY
  39 .Pq begemotSnmpdModulePath."usm" = "/usr/lib/snmp_usm.so"
  40 .Sh DESCRIPTION
  41 The
  42 .Nm snmp_usm
  43 module implements SNMPv3 User-Based Security Model MIB as defined in RFC 3414.
  44 The module is used to manage the internal list of SNMPv3 USM active users in
  45 .Nm bsnmpd .
  46 The module must be loaded for
  47 .Nm bsnmpd
  48 to receive and process SNMPv3 USM PDUs correctly.
  49 .Sh IMPLEMENTATION NOTES
  50 A short description of the objects in the MIB follows.
  51 .Bl -tag -width "XXXXXXXXX"
  52 .It Va usmStats
  53 The subtree contains statistics for the User-based Security Model PDU processing.
  54 The statistics are reset each time the module is loaded.
  55 .It Va usmUserSpinLock
  56 An advisory lock used to coordinate several Command Generator Applications when
  57 altering the SNMP USM users.
  58 .It Va usmUserTable
  59 The table contains all SNMP USM users configured in
  60 .Nm bsnmpd .
  61 The table contains the following objects
  62 .Bl -tag -width ".It Va usmUserEngineID"
  63 .It Va usmUserEngineID
  64 An SNMP engine's administratively-unique identifier. Must be set to the same
  65 Engine ID as
  66 .Nm bsnmpd
  67 so that the user will actually be allowed to communicate with the daemon.
  68 The column is used as entry key and is not accessible for GET or SET operations.
  69 .It Va usmUserName
  70 The USM user name. The second entry key, again not accessible for GET or SET
  71 operations.
  72 .It Va usmUserSecurityName
  73 The column has the exact same value as the
  74 .Va usmUserName
  75 column, however is accessible for GET operations.
  76 .It Va usmUserCloneFrom
  77 A GET on this column will return an empty OID. SET operations are currently not
  78 supported.
  79 .It Va usmUserAuthProtocol
  80 The value of this column contains the OID corresponding to the authentication
  81 protocol used by the USM user. The following protocols and their OIDs are known to
  82 .Nm
  83 module
  84 .Bl -tag -width ".It Va NoAuthProtocol"
  85 .It NoAuthProtocol 1.3.6.1.6.3.10.1.1.1
  86 .It HMACMD5AuthProtocol 1.3.6.1.6.3.10.1.1.2
  87 .It HMACSHAAuthProtocol 1.3.6.1.6.3.10.1.1.3
  88 .El
  89 .It Va usmUserAuthKeyChange , Va usmUserOwnAuthKeyChange
  90 These columns may be used to change the user's authentication key.
  91 .It Va usmUserPrivProtocol
  92 The value of this column contains the OID corresponding to the privacy
  93 protocol used by the USM user. The following protocols and their OIDs are known to
  94 .Nm
  95 module
  96 .Bl -tag -width ".It Va NoPrivProtocol"
  97 .It NoPrivProtocol 1.3.6.1.6.3.10.1.2.1
  98 .It DESPrivProtoco 1.3.6.1.6.3.10.1.2.2
  99 .It AesCfb128Protocol 1.3.6.1.6.3.10.1.2.4
 100 .El
 101 .It Va usmUserPrivKeyChange , Va usmUserOwnPrivKeyChange
 102 These columns may be used to change the user's privacy key.
 103 .It Va usmUserPublic
 104 An arbitrary octet string that may be modified to confirm a SET operation on any
 105 of the columns was successful.
 106 .It Va usmUserStorageType
 107 This column always has either of two values. Entries created via
 108 .Nm bsnmpd's
 109 configuration file always have this column set to readOnly (5) and
 110 it is not possible to modify those entries. Entries created by Command Generator
 111 Applications always have this column set to volatile(2) and such entries are
 112 lost when the module is restarted. A SET operation on this column is not
 113 allowed.
 114 .It Va usmUserStatus
 115 This column is used to create new USM user entries or delete existing ones from
 116 the table.
 117 .El
 118 .El
 119 .Sh FILES
 120 .Bl -tag -width "XXXXXXXXX"
 121 .It Pa /usr/share/snmp/defs/usm_tree.def
 122 The description of the MIB tree implemented by
 123 .Nm .
 124 .El
 125 .Sh SEE ALSO
 126 .Xr bsnmpd 1 ,
 127 .Xr gensnmptree 1 ,
 128 .Xr snmpmod 3
 129 .Sh STANDARDS
 130 IETF RFC 3414
 131 .Sh AUTHORS
 132 .An Shteryana Shopova Aq syrinx@FreeBSD.org