userapps/opensource/net-snmp/README.krb5

   1 This version of net-snmp supports an experimental SNMPv3 security model
   2 using Kerberos 5 for authentication.  The protocol is described in an
   3 up-and-coming IETF Internet-Draft.
   4
   5 This document describes a brief overview of the Kerberos Security Model
   6 and how to use it.
   7
   8 DESCRIPTION:
   9
  10 The Kerberos Security Model does not use USM; it is completely seperate
  11 and is not tied to USM in any way.  It works by placing the following
  12 ASN.1 sequence inside of the SNMPv3 msgSecurityParameters:
  13
  14 ksmSecurityParameters ::= SEQUENCE {
  15 -- The Kerberos 5 checksum type used to checksum this message
  16     ksmChecksumType             INTEGER(0..2147483647),
  17 -- The actual keyed checksum data returned by Kerberos
  18     ksmChecksum                 OCTET STRING,
  19 -- The Kerberos 5 message (either an AP_REQ or AP_REP)
  20     ksmKerberosMsg              OCTET STRING,
  21 -- The cached ticket identifier
  22     ksmCachedTicket             INTEGER(0..2147483647)
  23 }
  24
  25 Note that the whole SEQUENCE is BER encoded as an OCTET STRING.
  26
  27 ksmChecksumType is an integer which corresponded to the checksum algorithm
  28 used to secure this message as defined by Kerberos (see section 8.3 of
  29 RFC1510).
  30
  31 ksmChecksum is the output of the checksum algoritm defined by ksmChecksumtype
  32 (with all NULs in the space for the checksum).
  33
  34 ksmKerberosMsg is a Kerberos 5 AP_REQ or AP_REP message, depending on
  35 whether or not it is a request or a response (AP_REQ for requests, AP_REP
  36 for responses).
  37
  38 ksmCachedTicket is a integer which uniquely identifies a ticked already
  39 cached on the agent to save the overhead of transferring a whole AP_REQ/AP_REP.
  40 If there is no such cached ticket, it is left at zero.
  41
  42 An agent, upon receiving a message using the KSM, will decode the AP_REQ
  43 contained within the security parameters and thus validate the client's
  44 identity.  Using the subkey contained within the AP_REQ, the agent will
  45 validate the checksum (after first clearing the checksum bytes to zero),
  46 and issue a response, encoding the appropriate AP_REP message in the
  47 ksmSecurityParameters.
  48
  49 If the securityLevel of the message is set to AuthPriv, the scopedPdu
  50 payload will be encrypted using the encryption key and algorithm of the
  51 AP_REQ subkey.  Note that in this case, the msgData will be a BER-encoded
  52 OCTET STRING corresponding to the "cipher" element of the EncryptedData
  53 sequence defined in RFC 1510, section 6.1.
  54
  55 Since this security model is experimental, the number assigned to this
  56 security model is taken from the recommendations of RFC 2271, section 5,
  57 which specify enterprise-specific Security Models of the form:
  58
  59         SnmpSecurityModel = enterpriseID * 256 + security model number
  60                                                  in that enterprise ID;
  61
  62 In the case of KSM this gives us:
  63
  64         SnmpSecurityModel = 8072 * 256 + 0 = 2066432
  65
  66
  67 USAGE:
  68
  69 To actually USE the Kerberos Security Model, do the following:
  70
  71 0) Install Kerberos
  72
  73    Let it be stated up front - Installing Kerberos completely "cold", without
  74    any Kerberos experience at all, can be daunting (to say the least).  If you
  75    already have a Kerberos infrastructure at your site, then all of the hard
  76    work has been done.  If you do NOT, but you still want to tackle it,
  77    you might be interested in the Kerberos FAQ, which can be found at:
  78
  79    http://www.nrl.navy.mil/CCS/people/kenh/kerberos-faq.html
  80
  81    Currently the code in net-snmp only supports using MIT Kerberos
  82    libraries to link against (you should be able to use any kind of Kerberos
  83    server, however).
  84
  85 1) Compile net-snmp with Kerberos.
  86
  87    This assumes that you already have Kerberos libraries in place.
  88
  89    Configure net-snmp to include the Kerberos Security Model (ksm) and
  90    use --with-cflags and --with-ldflags to specify the location and names
  91    of Kerberos header files and libraries.  For example, on my system I
  92    run:
  93
  94    ./configure --with-cflags='-I/usr/krb5/include' \
  95       --with-ldflags='-L/usr/krb5/lib -lkrb5 -lcrypto -lcom_err -R/usr/krb5/lib'
  96
  97    Note that this is on Solaris, and that -R is required to set the correct
  98    shared library path.  If you have a newer version of Kerberos, you might
  99    instead have to use:
 100
 101    -lkrb5 -lk5crypto -lcom_err
 102
 103    as the libraries to link against.  If you get errors (for example, you
 104    get a message that says the compiler isn't working) you can check
 105    config.log for the output of the compiler.
 106
 107 2) Configure Kerberos and SNMP
 108
 109    Currently, net-snmp uses the "host" principal assigned to a host.  This
 110    may change in the future.  You will want to create host principals of
 111    the form:
 112
 113    host/f.q.d.n@YOUR.REALM
 114
 115    For example:
 116
 117    host/mydesktop.example.org@EXAMPLE.ORG
 118
 119    and place the encryption keys for these principals on every machine you
 120    wish to run a SNMP agent (you place each key on it's corresponding machine).
 121    Your Kerberos documentation should explain how to do this (in the case
 122    of MIT Kerberos, you want to look at the "ktadd" command inside of
 123    kadmin).
 124
 125    If you have a Kerberos infrastructure, you likely already have these
 126    principals in place on your systems.
 127
 128    If you're installing Kerberos for the first time as well, you also
 129    need to create client principals corresponding to your userid.  See
 130    your Kerberos documentation.
 131
 132    On the SNMP _agent_ side, you'll want to place in your snmpd.conf file
 133    (the one that lives in /usr/local/share/snmp/snmpd.conf, or whereever
 134    you have configured on your system):
 135
 136    rwuser -s userid@YOUR.REALM
 137
 138    to allow the Kerberos principal 'userid@YOUR.REALM' read/write access to
 139    the MIB tree.
 140
 141 3) Run the agent and client applications
 142
 143    Note that before you do any of this, you will have to have valid Kerberos
 144    credentials (generally acquired with the "kinit" program).
 145
 146    The agent should run without any additional flags.
 147
 148    You should run the client apps with the following flags:
 149
 150    -Y defSecurityModel=ksm
 151    -v 3
 152    -u username
 153    -l authNoPriv
 154
 155    for example:
 156
 157    snmpget -v 3 -Y defSecurityModel=ksm -u myname -l authNoPriv testhost \
 158                                                 system.sysDescr.0
 159
 160    If you wish to encrypt the payload, change the -l argument to "authPriv".
 161
 162    If you run into problems, you can add the -Dksm flag to both the manager
 163    applications and the agent to get more detailed Kerberos error messages.
 164    Note that this setup assumes a working Kerberos infrastructure; if you
 165    run into problems, check to make sure Kerberos is working for you.