Ever wanted to Host-Based Configure your AMT system using Java? Now you can

Often I’m asked "Can the Intel® WS-Management Java Client Library be used to Host-Based Configure an AMT system?" The answer to that question is yes. Of course that answer is usually followed by "can you show me?". So in this article I will demonstrate how you can perform a Host-Based setup from Java. Setting up an AMT system requires sending at least one (possibly more) WsMan commands. This can be accomplish in pure Java over TCP/IP with no problems. However, depending on the method of activation being used, some non-Java code or process will likley be needed to establish security with the AMT driver. Once initial security has been established with the AMT driver then all the setup logic can be done purely in Java over TCP/IP from then on out.

There are basically two ways to programmatically active AMT. One way is activating from the host operating system of the AMT client (Host based Configuration). Another way is activating remotely from a separate machine (Remote Configuration). Both can be done with our Java client and in this article I’ll focus on the simplest method which is Host based. I’ll post another blog showing the remote method.

It should be noted that the Host based method is available starting with AMT 6.2/7.0 and above. So if you try this approach on older systems it won’t work. However, the Remote Configuration method I'll blog about later is avaiable on all AMT systems.

What’s needed for Host base configuration? Well first you will need a machine that supports AMT version 6.2 or 7.0 and above. Second, you will need the AMT Drivers installed. With the drivers installed you can setup AMT from a Java client over TCP/IP. However, as stated previously, the security is not going to make it quite that easy. Basically, you can’t send any of the Wsman commands to activate AMT unless you know the initial setup password. What is the setup password? Well if I provided it here in the blog then it would not be very secure would it :)? For security, AMT generates a random setup password on each boot. So how do we obtain this randomly generated password for setting up an AMT system? This is where we need some kind of process to issue a driver command and get it. Because it’s a driver command you will also need to be "running as administrator" with elevated privileges. These are the same privileges as any installer program would need to configure the system.

Now Let’s talk about the sample. In principle, the sample is just invoking the IPS_HostBasedSetupService.Setup() method. However, as we will see, the code appears a bit more complicated than that largely due to some of the security involved.

First, the sample needs to get the setup credentials from the AMT driver. Remember to use "Run administrator" on your Java command line or IDE so this code will have permissions. This is done via the MeDevice() class (requires JNI call to fetch the setup password from the AMT Driver).

Next the sample will define a new administration password for AMT. This password needs to be MD5 hashed with the user name, AMT digest realm, then converted to an octet string. There is some messy code to do this but it’s all pretty standard.

Finally, with newly hashed AMT password in hand and we can Invoke IPS_HostSetupService.Setup() and get our AMT machine activated!

You can download and run the sample here.

Below you can take a look at the code from the sample as see what is involved for a host setup from Java.

import java.security.*;
import intel.management.wsman.*;
import intel.management.mei.*;
/**
 *
 * @author Intel
 */
public class Main {
    /**
     * @param args the command line arguments
     */
    public static void main(String[] args) {
        //MeDevice uses IntelAmtJNI.DLL to get the Http/Digest creds
        MeDevice me = new intel.management.mei.MeDevice();
        WsmanConnection connection = me.GetLocalConnection();
        //We need to set the new Admin Password to activate AMT
        //In order hash the Admin Password we need the Digest realm
        String amtUser="admin";
        String amtPassword = "P@ssw0rd"; //new AMT password
        String amtRealm;
        try {
            //The DigestRealm is use to generate a password Hash
            //Using JavaLib to get AMT_GeneralSettings.DigestRealm
            ManagedReference ref = connection.newReference("AMT_GeneralSettings");
            ManagedInstance inst = ref.get();
            amtRealm=inst.getProperty("DigestRealm").toString();
            String hashString = amtUser+":"+amtRealm+":"+amtPassword;
            //using java.security.MessageDigests to hash the password
            MessageDigest md=MessageDigest.getInstance("MD5");
            byte[] mdData=md.digest(hashString.getBytes());
            // the MD5 hash needs to be converted to an Octet String
            StringBuilder octBuilder = new StringBuilder();
            for (int i=0;i<mdData.length;i++) {
                int temp = 0xFF & mdData[i];
                String h = Integer.toHexString(temp);
                if (h.length()<2) octBuilder.append("0");
                octBuilder.append(h.toUpperCase());
            }
            //now invoke IPS_HostBasedSetupService.Setup(amtPassword)
            ref = connection.newReference("IPS_HostBasedSetupService");
            inst = ref.get();
            ManagedInstance input = ref.createMethodInput("Setup");
            input.setProperty("NetAdminPassEncryptionType", "2");//2=HTTP-MD5
            input.setProperty("NetworkAdminPassword", octBuilder.toString());
            ManagedInstance output = ref.invoke(input);
            // the output ReturnValue should be zero on success
            System.out.println(WsmanUtils.getXML(output));
            if (output.getProperty("ReturnValue").toString().equals("0")) {
                System.out.println("Setup worked!");
            }
        } catch (WsmanException wsmanException) {
            System.out.println(WsmanUtils.getXML(wsmanException));
            throw new RuntimeException(wsmanException.fillInStackTrace());
        } catch (java.security.NoSuchAlgorithmException nsaException) {
            System.out.println(nsaException.toString());
        }
    } //end main() function
} // end class Main

Share your comments on this article and engage with other developers