本文档详细介绍了WinSNMPv3.0 API的外部特性，作为WinSNMPv2.0 API的标准补充，引入了SNMPv3协议的新功能。文档覆盖了API的使用方法，支持独立开发者创建应用程序及提供反馈。
| Date | Rev | Comments |
| 2000-10-03:23:00 EDT | 1.0 | Initial release for public use and comment. |
| 2001-11-22:14:00 EST | 1.0a | Editorial fixes only; no changes to API content; tone changed to reflect deployed status. |
This document describes the external aspects of the WinSNMP v3.0 API. This document should be read as an Addendum to the industry-standard WinSNMP v2.0 API to incorporate the features and functions of the IETF SNMPv3 protocol. This document describes this API in sufficient detail to facilitate the following three goals:
-
- Enable SNMPv1/v2c/v3 applications running over implementations of this API (including both "agents" and "managers" and permutations defined in RFC2573) to be developed by independent programmers.
- Enable implementations of this API to be produced by independent developers.
- Enable and encourage feedback in the form of suggested improvements to this document or to the API it describes.
This is a working document, primarily intended for developers who are already closely familiar with WinSNMP v2.0 and SNMPv3. It has a fair amount of explanation in it intended to help guide a transition in thinking that will not be necessary in a final, unified WinSNMP v3.0 Specification--that is, one incorporating all pre-existing WinSNMP functions and features, not just those introduced or modified for this v3.0 edition--which will be worded in a more declarative form.
Although the function calls and the external data structures defined in this document must exhibit the exact external interfaces as specified herein, this document--despite using some concrete implementation ideas for grounding--does not intend to mandate a particular implementation approach in any respect..
Applied SNMP offers an updated suite of management applications (Auto*Manage, $149) and an updated Software Development Kit (SDK, $199, including the Auto*Manage package), with sample code, both of which can be purchased online at www.winsnmp.com.
The baseline functionality of WinSNMP v3.0 is everything in WinSNMP v2.0. All existing WinSNMP v2.0 applications (which subsumes all WinSNMP v1.x applications) will work "as is" in the presence of any compliant WinSNMP v3.0 implementation.
All WinSNMP v2.0 applications that currently support SNMPAPI_TRANSLATED_MODE for entity and context attribute look-up are able to utilize the SNMPv3 features of this WinSNMP v3.0 API via appropriate entries in the local configuration database (LCD) -- which is named np_wsnmp.ini for the Applied SNMP implementation -- directly (via text editing) or (preferably) via the "local database editor" utility -- which is np_ldbed.exe in the Applied SNMP Auto*Manage package (this local database editor has been updated to accommodate the additional entity and context attributes required for SNMPv3.)
Incorporating SNMPv3 support into the WinSNMP API -- resulting in the smooth evolution (as defined in the box above) of WinSNMP v2.0 into WinSNMP v3.0 -- primarily requires enriching the WinSNMP entity and context resource concepts, structures, and functions to support SNMPv1, SNMPv2c, and SNMPv3 in a single uniform manner. It also entails specifying rules and conditions for some automatic protocol operations (e.g., SNMPv3 engine discovery, time synchronization, and ReportPDU handling).
The concrete elements of this enrichment are:
-
- Two new primary functions:
SnmpCreateEntity()
SnmpCreateContext()
-
- Seven new closely related supporting functions:
SnmpGetEntityInfo(), SnmpSetEntityInfo(), SnmpFreeEntityInfo()
SnmpGetContextInfo(), SnmpSetContextInfo(), SnmpFreeContextInfo()
SnmpPasswordToKey()
-
- Two new supporting structured data types:
smiENTITYINFO
smiCONTEXTINFO
-
- Additional (SNMPv3-related) behavior specified for three pre-existing functions:
SnmpStrToEntity()
SnmpStrToContext()
SnmpListen()
SnmpSendMsg()
SnmpRecvMsg()
SnmpEncodeMsg() (TBD)
SnmpDecodeMsg() (TBD)
-
- <x> new constants added to winsnmp.h (see the v3 edition of this file at www.winsnmp.com for details):
| Constant | Value | Comments |
| SNMP_PDU_REPORT | 0xA8 | Report PDU (engine to engine)) |
| Security Models: | ||
| SNMP_SEC_MODEL_V1 | 1 | Security model = SNMPv1 |
| SNMP_SEC_MODEL_V2 | 2 | Security model = SNMPv2c |
| SNMP_SEC_MODEL_USM | 3 | Security model = User-based Security Model |
| Security Levels: | ||
| SNMP_NOAUTH_NOPRIV | 0 | Security level = noAuth/noPriv |
| SNMP_AUTH_NOPRIV | 1 | Security level = auth/noPriv |
| SNMP_AUTH_PRIV | 3 | Security level = auth/priv |
| Security Protocols: | ||
| SNMP_USM_NO_AUTH_PROTOCOL | 1 | Security protocol = No authentication |
| SNMP_USM_HMACMD5_AUTH_PROTOCOL | 2 | Security protocol = HMAC/MD5 authentication |
| SNMP_USM_HMACSHA_AUTH_PROTOCOL | 3 | Security protocol = HMAC/SHA authentication |
| SNMP_USM_NO_PRIV_PROTOCOL | 1 | Security protocol = No encryption |
| SNMP_USM_DES_PRIV_PROTOCOL | 2 | Security protocol = DES encryption |
| Miscellaneous: | ||
| SNMPAPI_V3_SUPPORT | 3 | Replaces SNMPAPI_MLM_SUPPORT |
| SMPAPI_UNTRANSLATED_V3 | 3 | New translation mode value for SNMPv3 |
| New Error Codes: | ||
| SNMPAPI_ENGINE_INVALID | 30 | Invalid engineID value |
| SNMPAPI_ENGINE_DISCOVERY_FAILED | 31 | Unable to discover engineID value |
| SNMPAPI_RPT_OTHER | 200 | ReportPDU error not covered below |
| SNMPAPI_RPT_INVALIDMSG | 201 | Invalid message |
| SNMPAPI_RPT_INASNPARSEERR | 202 | ASN.1 parsing error |
| SNMPAPI_RPT_UNKNOWNSECMODEL | 203 | Unknown security model value |
| SNMPAPI_RPT_UNKNOWNENGINEID | 204 | Unknown engineID value (at SNMP level) |
| SNMPAPI_RPT_UNSUPPSECLEVEL | 205 | Unsupported security level value |
| SNMPAPI_RPT_UNKNOWNUSERNAME | 206 | Unknown securityName |
| SNMPAPI_RPT_WRONGDIGEST | 207 | Incorrect authentication digest used |
| SNMPAPI_RPT_NOTINTIMEWINDOW | 208 | Message time parameters out of bounds |
| SNMPAPI_RPT_DECRYPTIONERROR | 209 | Decryption process failed |
Note also that the (now erroneous) holdover (from early SNMPv2 days) definition of SNMP_SYNTAX_UINT32 as an ASN.1 APPLICATION type has been corrected to be indistinguishable from SNMP_SYNTAX_GAUGE32.
As will be shown below, the enhancements required to realize SNMPv3 support are amenable to simple extensions that further benefit consumers of WinSNMP technology. In particular, the existing "scope" ambiguity of the TranslateMode and RetransmitMode settings can be totally removed for all new WinSNMP applications and further clarified for existing ones. Specifically, applications written to WinSNMP v3.0 will not need to use (but may use) the following pre-existing WinSNMP v2.0 functions:
| Pre-existing | Inclusive v3.0 Function(s) | Corresponding v3.0 Data Element |
| SnmpGetTranslateMode | SnmpGetEntityInfo | nTranslateMode |
| SnmpSetTranslateMode | SnmpCreateEntity, SnmpSetEntityInfo | nTranslateMode |
| SnmpGetRetransmitMode | SnmpGetEntityInfo | nRetransmitMode |
| SnmpSetRetransmitMode | SnmpCreateEntity, SnmpSetEntityInfo | nRetransmitMode |
| SnmpGetTimeout | SnmpGetEntityInfo | nPolicyTimeout, nActualTimeout |
| SnmpSetTimeout | SnmpCreateEntity, SnmpSetEntityInfo | nPolicyTimeout |
| SnmpGetRetry | SnmpGetEntityInfo | nPolicyRetry, nActualRetry |
| SnmpSetRetry | SnmpCreateEntity, SnmpSetEntityInfo | nPolicyRetry |
| SnmpSetPort | SnmpCreateEntity, SnmpSetEntityInfo | nRequestPort, nNotificationPort |
| SnmpStrToEntity | SnmpCreateEntity | smiENITYINFO structure |
| SnmpEntityToStr | SnmpGetEntityInfo | dFriendlyName |
| SnmpStrToContext | SnmpCreateContext | smiCONTEXTINFO structure |
| SnmpContextToStr | SnmpGetContextInfo | dFriendlyName |
Of course, these pre-existing baseline functions will continue to exist and be fully supported with their pre-existing semantics by all compliant WinSNMP v3.0 implementations.
The functionality provided by the above thirteen functions will be replaced by equivalent and additional functionality provided by the following nine new WinSNMP 3.0 functions (which are described in detail later in this document):
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| HSNMP_ENTITY | SnmpCreateEntity | IN IN | HSNMP_SESSION smiLPENTITYINFO | hSession lpEntityInfo |
| SNMPAPI_STATUS | SnmpSetEntityInfo | IN IN | HSNMP_ENTITY smiLPENTITYINFO | hEntity lpEntityInfo |
| SNMPAPI_STATUS | SnmpGetEntityInfo | IN OUT | HSNMP_ENTITY smiLPENTITYINFO | hEntity lpEntityInfo |
| SNMPAPI_STATUS | SnmpFreeEntityInfo | IN OUT | smiLPENTITYINFO | lpEntityInfo |
| HSNMP_CONTEXT | SnmpCreateContext | IN IN | HSNMP_SESSION smiLPCONTEXTINFO | hSession lpContextInfo |
| SNMPAPI_STATUS | SnmpSetContextInfo | IN IN | HSNMP_CONTEXT smiLPCONTEXTINFO | hContext lpContextInfo |
| SNMPAPI_STATUS | SnmpGetContextInfo | IN OUT | HSNMP_CONTEXT smiLPCONTEXTINFO | hContext lpContextInfo |
| SNMPAPI_STATUS | SnmpFreeContextInfo | IN OUT | smiLPCONTEXTNFO | lpContextInfo |
| SNMPAPI_STATUS | SnmpPasswordToKey | OUT IN IN | smiLPOCTETS smiINT32 smiLPOCTETS | lpKey nSecurityAuthProtocol lpPassword |
The WinSNMP v1.0 industry standardization process adopted the terms "entity" and "context" in the very early days of the IETF "party-based" SNMPv2 effort. As it turned out, that IETF SNMPv2 effort was eventually abandoned, yielding SNMPv2c as a modest set of protocol improvements and, later, SNMPv3 to bring secure operations to SNMP management systems. In between the IETF formalization of SNMPv2c and SNMPv3, WinSNMP v2.0 was adopted, integrating SNMPv2c support and maintaining the core "entity" and "context" abstractions of this API set. In the WinSNMP sense, an "entity" essentially identifies an end-point of an SNMP message and a "context" essentially identifies a principal in relation to a target set of managed objects. In the SNMPv1/v2c environment, a WinSNMP "entity" generally corresponds to an "agent" application or a "manager" application and a WinSNMP "context" generally corresponds to a "community profile" and its associated authentication/authorization schemes per RFC1157.
To accommodate the corresponding SNMPv3 evolution of these concepts, WinSNMP v3.0 extends and formalizes entity and context attributes as defined herein. In general, those SNMPv3 constructs specific to an end-point for SNMP communications have been added to the WinSNMP entity abstraction and those which relate to the principal initiating an SNMP operation and the particular set of management information involved in that given operation have been added to the WinSNMP context abstraction. It is necessary to bear in mind that the terms "entity" and "context" are used with some differences in both the WinSNMP and SNMPv3 specifications, although the core meanings are not all that dissimilar and are certainly not incompatible with one another.
As indicated above, two new application level data types--smiENTITYINFO and smiCONTEXTINFO--are employed in WinSNMP v3.0 to convey enhanced entity and context attribute information. More details about the structure elements are given in the tables that follow in this section. For ease of reference, these two structures are show below (as they appear in the v3.0 winsnmp.h file) along with some comments about the SNMPv3-specific elements of each.
typedef struct // smiENTITYINFO structure
{
HSNMP_ENTITY hEntity;
HSNMP_SESSION hSession;
smiUINT32 nTranslateMode;
smiUINT32 nSnmpVersion;
smiOCTETS dFriendlyName;
smiUINT32 nAddressFamily;
smiOCTETS dAddressString;
smiUINT32 nRequestPort;
smiUINT32 nNotificationPort;
smiUINT32 nMaxMsgSize; // added for SNMPv3
smiOCTETS dEngineID; // added for SNMPv3
smiUINT32 nEngineBoots; // added for SNMPv3
smiUINT32 nEngineTime; // added for SNMPv3
smiUINT32 nEngineSeconds; // added for SNMPv3
smiUINT32 nRetransmitMode;
smiTIMETICKS nPolicyTimeout;
smiUINT32 nPolicyRetry;
smiTIMETICKS nActualTimeout;
smiUINT32 nActualRetry;
} smiENTITYINFO, FAR *smiLPENTITYINFO;
Prior to v3.0, the WinSNMP API did not include the smiENTITYINFO data structure. However, many of the elements of this structure (as shown above) were present, in one form or another, in the logical equivalents of this structure that each particular implementation supported internally. For WinSNMP v3.0, we are explicitly exposing this structure to give applications better visibility into and control over the entity resource attributes. In addition, this structure provides a venue for the "translation mode" and "retransmission mode" attributes on a per-entity basis, thereby removing the (minor) obstacle to complete thread-safeness of the API that the "application-wide" mode of using these attributes (that is, via the original SnmpSetTranslateMode() and SnmpSetRetransmitMode() functions) raised. Also, this structure provides for both "request" and "notification" port settings for entities used as destinations, thereby removing a limitation of the pre-existing SnmpSetPort() function (which addressed only the port to which SNMP request messages would be directed).
The smiENTITYINFO structure includes five members introduced especially for SNMPv3 operations:
smiUINT32 nMaxMsgSize; // added for SNMPv3
smiOCTETS dEngineID; // added for SNMPv3
smiUINT32 nEngineBoots; // added for SNMPv3
smiUINT32 nEngineTime; // added for SNMPv3
smiUINT32 nEngineSeconds; // added for SNMPv3
Each of the above-listed data elements is dictated by one or more SNMPv3 RFCs and is explained in more detail in later sections. For now, you can note that the nMaxMsgSize element is used to control the maximum size of a message that can be sent to an SNMP entity. In general, this parameter is handled transparently to the application -- that is, remote SNMPv3 entities tell the local WinSNMP implementation what their nMaxMsgSize value is (in their response messages). Also, the triplet of attributes dEngineID, nEngineBoots, and nEngineTime, is managed transparently to most applications -- these values are discovered by the implementation during the initial message exchange process with a given remote "agent" entity and then do not need to be manipulated by the using "manager" applications. While those first four "SNMPv3" attributes correspond to actual physical elements of an SNMPv3 message, the nEngineSeconds element does not. It is a "virtual timer" of sorts, used to track the last time at which the nEngineBoots and nEngineTime values were authenticated (i.e. recorded as part of an authenticated exchange with the remote entity). The nEngineSeconds element is not writable by an application; it is provided as a visible element in this structure merely for the benefit of certain performance monitoring and debugging applications.
typedef struct // smiCONTEXTINFO structure
{
HSNMP_CONTEXT hContext;
HSNMP_SESSION hSession;
smiUINT32 nTranslateMode;
smiUINT32 nSnmpVersion;
smiOCTETS dFriendlyName;
smiOCTETS dContextEngineID; // added for SNMPv3
smiOCTETS dContextName; // added for SNMPv3
smiOCTETS dSecurityName; // extended for SNMPv3
smiUINT32 nSecurityModel; // added for SNMPv3
smiUINT32 nSecurityLevel; // added for SNMPv3
smiUINT32 nSecurityAuthProtocol; // added for SNMPv3
smiOCTETS dSecurityAuthKey; // added for SNMPv3
smiUINT32 nSecurityPrivProtocol; // added for SNMPv3
smiOCTETS dSecurityPrivKey; // added for SNMPv3
} smiCONTEXTINFO, FAR *smiLPCONTEXTINFO;
Prior to v3.0, the WinSNMP API did not include the smiCONTEXTINFO data structure. However, some of the elements of this structure (as shown above) were present, in one form or another, in the logical equivalents of this structure that each particular implementation supported internally. For WinSNMP v3.0, we are explicitly exposing this structure to give applications better visibility into and control over the context resource attributes. In addition, this structure provides a venue for the "translation mode" attribute on a per-context basis, thereby removing the (minor) obstacle to complete thread-safeness of the API that the "application-wide" mode of using this attribute (that is, via the original SnmpSetTranslateMode() function) raised.
The smiCONTEXTINFO structure includes eight members introduced especially for SNMPv3 operations and one (dSecurityName) extended (from "community name") for SNMPv3 operations.:
smiOCTETS dContextEngineID; // added for SNMPv3
smiOCTETS dContextName; // added for SNMPv3
smiOCTETS dSecurityName; // extended for SNMPv3
smiUINT32 nSecurityModel; // added for SNMPv3
smiUINT32 nSecurityLevel; // added for SNMPv3
smiUINT32 nSecurityAuthProtocol; // added for SNMPv3
smiOCTETS dSecurityAuthKey; // added for SNMPv3
smiUINT32 nSecurityPrivProtocol; // added for SNMPv3
smiOCTETS dSecurityPrivKey; // added for SNMPv3
Each of the above-listed data elements is dictated by one or more SNMPv3 RFCs and is explained in more detail in later sections. For now, you can note that the dContextEngineID and dContextName elements relate to the SNMPv3 concept of the "scoped PDU". This term means that the target agent identified by the dContextEngineID value (which will be the same as its dEngineID value...this is not the case for a "proxy forwarder" form of "proxy agent") will refer to a "MIB view" identified by the dContextName value to determine access rights and MIB object/instance validity and values (as such, it is somewhat similar to the "community profile" concepts of earlier SNMP versions). In most cases, WinSNMP "manager" applications will not populate these two attributes (that is, they will leave them as "empty strings") and the implementation and the remote agent will "do the right thing". This will not be the case when the dstEntity used in an SnmpSendMsg() call is a "proxy forwarder" application, in which case the dContextEngineID must identify the actual target remote agent entity, or when the target agent supports multiple SNMPv3 contexts (aka, "MIB views", per above), in which case the dContextName must identify any desired context ("MIB view") other than the default context (the "empty string").
In saying that the dSecurityName field has been "extended" for SNMPv3, we mean only that it serves the dual purpose of the "community name" for use in SNMPv1 and SNMv2c messages and the "msgUserName" element for SNMPv3 messages. When used as the "msgUserName" element of an SNMPv3 message (using the USM security model, which is the only one specified for SNMPv3 at this time) its size is limited to the range of 0..32 octets.
The remaining six elements are used in controlling SNMPv3 security operations. Legal values (at the WinSNMP level) for each of the four "nSecurity<x>" elements are given elsewhere in this document and in the v3.0 winsnmp.h file. When secure (that is, authenticated or authenticated and encrypted) SNMPv3 messages are to be sent, appropriate values for the dSecurityAuthKey and (in the latter case) dSecurityPrivKey must be present in the subject hContext object. These keys at this level are "non-localized" (see the SNMPv3 specs for details); they will be automatically and transparently localized to the subject authoritative entity's dEngineID by the WinSNMP implementation when used as message elements in out-going SNMPv3 messages. The SnmpPasswordToKey() function is one method of generating such non-localized keys. The "local database configuration utility" (np_ldbed.exe) provided as part of Applied SNMP's WinSNMP SDK and Auto*Manage products provides another way of generating them (especially for use in "translated mode" context generation).
Note that this specification identifies these two new data structures (smiENTITYINFO and smiCONTEXTINFO) as seen by the user application only. How the underlying information is actually instantiated, represented, and manipulated by a given WinSNMP implementation is strictly an implementation-private matter.
The application-level data structures will be organized as shown below, with the given order of named elements of the indicated data types. The access level codes of R, C, W, and V stand, respectively, for:
| Access Level | General Description |
| Read | The element's current value will always be returned by the implementation in response to the SnmpGetEntityInfo() or SnmpGetContextInfo() call, respectively. |
| Create | The member's value will be evaluated for data initialization purposes by the implementation during the SnmpCreateEntity() or SnmpCreateContext() call, respectively. |
| Write | The member's value will be evaluated for data modification purposes by the implementation during the SnmpSetEntityInfo() or SnmpSetContextInfo() call, respectively. |
| Verify | The member's value will be verified by the implementation as a data integrity check during the SnmpSetEntityInfo() or SnmpSetContextInfo() call, respectively. |
In general, only those elements with "Create" access are used (as input only) during the SnmpCreateEntity() and SnmpCreateContext() operations and only those elements with "Write" access are used (as input only) during the SnmpSetEntityInfo() and SnmpSetContextInfo() operations. All elements have "Read" access and, therefore, are returned with current values as output from the SnmpGetEntityInfo() and SnmpGetContextInfo() operations.
smiENTITYINFO Data Structure Elements:
| WinSNMP Type | Element Name | Access | Comments |
| HSNMP_ENTITY | hEntity | RV | Handle value assigned to this entity by the implementation. |
| HSNMP_SESSION | hSession | RV | Handle value of the session which "owns" this entity. |
| smiUINT32 | nTranslateMode | RC | Translation mode value in which this entity was created. |
| smiUINT32 | nSnmpVersion | RV | SNMP version supported by this entity. |
| smiOCTETS | dFriendlyName | RC | Friendly name assigned to this entity. |
| smiUINT32 | nAddressFamily | RC | Transport protocol address family (AF_INET [2]). |
| smiOCTETS | dAddressString | RC | Transport address of this entity (ASCII representation). |
| smiUINT32 | nRequestPort | RCW | Destination port for SNMP request messages. |
| smiUINT32 | nNotificationPort | RCW | Destination port for SNMP notification messages. |
| smiUINT32 | nMaxMsgSize | RCW | Maximum size of messages accepted by this entity. |
| smiOCTETS | dEngineID | RCW | snmpEngineID assigned to this entity (see box). |
| smiUINT32 | nEngineBoots | RCW | Last known boot count value for this entity. |
| smiUINT32 | nEngineTime | RW | Last known uptime value for this entity. |
| smiUINT32 | nEngineSeconds | R | Seconds since last known values (boots and time) update. |
| smiUINT32 | nRetransmitMode | RCW | Current retransmission mode setting for this entity. |
| smiTIMETICKS | nPolicyTimeout | RCW | Current timeout interval value for this entity. |
| smiUINT32 | nPolicyRetry | RCW | Current retry count value for this entity. |
| smiTIMETICKS | nActualTimeout | R | Last recorded actual response time interval. |
| smiUINT32 | nActualRetry | R | Last recorded actual retry count value. |
Note that an SNMPv3 entity's dEngineID value represents the authoritative SNMP engine (securityEngineID) when the entity is used as the dstEntity for a PDU type from the Confirmed Class in a call to SnmpSendMsg() or when the entity is used as the srcEntity for a PDU type from the Unconfirmed Class in a call to SnmpSendMsg().
The Confirmed Class contains all protocol operations which cause the receiving SNMP engine to send back a response: GetRequest-PDU, GetNextRequest-PDU, GetBulkRequest-PDU, SetRequest-PDU, and InformRequest-PDU.
The Unconfirmed Class contains all protocol operations which do not cause the receiving SNMP engine to send back a response: Report-PDU, Trapv2-PDU, and GetResponse-PDU.
smiCONTEXTINFO Data Structure Elements:
| WinSNMP Type | Element Name | Access | Comments |
| HSNMP_CONTEXT | hContext | RV | Handle value assigned to this context by the implementation |
| HSNMP_SESSION | hSession | RV | Handle value of the session which "owns" this context.. |
| smiUINT32 | nTranslateMode | RC | Translation mode value under which this context was created. |
| smiUINT32 | nSnmpVersion | RV | SNMP version supported by this context. |
| smiOCTETS | dFriendlyName | RC | Friendly name assigned to this context. |
| smiOCTETS | dContextEngineID | RCW | SNMP engine ID of the entity holding this context. |
| smiOCTETS | dContextName | RCW | Name of this context at the SNMP engine holding it. |
| smiOCTETS | dSecurityName | RC | Security model-independent name of principal using this context. |
| smiUINT32 | nSecurityModel | RCW | Security model of this context:. |
| smiUINT32 | nSecurityLevel | RCW | Security level of this context. |
| smiUINT32 | nSecurityAuthProtocol | RCW | Authentication protocol used for dSecurityAuthKey for USM |
| smiOCTETS | dSecurityAuthKey | RCW | Security model-dependent attribute: Authentication key for USM. |
| smiUINT32 | nSecurityPrivProtocol | RCW | Privacy protocol used for dSecurityPrivKey for USM |
| smiOCTETS | dSecurityPrivKey | RCW | Security model-dependent attribute: Encryption key for USM. |
At the heart of it all, an API such as WinSNMP is intended primarily to make it easier for applications, whether managers or agents (command generators or command responders) or hybrids, to send and receive SNMP messages with a degree of transparency appropriate to the API's target uses. The SNMPv3 message format is substantially different from the SNMPv1/v2c format (version, community, PDU) and this difference explains virtually all of the modifications of the WinSNMP API in going from v2.0 to v3.0. Therefore, this section will provide some background on the SNMPv3 message elements and their mapping to WinSNMP v3.0 API elements.
An SNMPv3 message consists of four major "parts" (or macro-elements) as depicted below:
+------------+---------------+-----------------------+---------+
| msgVersion | msgGlobalData | msgSecurityParameters | msgData |
+------------+---------------+-----------------------+---------+
The first "part" (msgVersion) is atomic; the other three are actually comprised of message elements as depicted below. The rightmost column below shows the WinSNMP source for each element -- of particular interest for now are those elements that come from the entity and context attributes. This breakdown will be explained in more detail in the table immediately following this diagram:
+-----------------------------+
| msgVersion | <-- Entity
+---------------+-----------------------------+
| msgGlobalData |.............................|
+---------------+-----------------------------+
| msgID | <-- Implementation
+-----------------------------+
| msgMaxSize | <-- Entity
+-----------------------------+
| msgFlags | <-- Implementation
+-----------------------------+
| msgSecurityModel | <-- Context
+-----------------------+-----------------------------+
| msgSecurityParameters |.............................|
+-----------------------+-----------------------------+
| msgAuthoritativeEngineID | <-- Entity
+-----------------------------+
| msgAuthoritativeEngineBoots | <-- Entity
+-----------------------------+
| msgAuthoritativeEngineTime | <-- Entity
+-----------------------------+
| msgUserName | <-- Context
+-----------------------------+
| msgAuthenticationParameters | <-- Context
+-----------------------------+
| msgPrivacyParameters | <-- Context
+---------+-----------------------------+
| msgData |.............................|
+---------+-----------------------------+
| contextEngineID | <-- Context
+-----------------------------+
| contextName | <-- Context
+-----------------------------+
| PDU | <-- Application
+-----------------------------+
The SNMPv3 message format is actually a superset of the SNMPv1/v2c message format, with the latter consisting of the msgVersion, msgUserName (as the community name), and PDU components only.
| Message Element | Description and Comments |
| msgVersion | From RFC2572: SNMP version; 3 for SNMPv3. Not directly visible to the applications. Derived from the nSnmpVersion of the dstEntity in SnmpSendMsg(); assigned to the srcEntity in SnmpRecvMsg(). |
| msgID | From RFC2572: Message ID; INTEGER (0..2147483647). Not visible to the applications. Assigned automatically. Allows the app-level RequestID in the PDU to remain unchanged on the wire. |
| msgMaxSize | From RFC2572: Maximum size (in bytes) of a message that can be accepted by an entity; INTEGER (484..2147483647). Taken from hEntity parameter nMaxMsgSize. SnmpSendMsg() fails with SNMPAPI_SIZE_INVALID if a constructed out-bound message exceeds a non-zero value for the nMaxMsgSize attribute at the dstEntity. |
| msgFlags | From RFC2572: Message processing indicators; OCTET STRING (SIZE(1)), consisting of authFlag, privFlag, and reportableFlag. Not visible to applications. Derived from the hContext nSecurityLevel parameter and the PDU type at SnmpSendMsg() time. |
| msgSecurityModel | From RFC2572: NTEGER (1..2147483647). Taken from hContext nSecurityModel parameter. For SNMPv3 messages the only value currently supported is SNMP_SEC_MODEL_USM [3]. |
| msgAuthoritativeEngineID | From RFC2574: OCTET STRING, specifies the snmpEngineID of the authoritative SNMP engine involved in the exchange of the message. Taken from the hEntity dEngineID parameter of the srcEntity or dstEntity, as appropriate to the PDU class, at SnmpSendMsg() time. |
| msgAuthoritativeEngineBoots | From RFC2574: INTEGER (0..2147483647), specifies the snmpEngineBoots value at the authoritative SNMP engine involved in the exchange of the message. Taken from the hEntity nEngineBoots parameter of the srcEntity or dstEntity, as appropriate to the PDU class, at SnmpSendMsg() time. |
| msgAuthoritativeEngineTime | From RFC2574: INTEGER (0..2147483647), specifies the snmpEngineTime value at the authoritative SNMP engine involved in the exchange of the message. Taken from the hEntity nEngineTime parameter of the srcEntity or dstEntity, as appropriate to the PDU class, at SnmpSendMsg() time. |
| msgUserName | From RFC2574: OCTET STRING (SIZE(0..32)), specifies the user (principal) on whose behalf the message is being exchanged. Note that a zero-length userName will not match any user, but it can be used for snmpEngineID discovery. Taken from the hContext dSecurityName parameter at SnmpSendMsg() time. |
| msgAuthenticationParameters | From RFC2574: OCTET STRING, defined by the authentication protocol in use for the message, as defined by the usmUserAuthProtocol column in the user's entry in the usmUserTable. Derived from the hContext dSecurityAuthKey parameter at SnmpSendMsg() time, localized automatically to the msgAuthoritativeEngineID and using the hContext nSecurityAuthProtocol value.. |
| msgPrivacyParameters | From RFC2574: OCTET STRING, defined by the privacy protocol in use for the message, as defined by the usmUserPrivProtocol column in the user's entry in the usmUserTable). Derived from the hContext dSecurityPrivKey parameter at SnmpSendMsg() time, localized automatically to the msgAuthoritativeEngineID and using the hContext nSecuirtyPrivProtocol value.. |
| contextEngineID | From RFC2572: OCTET STRING, uniquely identifies, within an administrative domain, an SNMP entity that may realize an instance of a context with a particular contextName. Taken from the hContext dContextEngineID parameter at SnmpSendMsg() time. |
| contextName | From RFC2572: OCTET STRING, in conjunction with the contextEngineID field, identifies the particular context associated with the management information contained in the PDU portion of the message. The contextName is unique within the SNMP entity specified by the contextEngineID, which may realize the managed objects referenced within the PDU. Taken from the hContext dContextName parameter at SnmpSendMsg() time. |
| PDU | From RFC2572: One of the PDUs defined in RFC 1905. |
Please note:
-
- The term "empty string" used in this document refers to a WinSNMP smiOCTETS instance with a ".len" value of 0 and a ".ptr" value of NULL.
- The term "Unused" in the "Behavior" columns of the tables in this section means "Unused as an input value to this particular function". Elements marked as "unused" in these columns are ignored by the implementation during processing of the subject functions.
- As used herein, the term "SNMPv3 message" refers to a message in which the entity used as the "authoritative engine" end-point of the operation has an nSnmpVersion value of SNMPAPI_V3_SUPPORT.
- In WinSNMP terms, the authoritative engine end-point is the dstEntity for a message bearing a confirmed class PDU and the srcEntity for a message bearing an unconfirmed class PDU.
- The PDU types in the confirmed class are: GetRequest, GetNextRequest, GetBulkRequest, SetRequest, and InformRequest.
- The PDU types in the unconfirmed class are: Response, Trapv2, and Report..
- The WinSNMP "engine" automatically issues a single response to an InformRequest PDU, which may have been received on behalf of multiple applications.
- The WinSNMP "engine" handles all SNMPv3 Report-PDU interactions automatically and may, in cases where specified, indicate such interactions to the relevant session via a transport layer or security layer error code.
- The term "empty string" used in this document refers to a WinSNMP smiOCTETS instance with a ".len" value of 0 and a ".ptr" value of NULL.
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| HSNMP_ENTITY | SnmpCreateEntity | IN IN | HSNMP_SESSION smiLPENTITYINFO | hSession lpEntityInfo |
The SnmpCreateEntity() function creates a new instance of an HSNMP_ENTITY resource object using values passed via the lpEntityInfo parameter (for those attributes which have "Create" access) and, upon successful completion, allocates the new entity to the WinSNMP session indicated by the hSession parameter. This function performs the same basic function as the older SnmpStrToEntity() function but with more user application control features (i.e., fewer entity attributes are assigned implementation-dependent default values).
Please note:
-
- SnmpCreateEntity() should be used in place of SnmpStrToEntity() in all new WinSNMP applications (because SnmpCreateEntity() provides a superset of SnmpStrToEntity() and leads to more capable and efficient applications).
- SnmpStrToEntity() may be replaced with SnmpCreateEntity() in all existing WinSNMP applications.
- SnmpStrToEntity() will continue to function as always in existing and new applications that choose to use it (but with some additional new default attribute values assigned).
- SnmpCreateEntity() should be used in place of SnmpStrToEntity() in all new WinSNMP applications (because SnmpCreateEntity() provides a superset of SnmpStrToEntity() and leads to more capable and efficient applications).
| Parameter | Description |
| hSession | A previously created open WinSNMP session to which this entity will be allocated. |
| lpEntityInfo | A pointer to an smiENTITYINFO structure. Elements of this structure with "Create" access will be evaluated for use in initializing the entity resource; all others will be ignored. No elements of this structure will be modified by this function. |
The SnmpCreateEntity() function uses the attributes of the smiENTITYINFO structure pointed to by the lpEntityInfo parameter as indicated in the following table:
| Element Name | SnmpCreateEntity() Behavior |
| hEntity | Unused. |
| hSession | Unused. |
| nTranslateMode | Required. Used to determine other entity attributes in accordance with its value, which must be one of the following: SNMPAPI_TRANSLATED SNMPAPI_UNTRANSLATED_V1 SNMPAPI_UNTRANSLATED_V2 SNMPAPI_UNTRANSLATED_V3 |
| nSnmpVersion | Unused. The implementation derives a value for this element from the application of nTranslateMode and associates it with the entity for future retrieval via SnmpGetEntityInfo(). Possible values are: SNMPAPI_V1_SUPPORT SNMPAPI_V2_SUPPORT SNMPAPI_V3_SUPPORT |
| dFriendlyName | Required if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. For SNMPAPI_TRANSLATED mode, this value is used by the implementation to retrieve entity attributes from the implementation- specific LCD. If no matching entry exists, the function fails with the SNMPAPI_ENTITY_UNKNOWN error. When present in any mode, this value is recorded by the implementation as an attribute of the entity that may later be retrieved via SnmpGetEntityInfo(). |
| nAddressFamily | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. If specified (>0) in any untranslated mode, then dAddressString must evaluate to a valid address for this address family. Allowable values for this element come from the address family defines in winsock2.h or its equivalent in a non-Win32 environment. Illegal values result in the function failing with the SNMPAPI_MODE_INVALID error. |
| dAddressString | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Required otherwise.. If a value for nAddressFamily was accepted (above), then this address string value must be parse-able in accordance with it; else, the function will fail with the SNMPAPI_MODE_INVALID error. Otherwise, the implementation will derive a value for nAddressFamily from the syntax of dAddressString (in accordance with the rules already defined for SnmpStrToEntity()). |
| nRequestPort | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. If specified (>0), the value is then used as the destination port (or equivalent artifact for the address family in question) for SNMP request messages sent to this entity. If unspecified (0), the address family default SNMP port (e.g., UDP/161) will be applied. |
| nNotificationPort | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. If specified (>0), the value is then used as the destination port (or equivalent artifact for the address family in question) for SNMP notification messages (Traps and Informs) sent to this entity. If unspecified (0), the address family default SNMP-trap port (e.g., UDP/162) will be applied. |
| nMaxMsgSize | Unused if nTranslateMode is SNMPAPI_TRANSLATED or if the derived value of nSnmpVersion is not SNMPAPI_V3_SUPPORT. Optional otherwise. If specified (>0), the value is used as the initial maximum size of messages sent to this entity. If unspecified (0), the implementation will assign an implementation-specific initial value. For an entity which may be used as an authoritative SNMPv3 engine, any supplied or assigned value may be replaced later by a smaller value as indicated in a Report, Response, or Notification message from that engine. If an out-bound SNMP message directed to this entity exceeds the then current value of nMaxMsgSize, SnmpSendMsg() will fail with SNMPAPI_SIZE_INVALID. |
| dEngineID | Unused if nTranslateMode is SNMPAPI_TRANSLATED or if the derived nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. If the value of this attribute is the empty string when this SNMPv3 entity is used as the dstEntity in a call to SnmpSendMsg() with a PDU type from the Confirmed Class, then the implementation will transparently attempt a synchronous auto-discovery exchange with this entity and, if successful, will use the snmpEngineID from the corresponding Report PDU to initialize this element and to automatically complete the original message requested by the application. If this discovery process fails to complete properly, the call to SnmpSendMsg() will fail with the SNMPAPI_ENGINE_DISCOVERY_FAILED error. When this SNMPv3 entity is used as the srcEntity in a call to SnmpSendMsg() with a PDU type from the Unconfirmed Class, the value of this attribute may not be the empty string; otherwise, the call to SnmpSendMsg() will fail with the SNMPAPI_ENGINE_INVALID error. |
| nEngineBoots | Unused if nTranslateMode is SNMPAPI_TRANSLATED or if the derived nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. If both this value and nEngineTime are 0 (the normal case when an hEntity is newly instantiated) and the derived nSnmpVersion value is SNMPAPI_V3_SUPPORT in a dstEntity passed to SnmpSendMsg() which also has an hContext parameter indicating that authentication is to be performed on the message, then the implementation will attempt a synchronous time synchronization exchange with this entity and use the corresponding Report PDU to update these values prior to building the SNMPv3 message to send. Note that local entities acting in an SNMPv3 command responder ("agent") role must supply a value (e.g., restore it from NVRAM) for this attribute before calling SnmpListen(), which will automatically increment whatever value it finds at the time. If a value is not supplied at SnmpCreateEntity() time it may be set prior to SnmpListen() time with a call to SnmpSetEntityInfo(). Note that a command responder application must reset this value to 0 (normally in its persistent venue) when the value of its administratively assigned snmpEngineID changes. |
| nEngineTime | Unused. SnmpCreateEntity() will cause the implementation to set its internal representation of this attribute to 0. |
| nEngineSeconds | Unused. SnmpCreateEntity() will cause the implementation to set its internal representation of this attribute to 0. |
| nRetransmitMode | Required. May be either SNMPAPI_ON (recommended) or SNMPAPI_OFF -- any other value will be treated as SNMPAPI_ON. |
| nPolicyTimeout | Optional. If a value of 0 is passed, an implementation-specific default will be applied. |
| nPolicyRetry | Optional. If a value of 0 is passed, an implementation-specific default will be applied. |
| nActualTimeout | Unused. |
| nActualRetry | Unused. |
Return values for SnmpCreateEntity():
-
- Success = WinSNMP handle value (>0) for the new HSNMP_ENTITY resource object.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below. If hSession evaluates to a valid open session, then SnmpGetLastError() may obtain the session-specific last error code; in all cases, it has access to the process-wide last error code.
- Success = WinSNMP handle value (>0) for the new HSNMP_ENTITY resource object.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_SESSION_INVALID | hSession is not a valid active WinSNMP session. |
| SNMPAPI_ENTITY_INVALID | A specified entity attribute value is invalid. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| SNMPAPI_OTHER_ERROR | Systemic memory failure. |
| SNMPAPI_ENTITY_UNKNOWN | An LCD entry was not found for the named entity or a critical piece of entity information (e.g., address) is missing from the LCD entry. |
| SNMPAPI_ENGINE_INVALID | The engine ID value in the LCD is not valid (structurally; e.g., too short). |
| SNMPAPI_MODE_INVALID | The value of lpEntityInfo->nTranslateMode is invalid or the entity address parameters are invalid. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| HSNMP_CONTEXT | SnmpCreateContext | IN IN | HSNMP_SESSION smiLPCONTEXTINFO | hSession lpContextInfo |
The SnmpCreateContext() function creates a new instance of an HSNMP_CONTEXT resource object using values passed via the lpContextInfo parameter (for those attributes which have "Create" access) and, upon successful completion, allocates the new context to the WinSNMP session indicated by the hSession parameter. This function performs the same basic function as the older SnmpStrToContext() function but with more user application control features required for SNMPv3 support.
Please note:
-
- SnmpCreateContext() should be used in place of SnmpStrToContext() in all new WinSNMP applications (because SnmpCreateContext() provides a superset of SnmpStrToContext() functionality and leads to more capable and efficient applications).
- SnmpStrToContext() may be replaced with SnmpCreateContext() in all existing WinSNMP applications.
- SnmpStrToContext() will continue to function as always in existing and new applications that choose to use it (but with some additional new default attribute values assigned).
- SnmpCreateContext() should be used in place of SnmpStrToContext() in all new WinSNMP applications (because SnmpCreateContext() provides a superset of SnmpStrToContext() functionality and leads to more capable and efficient applications).
| Parameter | Description |
| hSession | A previously created open WinSNMP session to which this context will be allocated. |
| lpContextInfo | A pointer to an smiCONTEXTINFO structure. Elements of this structure with "Create" access will be evaluated for use in initializing the context resource; all others will be ignored. No elements of this structure will be modified by this function. |
The SnmpCreateContext() function uses the attributes of the smiCONTEXTINFO structure pointed to by the lpContextInfo parameter as indicated in the following table:
| Element Name | SnmpCreateContext() Behavior |
| hContext | Unused. |
| hSession | Unused. |
| nTranslateMode | Required. Used to determine other context attributes in accordance with its value, which must be one of the following: SNMPAPI_TRANSLATED SNMPAPI_UNTRANSLATED_V1 SNMPAPI_UNTRANSLATED_V2 SNMPAPI_UNTRANSLATED_V3 |
| nSnmpVersion | Unused. The implementation derives a value for this element from the application of nTranslateMode and associates it with the context for future retrieval via SnmpGetContextInfo(). Possible values are: SNMPAPI_V1_SUPPORT SNMPAPI_V2_SUPPORT SNMPAPI_V3_SUPPORT |
| dFriendlyName | Required if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. For SNMPAPI_TRANSLATED mode, this value is used to retrieve context attributes from the implementation-specific LCD. If no matching entry exists, the function fails with the SNMPAPI_CONTEXT_UNKNOWN error. When present in any mode, this value is recorded by the implementation as an attribute of the context that may later be retrieved via SnmpGetContextInfo(). |
| dContextEngineID | Unused if nTranslateMode is SNMPAPI_TRANSLATED or if the derived nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. For calls to SnmpSendMsg() with PDU types from the Confirmed Class, this attribute should be the empty string, unless the target dstEntity is a proxy forwarder application (which will use this value to identify the actual command responder application which controls the requested managed objects). When this attribute is the empty string for a Confirmed Class PDU, SnmpSendMsg() will use the dEngineID value from the dstEntity as the dContextEngineID value in the actual SNMP message. For calls to SnmpSendMsg() with PDU types from the Unconfirmed Class, the srcEntity is the authoritative SNMP engine. In this case, the calling application may provide a specific value for this attribute and SnmpSendMsg() will use it to form the out-bound SNMP message. If this attribute is the empty string, SnmpSendMsg() will use the dEngineID, if any, from the srcEntity. In either case, the resulting value must be acceptable to the receiving application identified by the dstEntity. For command responder (agent) and notification receiver applications, WinSNMP contexts describing valid users must pre-exist when a request or notification message is received by the engine to permit proper SNMPv3 message processing. For command responders, the value of dContextEngineID in contexts used to validate users must be the same as the dEngineID set in the agent entity. For notification receivers, the value of dContextEngineID in contexts used to validate users must be identical to the authoritative engine ID that will be found in the in-coming notification messages. In the case of SNMPv3 messages sent to proxy forwarder applications, the value of this attribute must be the snmpEngineID of the SNMP engine holding the associated MIB information. |
| dContextName | Unused if nTranslateMode is SNMPAPI_TRANSLATED or if the derived nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. Name of this context at the SNMP engine holding it. The empty string value in this attribute equates to the default context at that SNMP engine. |
| dSecurityName | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Required otherwise. If the derived value of nSnmpVersion is SNMPAPI_V1_SUPPORT or SNMAPI_V2_SUPPORT, this element represents the community string value. Otherwise, it is the security model- independent name of the principal using this context. For USM, it is identical to the userName. Once established via this function, the value of this element may not be changed. |
| nSecurityModel | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. Security model of this context:. Possible values are: SNMPAPI_OFF SNMPAPI_SEC_MODEL_V1 SNMPAPI_SEC_MODEL_V2 SNMPAPI_SEC_MODEL_USM |
| nSecurityLevel | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. Security level of this context. Possible values are: SNMPAPI_NOAUTH_NOPRIV SNMPAPI_AUTH_NOPRIV SNMPAPI_AUTH_PRIV |
| nSecurityAuthProtocol | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. Authentication protocol used by this context. Possible values are: SNMP_USM_NO_AUTH_PROTOCOL SNMP_USM_HMACMD5_AUTH_PROTOCOL SNMP_USM_HMACSHA_AUTH_PROTOCOL |
| dSecurityAuthKey | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. Security model-dependent parameter. Authentication key (non-localized) for USM. |
| nSecurityPrivProtocol | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. Encryption protocol used by this context. Possible values are: SNMP_USM_NO_PRIV_PROTOCOL SNMP_USM_DES_PRIV_PROTOCOL |
| dSecurityPrivKey | Unused if nTranslateMode is SNMPAPI_TRANSLATED. Optional otherwise. Security model-dependent parameter. Encryption key (non-localized) for USM. |
Return values for SnmpCreateContext():
-
- Success = WinSNMP handle value (>0) for the new HSNMP_CONTEXT resource object.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below. If hSession evaluates to a valid open session, then SnmpGetLastError() may obtain the session-specific last error code; in all cases, it has access to the process-wide last error code.
- Success = WinSNMP handle value (>0) for the new HSNMP_CONTEXT resource object.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_SESSION_INVALID | hSession is not a valid active WinSNMP session. |
| SNMPAPI_CONTEXT_INVALID | A specified context attribute value was invalid. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| SNMPAPI_OTHER_ERROR | Systemic memory failure. |
| SNMPAPI_CONTEXT_UNKNOWN | An :LCD entry was not found for the named context or a critical piece of context information (e.g., address) is missing from the LCD entry. |
| SNMPAPI_MODE_INVALID | The value of lpContextInfo->nTranslateMode is invalid. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| SNMPAPI_STATUS | SnmpSetEntityInfo | IN IN | HSNMP_ENTITY smiLPENTITYINFO | hEntity lpEntityInfo |
The SnmpSetEntityInfo() function accepts values passed via the lpEntityInfo parameter (for only those attributes which have "Write" access), compares them to the corresponding values of the implementation's internal representation of the existing HSNMP_ENTITY resource object indicated by the hEntity parameter, and--for those with changed values--upon successful completion, modifies those internal values. In addition to other things, this function performs the same basic operations as the older SnmpSetTranslateMode(), SnmpSetRetransmitMode(), SnmpSetTimeout(), SnmpSetRetry(), and SnmpSetPort() functions and may be used to replace them, collectively (recommended) or individually.
Please note:
-
- SnmpSetEntityInfo() should be used in place of SnmpSetTranslateMode(), SnmpSetRetransmitMode(), SnmpSetTimeout(), SnmpSetRetry(), and SnmpSetPort() in all new WinSNMP applications.
- Any/all of those five pre-existing WinSNMP functions may be replaced with SnmpSetEntityInfo() in all existing WinSNMP applications.
- Any/all of those five pre-existing WinSNMP functions will continue to work as always in existing and new applications that choose to use them (possibly with some additional new semantics for SNMPv3 support).
- SnmpSetEntityInfo() should be used in place of SnmpSetTranslateMode(), SnmpSetRetransmitMode(), SnmpSetTimeout(), SnmpSetRetry(), and SnmpSetPort() in all new WinSNMP applications.
| Parameter | Description |
| hEntity | A previously created open WinSNMP entity which is the target of this attribute change operation. |
| lpEntityInfo | A pointer to an smiENTITYINFO structure. Elements of this structure with "Write" access will be evaluated for use in modifying the values of the corresponding implementation-specific internal representation of entity attributes; all others will be ignored. No elements of this structure will be modified by this function. |
Note: An application should call SnmpGetEntityInfo() to initialize an smiENTITYINFO structure with accurate current values, change the value of any of the attributes with "Write" access that it needs to change, and then call SnmpSetEntityInfo() with the address of that same smiENTITYINFO structure as the lpEntityInfo parameter. This is necessary to ensure that the hEntity and hSession attributes will "Verify" properly and to ensure that no attributes are unintentionally changed.
Note: The attributes dFriendlyName, dAddressString, and dEngineID are all smiOCTETS types and, when populated for the application by SnmpGetEntityInfo() must eventually be freed with calls to SnmpFreeDescriptor(). Only one of those attributes (dEngineID) is ever changeable via this function (SnmpSetEntityInfo) and that is permitted only when it is the empty string, in which case there is no need to first call SnmpFreeDescriptor() on that attribute.
The SnmpSetEntityInfo() function uses the attributes of the smiENTITYINFO structure pointed to by the lpEntityInfo parameter as indicated in the following table [refer to the description of SnmpCreateEntity() for attribute explanations]:
| Element Name | SnmpSetEntityInfo() Behavior |
| hEntity | Unused. |
| hSession | Unused. |
| nTranslateMode | Unused. |
| nSnmpVersion | Unused. |
| dFriendlyName | Unused. |
| nAddressFamily | Unused. |
| dAddressString | Unused. |
| nRequestPort | Optional. May not be set to zero by this function. |
| nNotificationPort | Optional. May not be set to zero by this function. |
| nMaxMsgSize | Optional. May not be set to zero by this function. If specified (>0), the value is used as the maximum size of messages sent to this entity. For an entity which may be used as an authoritative SNMPv3 engine, any supplied value may be replaced later by a smaller value as indicated in a Report, Response, or Notification message from that engine. If an out-bound SNMP message directed to this entity exceeds the then current value of nMaxMsgSize, SnmpSendMsg() will fail with SNMPAPI_SIZE_INVALID. |
| dEngineID | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. This element may be written to only once, if and when the pre-existing value is the empty string. Note that local entities that expect to act in command responder ("agent") role must first set this value to their administratively assigned value before calling SnmpListen(); otherwise, that function will fail with the SNMPAPI_ENGINE_INVALID error. |
| nEngineBoots | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. This element may be written to only to change its value: Note that local entities acting in a command responder ("agent") role must use SnmpSetEntityInfo() to establish this value (e.g., restore it from NVRAM) upon loading and to reset it to 0 when the value of their administratively assigned snmpEngineID changes. |
| nEngineTime | Unused. If the value of nSnmpVersion is SNMPAPI_V3_SUPPORT:
|
| nEngineSeconds | Unused. If the value of nSnmpVersion is SNMPAPI_V3_SUPPORT:
|
| nRetransmitMode | Optional. May be either SNMPAPI_ON (recommended) or SNMPAPI_OFF -- any other value will be treated as SNMPAPI_ON. |
| nPolicyTimeout | Optional. May not be set to zero by this function. |
| nPolicyRetry | Optional. |
| nActualTimeout | Unused. |
| nActualRetry | Unused. |
Return values for SnmpSetEntityInfo():
-
- Success = SNMPAPI_SUCCESS.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below. No internal attributes values will be changed in response to a failed call to SnmpSetEntityInfo(). If the hEntity parameter identified a valid HSNMP_ENTITY resource object, then SnmpGetLastError() may obtain the session-specific last error code; in all cases, it has access to the process-wide last error code.
- Success = SNMPAPI_SUCCESS.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_ENTITY_UNKNOWN | The value of the hEntity parameter does not specify an active entity. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| SNMPAPI_ENTITY_INVALID | An entity attribute value is invalid. |
| SNMPAPI_MODE_INVALID | An operational value is invalid. |
| SNMPAPI_ENGINE_INVALID | An engine value is invalid (SNMPv3 entity only). |
| SNMPAPI_OPERATION_INVALID | A port change was requested for an entity running as an agent. |
| SNMPAPI_OTHER_ERROR | Systemic memory failure. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| SNMPAPI_STATUS | SnmpSetContextInfo | IN IN | HSNMP_CONTEXT smiLPCONTEXTINFO | hContext lpContextInfo |
The SnmpSetContextInfo() function accepts values passed via the lpContextInfo parameter (for only those attributes which have "Write" access), compares them to the corresponding values of the implementation's internal representation of the existing HSNMP_CONTEXT resource object indicated by the hContext parameter, and--for those with changed values--upon successful completion, modifies those internal values.
| Parameter | Description |
| hContext | A previously created open WinSNMP context which is the target of this attribute change operation. |
| lpContextInfo | A pointer to an smiCONTEXTINFO structure. Elements of this structure with "Write" access will be evaluated for use in modifying the values of the corresponding implementation-specific internal representation of context attributes; all others will be ignored. No elements of this structure will be modified by this function. |
Note: An application should call SnmpGetContextInfo() to initialize an smiCONTEXTINFO structure with accurate current values, change the value of any of the attributes with "Write" access that it needs to change, and then call SnmpSetContextInfo() with the address of that same smiCONTEXTINFO structure as the lpContextInfo parameter. This is necessary to ensure that the hContext and hSession attributes will "Verify" properly and to ensure that no attributes are unintentionally changed.
Note: The attributes dFriendlyName, dContextEngineID, dContextName, dSecurityName, dSecurityAuthKey, and dSecurityPrivKey are all smiOCTETS types and, when populated for the application by SnmpGetContextInfo() must eventually be freed with calls to SnmpFreeDescriptor().
The SnmpSetContextInfo() function uses the attributes of the smiCONTEXTINFO structure pointed to by the lpContextInfo parameter as indicated in the following table [refer to the description of SnmpCreateContext() for attribute explanations]:
| Element Name | SnmpSetContextInfo() Behavior |
| hContext | Unused. |
| hSession | Unused. |
| nTranslateMode | Unused. |
| nSnmpVersion | Unused. |
| dFriendlyName | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| dContextEngineID | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| dContextName | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| dSecurityName | Unused. |
| nSecurityModel | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| nSecurityLevel | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| nSecurityAuthProtocol | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| dSecurityAuthKey | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| nSecurityPrivProtocol | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
| dSecurityPrivKey | Unused if the nSnmpVersion value is not SNMPAPI_V3_SUPPORT. Optional otherwise. |
Return values for SnmpSetContextInfo():
-
- Success = SNMPAPI_SUCCESS.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below. No internal attributes values will be changed in response to a failed call to SnmpSetContextInfo(). If the hContext parameter identified a valid HSNMP_CONTEXT resource object, then SnmpGetLastError() may obtain the session-specific last error code; in all cases, it has access to the process-wide last error code.
- Success = SNMPAPI_SUCCESS.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_CONTEXT_UNKNOWN | The value of the hContext parameter does not specify an active context. |
| SNMPAPI_CONTEXT_INVALID | A context attribute value was invalid. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| SNMPAPI_STATUS | SnmpGetEntityInfo | IN OUT | HSNMP_ENTITY smiLPENTITYINFO | hEntity lpEntityInfo |
The SnmpGetEntityInfo() function provides current values for all attributes of the smiENTITYINFO structure pointed to by the lpEntityInfo parameter based on the implementation's internal values for HSNMP_ENTITY resource object indicated by the hEntity parameter.
Please note:
-
- The contents, if any, of the smiENTITYINFO structure passed to this function by the lpEntityInfo parameter will be over-written with current values, or new instances of current values in the case of those attributes of type smiOCTETS or smiOID.
- Be sure to call SnmpFreeDescriptor() on any existing attribute values of type smiOCTETS or smiOID that were allocated by the implementation in a previous call to SnmpGetEntityInfo() before calling SnmpGetEntityInfo() with the same smiENTITYINFO structure again. The SnmpFreeEntityInfo() function is provided to facilitate this step.
- In general, it is advisable to call SnmpGetEntityInfo() to populate an smiENTITYINFO structure as a basis for a subsequent call to SnmpSetEntityInfo(), changing only those attributes with "Write" access that the application needs or wants to modify, taking care to call SnmpFreeDescriptor() first if any attributes values of type smiOCTETS or smiOID are to be changed.
- The contents, if any, of the smiENTITYINFO structure passed to this function by the lpEntityInfo parameter will be over-written with current values, or new instances of current values in the case of those attributes of type smiOCTETS or smiOID.
All attributes of the smiENTITYINFO structure are returned by a successful call to the SnmpGetEntityInfo() function and are set to zero (or the empty string) by a call which fails for any reason:
| Element Name | SnmpGetEntityInfo() Behavior |
| hEntity | Returned...will match the hEntity parameter value on success. |
| hSession | Returned. |
| nTranslateMode | Returned. |
| nSnmpVersion | Returned. |
| dFriendlyName | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeEntitytInfo(). |
| nAddressFamily | Returned. |
| dAddressString | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeEntityInfo(). |
| nRequestPort | Returned. |
| nNotificationPort | Returned. |
| nMaxMsgSize | Returned. |
| dEngineID | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeEntityInfo(). |
| nEngineBoots | Returned. |
| nEngineTime | Returned. |
| nEngineSeconds | Returned. |
| nRetransmitMode | Returned. |
| nPolicyTimeout | Returned. |
| nPolicyRetry | Returned. |
| nActualTimeout | Returned. |
| nActualRetry | Returned. |
Return values for SnmpGetEntityInfo():
-
- Success = SNMPAPI_SUCCESS.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below. Note that all scalar attributes will be set to 0 and all attributes of type smiOCTETS or smiOID will be set to the empty string. If the hEntity parameter identified a valid HSNMP_ENTITY resource object, then SnmpGetLastError() may obtain the session-specific last error code; in all cases, it has access to the process-wide last error code.
- Success = SNMPAPI_SUCCESS.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_ENTITY_UNKNOWN | The value of the hEntity parameter does not specify an active entity. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| SNMPAPI_ENTITY_INVALID | Entity address parameters not valid. |
| SNMPAPI_OTHER_ERROR | Systemic memory failure. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| SNMPAPI_STATUS | SnmpGetContextInfo | IN OUT | HSNMP_CONTEXT smiLPCONTEXTINFO | hContext lpContextInfo |
The SnmpGetContextInfo() function provides current values for all attributes of the smiCONTEXTINFO structure pointed to by the lpConextInfo parameter based on the implementation's internal values for HSNMP_CONTEXT resource object indicated by the hContext parameter.
Please note:
-
- The contents, if any, of the smiCONTEXTINFO structure passed to this function by the lpContextInfo parameter will be over-written with current values, or new instances of current values in the case of those attributes of type smiOCTETS or smiOID.
- Be sure to call SnmpFreeDescriptor() on any existing attribute values of type smiOCTETS or smiOID that were allocated by the implementation in a previous call to SnmpGetContextInfo() before calling SnmpGetContextInfo() with the same smiENTITYINFO structure again. The SnmpFreeContextInfo() function is provided to facilitate this step.
- In general, it is advisable to call SnmpGetContextInfo() to populate an smiCONTEXTINFO structure as a basis for a subsequent call to SnmpSetContextInfo(), changing only those attributes with "Write" access that the application needs or wants to modify, taking care to call SnmpFreeDescriptor() first if any attributes values of type smiOCTETS or smiOID are to be changed.
- The contents, if any, of the smiCONTEXTINFO structure passed to this function by the lpContextInfo parameter will be over-written with current values, or new instances of current values in the case of those attributes of type smiOCTETS or smiOID.
All attributes of the smiCONTEXTINFO structure are returned by a successful call to the SnmpGetContextInfo() function and are set to zero (or the empty string) by a call which fails for any reason:
| Element Name | SnmpGetContextInfo() Behavior |
| hContext | Returned...will match the hContext parameter value on success. |
| hSession | Returned. |
| nTranslateMode | Returned. |
| nSnmpVersion | Returned. |
| dFriendlyName | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeContextInfo(). |
| dContextEngineID | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeContextInfo(). |
| dContextName | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeContextInfo(). |
| dSecurityName | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeContextInfo(). |
| nSecurityModel | Returned. |
| nSecurityLevel | Returned. |
| nSecurityAuthProtocol | Returned. |
| dSecurityAuthKey | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeContextInfo(). |
| nSecurityPrivProtocol | Returned. |
| dSecurityPrivKey | Returned...must be freed with SnmpFreeDescriptor() or SnmpFreeContextInfo(). |
Return values for SnmpGetContextInfo():
-
- Success = SNMPAPI_SUCCESS.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below. Note that all scalar attributes will be set to 0 and all attributes of type smiOCTETS or smiOID will be set to the empty string. If the hContext parameter identified a valid HSNMP_CONTEXT resource object, then SnmpGetLastError() may obtain the session-specific last error code; in all cases, it has access to the process-wide last error code.
- Success = SNMPAPI_SUCCESS.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_CONTEXT_UNKNOWN | The value of the hContext parameter does not specify an active context. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| SNMPAPI_STATUS | SnmpFreeEntityInfo | IN OUT | smiLPENTITYINFO | lpEntityInfo |
The SnmpFreeEntityInfo() function takes a pointer to an smiENTITYINFO structure and frees the resources previously allocated to elements of that structure. Specifically, SnmpFreeEntityInfo() calls SnmpFreeDescriptor() on the following smiOCTETS elements of the smiENTITYINFO structure pointed to by the lpEntityInfo parameter:
-
- dFriendlyName
- dAddressString
- dEngineID
It then initializes the smiENTITYINFO structure pointed to by the lpEntityInfo parameter to all zeros.
Please note that calling SnmpFreeEntityInfo() does not free the WinSNMP entity that may have been associated with the smiENTITYINFO structure pointed to by the lpEntityInfo parameter (lpEntityInfo->hEntity) because that entity may be associated with other active smiENTITYINFO structures (currently or at a later time). The same is true for the WinSNMP session value, if any, in lpEntityInfo->hSession.
Return values for SnmpFreeEntityInfo():
-
- Success = SNMPAPI_SUCCESS.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below, via the process-wide last error code (since no session is attached to this call).
- Success = SNMPAPI_SUCCESS.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| SNMPAPI_STATUS | SnmpFreeContextInfo | IN OUT | smiLPCONTEXTINFO | lpContextInfo |
The SnmpFreeContextInfo() function takes a pointer to an smiCONTEXTINFO structure and frees the resources previously allocated to elements of that structure. Specifically, SnmpFreeContextInfo() calls SnmpFreeDescriptor() on the following smiOCTETS elements of the smiCONTEXTINFO structure pointed to by the lpContextInfo parameter:
-
- dFriendlyName
- dContextEngineID
- dContextName
- dSecurityName
- dSecurityAuthKey
- dSecurityPrivKey
It then initializes the smiCONTEXTINFO structure pointed to by the lpContextInfo parameter to all zeros.
Please note that calling SnmpFreeContextInfo() does not free the WinSNMP context that may have been associated with the smiCONTEXTINFO structure pointed to by the lpContextInfo parameter (lpContextInfo->hContext). because that context may be associated with other active smiCONTEXTINFO structures (currently or at a later time). The same is true for the WinSNMP session value, if any, in lpContextInfo->hSession.
Return values for SnmpFreeContextInfo():
-
- Success = SNMPAPI_SUCCESS.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below, via the process-wide last error code (since no session is attached to this call).
- Success = SNMPAPI_SUCCESS.
| Error Code | Cause |
| SNMPAPI_NOT_INITIALIZED | SnmpStartup() was not previously called successfully. |
| SNMPAPI_ALLOC_ERROR | Generic memory allocation or access failure. |
| Return Type | Function Name | Parameter Mode | Parameter Type | Parameter Name |
| SNMPAPI_STATUS | SnmpPasswordToKey | OUT IN IN | smiLPOCTETS smiINT32 smiLPOCTETS | lpKey nSecurityAuthProtocol lpPassword |
The SnmpPasswordToKey() function takes a password input value from the lpPassword parameter and converts it to a non-localized key value which is returned in the lpKey parameter. The specific key hash function used (MD5 or SHA) is determined by the value of the nSecurityAuthProtocol input parameter.
Please note:
Return values for SnmpPasswordToKey():
-
- Success = SNMPAPI_SUCCESS.
- Failure = SNMPAPI_FAILURE, with SnmpGetLastError() set to return one of the extended error codes shown below, via the process-wide last error code (since no session is attached to this call).
- Success = SNMPAPI_SUCCESS.
| Error Code | Cause |
| SNMPAPI_OPERATION_INVALID | The nSecurityAuthProtocol parameter is neither SNMP_USM_HMACMD5_AUTH_PROTOCOL nor SNMP_USM_HMACSHA_AUTH_PROTOCOL. |
| SNMPAPI_ALLOC_ERROR | Either lpKey, lpPassword, or lpPassword->ptr is not a valid read pointer or password->len is equal to zero. |
| SNMPAPI_ALLOC_ERROR | Unable to allocate memory for lpKey->ptr |
Updated Pre-Existing Functions
A number of pre-existing WinSNMP functions require internal modifications to accommodate SNMPv3 operations as embodied in this WinSNMP v3.0 Addendum specification:
-
- SnmpStrToEntity()
- SnmpStrToContext()
- SnmpListen()
- SnmpSendMsg()
- SnmpRecvMsg()
- SnmpEncodeMsg() (TBD)
- SnmpDecodeMsg() (TBD)
New applications should use SnmpCreateEntity() in place of SnmpStrToEntity(); existing applications should be modified to use SnmpCreateEntity() in place of SnmpStrToEntity() when, if ever, convenient. Although its use is discouraged, in favor of SnmpCreateEntity(), SnmpStrToEntity() will continue to function for existing and/or new applications.
When called in SNMPAPI_TRANSLATED mode, SnmpStrToEntity() will continue to function as always and will, in addition, accept local database entries defined for SNMPv3 entities. A compliant implementation must allow for (but not necessarily require) specification of all smiENTITYINFO attributes with "Create" access in its LCD facility.
When an application calls SnmpStrToEntity() against a WinSNMP v3.0 implementation, the implementation logically initializes its internal representation of an smiENTITYINFO structure and assigns default values to all of its elements (such default values may consist of whatever other legal values the implementation elects to use, including zeros and empty strings). Then:
If SnmpStrToEntity() is called in SNMPAPI_TRANSLATED mode and the entity named in the call is found in the local database, corresponding attribute values are taken from the local database and over-ride the previously assigned default values. Assuming a successful return from this call yielding a "newEntity" handle, an immediate call to SnmpGetEntityInfo (newEntity, lpEntityInfo) would produce the following smiENTITYINFO output:
| Element Name | From TranslatedMode SnmpStrToEntity(), SnmpGetEntityInfo() Returns: |
| hEntity | The "newEntity" parameter value. |
| hSession | The hSession value used in the SnmpStrToEntity() call. |
| nTranslateMode | SNMPAPI_TRANSLATED. |
| nSnmpVersion | The value derived from the LCD entry. |
| dFriendlyName | The entityName passed to the SnmpStrToEntity() call. |
| nAddressFamily | The value derived from the LCD entry. |
| dAddressString | The value derived from the LCD entry. |
| nRequestPort | The value derived from the LCD entry, if any, or implementation default. |
| nNotificationPort | The value derived from the LCD entry, if any, or implementation default. |
| nMaxMsgSize | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| dEngineID | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| nEngineBoots | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| nEngineTime | Zero. |
| nEngineSeconds | Zero. |
| nRetransmitMode | The value derived from the LCD entry, if any, or implementation default. |
| nPolicyTimeout | The value derived from the LCD entry, if any, or implementation default. |
| nPolicyRetry | The value derived from the LCD entry, if any, or implementation default. |
| nActualTimeout | Zero. |
| nActualRetry | Zero. |
If SnmpStrToEntity() is called in any of the SNMPAPI_UNTRANSLATED_V<x> modes, certain attribute values are derived from the call parameters and runtime settings and assigned by the implementation; the others are left at their previously assigned default values. Assuming a successful return from this call yielding a "newEntity" handle, an immediate call to SnmpGetEntityInfo (newEntity, lpEntityInfo) would produce the following smiENTITYINFO output:
| Element Name | From UntranslatedMode SnmpStrToEntity(), SnmpGetEntityInfo() Returns: |
| hEntity | The "newEntity" parameter value. |
| hSession | The hSession value used in the SnmpStrToEntity() call. |
| nTranslateMode | The TranslateMode value in effect when the call to SnmpStrToEntity() was made, which may be the implementation default if no prior call to SnmpSetTranslateMode() had been made. |
| nSnmpVersion | The value indicated by the nTranslateMode value. |
| dFriendlyName | The empty string. |
| nAddressFamily | The value derived from address string passed to SnmpStrToEntity(). |
| dAddressString | The value derived from address string passed to SnmpStrToEntity(). |
| nRequestPort | The SNMP request default port for the nAddressFamily. |
| nNotificationPort | The SNMP notification default port for the nAddressFamily. |
| nMaxMsgSize | Zero. |
| dEngineID | The empty string. |
| nEngineBoots | Zero. |
| nEngineTime | Zero. |
| nEngineSeconds | Zero. |
| nRetransmitMode | The RetransmitMode value in effect when the call to SnmpStrToEntity() was made, which may be the implementation default if no prior call to SnmpSetRetransmitMode() had been made. |
| nPolicyTimeout | An implementation default. |
| nPolicyRetry | An implementation default. |
| nActualTimeout | Zero. |
| nActualRetry | Zero. |
The design intent of WinSNMP v3.0 is that pre-existing WinSNMP v2.0 applications must be able to continue to function without change in a WinSNMP v3.0 runtime environment. With respect to WinSNMP entity considerations:
-
- For manager or agent applications working only with either SNMPv1 or SNMPv2 operations, that goal is achieved without qualification. This is the primary objective.
- For applications working in "translated mode", that goal can be achieved for SNMPv3 operations as well, with only the single (and obvious) qualification that the LCD entries must include all necessary SNMPv3 attributes. Exactly which ones are necessary will depend upon the security level under which the application wants to operate.
- For pre-existing applications able to work in SNMPAPI_UNTRANSLATED_V3 mode (where the mode is set via a runtime parameter whose value comes from user or programmatic input), SNMPv3 command generator (and response processing) operations will work at a security level of noAuth/noPriv, as long as SnmpSendMsg() can perform the auto-discovery exchange with the target SNMPv3 command responders.
- For manager or agent applications working only with either SNMPv1 or SNMPv2 operations, that goal is achieved without qualification. This is the primary objective.
Note that following a successful SnmpGetEntityInfo() operation, SnmpSetEntityInfo() may be used to modify those attributes of an HSNMP_ENTITY resource object, subject to its nSnmpVersion value, without prejudice deriving from its origin via either SnmpCreateEntity() or SnmpStrToEntity(). That is, once instantiated, all entities are treated as equals.
New applications should use SnmpCreateContext() in place of SnmpStrToContext(); existing applications should be modified to use SnmpCreateContext() in place of SnmpStrToContext() when, if ever, convenient. Although its use is discouraged, in favor of SnmpCreateContext(), SnmpStrToContext() will continue to function for existing and/or new applications.
When called in SNMPAPI_TRANSLATED mode, SnmpStrToContext() will continue to function as always and will, in addition, accept local database entries defined for SNMPv3 entities. A compliant implementation must allow for (but not necessarily require) specification of all smiCONTEXTINFO attributes with "Create" access in its LCD facility.
When an application calls SnmpStrToContext() against a WinSNMP v3.0 implementation, the implementation logically initializes its internal representation of an smiCONTEXTNFO structure and assigns default values to all of its elements (such default values may consist of whatever legal values the implementation elects to use, including zeros and empty strings). Then:
If SnmpStrToContext() is called in SNMPAPI_TRANSLATED mode and the context named in the call is found in the local database, corresponding attribute values are taken from the local database and over-ride the previously assigned default values. Assuming a successful return from this call yielding a "newContext" handle, an immediate call to SnmpGetContextInfo (newContext, lpContextInfo) would produce the following smiCONTEXTINFO output:
| Element Name | From TranslatedMode SnmpStrToContext(), SnmpGetContextInfo() Returns: |
| hContext | The "newContext" parameter value. |
| hSession | The hSession value used in the SnmpStrToContext() call. |
| nTranslateMode | SNMPAPI_TRANSLATED. |
| nSnmpVersion | The value derived from the LCD entry. |
| dFriendlyName | The contextName passed to the SnmpStrToContext() call. |
| dContextEngineID | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| dContextName | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| dSecurityName | The value derived from the LCD entry. |
| nSecurityModel | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| nSecurityLevel | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| nSecurityAuthProtocol | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| dSecurityAuthKey | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| nSecurityPrivProtocol | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
| dSecurityPrivKey | The value derived from the LCD entry if nSnmpVersion is SNMPAPI_V3_SUPPORT, if any, or implementation default. |
If SnmpStrToContext() is called in any of the SNMPAPI_UNTRANSLATED_V<x> modes, certain attribute values are derived from the call parameters and runtime settings and assigned by the implementation; the others are left at their previously assigned default values. Assuming a successful return from this call yielding a "newContext" handle, an immediate call to SnmpGetContextInfo (newContext, lpContextInfo) would produce the following smiCONTEXTINFO output:
| Element Name | From UntranslatedMode SnmpStrToContext(), SnmpGetContextInfo() Returns: |
| hContext | The "newContext" parameter value. |
| hSession | The hSession value used in the SnmpStrToContext() call. |
| nTranslateMode | The TranslateMode value in effect when the call to SnmpStrToContext() was made, which may be the implementation default if no prior call to SnmpSetTranslateMode() had been made. |
| nSnmpVersion | The value indicated by the nTranslateMode value. |
| dFriendlyName | The empty string. |
| dContextEngineID | The empty string. |
| dContextName | The empty string. |
| dSecurityName | The value of contextName passed to SnmpStrToContext(). |
| nSecurityModel | Corresponding to the value of nSnmpVersion, as follows: SNMPAPI_V1_SUPPORT = SNMPAPI_SEC_MODEL_V1 SNMPAPI_V1_SUPPORT = SNMPAPI_SEC_MODEL_V2 SNMPAPI_V1_SUPPORT = SNMPAPI_SEC_MODEL_USM |
| nSecurityLevel | SNMPAPI_NOAUTH_NOPRIV |
| nSecurityAuthProtocol | SNMP_USM_NO_AUTH_PROTOCOL |
| dSecurityAuthKey | The empty string. |
| nSecurityPrivProtocol | SNMP_USM_NO_PRIV_PROTOCOL |
| dSecurityPrivKey | The empty string. |
The design intent of WinSNMP v3.0 is that pre-existing WinSNMP v2.0 applications must be able to continue to function without change in a WinSNMP v3.0 runtime environment. With respect to WinSNMP context considerations:
-
- For manager or agent applications working only with either SNMPv1 or SNMPv2 operations, that goal is achieved without qualification. This is the primary objective.
- For applications working in "translated mode", that goal can be achieved for SNMPv3 operations as well, with only the single (and obvious) qualification that the LCD entries must include all necessary SNMPv3 attributes. Exactly which ones are necessary will depend upon the security level under which the application wants to operate.
- For pre-existing applications able to work in SNMPAPI_UNTRANSLATED_V3 mode (where the mode is set via a runtime parameter whose value comes from user or programmatic input), SNMPv3 command generator (and response processing) operations will work at a security level of SNMPAPI_NOAUTH_NOPRIV for the default contextEngineID and contextName.. (Proxy forwarder targets are excluded in this particular scenario, since a non-default contentEngineID is required to differentiate them from native command responder targets.)
Note that following a successful SnmpGetContextInfo() operation, SnmpSetContextInfo() may be used to modify those attributes of an HSNMP_CONTEXT resource object, subject to its nSnmpVersion value, without prejudice deriving from its origin via either SnmpCreateContext() or SnmpStrToContext(). That is, once instantiated, all contexts are treated as equals.
This function is unchanged with respect to entities operating in SNMPv1 or SNMPv2 mode.
For entities whose nSnmpVersion attribute value is SNMPAPI_V3_SUPPORT that expect to act in a command responder (i.e., "agent") role, SnmpListen() will:
-
- Require that such entities first have a value (i.e., not the empty string) for their dEngineID attribute representing their administratively assigned snmpEngineID value and that this value be unique among all entities registered as agents in the given instance of the WinSNMP implementation; otherwise, the call to SnmpListen() will fail with the SNMPAPI_ENGINE_INVALID error. The dEngineID value can be initialized at SnmpCreateEntity() time or later via SnmpSetEntityInfo().
- Increment the corresponding value of dEngineBoots and set both dEngineTime and dEngineSeconds to zero before returning. It is the responsibility of the "agent" application to maintain a record (whether fully automatic or with some degree of human intervention) of its administratively assigned dEngineID value and its dEngineBoots value upon termination for restoration via either SnmpCreateEntity() and/or SnmpSetEntity() at its next re-start.
- Cause the implementation to maintain "authoritative time" for use when this entity is used as the authoritative engine in an SNMPv3 message.
- Require that such entities first have a value (i.e., not the empty string) for their dEngineID attribute representing their administratively assigned snmpEngineID value and that this value be unique among all entities registered as agents in the given instance of the WinSNMP implementation; otherwise, the call to SnmpListen() will fail with the SNMPAPI_ENGINE_INVALID error. The dEngineID value can be initialized at SnmpCreateEntity() time or later via SnmpSetEntityInfo().
This function is unchanged with respect to entities operating in SNMPv1 or SNMPv2 mode.
For entities whose nSnmpVersion attribute value is SNMPAPI_V3_SUPPORT:
-
- If a dstEntity's dEngineID is the empty string in a call to SnmpSendMsg() for a confirmed class PDU type (i.e., "request"), the implementation will transparently attempt a synchronous auto-discovery exchange with this entity and, if successful, will use the snmpEngineID from the corresponding Report PDU to initialize this attribute and to automatically complete the original message requested by the application.. Applications may use SnmpGetEntityInfo() to determine whether the auto-discovery exchange has completed successfully.
- If the auto-discovery exchange times out (using the dstEntity's existing timeout interval and retry count values), SnmpSendMsg() will fail and SnmpGetLastError() will be set to return SNMPAPI_ENGINE_INVALID for the hSession passed to SnmpSendMsg().
- If a srcEntity's dEngineID is the empty string in a call to SnmpSendMsg() for a confirmed class PDU type (i.e., "request"), that function will fail and SnmpGetLastError() will be set to return SNMPAPI_ENGINE_INVALID for the hSession passed to SnmpSendMsg().
- If both nEngineBoots and nEngineTime are 0 (the normal case when an hEntity is newly instantiated) in a dstEntity passed to SnmpSendMsg() which also has an hContext parameter indicating that authentication is to be performed on the message (i.e., the hContext's nSecurityModel attribute is SNMPAPI_AUTH_NOPRIV or SNMPAPI_AUTH_PRIV), then the implementation will attempt a synchronous time synchronization exchange with this entity and use the corresponding Report PDU to update these values prior to building the SNMPv3 message to send. [Need an error code here!]
- If the size of a constructed SNMP message exceeds the nMaxMsgSize attribute for the dstEntity, SnmpSendMsg() will fail with SNMPAPI_SIZE_INVALID.
- If a dstEntity's dEngineID is the empty string in a call to SnmpSendMsg() for a confirmed class PDU type (i.e., "request"), the implementation will transparently attempt a synchronous auto-discovery exchange with this entity and, if successful, will use the snmpEngineID from the corresponding Report PDU to initialize this attribute and to automatically complete the original message requested by the application.. Applications may use SnmpGetEntityInfo() to determine whether the auto-discovery exchange has completed successfully.
Notes:
-
- Recommend NULL for dstEntity and context parameters for command generator (CG) applications (i.e., "managers" in pre-SNMPv3 terminology) when receiving responses to previously issued request messages. In this case, the dstEntity will refer to this CG application itself and the context will be identical to the one used in sending out the corresponding request message; hence, both are superfluous..
- For command responder (CR) applications (i.e., "agents" in pre-SNMPv3 terminology), the WinSNMP context handle received in an incoming request message must be used in the call to SnmpSendMsg() when sending the corresponding response message (so that the proper msgID value will be applied).
- Recommend NULL for dstEntity and context parameters for command generator (CG) applications (i.e., "managers" in pre-SNMPv3 terminology) when receiving responses to previously issued request messages. In this case, the dstEntity will refer to this CG application itself and the context will be identical to the one used in sending out the corresponding request message; hence, both are superfluous..
Updated Coexistence Operations
Mapping between SNMPv1 and SNMPv2 Trap-PDUs is now governed by the SNMPv3 "Coexistence" document (RFC2576), rather than RFC2089.
Following are rough notes concerning the Applied SNMP implementation as of this date:
-
- Conforms with 3.1.1-3.1.3 on v1 to v2 mapping of time-ticks and snmpTrapOid. Conforms with 3.1.4 on rest of payload, except no check for pre-existence of the trapAddress, community and Enterprise varbinds to be added. The spec says these are required only of a proxy forwarder.
- Conforms to 3.2.1, 3.2.3, 3.2.4, 3.2.5 on v2 to v1 mapping of enterprise, generic-trap, specific-trap, time-ticks . 3.2.2 for agent-addr says that app is NO, agent-addr should be NO's IP or 0.0.0.0, and if app is proxy, agent-addr should be snmpTrapAddress.0 varbind or 0.0.0.0. Implementation will use snmpTrapAddress, or app's IP or 0, in that order. Note that for enterprise, the implementation will use snmpTrapEnterprise VB if present and specific trap is calculated as 0. Can specific trap be 0 and the enterprise portion of snmpTrapOID be different than the value of snmpTrapEnterprise? 3.2.6 for the rest of the payload says to fail for Counter64 while implementation deletes. Implementation removes sysUpTime, snmpTrapOID, snmpTrapEnterprise varbinds if present. RFC does not specify removal.
- Conforms to 4.1.1, CG downgrades GetBulk
- Several items under 4.1.2 on multilingual CR's so not seem to be addressed the implementation: 4.1.2.1 on Counter64 requests from v1; 4.1.2.2 on handling v2 noSuchObject, noSuchInstance, etc responses for v1 requests; 4.1.2.3 on other error-status mappings; and others.
- Conforms with 3.1.1-3.1.3 on v1 to v2 mapping of time-ticks and snmpTrapOid. Conforms with 3.1.4 on rest of payload, except no check for pre-existence of the trapAddress, community and Enterprise varbinds to be added. The spec says these are required only of a proxy forwarder.
- 4.1.3 Again states that a NO trying to send a v2 pdu with Cntr64 to a v1 entity should fail instead of silently removing the vb's as the implementation does. It also *implies* mapping informs into traps instead of failing as the implementation does.
-
-
-
- 4.2 on Proxy Implementations has provisions for pdu downgrade and error mapping. This section not closely reviewed as of yet.
-
扫一扫
3176
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
