org.snmp4j.security.PrivacyProtocol Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of snmp4j Show documentation
SNMP API for Java
There is a newer version: 3.8.2
/*_############################################################################
  _## 
  _##  SNMP4J - PrivacyProtocol.java  
  _## 
  _##  Copyright (C) 2003-2022  Frank Fock (SNMP4J.org)
  _##  
  _##  Licensed under the Apache License, Version 2.0 (the "License");
  _##  you may not use this file except in compliance with the License.
  _##  You may obtain a copy of the License at
  _##  
  _##      http://www.apache.org/licenses/LICENSE-2.0
  _##  
  _##  Unless required by applicable law or agreed to in writing, software
  _##  distributed under the License is distributed on an "AS IS" BASIS,
  _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  _##  See the License for the specific language governing permissions and
  _##  limitations under the License.
  _##  
  _##########################################################################*/
package org.snmp4j.security;

import org.snmp4j.smi.OID;
import org.snmp4j.smi.OctetString;

/**
 * The PrivacyProtocol interface defines a common
 * interface for all SNMP privacy protocols.
 *
 * @author Frank Fock
 * @author Jochen Katz
 * @version 1.9
 */
public interface PrivacyProtocol extends SecurityProtocol {

    /**
     * Encrypts a message using a given encryption key, engine boots count, and
     * engine ID.
     *
     * @param unencryptedData
     *    the unencrypted data. This byte array may contain leading and trailing
     *    bytes that will not be encrypted.
     * @param offset
     *    the offset into the unencryptedData where to start
     *    encryption.
     * @param length
     *     the length of the substring starting at offset to encrypt.
     * @param encryptionKey
     *     the key to be used for encryption.
     * @param engineBoots
     *     the engine boots counter to use.
     * @param engineTime
     *     the engine time to use.
     * @param decryptParams
     *     returns the decryption parameters needed to decrypt the data that
     *     has been encrypted by this method.
     * @return
     *     the encrypted copy of unencryptedData.
     */
    byte[] encrypt(byte[] unencryptedData,
                   int offset,
                   int length,
                   byte[] encryptionKey,
                   long engineBoots,
                   long engineTime,
                   DecryptParams decryptParams);

    /**
     * Decrypts a message using a given decryption key, engine boots count, and
     * engine ID.
     *
     * @param cryptedData
     *    the crypted data. This byte array may contain leading and trailing
     *    bytes that will not be decrypted.
     * @param offset
     *    the offset into the cryptedData where to start
     *    encryption.
     * @param length
     *     the length of the substring starting at offset to decrypt.
     * @param decryptionKey
     *     the key to be used for decryption.
     * @param engineBoots
     *     the engine boots counter to use.
     * @param engineTime
     *     the engine time to use.
     * @param decryptParams
     *     contains the decryption parameters.
     * @return
     *    the decrypted data, or null if decryption failed.
     */
    byte[] decrypt(byte[] cryptedData,
                   int offset,
                   int length,
                   byte[] decryptionKey,
                   long engineBoots,
                   long engineTime,
                   DecryptParams decryptParams);

    /**
     * Gets the OID uniquely identifying the privacy protocol.
     * @return
     *    an OID instance.
     */
    OID getID();

    /**
     * Gets the length of a scoped PDU when encrypted with this security protocol.
     * @param scopedPDULength
     *    the length of the (unencrypted) scoped PDU.
     * @return
     *    the length of the encrypted scoped PDU.
     */
    int getEncryptedLength(int scopedPDULength);

    /**
     * Gets the minimum key size for this privacy protocol.
     * @return
     *    the minimum key size for this privacy protocol.
     */
    int getMinKeyLength();

    /**
     * Gets the maximum key size for this privacy protocol.
     * @return
     *    the minimum key size for this privacy protocol.
     */
    int getMaxKeyLength();

    /**
     * Gets the length of the decryption parameters used by this security
     * protocol.
     * @return
     *    a positive integer denoting the length of decryption parameters returned
     *    by this security protocol.
     */
    int getDecryptParamsLength();

    /**
     * Extend a localized key that is too short.
     *
     * Some privacy protocols require a key that is longer than the key
     * generated by the password-to-key algorithm of the authentication
     * protocol. This function extends a short key to the required length.
     *
     * @param shortKey
     *    the short key that was generated using
     *    {@link AuthenticationProtocol#passwordToKey} function.
     * @param password
     *    the password to use for key extension.
     * @param engineID
     *    the SNMP engine ID of the authoritative engine.
     * @param authProtocol
     *    the authentication protocol that should be used.
     * @return
     *    the extended key or shortKey if no extension is needed.
     * @since 1.9
     */
    byte[] extendShortKey(byte[] shortKey,
                          OctetString password,
                          byte[] engineID,
                          AuthenticationProtocol authProtocol);
}