mirror of https://github.com/UMSKT/xpmgr.git
241 lines
8.1 KiB
Plaintext
241 lines
8.1 KiB
Plaintext
////////////////////////////////////////////////////////////
|
|
//
|
|
// Copyright (c) Microsoft Corporation.
|
|
//
|
|
// SYNOPSIS
|
|
//
|
|
// IDL source for interaction with System health
|
|
// validators.
|
|
//
|
|
////////////////////////////////////////////////////////////
|
|
|
|
#ifndef NAPSYSTEMHEALTHVALIDATOR_IDL
|
|
#define NAPSYSTEMHEALTHVALIDATOR_IDL
|
|
|
|
import "NapTypes.idl";
|
|
import "unknwn.idl";
|
|
|
|
interface INapServerCallback;
|
|
interface INapSystemHealthValidationRequest;
|
|
|
|
|
|
// System health validators must implement the following
|
|
// interface so that the NAP system can communicate
|
|
// with it. SHVs must populate registry with registration
|
|
// information, so that the NAP system can
|
|
// instantiate it.
|
|
//
|
|
[object,
|
|
uuid(EF43D87C-5B6D-4820-8620-868907FE07D3),
|
|
async_uuid(2516031A-A391-454d-B53D-C5DC84C7F2DB),
|
|
pointer_default(unique)]
|
|
interface INapSystemHealthValidator : IUnknown
|
|
{
|
|
// The NAP system calls this API to validate the
|
|
// SoHRequest received from a client.
|
|
//
|
|
// In order to support intrusion detection, SHVs will be
|
|
// asked to validate the client machine irrespective of
|
|
// whether or not the client sent an SoHRequest destined
|
|
// for the SHV.
|
|
//
|
|
// The validator must do the following:
|
|
//
|
|
// 1). Retrieve the SoHRequest from the 'request' object.
|
|
//
|
|
// 2). If the SoHRequest packet is null, then
|
|
// a). If the SHV is an intrusion detection system,
|
|
// then populate an SoH-Response packet with the
|
|
// appropriate error code as to why the client
|
|
// machine is malicious.
|
|
// b). All other SHVs should populate an SoHResponse
|
|
// packet with an error code of
|
|
// NAP_E_MISSING_SOH.
|
|
//
|
|
// 3). If the napAgentGenerated value is TRUE, the SHV
|
|
// should expect an SoH packet with the following
|
|
// 3 TLVs :
|
|
// napAttributeTypeSystemHealthId,
|
|
// napAttributeTypeFailureCategory,
|
|
// napAttributeTypeErrorCodes
|
|
// This SoHRequest is generated by the NapAgent on
|
|
// behalf of the SHA since there was an error in
|
|
// retrieving a request packet from the SHA.
|
|
//
|
|
// 4). Validate the format of the SoH-Request packet.
|
|
// If the SoHRequest is malformed, then construct
|
|
// an SoHResponse packet with error code
|
|
// NAP_E_INVALID_PACKET.
|
|
//
|
|
// 5). Validate the SoHRequest packet.
|
|
// a). 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 'request' object
|
|
// and return S_OK.
|
|
// b). If the SHV is doing I/O 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. Otherwise, the SHV's response
|
|
// will be dropped.
|
|
//
|
|
// 6). If any other error code is returned by the SHV
|
|
// (eg. some system error), then the packet will be
|
|
// discarded.
|
|
//
|
|
// Parameters:-
|
|
// request: pointer to the validation request object.
|
|
// hintTimeOutInMsec: the SHV should respond within this
|
|
// timeout; otherwise, the response is dropped.
|
|
// callback: pointer to the callback object.
|
|
//
|
|
// Return values:-
|
|
// S_OK: indicates that the validator has set a
|
|
// SoHResponse on the 'request' object.
|
|
// E_PENDING: indicates that OnComplete() will be called
|
|
// on a separate thread.
|
|
// RPC_S_SERVER_UNAVAILABLE: indicates that the SHV
|
|
// process terminated without the NapServer actually
|
|
// releasing a reference to it.
|
|
// The NapServer will try to re-create a new
|
|
// reference to the SHV and if re-execute the
|
|
// Validate call just once.
|
|
// If the creation of the object or the re-excuted
|
|
// Validate fails, the SHV is removed from the
|
|
// list of loaded SHVs. The only way this SHV can
|
|
// now be reloaded is to unregister and reregister
|
|
// the SHV again, or when the NapServer restarts
|
|
// <any other error code>: if any other error code is
|
|
// returned, then the system assumes
|
|
// serverComponent failure has occured, and the
|
|
// appropriate mapping is done to pass/fail.
|
|
//
|
|
// The SHV must not hold references to the request object
|
|
// or the 'callback' object once the async call completes
|
|
//
|
|
//
|
|
// Failure-Category:
|
|
// An SHV can return either one of two TLVs in its
|
|
// SoH-Response:
|
|
// 1). Compliance-Result-Code TLV: If the SHV could
|
|
// validate the health of the client (i.e. healthy
|
|
// or unhealthy), then this TLV is returned.
|
|
// 2). Failure-Category TLV: If there was any component
|
|
// or communication failure either on the client
|
|
// or server, then that must be indicated in this
|
|
// TLV. This TLV will further be mapped to healthy
|
|
// or unhealthy using the SHV's config. For more
|
|
// details, see the INapServerManagement interface.
|
|
//
|
|
HRESULT
|
|
Validate(
|
|
[in] INapSystemHealthValidationRequest* request,
|
|
[in] UINT32 hintTimeOutInMsec,
|
|
[in] INapServerCallback* callback
|
|
);
|
|
};
|
|
|
|
|
|
// System health validators use this interface to talk to
|
|
// the NAP system
|
|
//
|
|
[object,
|
|
uuid(09C20568-F30C-489b-AE9C-4930AD7F165F),
|
|
pointer_default(unique)]
|
|
interface INapServerCallback : IUnknown
|
|
{
|
|
// SHVs use this API to signal async request completion.
|
|
//
|
|
// Parameters:-
|
|
// errorCode: indicates the reason why the validation
|
|
// could not be performed. Validators must indicate
|
|
// S_OK if SoHRequest validation could be completed
|
|
// (whether or not the SoHRequest passed the
|
|
// health check).
|
|
//
|
|
HRESULT
|
|
OnComplete(
|
|
[in] INapSystemHealthValidationRequest* request,
|
|
[in] HRESULT errorCode
|
|
);
|
|
};
|
|
|
|
|
|
[object,
|
|
uuid(ADACB3A0-D4F4-4f17-8933-51D60FCCA606),
|
|
pointer_default(unique)]
|
|
interface INapSystemHealthValidationRequest : IUnknown
|
|
{
|
|
// Validators must log this information
|
|
//
|
|
HRESULT
|
|
GetCorrelationId([out] CorrelationId* correlationId) const;
|
|
|
|
// Validators must log this information.
|
|
//
|
|
HRESULT
|
|
GetStringCorrelationId(
|
|
[out] StringCorrelationId** correlationId
|
|
) const;
|
|
|
|
// Validators must log this information.
|
|
//
|
|
HRESULT
|
|
GetMachineName([out] CountedString** machineName) const;
|
|
|
|
// Validators retrieve the SoHRequest information sent by
|
|
// their agent counterpart on the client-side using the
|
|
// following function. This may return null if the client
|
|
// didn't send an SoHRequest destined for the validator.
|
|
//
|
|
// Parameters:-
|
|
// napAgentGenerated: the SoH was created by the
|
|
// NapAgent on behalf of the SHA. Primarily used to
|
|
// indicate an SHA failure to the SHV. The format of
|
|
// the SoH is as follows:
|
|
// System-Health-Id = <id>
|
|
// Failure-Category = clientComponentFailure
|
|
// Error-Codes = <sha-failure-error-code>
|
|
//
|
|
HRESULT
|
|
GetSoHRequest(
|
|
[out] SoHRequest** sohRequest,
|
|
[out] BOOL* napSystemGenerated
|
|
) const;
|
|
|
|
// Validators set the SoHResponse to be sent to their
|
|
// agent counterpart on the client-side using the
|
|
// following function.
|
|
//
|
|
HRESULT
|
|
SetSoHResponse([in] const SoHResponse* sohResponse);
|
|
HRESULT
|
|
GetSoHResponse([out] SoHResponse** sohResponse) const;
|
|
|
|
// NapServer stores some state information here.
|
|
//
|
|
// Parameters:-
|
|
// privateData: blob that only the NapServer can interpret
|
|
//
|
|
HRESULT
|
|
SetPrivateData([in] const PrivateData* privateData);
|
|
HRESULT
|
|
GetPrivateData([out] PrivateData** privateData) const;
|
|
};
|
|
|
|
[object,
|
|
uuid(91A5D706-0CB4-4a84-8315-9380D453E385),
|
|
pointer_default(unique)]
|
|
interface INapSystemHealthValidationRequest2 : INapSystemHealthValidationRequest
|
|
{
|
|
HRESULT
|
|
GetConfigID([out] UINT32* configID) const;
|
|
};
|
|
|
|
|
|
#endif // NAPSYSTEMHEALTHVALIDATOR_IDL
|
|
|