usm_v3.h

hp snmp++ (support ipv6)

   *
   * @return - SNMPv3_USM_OK
   *           SNMP_v3_USM_ERROR (not initialized, no memory)
   */
  int add_usm_user(const OctetStr& user_name,
		   const OctetStr& security_name,
		   const long int  auth_protocol,
		   const long int  priv_protocol,
		   const OctetStr& auth_password,
		   const OctetStr& priv_password,
		   const OctetStr& engine_id);

  int add_usm_user(const OctetStr& security_name,
		   const long int  auth_protocol,
		   const long int  priv_protocol,
		   const OctetStr& auth_password,
		   const OctetStr& priv_password,
		   const OctetStr& engine_id)
    { return add_usm_user(security_name, security_name, auth_protocol,
			  priv_protocol, auth_password, priv_password,
			  engine_id); };


  /**
   * Delete all occurences of the user with the given security name
   * from the USM.
   *
   * @param security_name - the securityName of the user
   *
   * @return - SNMPv3_USM_OK, SNMPv3_USM_ERROR (not initialized)
   */
  int delete_usm_user(const OctetStr& security_name);


  /**
   * Save all localized users into a file.
   *
   * @param file - filename including path
   *
   * @return SNMPv3_USM_ERROR, SNMPv3_USM_FILECREATE_ERROR,
   *         SNMPv3_USM_FILERENAME_ERROR or SNMPv3_USM_OK
   */
  int save_localized_users(const char *file);

  /**
   * Load localized users from a file.
   *
   * @param file - filename including path
   *
   * @return SNMPv3_USM_ERROR, SNMPv3_USM_FILEOPEN_ERROR,
   *         SNMPv3_USM_FILEREAD_ERROR or SNMPv3_USM_OK
   */
  int load_localized_users(const char *file);

  /**
   * Save all users with their passwords into a file.
   *
   * @param file - filename including path
   *
   * @return SNMPv3_USM_ERROR, SNMPv3_USM_FILECREATE_ERROR,
   *         SNMPv3_USM_FILERENAME_ERROR or SNMPv3_USM_OK
   */
  int save_users(const char *file);

  /**
   * Load users with their passwords from a file.
   *
   * @param file - filename including path
   *
   * @return SNMPv3_USM_ERROR, SNMPv3_USM_FILEOPEN_ERROR,
   *         SNMPv3_USM_FILEREAD_ERROR or SNMPv3_USM_OK
   */
  int load_users(const char *file);

  /**
   * Add or replace a localized user in the USM table. Use this method
   * only, if you know what you are doing.
   *
   * @param engine_id         - The engineID, the key was localized with
   * @param user_name         - The name of the user (in the USM)
   * @param security_name     - The securityName of the user, this name
   *                                is the same for all securityModels
   * @param auth_protocol     - Possible values are:
   *                                SNMP_AUTHPROTOCOL_NONE,
   *                                SNMP_AUTHPROTOCOL_HMACMD5,
   *                                SNMP_AUTHPROTOCOL_HMACSHA,...
   * @param auth_key          - The key used for authentications
   * @param priv_protocol     - Possible values are:
   *                                SNMP_PRIVPROTOCOL_NONE,
   *                                SNMP_PRIVPROTOCOL_DES,
   *                                SNMP_PRIVPROTOCOL_IDEA,...
   * @param priv_key          - The key used for privacy
   *
   * @return - SNMPv3_USM_OK
   *           SNMP_v3_USM_ERROR (not initialized, no memory)
   */
  int add_localized_user(const OctetStr &engine_id,
			 const OctetStr &user_name,
			 const OctetStr &security_name,
			 const long auth_protocol,
			 const OctetStr &auth_key,
			 const long priv_protocol,
			 const OctetStr &priv_key);

  /**
   * Generate localized keys for the given params.
   *
   * The buffers for the keys should be of size SNMPv3_USM_MAX_KEY_LEN.
   *
   * @param engine_id - 
   * @param auth_prot -
   * @param priv_prot -
   * @param auth_password     -
   * @param auth_password_len -
   * @param priv_password     -
   * @param priv_password_len -
   * @param auth_key     - allocated space for the authentication key
   * @param auth_key_len - IN: length of the buffer, OUT: key length
   * @param priv_key     - allocated space for the privacy key
   * @param priv_key_len - IN: length of the buffer, OUT: key length
   * @return SNMPv3_USM_OK, or USM error codes
   */
  int build_localized_keys(const OctetStr      &engine_id,
			   const int            auth_prot,
			   const int            priv_prot,
			   const unsigned char *auth_password,
			   const unsigned int   auth_password_len,
			   const unsigned char *priv_password,
			   const unsigned int   priv_password_len,
			   unsigned char *auth_key,
			   unsigned int  *auth_key_len,
			   unsigned char *priv_key,
			   unsigned int  *priv_key_len);

  /**
   * Delete all localized entries of this user from the usmUserTable.
   *
   * @param user_name - The userName that should be deleted
   *
   * @return - SNMPv3_USM_ERROR (not initialized),
   *           SNMPv3_USM_OK (user deleted or not in table)
   */
  int delete_localized_user(const OctetStr& user_name);


  /**
   * Delete the entry with the given userName and engineID
   * from the usmUserTable
   *
   * @param engine_id - The engineID
   * @param user_name - The userName that should be deleted
   *
   * @return - SNMPv3_USM_ERROR (not initialized),
   *           SNMPv3_USM_OK (user deleted or not in table)
   */
  int delete_localized_user(const OctetStr& engine_id,
			    const OctetStr& user_name);


  /**
   * Delete this engine id form all USM tables (users and engine time).
   *
   * @param engine_id - the engine id
   *
   * @return - SNMPv3_USM_ERROR (not initialized),
   *           SNMPv3_USM_OK (user deleted or not in table)
   */
  int remove_engine_id(const OctetStr &engine_id);

  /**
   * Replace a localized key of the user and engineID in the
   * usmUserTable.
   *
   * @param user_name     - The name of the user in the USM
   * @param user_name_len - The length of the user name
   * @param engine_id     - Change the localized key for the SNMP
   *                        entity with this engine id
   * @param engine_id_len - The length of the engine id
   * @param new_key       - The new key
   * @param new_key_len   - The length of the new key
   * @param type_of_key   - AUTHKEY, OWNAUTHKEY, PRIVKEY or OWNPRIVKEY
   *
   * @return - SNMPv3_USM_ERROR (no such entry or not initialized),
   *           SNMPv3_USM_OK
   */
   int update_key(const unsigned char* user_name, const long user_name_len,
	          const unsigned char* engine_id, const long engine_id_len,
	          const unsigned char* new_key,   const long new_key_len,
	          const int type_of_key);

  /**
   * Search for a user with the given securityName and engineID
   * in the usmUserTable and return the entry. If no entry
   * could be found, the usmUserNameTable is searched for the given
   * securityName. If this table has an entry of this user, a
   * localized entry is generated, added to the usmUserTable and
   * returned to the caller.
   *
   * The caller has to do a delete on the returned struct.
   *
   * @param engine_id         -
   * @param security_name     -
   *
   * @return - a pointer to the structure if an entry could be found
   *           or was generated, NULL for all errors
   */
  struct UsmUser *get_user(const OctetStr &engine_id,
			   const OctetStr &security_name);


  /**
   * Get the security name from a user name.
   *
   * @param user_name         -
   * @param user_name_len     -
   * @param security_name     - Buffer for the securityName
   *
   * @return - SNMPv3_USM_ERROR (not initialized, not found, buffer too small),
   *           SNMPv3_USM_OK
   */
  int get_security_name(const unsigned char *user_name,
			const long int user_name_len,
			OctetStr &security_name);

  /**
   * Get the user name from a security name.
   *
   * @param user_name         - Buffer for the userName
   * @param user_name_len     - Has to be set to the max length of the
   *                            buffer. Is set to the length of the found
   *                            securityName or to 0 if not found.
   * @param security_name     -
   * @param security_name_len -
   *
   * @return - SNMPv3_USM_ERROR (not initialized, not found, buffer too small),
   *           SNMPv3_USM_OK
   */
  int get_user_name(unsigned char *user_name,
		    long int *user_name_len,
		    const unsigned char *security_name,
		    const long int security_name_len);


  /**
   * Prepare a key update in the USM. The following procedure is used: To
   * prepare the key update, this function adds the neccessary variable
   * bindings to the Pdu to do the key update on the target SNMP entity.
   * The Pdu has to be sent to the target. If the key update on the target
   * is successful, usmCommitKeyUpdate() has to be called to do the local key
   * update. On failure usmAbortKeyUpdate() has to be called to free
   * temporary ressources.
   *
   * @param securityName - The name of the user
   * @param target       - A target to identify the SNMP entity on which the
   *                       key will be updated
   * @param newPassword  - The new password for the user
   * @param pdu          - A PDU into which this funktion adds the VBs needed
   *                       to change the keys on the target
   * @param type         - Indicates how and which key should be chaned:
   *                       possilbe values are: AUTHKEY, PRIVKEY and
   *                       OWNAUTHKEY, OWNPRIVKEY.
   * @param status       - The return status: SNMPv3_USM_OK or one of the
   *                       error codes
   *
   * @return - A structure, that is needed to commit/abort the key update.
   *           If an error occurs, the return value is NULL
   */
  struct UsmKeyUpdate* key_update_prepare(const OctetStr& securityName,
					  SnmpTarget& target,
					  const OctetStr& newPassword,
					  Pdu& pdu, int type,
					  int &status,
					  const OctetStr& oldpass = "",
					  const OctetStr& oldengid= "",
					  const OctetStr& newengid= "");

  /**
   * Abort the local key update.
   *
   * @param uku - The pointer returned by usmPrepareKeyUpdate()
   */
  void key_update_abort(struct UsmKeyUpdate *uku);


  /**
   * Commit the local key update.
   *
   * @param uku - The pointer returned by usmPrepareKeyUpdate()
   * @param update_type - One of USM_KeyUpdate, USM_PasswordKeyUpdate,
   *                      USM_PasswordAllKeyUpdate
   *
   * @return - SNMPv3_USM_ERROR, SNMPv3_USM_OK
   */
  int key_update_commit(struct UsmKeyUpdate *uku, int update_type);


  /**
   * Get a pointer to the AuthPriv object used by the USM.
   *
   */
  AuthPriv *get_auth_priv();


  /**
   * Return engineBoots and engineTime for a given engineID
   *
   * @param  engine_id    - The engineID of the SNMP entity
   * @param  engine_boots - OUT: boot counter (0 if not found)
   * @param  engine_time  - OUT: engine time (0 if not found)
   *
   * @return - SNMPv3_USM_ERROR (not initialized),
   *           SNMPv3_USM_OK (entry found, values are filled)
   *           SNMPv3_USM_UNKNOWN_ENGINEID ( not found)
   */
  int get_time(const OctetStr &engine_id,
	       long int *engine_boots, long int *engine_time);



  /**
   * Return engineBoots and engineTime of the local snmp entity
   *
   * @param engine_boots - OUT: boot counter (0 if not found)
   * @param engine_time  - OUT: engine time (0 if not found)
   *
   * @return - SNMPv3_USM_ERROR (not initialized),
   *           SNMPv3_USM_OK (entry found, values are filled)
   */
  int get_local_time(long int *engine_boots, long int *engine_time) const;


  /**
   * Return the local snmp engine id.
   */
  const OctetStr& get_local_engine_id() const { return local_snmp_engine_id; };

  /**
   * Get the number of received messages with an unsupported securityLevel
   *
   * @return - usmStatsUnsupportedSecLevels
   */
  unsigned long get_stats_unsupported_sec_levels() const
    { return usmStatsUnsupportedSecLevels; };

  /**
   * Get the number of received messages outside time window
   *
   * @return - usmStatsNotInTimeWindows
   */
  unsigned long get_stats_not_in_time_windows() const
    { return usmStatsNotInTimeWindows; };

  /**