org.snmp4j.security.SecurityModel Maven / Gradle / Ivy
/*_############################################################################
_##
_## SNMP4J 2 - SecurityModel.java
_##
_## Copyright (C) 2003-2016 Frank Fock and Jochen Katz (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 java.io.*;
import org.snmp4j.TransportStateReference;
import org.snmp4j.mp.StatusInformation;
import org.snmp4j.smi.OctetString;
import org.snmp4j.smi.Integer32;
import org.snmp4j.asn1.BERInputStream;
// for JavaDoc
import org.snmp4j.mp.SnmpConstants;
import org.snmp4j.asn1.BEROutputStream;
/**
* The SecurityModel interface as described in RFC3411 section 4.4
* and RFC 5590 section 5.
*
* @author Frank Fock
* @version 2.0
*/
public interface SecurityModel {
int SECURITY_MODEL_ANY = 0;
int SECURITY_MODEL_SNMPv1 = 1;
int SECURITY_MODEL_SNMPv2c = 2;
int SECURITY_MODEL_USM = 3;
int SECURITY_MODEL_TSM = 4;
/**
* Gets the ID of the security model.
* @return
* one of the integer constants defined in the {@link SecurityModel}
* interface.
* @see SecurityModel#SECURITY_MODEL_ANY
* @see SecurityModel#SECURITY_MODEL_SNMPv1
* @see SecurityModel#SECURITY_MODEL_SNMPv2c
* @see SecurityModel#SECURITY_MODEL_USM
*/
int getID();
/**
* Creates a new {@link SecurityParameters} instance that corresponds to this
* security model.
* @return
* a new SecurityParameters instance.
*/
SecurityParameters newSecurityParametersInstance();
/**
* Creates a new {@link SecurityStateReference} instance that corresponds to
* this security model.
* @return
* a new SecurityStateReference instance.
*/
SecurityStateReference newSecurityStateReference();
/**
* Generate a request message.
* @param messageProcessingModel
* the ID of the message processing model (SNMP version) to use.
* @param globalData
* the message header and admin data.
* @param maxMessageSize
* the maximum message size of the sending (this) SNMP entity for the
* selected transport mapping (determined by the message processing model).
* @param securityModel
* the security model for the outgoing message.
* @param securityEngineID
* the authoritative SNMP entity.
* @param securityName
* the principal on behalf of this message is generated.
* @param securityLevel
* the requested {@link SecurityLevel}.
* @param scopedPDU
* a BERInputStream containing the message (plain text) payload.
* @param securityParameters
* returns the {@link SecurityParameters} filled by the security model.
* @param wholeMsg
* returns the complete generated message in a BEROutputStream.
* The buffer of wholeMsg is set to null by the
* caller and must be set by the implementation of this method.
* @param tmStateReference
* the transport model state reference as defined by RFC 5590.
* @throws IOException
* if generation of the message fails because of an internal or an resource
* error.
* @return
* the error status of the message generation. On success
* {@link SnmpConstants#SNMPv3_USM_OK} is returned, otherwise one of the
* other SnmpConstants.SNMPv3_USM_* values is returned.
*/
int generateRequestMessage(int messageProcessingModel,
byte[] globalData,
int maxMessageSize,
int securityModel,
byte[] securityEngineID,
byte[] securityName,
int securityLevel,
BERInputStream scopedPDU,
// out parameters
SecurityParameters securityParameters,
BEROutputStream wholeMsg,
TransportStateReference tmStateReference) throws IOException;
/**
* Generates a response message.
* @param messageProcessingModel
* the ID of the message processing model (SNMP version) to use.
* @param globalData
* the message header and admin data.
* @param maxMessageSize
* the maximum message size of the sending (this) SNMP entity for the
* selected transport mapping (determined by the message processing model).
* @param securityModel
* the security model for the outgoing message.
* @param securityEngineID
* the authoritative SNMP entity.
* @param securityName
* the principal on behalf of this message is generated.
* @param securityLevel
* the requested {@link SecurityLevel}.
* @param scopedPDU
* a BERInputStream containing the message (plain text) payload.
* @param securityStateReference
* a {@link SecurityStateReference} instance providing information from
* original request.
* @param securityParameters
* returns the {@link SecurityParameters} filled by the security model.
* @param wholeMsg
* returns the complete generated message in a BEROutputStream.
* The buffer of wholeMsg is set to null by the
* caller and must be set by the implementation of this method.
* @throws IOException
* if generation of the message fails because of an internal or an resource
* error.
* @return
* the error status of the message generation. On success
* {@link SnmpConstants#SNMPv3_USM_OK} is returned, otherwise one of the
* other SnmpConstants.SNMPv3_USM_* values is returned.
*/
int generateResponseMessage(int messageProcessingModel,
byte[] globalData,
int maxMessageSize,
int securityModel,
byte[] securityEngineID,
byte[] securityName,
int securityLevel,
BERInputStream scopedPDU,
SecurityStateReference securityStateReference,
// out parameters
SecurityParameters securityParameters,
BEROutputStream wholeMsg) throws IOException;
/**
* Processes an incoming message and returns its plaintext payload.
* @param messageProcessingModel
* the ID of the message processing model (SNMP version) to use.
* @param maxMessageSize
* the maximum message size of the message processing model for the
* transport mapping associated with this message's source address less
* the length of the maximum header length of the message processing model.
* This value is used by the security model to determine the
* maxSizeResponseScopedPDU value.
* @param securityParameters
* the {@link SecurityParameters} for the received message.
* @param securityModel
* the {@link SecurityModel} instance for the received message.
* @param securityLevel
* the {@link SecurityLevel} ID.
* @param wholeMsg
* the BERInputStream containing the whole message as received
* on the wire.
* @param tmStateReference
* the transport model state reference as defined by RFC 5590.
* @param securityEngineID
* the authoritative SNMP entity.
* @param securityName
* the identification of the principal.
* @param scopedPDU
* returns the message (plaintext) payload into the supplied
* BEROutputStream.
* The buffer of scopedPDU is set to null by the
* caller and must be set by the implementation of this method.
* @param maxSizeResponseScopedPDU
* the determined maximum size for a response PDU.
* @param securityStateReference
* the SecurityStateReference information needed for
* a response.
* @param statusInfo
* the StatusInformation needed to generate reports if
* processing of the incoming message failed.
* @throws IOException
* if an unexpected (internal) or an resource error occurred.
* @return
* the error status of the message processing. On success
* {@link SnmpConstants#SNMPv3_USM_OK} is returned, otherwise one of the
* other SnmpConstants.SNMPv3_USM_* values is returned.
*/
int processIncomingMsg(int messageProcessingModel,
int maxMessageSize,
SecurityParameters securityParameters,
SecurityModel securityModel,
int securityLevel,
BERInputStream wholeMsg,
TransportStateReference tmStateReference,
// out parameters
OctetString securityEngineID,
OctetString securityName,
BEROutputStream scopedPDU,
Integer32 maxSizeResponseScopedPDU,
SecurityStateReference securityStateReference,
StatusInformation statusInfo) throws IOException;
/**
* Checks whether this {@link SecurityModel} supports authoritative
* engine ID discovery.
* The {@link USM} for instance, returns true whereas
* {@link TSM} returns false.
* See also RFC 5343 3.2 for details.
* @return
* true if this security model has its own authoritative
* engine ID discovery mechanism.
*/
boolean supportsEngineIdDiscovery();
/**
* Checks whether this {@link SecurityModel} has an authoritative engine ID.
* @return
* true if an authoritative engine ID is exchanged between
* command sender and responder using this security model, false
* otherwise.
*/
boolean hasAuthoritativeEngineID();
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy