usm_v3.h

hp snmp++ (support ipv6)

   * Get the number of received messages with a unknown userName
   *
   * @return - usmStatsUnknownUserNames
   */
  unsigned long get_stats_unknown_user_names() const
    { return usmStatsUnknownUserNames; };

  /**
   * Get the number of received messages with a unknown engineID
   *
   * @return - usmStatsUnknownEngineIDs
   */
  unsigned long get_stats_unknown_engine_ids() const
    { return usmStatsUnknownEngineIDs; };

  /**
   * Get the number of received messages with a wrong digest
   *
   * @return - usmStatsWrongDigests
   */
  unsigned long get_stats_wrong_digests() const
    { return usmStatsWrongDigests; };

  /**
   * Get the number of received messages with decryption errors
   *
   * @return - usmStatsDecryptionErrors
   */
  unsigned long get_stats_decryption_errors() const
    { return usmStatsDecryptionErrors; };

  //@{
  /**
   * Increase the stats counter. Should only be used by agent++.
   */
  void inc_stats_unsupported_sec_levels();
  void inc_stats_not_in_time_windows();
  void inc_stats_unknown_user_names();
  void inc_stats_unknown_engine_ids();
  void inc_stats_wrong_digests();
  void inc_stats_decryption_errors();
  //@}


  /**
   * Get a const pointer to the first entry of the UsmUserNameTable.
   */
  const UsmUserNameTableEntry *peek_first_user();

  /**
   * Get a const pointer to the next entry of the UsmUserNameTable.
   */
  const UsmUserNameTableEntry *peek_next_user(const UsmUserNameTableEntry *e);


  /**
   * Get a const pointer to the first entry of the UsmUserTable.
   */
  const UsmUserTableEntry *peek_first_luser();

  /**
   * Get a const pointer to the next entry of the UsmUserTable.
   */
  const UsmUserTableEntry *peek_next_luser(const UsmUserTableEntry *e);

  /**
   * for v3MP:
   *
   * Delete the pointers within the structure and the structure
   * itself.
   *
   * @param ssr - The structure that should be deleted.
   */
  void delete_sec_state_reference(struct SecurityStateReference *ssr);

  /**
   * Protected (for agent++):
   *
   * Get the user at the specified position of the usmUserTable.
   *
   * The caller is responsible to delete the entries usmUserEngineID,
   * usmUserNamem, usmUserSecurityName of the returned struct and the
   * struct.
   *
   * @param number - get the entry at position number (1...)
   *
   * @return - a pointer to the structure or NULL if number is out
   *           of range
   */
  struct UsmUserTableEntry *get_user(int number);

  /**
   * Protected (for agent++):
   *
   * Get the properties of the specified user.
   *
   * The caller is responsible to delete the returned struct.
   *
   * @param security_name - The security name of the user
   *
   * @return - a pointer to the structure or NULL if number is out
   *           of range
   */
  struct UsmUserNameTableEntry *get_user(const OctetStr &security_name);

  /**
   * Protected (for agent++):
   *
   * Get the number of elements in the usmUserTable
   *
   * @return - number of elements
   */
  int get_user_count() const;


  /**
   * Protected (for agent++)
   *
   * Register a callback function that is called if a new localized user
   * has been added to the usm user table
   */
  void add_user_added_callback(const usm_add_user_callback cb);


 protected:

  /**
   * Get a new security state reference (for v3MP).
   *
   * @return - A newly created security state reference.
   */
  struct SecurityStateReference *get_new_sec_state_reference();

  /**
   * Generate a complete message that is ready to send to the target.
   *
   * @param globalData       - Buffer containing the serialized globalData,
   *                           ready to be copied into the wholeMsg
   * @param globalDataLength - The length of this buffer
   * @param maxMessageSize   - The maximum message size
   * @param securityEngineID - The engineID of the authoritative SNMP entity
   * @param securityName     - The name of the user
   * @param securityLevel    - The security Level for this Message
   * @param scopedPDU        - Buffer containing the serialized scopedPDU,
   *                           ready to be copied into the wholeMsg
   * @param scopedPDULength  - The length of this Buffer
   * @param securityStateReference - The reference that was generated when
   *                                 the request was parsed. For request, this
   *                                 param has to be NULL. The reference
   *                                 is deleted by this function.
   * @param wholeMsg         - OUT: the buffer for the whole message
   * @param wholeMsgLength   - IN:  lenght of the buffer.
   *                           OUT: length of the generated message
   *
   * @return - SNMPv3_USM_OK on success. See snmperrs.h for the error codes
   *           of the USM.
   */
  int generate_msg(
             unsigned char *globalData,       // message header, admin data
             int globalDataLength,
             int maxMessageSize,              // of the sending SNMP entity
             const OctetStr &securityEngineID,// authoritative SNMP entity
             const OctetStr &securityName,    // on behalf of this principal
             int  securityLevel,              // Level of Security requested
             unsigned char  *scopedPDU,       // message (plaintext) payload
             int scopedPDULength,
             struct SecurityStateReference *securityStateReference,
             unsigned char *wholeMsg,         // OUT complete generated message
             int *wholeMsgLength);            // OUT length of generated message



  /**
   * Parse a received message.
   *
   * @param maxMessageSize         - The maximum message size of the snding
   *                                 SNMP entity.
   * @param securityParameters     - The security parameters as received
   * @param securityParametersLength - The length of the security parameters
   * @param securityParametersPosition - The position of the security
   *                                     parameters in the message
   * @param securityLevel          - The securityLevel of the message
   * @param wholeMsg               - The buffer with the whole message
   * @param wholeMsgLength         - The length of the whole message
   * @param msgData                - The buffer with the messageData
   * @param msgDataLength          - The length of the messageData buffer
   * @param security_engine_id     - OUT: the authoritative engineID
   * @param security_name          - OUT: the name of the user
   * @param scopedPDU              - OUT: buffer containing the scopedPDU
   * @param scopedPDULength        - IN: length of the buffer
   *                                 OUT: length of the scopedPDU
   * @param maxSizeResponseScopedPDU - OUT: maximum size for a scopedPDU in a
   *                                        response message
   * @param securityStateReference - OUT: the securityStateReference
   * @param fromAddress            - IN: Address of the sender
   *
   * @return - SNMPv3_USM_OK on success. See snmperrs.h for the error codes
   *           of the USM.
   */
  int process_msg(
           int maxMessageSize,                // of the sending SNMP entity
           unsigned char *securityParameters, // for the received message
           int securityParametersLength,
           int securityParametersPosition,
           long int securityLevel,            // Level of Security
           unsigned char *wholeMsg,           // as received on the wire
           int wholeMsgLength,                // length as received on the wire
           unsigned char *msgData,
           int msgDataLength,
	   OctetStr &security_engine_id,      // authoritative SNMP entity
	   OctetStr &security_name,           //identification of the principal
           unsigned char *scopedPDU,          // message (plaintext) payload
           int *scopedPDULength,
           long *maxSizeResponseScopedPDU,// maximum size of the Response PDU
           struct SecurityStateReference *securityStateReference,
                                            // reference to security state
                                            // information, needed for response
           const UdpAddress &fromAddress);  // Address of the sender

