IntelECSClientLibrary 1.3.2

Intel® Endpoint Cloud Services Library Usage

Notices

Intel Confidential

Legal Notices and Disclaimers

All information provided here is subject to change without notice. Contact your Intel representative to obtain the latest Intel product specifications and roadmaps. Intel technologies’ features and benefits depend on system configuration and may require enabled hardware, software or service activation. Performance varies depending on system configuration. No computer system can be absolutely secure. Check with your system manufacturer or retailer or learn more at intel.com. No license (express or implied, by estoppel or otherwise) to any intellectual property rights is granted by this document. The products described may contain design defects or errors known as errata which may cause the product to deviate from published specifications. Current characterized errata are available on request. Intel disclaims all express and implied warranties, including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, as well as any warranty arising from course of performance, course of dealing, or usage in trade. Intel, the Intel logo, Intel Unite, Intel vPro, and Intel Core are trademarks of Intel Corporation in the United States and/or other countries. *Other names and brands may be claimed as the property of others © Intel Corporation.

About

This library is a .NET Standard class library that provides common cloud service APIs for Intel® Endpoint Cloud Service. This library can be integrated into a software agent and allows the execution of Intel® Endpoint Cloud Service modules.

Prerequisites and Known Issues

To ensure smooth operation, please note the following requirements and known compatibility issues:

Permissions

The agent application must be run with elevated (administrator) privileges.

Platform Configuration

Set the platform target for the agent solution to x64.

Required Dependencies

Install the Visual C++ Redistributable for Visual Studio 2015 on the endpoint to support required libraries.

Known Issue: Memory Corruption Exception

In cases where an older version of the Visual C++ Redistributable is installed, the agent may encounter a memory corruption issue. This can result in a crash due to a System.AccessViolationException, which is indicative of corrupt memory access.

• .NET Framework Apps: The library will typically handle this error gracefully, exiting without crashing the application.
• .NET Core Apps: In .NET Core, the library may not catch the exception effectively, leading to application failure.

Potential Solution:

Consumers of the library may try setting the environment variable COMPlus_legacyCorruptedStateExceptionsPolicy to 1, which might help the app avoid crashing in the event of corrupted memory.

Error Message

If this issue occurs, you may see the following error message in your logs:

Default buffer length: 100000
Fatal error. System.AccessViolationException: Attempted to read or write protected memory. This is often an indication that other memory is corrupt.

Ensuring that the correct version of the Visual C++ Redistributable is installed should help prevent this issue.

Installation

Client

1. Add nuget the IntelECSClientLibrary package from nuget.org to your project.

Modules

The Intel® Device Health and Chip to Cloud modules have been conveniently bundled within the primary NuGet package. Upon integrating this package into your main project, these modules will be seamlessly linked and copied into the project directory during the build process.

Below is an illustrative example of the expected output directory structure.

Chip to Cloud

. targetdir
├─ Modules                                       
│  └─ c2c
│     ├─ Intel.C2C.Client.Module.dll
│     └─ rpc.dll

Intel® Device Collector

. targetdir
├─ Modules                                       
│  └─ collector
│     ├─ Intel.Ccs.Collector.dll

The Intel® Device Health module requires some assemblies to be co-located with the agent's main executable.

. targetdir
├─ ...
├─ applicationprovider.dll
├─ CCHWAPIExt.sys
├─ collector.dll
├─ AmtProvider.dll
├─ cpuprovider.dll
├─ csmeprovider.dll
├─ driverprovider.dll
├─ diskdriveprovider.dll
├─ Intel.Ccs.ClientCollector.dll
├─ firmwareversionprovider.dll
├─ LibCSMEInterface.dll
├─ osprovider.dll
├─ serviceprovider.dll
├─ systeminfoprovider.dll
├─ ...
└─ agent.exe

How to use it

Create an instance of the client.

var client = ClientFactory.Create();

Optionally, a logger instance can be used.

class CustomLogger : ILogger
{
  public void LogMessage(...); // Method body omitted on purpose for simplicity
  public void LogException(...); // Method body omitted on purpose for simplicity
}

var logger = new CustomLogger();
var client = ClientFactory.Create(logger); // This instance will use LogLevel.information as default value

Optionally, a logger instance with a specific LogLevel

class CustomLogger : ILogger
{
  public void LogMessage(...); // Method body omitted on purpose for simplicity
  public void LogException(...); // Method body omitted on purpose for simplicity
}

var logger = new CustomLogger();
// This instance will modify the log level for the modules
var client = ClientFactory.Create(logger, (clientOptions) => {
    clientOptions.LogLevel = LogLevel.Debug;
});

Optionally, a logger instance with a specific LogLevel and proxy configuration

class CustomLogger : ILogger
{
  public void LogMessage(...); // Method body omitted on purpose for simplicity
  public void LogException(...); // Method body omitted on purpose for simplicity
}

var logger = new CustomLogger();
// This instance will modify the log level for the modules and configure the proxy
var client = ClientFactory.Create(logger, (clientOptions) => {
    clientOptions.LogLevel = LogLevel.Debug;
    clientOptions.UseProxy = true;
    clientOptions.Proxy = new WebProxy("Proxy_url") // Configure the webProxy object as needed
});

