Copyright (C) 2007 Intel Corporation

Intel(R) Active Management Technology (Intel AMT):
A short description of the SDK's WS-Management C# samples for developers.

Introduction:
-------------
Intel AMT SDK WS-Management C# Samples implement different usages of AMT 
features. Samples use Intel.Wsman.Scripting dll as infrastructure. Its source 
code can be found in the WsmanLib module. Intel AMT SDK WS-Management Samples 
directory includes the following sample applications; see readme file provided 
with each sample for additional information.

Note:   To ensure that security is maintained, the samples should be run from 
        a directory that can be accessed only by the Administrator user. This is 
        to prevent unauthorized manipulation of files in the directory.

AgentPresence:
A C# sample application that demonstrates the use of the Remote Agent
Presence interfaces.

AlarmClock:
A C# sample application that demonstrates the use of the Alarm Clock
interface.

GeneralInfo:
A C# sample that demonstrates reading Intel AMT status using the GeneralInfo 
structures.

NetworkAdministration:
A C# sample application that demonstrates the use of the Network Administration
interface.

PowerPackages:
A C# sample application that demonstrates how to use various commands of the 
PowerPackage service. 

RedirectionConfig:
A C# sample application that demonstrates how to use various commands of the 
Redirection service. 

RemoteControl:
A C# sample application that demonstrates the use of the Remote Control
interface.

SecurityAdmin:
A C# sample application that demonstrates the use of the Security 
Administration interface. 

SystemDefense:
A C# sample application that demonstrates the use of the System Defense
interface.

UserConsent:
A C# sample application that demonstrates the use of the User Consent
interface.

How to Build:
-------------
In order to compile the sources:
	1) Use Visual Studio and the latest windows SDK toolkit. 
	2) Open the VS project from the Src folder\Sample. Each sample has its own 
	   VS project. 	
	3) Invoke build from the Visual Studio menu. 


Usage:
------
<Samplename> <opt> -host <Hostname> [-user <user name> -pass <password>]
			[-krb] [-tls -certname <certName> –acceptselfsignedcert]
			[-proxy <host:port> [-proxyUser <proxy user> -proxyPass
			<proxy password>]]

		<Samplename> name of executable 
 		[Option] sample options as defined for each sample
		[-verbose] printing in verbose mode
		[-host] the Intel AMT machines's host name or IP address
		[-user] the Intel AMT machine's username  
		[-pass] the Intel AMT machine's password
		[-tls] in order to work over TLS
		[-krb] in order to work via kerberos authentication
		[-certname] specifies the client certificate's Common Name
		[-acceptselfsignedcert] is used to accept self signed certificate.
				If set, in case that the certificate is self-signed, the sample
				application will ignore certificate errors
		[-proxy] the proxy server IP address or host name 
		[-proxyUser] proxy username (if it was defined)
		[-proxyPass] proxy password (if it was defined)


		Notes:
		1. If -user <username> -pass <password> are defined the Digest
		   authentication scheme is used, if -krb is used the Kerberos 
		   authentication scheme will be attempted.
		   If specified, the kerberos user should be given in domain\name format
		2. If -certname option is defined, <certname> specifies the client
		   certificate's Common Name (CN). If this option is not specified, the
		   sample application will search the certificate store for a client
		   certificate matching Intel AMT requirements. The first such 
		   certificate found will be used for authentication.
		3. The –acceptselfsignedcert option is used to accept self signed
		   certificate. If set, in case the certificate is self-signed, the
		   sample application will ignore any certificate errors.
		4. If -proxy option defined the connection with Intel AMT will be 
		   through the proxy server.  
		   If the proxy server username and password were defined the options 
		   <proxyUserName> and <proxyPassword> should be defined.


	Examples: how to run samples from the command line:

		1. Using username and password
			<sample path> -host 10.0.0.1 -user AMTusername -pass AMTpassword 
		
		2. Kerberos 
			<sample path> -host 10.0.0.1 -krb
		
		3. TLS mode mutual authentication
			<sample path> -host desktop.demo.intel.com -certname 
			management_console.intel.com -user AMTusername -pass AMTpassword

		4. TLS mode server authentication
			<sample path> -host desktop.demo.intel.com -tls -user AMTusername 
				      -pass AMTpassword
		
		5. Using proxy 
			<sample path> -host 10.0.0.1 -user AMTusername -pass AMTpassword
			       -proxy 10.0.0.1:9090 -proxyUser proxyusername
			       -proxyPass proxyPassword

