001: /*_############################################################################
002: _##
003: _## SNMP4J - AuthenticationProtocol.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.smi.OID;
024: import org.snmp4j.smi.OctetString;
025:
026: /**
027: * The <code>AuthenticationProtocol</code> interface defines a common
028: * interface for all SNMP authentication protocols.
029: *
030: * @author Frank Fock
031: * @version 1.0
032: */
033: public interface AuthenticationProtocol extends SecurityProtocol {
034:
035: int MESSAGE_AUTHENTICATION_CODE_LENGTH = 12;
036:
037: /**
038: * Authenticates an outgoing message.
039: *
040: * This method fills the authentication parameters field of the
041: * given message. The parameter <code>digestOffset</code> offset is pointing
042: * inside the message buffer and must be zeroed before the authentication
043: * value is computed.
044: *
045: * @param authenticationKey
046: * the authentication key to be used for authenticating the message.
047: * @param message
048: * the entire message for which the digest should be determined.
049: * @param messageOffset
050: * the offset in <code>message</code> where the message actually starts.
051: * @param messageLength
052: * the actual message length (may be smaller than
053: * <code>message.length</code>).
054: * @param digest
055: * the offset in <code>message</code> where to store the digest.
056: * @return
057: * <code>true</code> if the message digest has been successfully computed
058: * and set, <code>false</code> otherwise.
059: */
060: boolean authenticate(byte[] authenticationKey, byte[] message,
061: int messageOffset, int messageLength, ByteArrayWindow digest);
062:
063: /**
064: * Authenticates an incoming message.
065: *
066: * This method checks if the value in the authentication parameters
067: * field of the message is valid.
068: *
069: * The following procedure is used to verify the authenitcation value
070: * <UL>
071: * <LI> copy the authentication value to a temp buffer
072: * <LI> zero the auth field
073: * <LI> recalculate the authenthication value
074: * <LI> compare the two authentcation values
075: * <LI> write back the received authentication value
076: * </UL>
077: *
078: * @param authenticationKey
079: * the authentication key to be used for authenticating the message.
080: * @param message
081: * the entire message for which the digest should be determined.
082: * @param messageOffset
083: * the offset in <code>message</code> where the message actually starts.
084: * @param messageLength
085: * the actual message length (may be smaller than
086: * <code>message.length</code>).
087: * @param digest
088: * the digest of the <code>message</code>.
089: * @return
090: * <code>true</code> if the message is authentic, <code>false</code>
091: * otherwise.
092: */
093: boolean isAuthentic(byte[] authenticationKey, byte[] message,
094: int messageOffset, int messageLength, ByteArrayWindow digest);
095:
096: /**
097: * Computes the delta digest needed to remotely change an user's
098: * authenitcation key. The length of the old key (e.g. 16 for MD5,
099: * 20 for SHA) must match the length of the new key.
100: *
101: * @param oldKey
102: * the old authentication/privacy key.
103: * @param newKey
104: * the new authentication/privacy key.
105: * @param random
106: * the random 'seed' to be used to produce the digest.
107: * @return
108: * the byte array representing the delta for key change operations.
109: * To obtain the key change value, append this delta to the
110: * <code>random</code> array.
111: */
112: byte[] changeDelta(byte[] oldKey, byte[] newKey, byte[] random);
113:
114: /**
115: * Gets the OID uniquely identifying the authentication protocol.
116: * @return
117: * an <code>OID</code> instance.
118: */
119: OID getID();
120:
121: /**
122: * Generates the localized key for the given password and engine id.
123: *
124: * @param passwordString
125: * the authentication pass phrase.
126: * @param engineID
127: * the engine ID of the authoritative engine.
128: * @return
129: * the localized authentication key.
130: */
131: byte[] passwordToKey(OctetString passwordString, byte[] engineID);
132:
133: /**
134: * Generates a hash value for the given data.
135: *
136: * @param data
137: * the data
138: * @return
139: * the generated hash.
140: */
141: byte[] hash(byte[] data);
142:
143: /**
144: * Generates a hash value for the given data.
145: *
146: * @param data
147: * the data
148: * @param offset
149: * offset into data
150: * @param length
151: * length of data to hash
152: * @return
153: * the generated hash.
154: */
155: byte[] hash(byte[] data, int offset, int length);
156:
157: /**
158: * Gets the length of the digest generated by this authentication protocol.
159: * This value can be used to compute the BER encoded length of the security
160: * parameters for authentication.
161: *
162: * @return
163: * the number of bytes of digests generated by this authentication
164: * procotol.
165: */
166: int getDigestLength();
167: }
|