INapSystemHealthValidator::Validate method

The INapSystemHealthValidator::Validate method is defined by the SHV developer and called by the NAP system to validate the SoHRequest received from a client.

Syntax

HRESULT Validate(
  [in] INapSystemHealthValidationRequest *request,
  [in] UINT32                            hintTimeOutInMsec,
  [in] INapServerCallback                *callback
);

Parameters

request [in]

A COM pointer to an INapSystemHealthValidationRequest object that identifies the validation request object.

hintTimeOutInMsec [in]

The duration, in milliseconds, of the communication timeout period. The System Health Validator (SHV) should respond within this amount of time; otherwise the response is dropped.

Note

The default timeout for all SHVs is 2000 milliseconds. Using a value other than the default will change the timeout for all registered SHVs.

callback [in]

A pointer to the callback object INapServerCallback. This callback pointer is used by the SHVs when they return E_PENDING from the call to INapSystemHealthValidator::Validate. This is used for asynchronous validation. The SHVs are expected to respond within the hintTimeOutInMsec time or else the response will be dropped.

Return value

If any other error code is returned, then the system assumes serverComponent failure has occurred, and the appropriate mapping is done to pass/fail.

Remarks

In order to support intrusion detection, SHVs will be asked to validate the client machine regardless of whether the client sent an SoHRequest intended for the SHV.

The SHV must do the following:

• Retrieve the SoHRequest from request by calling request.GetSoHRequest().
• If the SoHRequest packet is null:
  • If the SHV is an intrusion detection system, populate an SoHRequest packet with the appropriate NAP error code as to why the client machine is malicious.
  • All other SHVs should populate an SoHRequest packet with an error code of NAP_E_MISSING_SOH.
• If napSystemGenerated is TRUE from the call to request.GetSoHRequest(), the SHV should expect an SoH packet with the following 3 TLVs: sohAttributeTypeSystemHealthId, sohAttributeTypeFailureCategory, sohAttributeTypeErrorCodes. This SoHRequest is generated by the NapAgent on behalf of the System Health Agent (SHA) since there was an error in retrieving a request packet from the SHA.
• Validate the SoHRequest packet.
  • If the SoHRequest is malformed, then construct a SoHResponse packet with error code NAP_E_INVALID_PACKET.
  • If the SHV is only using cached information to validate the SoHRequest packet (i.e. no I/O is performed), then it can construct the SoHResponse, set it on the object in request and return S_OK.
  • If the SHV is performing I/O in order to talk to its back-end servers to validate the client's health, then it must queue up the I/O and return this function with E_PENDING. In this case, the SHV must call callback.OnComplete() on a separate thread within the timeout period, hintTimeOutInMsec. Otherwise, the SHV's response will be dropped.
• Do not return any other error other than those listed above. If any other error code is returned by the SHV (eg. some system error), the packet will be discarded.

An SHV must return either an sohAttributeTypeComplianceResultCodes or sohAttributeTypeFailureCategory TLV in its SoHRequest.

• sohAttributeTypeComplianceResultCodes TLV: If the SHV could validate the health of the client (i.e. healthy or unhealthy), this TLV is returned.
• sohAttributeTypeFailureCategory TLV: If there was any component or communication failure on the client or server, it must be indicated by this TLV. This TLV will further be mapped to healthy or unhealthy depending upon the SHV's configuration. For more details, see the INapServerManagement interface and the FailureCategoryMapping structure.

The SHV must not hold references to request or callback once the asyncronous call completes.

Requirements

See also

INapSystemHealthValidator