Adittional information:
-----------------------
The C# samples use Intel.Wsman.Scripting dll. For the WS-Man client, the samples
use one of two clients: a native C# WS-Management client (DotNetWSManClient) or 
WinRM (WinRMWSManClient). If the WinRM client is used, please see the 
WinRMWSManClient Readme for prerequisites. Both clients and the framework are 
packaged in dll's that should be referenced by the samples. For more information
on changing to the winRM client see the 
SDK\Windows\Common\WS-Management\C#\WinRMWSManClient\Readme .
See the SystemDefense sample that demonstrates how to use the C# WS-Management 
client and the Cim framework.


Microsoft WinRM*:
-----------------
For the samples to work, make sure that WinRM has been activated and that a 
WinRM listener is working.
Be sure you have proper permissions to run the following commands (try running
from an administrator account).
Use the following steps to perform initial configuration of WinRM:
1. Type the following line in the command window:
	winrm quickconfig
	(The command questions whether you really want to enable 
	  Windows Remote Management:
	   "WinRM is not set up to allow remote access to this machine 
		for management.
		The following changes must be made: Create a WinRM 
		listener on HTTP://* to accept WS-Man requests to any IP
		on this machine"
	  press 'y' to continue)

To see the configuration type:
winrm get winrm/config

To see the list of Listeners:
winrm enumerate winrm/config/Listener

2. UnEncryption:
To set UnEncryption, either use the GPO GUI or the command line.

To use the Group Policy GUI, enter the following on the command line: gpedit.msc
Select Computer Configuration -> Administrative Templates ->
       -> Windows Components -> Windows Remote Management
and update the following:
WinRM client: Allow Basic Authentication: Enabled
	      Allow unencrypted traffic: Enabled

These and other changes can also be done in the command line.
For example if you want to set the "Allow Unencrypted" to "true" then type:
winrm set winrm/config/client @{AllowUnencrypted="true"}

3. Address: enter the target IP (Intel AMT device IP) to the trusted hosts type:
   winrm set winrm/config/client @{TrustedHosts="IP"}
   (Where 'IP' is the IP address of the Intel AMT device)
   (When running a WS-Management sample, set the -host parameter to the same
   value of the WinRM TrustedHost parameter; a hostname cannot substitute the
   IP address if an IP address has been supplied to WinRM, and vice versa.)

4. To configure MPS as the proxy, follow the instructions on configuring a proxy
   for WinRM at:
   http://msdn2.microsoft.com/en-us/library/aa384372(VS.85).aspx

5. The default encoding of WinRM is UTF-16, however, Intel AMT works only with 
   UTF-8. To do so it is required to add "-encoding:utf-8" option.

6. Example of winRM command:
   winrm identify -remote:10.10.10.20:16992/wsman -u:admin -p:Admin!23 -a:Digest
   -encoding:utf-8


To use WinRM with Kerberos follow the steps:
--------------------------------------------
1. Set the authentication to Kerberos:
   WinRM service: winrm set winrm/config/service/auth @{Kerberos="true"}
   WinRM client: winrm set winrm/config/client/auth @{Kerberos="true"}
	
2. Port:
   -SPNPort Specifies a port number to append to the Service Principal Name 
   (SPN) of the remote service. The utility uses the SPN for authentication 
   purposes when using Negotiate or Kerberos authentication. 

   Use -SPNPort flag when execute command via WinRM.

3. UnEncryption:
   Use -unencrypted flag when executing the command via WinRM.

4. Example of winRM command:
   winrm enumerate 
		 http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ComputerSystem 
         -r:http://10.10.10.20:16992/wsman -u:admin -p:Admin!98 -encoding:utf-8 
         -a:Kerberos -SPNPort -unencrypted 
		 
For more help on this issue type WinRM -? on the command line.

-------------------------------------------------------------------
 * Other names and brands may be claimed as the property of others.