KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > snmp4j > security > UsmUser


1 /*_############################################################################
2   _##
3   _## SNMP4J - UsmUser.java
4   _##
5   _## Copyright 2003-2007 Frank Fock and Jochen Katz (SNMP4J.org)
6   _##
7   _## Licensed under the Apache License, Version 2.0 (the "License");
8   _## you may not use this file except in compliance with the License.
9   _## You may obtain a copy of the License at
10   _##
11   _## http://www.apache.org/licenses/LICENSE-2.0
12   _##
13   _## Unless required by applicable law or agreed to in writing, software
14   _## distributed under the License is distributed on an "AS IS" BASIS,
15   _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   _## See the License for the specific language governing permissions and
17   _## limitations under the License.
18   _##
19   _##########################################################################*/
20
21 package org.snmp4j.security;
22
23 import org.snmp4j.User;
24 import org.snmp4j.smi.OctetString;
25 import org.snmp4j.smi.OID;
26
27 /**
28  * The <code>UsmUser</code> class represents USM user providing information
29  * to secure SNMPv3 message exchange. A user is characterized by its security
30  * name and optionally by a authentication protocol and passphrase as well as
31  * a privacy protocol and passphrase.
32  * <p>
33  * There are no mutators for the attributes of this class, to prevent
34  * inconsistent states in the USM, when a user is changed from outside.
35  *
36  * @author Frank Fock
37  * @version 1.6
38  */
39 public class UsmUser implements User, Comparable JavaDoc, Cloneable JavaDoc {
40
41   private static final long serialVersionUID = -2258973598142206767L;
42
43   private OctetString securityName;
44   private OctetString authenticationPassphrase;
45   private OctetString privacyPassphrase;
46   private OID authenticationProtocol;
47   private OID privacyProtocol;
48   private OctetString localizationEngineID;
49
50   /**
51    * Creates a USM user.
52    * @param securityName
53    * the security name of the user (typically the user name).
54    * @param authenticationProtocol
55    * the authentication protcol ID to be associated with this user. If set
56    * to <code>null</code>, this user only supports unauthenticated messages.
57    * @param authenticationPassphrase
58    * the authentication passphrase. If not <code>null</code>,
59    * <code>authenticationProtocol</code> must also be not <code>null</code>.
60    * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
61    * If the length of <code>authenticationPassphrase</code> is less than 8
62    * bytes an <code>IllegalArgumentException</code> is thrown.
63    * @param privacyProtocol
64    * the privacy protcol ID to be associated with this user. If set
65    * to <code>null</code>, this user only supports unencrypted messages.
66    * @param privacyPassphrase
67    * the privacy passphrase. If not <code>null</code>,
68    * <code>privacyProtocol</code> must also be not <code>null</code>.
69    * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
70    * If the length of <code>authenticationPassphrase</code> is less than 8
71    * bytes an <code>IllegalArgumentException</code> is thrown.
72    */
73   public UsmUser(OctetString securityName,
74                  OID authenticationProtocol,
75                  OctetString authenticationPassphrase,
76                  OID privacyProtocol,
77                  OctetString privacyPassphrase) {
78     if (securityName == null) {
79       throw new NullPointerException JavaDoc();
80     }
81     if ((authenticationProtocol != null) &&
82         ((authenticationPassphrase != null) &&
83          (authenticationPassphrase.length() < 8))) {
84       throw new IllegalArgumentException JavaDoc(
85           "USM passphrases must be at least 8 bytes long (RFC3414 §11.2)");
86     }
87     if ((privacyProtocol != null) &&
88         ((privacyPassphrase != null) &&
89          (privacyPassphrase.length() < 8))) {
90       throw new IllegalArgumentException JavaDoc(
91           "USM passphrases must be at least 8 bytes long (RFC3414 §11.2)");
92     }
93     this.securityName = securityName;
94     this.authenticationProtocol = authenticationProtocol;
95     this.authenticationPassphrase = authenticationPassphrase;
96     this.privacyProtocol = privacyProtocol;
97     this.privacyPassphrase = privacyPassphrase;
98   }
99
100   /**
101    * Creates a localized USM user.
102    * @param securityName
103    * the security name of the user (typically the user name).
104    * @param authenticationProtocol
105    * the authentication protcol ID to be associated with this user. If set
106    * to <code>null</code>, this user only supports unauthenticated messages.
107    * @param authenticationPassphrase
108    * the authentication passphrase. If not <code>null</code>,
109    * <code>authenticationProtocol</code> must also be not <code>null</code>.
110    * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
111    * If the length of <code>authenticationPassphrase</code> is less than 8
112    * bytes an <code>IllegalArgumentException</code> is thrown.
113    * @param privacyProtocol
114    * the privacy protcol ID to be associated with this user. If set
115    * to <code>null</code>, this user only supports unencrypted messages.
116    * @param privacyPassphrase
117    * the privacy passphrase. If not <code>null</code>,
118    * <code>privacyProtocol</code> must also be not <code>null</code>.
119    * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
120    * If the length of <code>authenticationPassphrase</code> is less than 8
121    * bytes an <code>IllegalArgumentException</code> is thrown.
122    * @param localizationEngineID
123    * if not <code>null</code>, the localizationEngineID specifies the
124    * engine ID for which the supplied passphrases are already localized.
125    * Such an USM user can only be used with the target whose engine ID
126    * equals localizationEngineID.
127    */
128   public UsmUser(OctetString securityName,
129                  OID authenticationProtocol,
130                  OctetString authenticationPassphrase,
131                  OID privacyProtocol,
132                  OctetString privacyPassphrase,
133                  OctetString localizationEngineID) {
134     this(securityName, authenticationProtocol, authenticationPassphrase,
135          privacyProtocol, privacyPassphrase);
136     this.localizationEngineID = localizationEngineID;
137   }
138
139   /**
140    * Gets the user's security name.
141    * @return
142    * a clone of the user's security name.
143    */
144   public OctetString getSecurityName() {
145     return (OctetString) securityName.clone();
146   }
147
148   /**
149    * Gets the authentication protocol ID.
150    * @return
151    * a clone of the authentication protocol ID or <code>null</code>.
152    */
153   public OID getAuthenticationProtocol() {
154     if (authenticationProtocol == null) {
155       return null;
156     }
157     return (OID) authenticationProtocol.clone();
158   }
159
160   /**
161    * Gets the privacy protocol ID.
162    * @return
163    * a clone of the privacy protocol ID or <code>null</code>.
164    */
165   public OID getPrivacyProtocol() {
166     if (privacyProtocol == null) {
167       return null;
168     }
169     return (OID) privacyProtocol.clone();
170   }
171
172   /**
173    * Gets the authentication passphrase.
174    * @return
175    * a clone of the authentication passphrase or <code>null</code>.
176    */
177   public OctetString getAuthenticationPassphrase() {
178     if (authenticationPassphrase == null) {
179       return null;
180     }
181     return (OctetString) authenticationPassphrase.clone();
182   }
183
184   /**
185    * Gets the privacy passphrase.
186    * @return
187    * a clone of the privacy passphrase or <code>null</code>.
188    */
189   public OctetString getPrivacyPassphrase() {
190     if (privacyPassphrase == null) {
191       return null;
192     }
193     return (OctetString) privacyPassphrase.clone();
194   }
195
196   /**
197    * Returns the localization engine ID for which this USM user has been already
198    * localized.
199    * @return
200    * <code>null</code> if this USM user is not localized or the SNMP engine
201    * ID of the target for which this user has been localized.
202    * @since 1.6
203    */
204   public OctetString getLocalizationEngineID() {
205     return localizationEngineID;
206   }
207
208   /**
209    * Indicates whether the passphrases of this USM user need to be localized
210    * or not (<code>true</code> is returned in that case).
211    * @return
212    * <code>true</code> if the passphrases of this USM user represent
213    * localized keys.
214    * @since 1.6
215    */
216   public boolean isLocalized() {
217     return (localizationEngineID != null);
218   }
219
220   /**
221    * Gets the security model ID of the USM.
222    * @return
223    * {@link USM#getID()}
224    */
225   public int getSecurityModel() {
226     return SecurityModel.SECURITY_MODEL_USM;
227   }
228
229   /**
230    * Compares two USM users by their security names.
231    * @param o
232    * another <code>UsmUser</code> instance.
233    * @return
234    * a negative integer, zero, or a positive integer as this object is
235    * less than, equal to, or greater than the specified object.
236    */
237   public int compareTo(Object JavaDoc o) {
238     // allow only comparison with UsmUsers
239 UsmUser other = (UsmUser)o;
240     return securityName.compareTo(other.securityName);
241   }
242
243   public Object JavaDoc clone() {
244     UsmUser copy = new UsmUser(this.securityName, this.authenticationProtocol,
245                                this.authenticationPassphrase,
246                                this.privacyProtocol, this.privacyPassphrase,
247                                this.localizationEngineID);
248     return copy;
249   }
250
251   public String JavaDoc toString() {
252     return "UsmUser[secName="+securityName+
253         ",authProtocol="+authenticationProtocol+
254         ",authPassphrase="+authenticationPassphrase+
255         ",privProtocol="+privacyProtocol+
256         ",privPassphrase="+privacyPassphrase+
257         ",localizationEngineID="+getLocalizationEngineID()+"]";
258   }
259
260 }
261
Popular Tags