001: /*_############################################################################
002: _##
003: _## SNMP4J - PrivacyProtocol.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>PrivacyProtocol</code> interface defines a common
028: * interface for all SNMP privacy protocols.
029: *
030: * @author Jochen Katz & Frank Fock
031: * @version 1.9
032: */
033: public interface PrivacyProtocol extends SecurityProtocol {
034:
035: /**
036: * Encrypts a message using a given encryption key, engine boots count, and
037: * engine ID.
038: *
039: * @param unencryptedData
040: * the unencrypted data. This byte array may contain leading and trailing
041: * bytes that will not be encrypted.
042: * @param offset
043: * the offset into the <code>unencryptedData</code> where to start
044: * encryption.
045: * @param length
046: * the length of the substring starting at <code>offset</code> to encrypt.
047: * @param encryptionKey
048: * the key to be used for encryption.
049: * @param engineBoots
050: * the engine boots counter to use.
051: * @param engineTime
052: * the engine time to use.
053: * @param decryptParams
054: * returns the decryption parameters needed to decrypt the data that
055: * has been encrypted by this method.
056: * @return
057: * the encrypted copy of <code>unencryptedData</code>.
058: */
059: byte[] encrypt(byte[] unencryptedData, int offset, int length,
060: byte[] encryptionKey, long engineBoots, long engineTime,
061: DecryptParams decryptParams);
062:
063: /**
064: * Decrypts a message using a given decryption key, engine boots count, and
065: * engine ID.
066: *
067: * @param cryptedData
068: * the crypted data. This byte array may contain leading and trailing
069: * bytes that will not be decrypted.
070: * @param offset
071: * the offset into the <code>cryptedData</code> where to start
072: * encryption.
073: * @param length
074: * the length of the substring starting at <code>offset</code> to decrypt.
075: * @param decryptionKey
076: * the key to be used for decryption.
077: * @param engineBoots
078: * the engine boots counter to use.
079: * @param engineTime
080: * the engine time to use.
081: * @param decryptParams
082: * contains the decryption parameters.
083: * @return
084: * the decrypted data, or <code>null</code> if decryption failed.
085: */
086: byte[] decrypt(byte[] cryptedData, int offset, int length,
087: byte[] decryptionKey, long engineBoots, long engineTime,
088: DecryptParams decryptParams);
089:
090: /**
091: * Gets the OID uniquely identifying the privacy protocol.
092: * @return
093: * an <code>OID</code> instance.
094: */
095: OID getID();
096:
097: /**
098: * Gets the length of a scoped PDU when encrypted with this security protocol.
099: * @param scopedPDULength
100: * the length of the (unencrypted) scoped PDU.
101: * @return
102: * the length of the encrypted scoped PDU.
103: */
104: int getEncryptedLength(int scopedPDULength);
105:
106: /**
107: * Gets the minimum key size for this privacy protcol.
108: * @return
109: * the minimum key size for this privacy protcol.
110: */
111: int getMinKeyLength();
112:
113: /**
114: * Gets the maximum key size for this privacy protcol.
115: * @return
116: * the minimum key size for this privacy protcol.
117: */
118: int getMaxKeyLength();
119:
120: /**
121: * Gets the length of the decryption parameters used by this security
122: * protocol.
123: * @return
124: * a positive integer denoting the length of decryption parameters returned
125: * by this security protocol.
126: */
127: int getDecryptParamsLength();
128:
129: /**
130: * Extend a localized key that is too short.
131: *
132: * Some privacy protocols require a key that is longer than the key
133: * generated by the pasword to key algorithm of the authentication
134: * protocol. This function extends a short key to the required length.
135: *
136: * @param shortKey
137: * the short key that was generated using
138: * {@link AuthenticationProtocol#passwordToKey} function.
139: * @param password
140: * the password to use for key extension.
141: * @param engineID
142: * the SNMP engine ID of the authoritative engine.
143: * @param authProtocol
144: * the authentication protocol that should be used.
145: * @return
146: * the extended key or <code>shortKey</code> if no extension is needed.
147: * @since 1.9
148: */
149: byte[] extendShortKey(byte[] shortKey, OctetString password,
150: byte[] engineID, AuthenticationProtocol authProtocol);
151: }
|