1
by Martin Pitt
Import upstream version 5.1.1 |
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 ksm 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. |