private:

  /**
   * Delete the pointers in the structure and set all values to 0/NULL.
   *
   * @param usp - The structure that should be deleted
   */
  void delete_sec_parameters( struct UsmSecurityParameters *usp);


  /**
   * Serialize the given values into the buffer according to the BER.
   *
   *  UsmSecurityParameters ::=
   *      SEQUENCE {
   *      -- global User-based security parameters
   *          msgAuthoritativeEngineID     OCTET STRING (5..32)
   *          msgAuthoritativeEngineBoots  INTEGER (0..2147483647),
   *          msgAuthoritativeEngineTime   INTEGER (0..2147483647),
   *          msgUserName                  OCTET STRING (SIZE(0..32)),
   *       -- authentication protocol specific parameters
   *          msgAuthenticationParameters  OCTET STRING,
   *       -- privacy protocol specific parameters
   *          msgPrivacyParameters         OCTET STRING
   *      }
   *
   * @param outBuf    - buffer for the serialized values
   * @param maxLength - before call: length of the buffer
   *                    after call: bytes left in the buffer
   * @param sp        - the values to serialize
   * @param position  - after call: points to the first byte of the
   *                    field for the authentication parameter
   *
   * @return - a pointer to the first free byte in the buffer,
   *           NULL on error
   */
  unsigned char *build_sec_params(unsigned char *outBuf, int *maxLength,
                                  struct UsmSecurityParameters sp,
                                  int *position);

  /**
   * Serialize the given values acording to the BER into the
   * buffer. On success, the buffer contains a valid SNMPv3 message.
   *
   * @param outBuf             - buffer for the serialized values
   * @param maxLength          - before call: length of the buffer
   *                             after call: bytes left in the buffer
   * @param globalData         - Buffer that contains the serialized globalData
   * @param globalDataLength   - The length of this buffer
   * @param positionAuthPar    - after call: points to the first byte of the
   *                             field for the authentication parameter
   * @param securityParameters - The security parameters
   * @param msgData            - Buffer that contains the serialized msgData
   * @param msgDataLength      - The length of this buffer
   *
   * @return - a pointer to the first free byte in the buffer,
   * NULL on error
   */
  unsigned char *build_whole_msg(
                      unsigned char *outBuf, int *maxLength,
                      unsigned char *globalData, long int globalDataLength,
                      int *positionAuthPar,
                      struct UsmSecurityParameters  securityParameters,
                      unsigned char *msgData, long int msgDataLength);


  /**
   * Delete the pointers in the structure
   *
   * @param user - The structure that should be deleted
   */
  inline void delete_user_ptr(struct UsmUser *user);


 private:

  OctetStr local_snmp_engine_id; ///< local snmp engine id
  const v3MP *v3mp;          ///< Pointer to the v3MP that created this object

  // 0: don't accept messages from hosts with a unknown engine id
  int discovery_mode;

   // MIB Counters
   unsigned int usmStatsUnsupportedSecLevels;
   unsigned int usmStatsNotInTimeWindows;
   unsigned int usmStatsUnknownUserNames;
   unsigned int usmStatsUnknownEngineIDs;
   unsigned int usmStatsWrongDigests;
   unsigned int usmStatsDecryptionErrors;

   // the instance of AuthPriv
   AuthPriv *auth_priv;

   // this table contains time values of contacted snmp entities
   USMTimeTable *usm_time_table;

   // Users that are known but not localized to a engine ID
   USMUserNameTable *usm_user_name_table;

   // Table containing localized Users ready to use
   USMUserTable *usm_user_table;

   // Callback for agent++ to indicate new users in usm tables
   usm_add_user_callback usm_add_user_cb;

};