Provisioning

The first time the client library is used on the device, a provisioning call should be performed. The credential information is obtained when the device is created in the registry service.

var args = new ProvisioningParameters
{
    ClientId = "", // The clientId of the credential for the current device
    UserName = "", // The username of the credential for the current device
    Password = "", // The password of the credential for the current device
    DeviceId = "", // The id of the current device
    ApiUrl   = ""  // The cloud services endpoint: Default: https://endpointcloudservices.intel.com
};
await client.ProvisionAsync(args);

Subsequent calls will override the previous information.

Executing modules

The client library executes all modules in the Modules directory.

// Option 1: Execute all modules
await client.ExecuteAsync();

// Option 2: Execute all modules and pass some properties to some of them
var moduleProperties = new ModuleExecutionProperties
{
    { "amt_password", "password_value" },
    { "json_sample", "{{ \"key\": \"value\" }}" }
};
//The executeParameter allow 
var executeParameters = new ExecuteParameters
{
    // There are two ways to pass properties to the modules by module id or module name 
    { Guid.Parse("09DEF649-E133-4E97-A2A5-B40C208913A0"), moduleProperties },
    { "SampleModule", moduleProperties },
};

ExecutionResult results = await client.ExecuteAsync(executeParameters);
foreach (var moduleResult in results.ModuleExecutionResults)
{
    Console.WriteLine($"Result: {moduleResult.Success}. Module Id: {moduleResult.ModuleId}. Details: {moduleResult.ResultDetails}");
}

Forcing module execution

For non-scheduled executions, the ForceExecuteAsync can be used. A list of the modules to be executed must be passed.

// Option 1: Execute only the modules provided
var modules = client.GetModules();
var modulesToBeExecuted = new List<IModuleInfo>();
await client.ForceExecuteAsync(modulesToBeExecuted);

// Option 2: Execute only the modules provided and pass properties to them
var moduleProperties = new ModuleExecutionProperties
{
    { "amt_password", "password_value" },
    { "json_sample", "{{ \"key\": \"value\" }}" }
};

var forceExecuteParameters = new ForceExecuteParameters
{
    // There are two ways to pass properties to the modules by module id or module name 
    { Guid.Parse("09DEF649-E133-4E97-A2A5-B40C208913A0"), moduleProperties },
    { "SampleModule", moduleProperties },
};

ExecutionResult results = await client.ForceExecuteAsync(forceExecuteParameters);

foreach (var moduleResult in results.ModuleExecutionResults)
{
    Console.WriteLine($"Result: {moduleResult.Success}. Module Id: {moduleResult.ModuleId}. Details: {moduleResult.ResultDetails}");
}

Unprovisioning

In the case of uninstalling the agent, an unprovisioning call should be performed

await client.UnprovisionAsync();

This will delete all cached data used by the client from the device

Client Discovery

About

Client Discovery is a newly added feature within the ECS Client Library, designed to allow the retrieval of raw discovery data, such as AMT, without requiring ECS registration or credentials.

Usage

using Intel.Ccs.Client.Discovery;

// Create an instance to use as logger
var logger = new CustomLogger();
// Get an instance of IClientDiscovery by using ClientDiscoveryFactory
IClientDiscovery discoveryClient = ClientDiscoveryFactory.CreateClient(logger, discoveryOptions =>
{
    discoveryOptions.LogLevel = LogLevel.Information;
});

// Option 1: Call GetAsync() method to receive an instance of ClientDiscoveryResult. Optionally, pass a cancellation token.
var result = discoveryClient.GetAsync();

// Option 2: Call GetJsonAsync() method to receive the JSON representation of ClientDiscoveryResult. Optionally, pass a cancellation token.
string discoveryJson = discoveryClient.GetJsonAsync();

if (result.Success)
{
  Console.WriteLine($"AMTEnabled: {result.Data.Amt.AmtEnabled}");
  Console.WriteLine($"FullManageability: {result.Data.Amt.FullManageability}");
  Console.WriteLine($"StdManageability: {result.Data.Amt.StdManageability}");
  Console.WriteLine($"KvmSupported: {result.Data.Amt.KvmSupported}");
}

public class ClientDiscoveryResult
{
    public bool Success { get; }
    public Discovery Data { get; }
}

public class Discovery
{
    public AmtResult Amt { get; }
}

public class AmtResult
{
    public bool AmtEnabled { get; }
    public bool FullManageability { get; }
    public bool StdManageability { get; }
    public bool KvmSupported { get; }
}

Troubleshooting

Module execution in .NetCore

When working with .NET Core, there is an additional step required to execute Intel® Device Health module. After you have successfully built your project, follow these instructions:

• Navigate to your project's build folder.
• Search for a file named < project Name >.runtimeconfig.json.
• Inside this JSON file, you'll need to add the following configuration properties within the runtimeOptions section:

{
  "runtimeOptions": {
    // other options
    "configProperties": {
      "System.Reflection.Metadata.MetadataUpdater.IsSupported": false,
      "Microsoft.NETCore.DotNetHostPolicy.SetAppPaths": true
    }
  }
}

This configuration step is essential to ensure the proper execution of your module in the .NET Core environment.