001: /*_############################################################################
002: _##
003: _## SNMP4J - UsmUser.java
004: _##
005: _## Copyright (C) 2003-2008 Frank Fock and Jochen Katz (SNMP4J.org)
006: _##
007: _## Licensed under the Apache License, Version 2.0 (the "License");
008: _## you may not use this file except in compliance with the License.
009: _## You may obtain a copy of the License at
010: _##
011: _## http://www.apache.org/licenses/LICENSE-2.0
012: _##
013: _## Unless required by applicable law or agreed to in writing, software
014: _## distributed under the License is distributed on an "AS IS" BASIS,
015: _## WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
016: _## See the License for the specific language governing permissions and
017: _## limitations under the License.
018: _##
019: _##########################################################################*/
020:
021: package org.snmp4j.security;
022:
023: import org.snmp4j.User;
024: import org.snmp4j.smi.OctetString;
025: import org.snmp4j.smi.OID;
026:
027: /**
028: * The <code>UsmUser</code> class represents USM user providing information
029: * to secure SNMPv3 message exchange. A user is characterized by its security
030: * name and optionally by a authentication protocol and passphrase as well as
031: * a privacy protocol and passphrase.
032: * <p>
033: * There are no mutators for the attributes of this class, to prevent
034: * inconsistent states in the USM, when a user is changed from outside.
035: *
036: * @author Frank Fock
037: * @version 1.6
038: */
039: public class UsmUser implements User, Comparable, Cloneable {
040:
041: private static final long serialVersionUID = -2258973598142206767L;
042:
043: private OctetString securityName;
044: private OctetString authenticationPassphrase;
045: private OctetString privacyPassphrase;
046: private OID authenticationProtocol;
047: private OID privacyProtocol;
048: private OctetString localizationEngineID;
049:
050: /**
051: * Creates a USM user.
052: * @param securityName
053: * the security name of the user (typically the user name).
054: * @param authenticationProtocol
055: * the authentication protcol ID to be associated with this user. If set
056: * to <code>null</code>, this user only supports unauthenticated messages.
057: * @param authenticationPassphrase
058: * the authentication passphrase. If not <code>null</code>,
059: * <code>authenticationProtocol</code> must also be not <code>null</code>.
060: * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
061: * If the length of <code>authenticationPassphrase</code> is less than 8
062: * bytes an <code>IllegalArgumentException</code> is thrown.
063: * @param privacyProtocol
064: * the privacy protcol ID to be associated with this user. If set
065: * to <code>null</code>, this user only supports unencrypted messages.
066: * @param privacyPassphrase
067: * the privacy passphrase. If not <code>null</code>,
068: * <code>privacyProtocol</code> must also be not <code>null</code>.
069: * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
070: * If the length of <code>authenticationPassphrase</code> is less than 8
071: * bytes an <code>IllegalArgumentException</code> is thrown.
072: */
073: public UsmUser(OctetString securityName,
074: OID authenticationProtocol,
075: OctetString authenticationPassphrase, OID privacyProtocol,
076: OctetString privacyPassphrase) {
077: if (securityName == null) {
078: throw new NullPointerException();
079: }
080: if ((authenticationProtocol != null)
081: && ((authenticationPassphrase != null) && (authenticationPassphrase
082: .length() < 8))) {
083: throw new IllegalArgumentException(
084: "USM passphrases must be at least 8 bytes long (RFC3414 §11.2)");
085: }
086: if ((privacyProtocol != null)
087: && ((privacyPassphrase != null) && (privacyPassphrase
088: .length() < 8))) {
089: throw new IllegalArgumentException(
090: "USM passphrases must be at least 8 bytes long (RFC3414 §11.2)");
091: }
092: this .securityName = securityName;
093: this .authenticationProtocol = authenticationProtocol;
094: this .authenticationPassphrase = authenticationPassphrase;
095: this .privacyProtocol = privacyProtocol;
096: this .privacyPassphrase = privacyPassphrase;
097: }
098:
099: /**
100: * Creates a localized USM user.
101: * @param securityName
102: * the security name of the user (typically the user name).
103: * @param authenticationProtocol
104: * the authentication protcol ID to be associated with this user. If set
105: * to <code>null</code>, this user only supports unauthenticated messages.
106: * @param authenticationPassphrase
107: * the authentication passphrase. If not <code>null</code>,
108: * <code>authenticationProtocol</code> must also be not <code>null</code>.
109: * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
110: * If the length of <code>authenticationPassphrase</code> is less than 8
111: * bytes an <code>IllegalArgumentException</code> is thrown.
112: * @param privacyProtocol
113: * the privacy protcol ID to be associated with this user. If set
114: * to <code>null</code>, this user only supports unencrypted messages.
115: * @param privacyPassphrase
116: * the privacy passphrase. If not <code>null</code>,
117: * <code>privacyProtocol</code> must also be not <code>null</code>.
118: * RFC3414 §11.2 requires passphrases to have a minimum length of 8 bytes.
119: * If the length of <code>authenticationPassphrase</code> is less than 8
120: * bytes an <code>IllegalArgumentException</code> is thrown.
121: * @param localizationEngineID
122: * if not <code>null</code>, the localizationEngineID specifies the
123: * engine ID for which the supplied passphrases are already localized.
124: * Such an USM user can only be used with the target whose engine ID
125: * equals localizationEngineID.
126: */
127: public UsmUser(OctetString securityName,
128: OID authenticationProtocol,
129: OctetString authenticationPassphrase, OID privacyProtocol,
130: OctetString privacyPassphrase,
131: OctetString localizationEngineID) {
132: this (securityName, authenticationProtocol,
133: authenticationPassphrase, privacyProtocol,
134: privacyPassphrase);
135: this .localizationEngineID = localizationEngineID;
136: }
137:
138: /**
139: * Gets the user's security name.
140: * @return
141: * a clone of the user's security name.
142: */
143: public OctetString getSecurityName() {
144: return (OctetString) securityName.clone();
145: }
146:
147: /**
148: * Gets the authentication protocol ID.
149: * @return
150: * a clone of the authentication protocol ID or <code>null</code>.
151: */
152: public OID getAuthenticationProtocol() {
153: if (authenticationProtocol == null) {
154: return null;
155: }
156: return (OID) authenticationProtocol.clone();
157: }
158:
159: /**
160: * Gets the privacy protocol ID.
161: * @return
162: * a clone of the privacy protocol ID or <code>null</code>.
163: */
164: public OID getPrivacyProtocol() {
165: if (privacyProtocol == null) {
166: return null;
167: }
168: return (OID) privacyProtocol.clone();
169: }
170:
171: /**
172: * Gets the authentication passphrase.
173: * @return
174: * a clone of the authentication passphrase or <code>null</code>.
175: */
176: public OctetString getAuthenticationPassphrase() {
177: if (authenticationPassphrase == null) {
178: return null;
179: }
180: return (OctetString) authenticationPassphrase.clone();
181: }
182:
183: /**
184: * Gets the privacy passphrase.
185: * @return
186: * a clone of the privacy passphrase or <code>null</code>.
187: */
188: public OctetString getPrivacyPassphrase() {
189: if (privacyPassphrase == null) {
190: return null;
191: }
192: return (OctetString) privacyPassphrase.clone();
193: }
194:
195: /**
196: * Returns the localization engine ID for which this USM user has been already
197: * localized.
198: * @return
199: * <code>null</code> if this USM user is not localized or the SNMP engine
200: * ID of the target for which this user has been localized.
201: * @since 1.6
202: */
203: public OctetString getLocalizationEngineID() {
204: return localizationEngineID;
205: }
206:
207: /**
208: * Indicates whether the passphrases of this USM user need to be localized
209: * or not (<code>true</code> is returned in that case).
210: * @return
211: * <code>true</code> if the passphrases of this USM user represent
212: * localized keys.
213: * @since 1.6
214: */
215: public boolean isLocalized() {
216: return (localizationEngineID != null);
217: }
218:
219: /**
220: * Gets the security model ID of the USM.
221: * @return
222: * {@link USM#getID()}
223: */
224: public int getSecurityModel() {
225: return SecurityModel.SECURITY_MODEL_USM;
226: }
227:
228: /**
229: * Compares two USM users by their security names.
230: * @param o
231: * another <code>UsmUser</code> instance.
232: * @return
233: * a negative integer, zero, or a positive integer as this object is
234: * less than, equal to, or greater than the specified object.
235: */
236: public int compareTo(Object o) {
237: // allow only comparison with UsmUsers
238: UsmUser other = (UsmUser) o;
239: return securityName.compareTo(other.securityName);
240: }
241:
242: public Object clone() {
243: UsmUser copy = new UsmUser(this .securityName,
244: this .authenticationProtocol,
245: this .authenticationPassphrase, this .privacyProtocol,
246: this .privacyPassphrase, this .localizationEngineID);
247: return copy;
248: }
249:
250: public String toString() {
251: return "UsmUser[secName=" + securityName + ",authProtocol="
252: + authenticationProtocol + ",authPassphrase="
253: + authenticationPassphrase + ",privProtocol="
254: + privacyProtocol + ",privPassphrase="
255: + privacyPassphrase + ",localizationEngineID="
256: + getLocalizationEngineID() + "]";
257: }
258:
259: }
|