// only for compatibility do not use these values and functions:
// =============================================================

#define SecurityLevel_noAuthNoPriv    SNMP_SECURITY_LEVEL_NOAUTH_NOPRIV
#define SecurityLevel_authNoPriv      SNMP_SECURITY_LEVEL_AUTH_NOPRIV
#define SecurityLevel_authPriv        SNMP_SECURITY_LEVEL_AUTH_PRIV

#define SNMPv3_usmNoAuthProtocol      SNMP_AUTHPROTOCOL_NONE
#define SNMPv3_usmHMACMD5AuthProtocol SNMP_AUTHPROTOCOL_HMACMD5
#define SNMPv3_usmHMACSHAAuthProtocol SNMP_AUTHPROTOCOL_HMACSHA

#define SNMPv3_usmNoPrivProtocol     SNMP_PRIVPROTOCOL_NONE
#define SNMPv3_usmDESPrivProtocol    SNMP_PRIVPROTOCOL_DES
#define SNMPv3_usmIDEAPrivProtocol   SNMP_PRIVPROTOCOL_IDEA
#define SNMPv3_usmAES128PrivProtocol SNMP_PRIVPROTOCOL_AES128
#define SNMPv3_usmAES192PrivProtocol SNMP_PRIVPROTOCOL_AES192
#define SNMPv3_usmAES256PrivProtocol SNMP_PRIVPROTOCOL_AES256

#ifdef SNMP_PP_NAMESPACE
}; // end of namespace Snmp_pp
#endif 

#endif // _SNMPv3

#endif