Beispiel-SHV
Hinweis
Die Netzwerkzugriffsschutzplattform ist ab Windows 10
Im folgenden Beispiel wird ein Systemintegritätsüberprüfungs-System (System Health Validator, SHV) auf einem NAP-Integritätsrichtlinienserver eingerichtet.
Hinweis
Das NAP SDK enthält auch einen vollständigen Satz von Beispielcode, der unter ...\Samples\NetDS\NAP... Verzeichnis Ihrer SDK-Installation. Dieser Beispielsatz umfasst system health agent (SHA), SHV und Erzwingungsclient (EC). Es verfügt über vollständige funktionierende NAP-Szenarien, die die Kommunikation zwischen SHA-SHV und SHA-EC einrichten.
#include <windows.h>
#include "stdafx.h"
#include "NapUtil.h"
#include "NapTypes.h"
#include "NapProtocol.h"
#include "NapMicrosoftVendorIds.h"
#include "NapSystemHealthValidator.h"
#include "NapError.h"
STDMETHODIMP CSampleShv::Validate(
/*[in]*/ INapSystemHealthValidationRequest* pShvRequest,
/*[in]*/ UINT32 hintTimeOutInMsec,
/*[in]*/ INapServerCallback* pCallback)
{
HRESULT hr = S_OK;
//
// SDK Note:
//
// If a SoH validation code determines that it needs to contact an external
// server to assist with validation, it must start a separate helper thread
// to contact the server, and return E_PENDING in this thread. When that
// occurs, this thread must exit to the SHV Host, returning the E_PENDING
// result; the helper thread should independently determine the final
// validation result, generate the response SoH, and call the SHV Host's
// Callback interface.
//
// This SHV handles the Validate() call asynchronously. Validate() method
// return with hr = E_PENDING and does the processing of SoH request and
// generating SoHResponse in a separate thread.
//
// SDK Note:
//
// If a SHV does not require processing in a separate thread but can return
// the response immediately, it should call the function QShvRespondSHVHost()
// below.
// Store the callback and request pointers.
m_pShvRequest = pShvRequest;
m_callback = pCallback;
//
// SDK Note:
//
// Creating a separate helper thread is done whenever a SHV must contact
// the external server. Therefore, the following code that creates a thread
// should be executed whenever the need arises.
//
// Here we assume the SHV will always contact an external server. Therefore,
// create the thread at the very start and do all the processing in the helper
// thread.
// Create Thread to process the SoHRequest and reply with SoHResponse.
hr = QShvCreateThread();
// AddRef the request and callback pointers.
pShvRequest->AddRef();
pCallback->AddRef();
return hr;
}
// Creates a thread for asynchronous handling of the Validate() call.
HRESULT CSampleShv::QShvCreateThread()
{
HRESULT hr = S_OK;
threadHandle = NULL;
DWORD threadId = 0;
// Windows API to create a thread.
threadHandle = (HANDLE) CreateThread( NULL, 0, AsyncThreadHandler, (LPVOID) this,
0, &threadId );
//
// SDK Note:
//
// Here we assume the thread was created successfully and respond with status =
// E_PENDING to the SHV Host.
hr = E_PENDING;
return hr;
}
// This is the thread handler. The input parameter is the pointer to this object.
DWORD CSampleShv::AsyncThreadHandler(LPVOID lpParameter)
{
DWORD errCode = ERROR_SUCCESS;
errCode = reinterpret_cast<CSampleShv *>(lpParameter)->AsyncThreadHandlerMain();
return errCode;
}
// The thread handler calls this method that has access to member variables.
DWORD __stdcall CSampleShv::AsyncThreadHandlerMain()
{
DWORD errCode = ERROR_SUCCESS;
HRESULT hr = S_OK;
hr = QShvRespondSHVHost();
CloseHandle(threadHandle);
errCode = HRESULT_CODE(hr);
return errCode;
}
// Handles processing of incoming SoH Request and generating SoH Response.
HRESULT CSampleShv::QShvRespondSHVHost()
{
HRESULT hr = S_OK;
hr = HandleRequestSoH(m_pShvRequest);
if (FAILED(hr))
{
//
// SDK Note:
//
// If errors occur here, do not terminate this method -- the SHV should
// still generate an SoH response.
}
hr = HandleResponseSoH(hr, m_pShvRequest);
// SoH Response is now set. Calling OnComplete() notifies setting of SoHResponse.
hr = m_callback->OnComplete(m_pShvRequest, hr);
// Release the request and callback pointers.
m_pShvRequest->Release();
m_callback->Release();
return hr;
}
// Perform all handling of inbound SoH requests from clients.
HRESULT CSampleShv::HandleRequestSoH(INapSystemHealthValidationRequest* pShvRequest) throw()
{
HRESULT hr = S_OK;
SoH *pSohRequest = NULL;
INapSoHProcessor *pSohProcessor = NULL;
SystemHealthEntityId systemHealthId = 0;
BOOL napAgentGenerated = FALSE;
// Obtain the client's SoH data from the SHV Host.
hr = pShvRequest->GetSoHRequest(&pSohRequest, &napAgentGenerated);
// Wrap it inside an INapSoHProcessor object.
hr = CreateInputSoHProcessor(pSohProcessor, systemHealthId, SOH_REQUEST, pSohRequest);
// Verify whether the client's SoH request data is considered "healthy".
hr = CheckRequestSoHHealth(systemHealthId, pSohProcessor);
// Release the SoH handler object.
ReleaseObject(pSohProcessor);
// Free the temporary SoH struct.
FreeSoH(pSohRequest);
return hr;
}
// Verify whether the client's SoH data is considered healthy.
HRESULT CSampleShv::CheckRequestSoHHealth( SystemHealthEntityId systemHealthId,
INapSoHProcessor *pSohRequest) throw()
{
HRESULT hr = S_OK;
//
// SDK Note:
//
// Each vendor should update this method & its helper functions, based upon their
// own business logic.
// Sanity check -- if no SoH data was passed in, leave client data unset.
if (! pSohRequest)
{
//
// SDK Note:
//
// - If this SHV is acting as an intrusion detection system, it
// should use its specific business logic to determine whether
// the client is trusted or malicious, and should create an
// SoH Response containing the appropriate error code to
// convey the result to the SHV Host.
// - All other SHVs should return NAP_E_MISSING_SOH.
hr = NAP_E_MISSING_SOH;
goto Cleanup;
}
//
// SDK Note:
//
// Check for the existence and values for each attribute that are expected
// from the client and determine if the client is healthy or needs to be
// quarantined.
Cleanup:
return hr;
}
// Perform all handling of outbound SoH responses sent back to clients.
HRESULT CSampleShv::HandleResponseSoH(HRESULT validationResult,
INapSystemHealthValidationRequest* pShvRequest) throw()
{
HRESULT hr = S_OK;
INapSoHConstructor *pSohConstructor = NULL;
SoH *pSohResponse = NULL;
// Create an empty SoH response.
hr = CreateOutputSoHConstructor(pSohConstructor, QuarSampleSystemHealthId, SOH_RESPONSE);
// Populate the SoH response based on the client's health state.
hr = FillResponseSoH(validationResult, pSohConstructor);
// Get portable SoH interface.
hr = pSohConstructor->GetSoH(&pSohResponse);
if (! pSohResponse){
hr = E_POINTER;
}
// Pass the SoH response along to the SHV Host where it is saved.
hr = pShvRequest->SetSoHResponse(pSohResponse);
// Release the SoH handler object.
ReleaseObject(pSohConstructor);
// Free the temporary SoH struct.
FreeSoH(pSohResponse);
return hr;
}
// Fill the specified response SoH object, given the current client's health state.
HRESULT CSampleShv::FillResponseSoH(HRESULT validationResult,
INapSoHConstructor* &pSohResponse) throw()
{
HRESULT hr = S_OK;
SoHAttributeValue value = {0};
//
// SDK Note:
//
// Append the manditory attribute: Compliance Result Codes. If SHV was not able to
// contact the external server (due to network failure, the is server down, etc...),
// then the SHV should return the failure category attribute instead of the
// compliance result with FailureCategory = failureCategoryServerCommunication.
// Here we assume there is no such failure.
value.codesVal.count = 1;
value.codesVal.results = &validationResult;
hr = pSohResponse->AppendAttribute(sohAttributeTypeComplianceResultCodes, &value);
ZeroMemory(&value, sizeof(value));
//
// Append any optional attributes.
//
return hr;
}