Copyright (C) 2003 Intel Corporation Intel(R) Active Management Technology (Intel(R) AMT): A short description of the USBFile tool USBfile tool description: ------------------------- USBfile is a command line tool used to create an Intel(R) AMT USB file. The tool allows the user to create two types of USB key files for the purpose of preparing an AMT machine for provisioning using a USB device. For PSK provisioning, the tool allows to automatically generate PSK pairs. For testing PKI provisioning, the tool can be used to create a single (non- consumable) PKI record file. Notes: a) To ensure that security is maintained, the application 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. b) In order to calculate sha256 and sha384 hashes, the tool uses the OpenSSL* dll file: libcrypto.dll, win32: * The user should download OpenSSL, locate the relevant dlls and place it in the same folder as the USBFile application. * The Dll name must be libcrypto.dll. The user may need to rename the dll. * libcrypto.dll depends on vcruntime140.dll, which is a part of the Microsoft* C Runtime Library application extension. This dll is located in the System32 folder and is a part of the Microsoft* Visual Studio installation package. If you you do not have it on your system, you may need to download it. Usage: ------ *** Intel(R) AMT USB file writer and viewer sample v4.0*** syntax: To view the valid records of a USB file: USBfile -view To view a summary of a USB file: USBfile -summary To create a USB file: USBfile -create Optional/Additional parameters for creating a file: * General parameters: -v 1|2|2.1|3|4: the setup file version, 4 by default. -v1file : creates an additional version 1 setup file. * Version 1 parameters: -amt: this will set the manageability selection value to AMT. -pid -pps : a psk pair. -rpsk : this will generate a random psk pair. Note: this parameter was removed in AMT Version 11.0. -nrec : create the requested number of records. -gen : create the requested number of records and generate a random psk pair for each one of the records, Note: this option is deprecated, use -nrec and -rpsk options to generate multiple records with random psk pair. -xml : if psk configuration is chosen the PSK records that are created will be dumped to the given file. * Version 2 parameters: -consume 0|1: generate inconsumable record or consumable record(s). 0 (inconsumable) by default. -dns : sets the PKI dns suffix name (up to length 255). -fqdn : string up to length 255. -ztc 0|1: disable/enable PKI Configuration. -oHash 0|1 disable/enable all preinstalled certs. -uHash 0|1|2 disable/enable all user defined certs/delete all. -hash [sha1|sha256|sha384]: to compute and add the hash of the given root certificate file according to the given hash algorithm. Up to three certificates hashes may be specified. Notes: 1. The hash algorithm is optional, if no hash algorithm is given, the tool uses as default sha1. 2. When certificate hash is added, all default hashes will be disabled and all existing user defined hashes will be deleted. 3. The sha256 and sha384 hash algorithms supported only in version 3(+) file format. 4. In order to calculate sha256 and sha384 hashes, the tool uses the OpenSSL* dll file: libcrypto.dll, win32: * The user should download OpenSSL, locate the relevant dlls and place it in the same folder as the USBFile application. * The Dll name must be libcrypto.dll. The user may need to rename the dll. * libcrypto.dll depends on vcruntime140.dll, which is a part of the Microsoft* C Runtime Library application extension. This dll is located in the System32 folder and is a part of the Microsoft* Visual Studio installation package. If you you do not have it on your system, you may need to download it. 5. Each hash requires this usage separately, for example: for two hashes use the following usage: -hash [sha1|sha256|sha384] -hash [sha1|sha256|sha384]. -redir : This is an integer that is calculated as follows: bit 0 : 1 (Enable) or 0 (Disable) - SOL feature bit 1 : 1 (Enable) or 0 (Disable) - IDER feature bit 2 : 1 (Enable) or 0 (Disable) - Username/password Authentication type of the SOL/IDER in the ME FW. * Version 2.1 parameters: -hostname : host name max length is 63. Note: this option is not valid when generating an inconsumable record. -domname : domain name max length is 255. -dhcp 0|1 : disable/enable DHCP. -pm 0|1: enterprise provisioning / small business(SMB), 0 (enterprise) by default. Note: this option is deprecated in version 3(+) file format -fwu 0|1|2: disable/enable/enable password protected Firmware Local Update (Password protected mode is supported starting from version 4). -fwuq 0|1|2: Always|Never|Restricted Firmware Update Qualifier (Supported in versions 2.1 - 3). -sfwu 0|1 : disable/enable Secure Firmware Update (Supported in v2.1 - v3 ). -ito <4 bytes of idle time out>: idle time out (valid values: 1-65535). Note: this setting may not be applicable under some power package definitions. -pspo provision server port number. -psadd :ip address for provision server; ipv4 example: 123.222.222.121; ipv6 example: fe80:ffff:0012::212; Note: ipv6 address supported only in version 3(+) file format. -s4p :e.g 10.0.0.1:255.255.255.0:10.0.0.2:10.0.0.3:10.0.0.4 Notes: This option is not valid when generating an inconsumable record DHCP flag must be disabled. -passPolicyFlag<0|1|2> : Default/block in post/always open. -vlan : VlanStatus disable/enable, e.g. 0-4011. Note: for non supporting VLAN platforms, MEBx ignores this setting. -pp : Set the power package, GUID length should be 16. GUID should be in network order just as it returns from the enumerate power package soap command. * Version 3 parameters: -ipv6 : XML file which holds the IPv6 configuration data -sdFqdn 1|0: shared (1)/dedicated (0) FQDN. specifies whether the domain name is shared with the host, or dedicated to ME. Note: This option is valid only if configuring the hostname as well. -dDnsUpdate 0|1: disable/enable dynamic DNS update. -kvm 0|1: disable/enable KVM. -userConsentOption 0|1|255: user consent disabled/enabled for KVM only/ enabled for all features. ('255'-enabled for all features option is supported starting from version 4). -userConsentPolicy 0|1: Configure user consent policy disabled/enabled. -prov 0|1: Stop/start configuration. Notes: 1. Sending the ME provisioning Halt/Activate value of 0, stop configuration, will cause a global reset after all the USB key settings have been applied. 2. To guaranty success of this command it is recommended to configure either -dns or -fqdn, otherwise the success depends on the DHCP state of the FW. -conf 0: automated configuration. Automatic configuration will provision the system through communication with the setup and configuration servers. -scIden: <4 bytes of support channel id.>: support channel identifier (valid values: 1-65536). -scDesc : friendly name used to describe the party represented by the support channel identifier. 60 character max. -sano : unique string identifier given to the end user by the service provider. 32 character max. -enrPass : unique string that allows access to the service to complete enrollment. 32 character max. -servType 1|2|4: Reactive/proactive/one time session. -spIden : Set the service provider identifier. GUID should be 32 hexadecimal chars in network order without spaces. For example: -spIden 0102030405060708090a0b0c0d0e0f00, represents the GUID: 04030201-0605-0807-090a-0b0c0d0e0f00 * Version 4 parameters: -scramble : Specify this flag in order to scramble the setup file records. Notes: ------ 1. In case of using an option which is not supported in the used file version, the tool will create a legal file, ignoring the not supported option. For example: in case of using the -consume option on file version 1 (using the -v option set to 1), the generated file will not include the -consume configuration. 2. In order to create a PSK file (by using the -pid and -pps, or alternatively by -rpsk), the user needs to provide the old and new MEBx passwords. The user must select the format version of the generated file, according to the version of AMT that will be provisioned. Format version 2 provides the ability to enable AMT (i.e. set the manageability mode to AMT) from the usb key (by using the �amt flag), as well as to configure the sol/ider settings (by using the -redir). However, this version is currently only supported by AMT 2.6(+). The user may optionally generate an associated XML file with the generated PSK pairs. This file may be used to import the PSK pairs to the configuration server. 3. To create a PKI file, the user needs to provide the old and new MEBx passwords and enable PKI configuration (using the -ztc flag). In addition the user may optionally set the PKI dns suffix, set the provisioning server FQDN and add user defined certificate hashes. Note that if a user adds a user defined hash, the default hashes will be disabled and the previously added user defined hashes will be deleted. Note that a PKI file is only supported by the version 2(+) file format. 4. The tool is intended to support only the two use cases described above ( PSK and PKI). There may be additional USB key record configurations that are available(according to the USB format file specifications) which are allowed or blocked by the tool, however users are advised to follow one of the two configurations described. 5. If -nrec option is not selected a single record is created. 6. If -consume option is not selected an inconsumable record is created. 7. If -pid option is selected the -pps option must come with it and vice versa. 8. If -rpsk or -gen option is selected along with -pid and -pps options, the psk pair that will be used is the one supplied using -pid and -pps. 9. Since configuration of more than 1 inconsumable records is invalid: If -nrec option is selected with more than 1 record, the -consume flag must be set to 1. 10. If -pspo option is selected the -psadd option must come with it and vice versa. 11. The BIOS requires a binary file with the name "setup.bin". 12. If a certificate hash is added, all default hashes will be disabled and all existing user defined hashes will be deleted. 13. The -pm option is deprecated in version 3(+) file format, if still trying to use it in version 3(+) file format, it will be accepted and entered into the file but a warning will be displayed to the screen. 14. Although -hash option is supported by the version 2(+) file format, the sha256 and sha384 hash algorithms (which can be configured using this option) supported only in version 3(+) file format, for version 2(+) file format up to version 3 file format (not included) the only supported hash algorithm is sha1. 15. Although -psadd option is supported by the version 2.1(+) file format, the ipv6 address for the provision server (which can be configured using this option) supported only in version 3(+) file format, for version 2.1 file the only supported address is ipv4. 16. The expected format of the xml file for the -ipv6 option is as follows: Wired True Intel 1234567890abcdef 2000::2 :: 2000::3 :: 17. On LAN-less platforms the following commands always return �Successful� and are, therefore, meaningless: -rpsk, -ztc, -pspo, -pid, -hash, -psadd, -dhcp, -prov Usage concept: -------------- 1. Use USBFile to create a USB file. Use the command line options to determine the type of file that will be created (PSK or PKI), as well as the fields that will be included (dns suffix, provisioning server fqdn...) Note: 2. If PSK records are generated, integrate the corresponding XML file (created using the -xml flag) into the Configuration Server. 3. Copy the generated file to a cleanly formatted USB storage device (FAT formatted). 4. Insert the USB storage device into an Intel AMT system. For version 1 files, AMT must be enabled. For version 2 files, AMT can be enabled using the USB device by configuring the records with the -amt flag. 5. Boot the AMT system. 6. Intel AMT reads the USB storage device, and reads the next available record. If the record is consumable, the record is marked as "used" on the USB storage device. 7. Intel AMT validates its password against the password in the record and then saves the parameters in the record. 8. Intel AMT can begin network provisioning. Examples of usage: ------------------ 1. Create a version 1.0 10-record USB file and a corresponding XML file with pseudo-randomly generated PID/PPS pairs, where all records have the same current MEBx password and new MEBx password. USBfile -create setup.bin admin Admin22@ -rpsk -v 1 -nrec 10 -xml setup.xml -consume 1 2. Create a version 2.1 10-record USB file and a corresponding version 1.0 file with pseudo-randomly generated PID/PPS pairs, where all records have the same current MEBx password and new MEBx password. USBfile -create setup.bin admin Admin22@ -rpsk -v1file setup1.bin -nrec 10 -consume 1 3. Create a single (version 2.1, inconsumable) PKI record file. Set the manageability mode, enable ZTC and Generate a hash from cert.pem. USBfile -create setup.bin admin Admin22@ -amt -ztc 1 -hash cert.pem friendlyName 4. Dump contents of USB file to the screen USBFile -view setup.bin USBTool Error: -------------- * If an invalid argument was given to one of the parameters, an error message describing the related error will be presented followed by the usage screen. * An error code will be presented to the user if an error occurs while the tool is creating or viewing the file. Possible errors: 1 - The setup file header has an illegal UUID 2 - The setup file version is unsupported 3 - A record entry that does not contain a current MEBx Password was encountered 4 - The given buffer length is invalid 5 - The header chunk count cannot contain all of the setup file header data 6 - The record chunk count cannot contain all of the setup file record data 7 - The requested index is invalid 8 - The setup file header indicates that there are no valid records (RecordsConsumed >= RecordCount) 9 - The given buffer is invalid 10 - A record entry with an invalid Module ID was encountered 11 - A record entry with an invalid record number was encountered 12 - The setup file header contains an invalid module ID list 13 - The setup file header contains an invalid byte count 14 - The setup file record id is not RECORD_IDENTIFIER_DATA_RECORD 15 - The list of data record entries is invalid 16 - The setup file is corrupted 17 - The setup record has already been used 18 - A record entry that does not contain a new MEBx password was encountered 19 - A record with an invalid manageability feature selection was found 20 - Invalid input was received 21 - A record with invalid certificate hash settings was encountered 22 - A file contains both scrambled and clear records was encountered 101 - Failed to write to the given file 102 - Failed to read from the given file 103 - Failed to create random numbers 104 - The CurrentMEBx password is invalid 105 - The NewMEBx password is invalid 106 - The PID is invalid 107 - The PPS is invalid 108 - The data record is missing a CurrentMEBx password entry 109 - The data record is missing a NewMEBx password entry 110 - The data record is missing a PID entry 111 - The data record is missing a PPS entry 112 - Invalid DnsSuffix 113 - Invalid fqdn 114 - Invalid ZTC setting 115 - Invalid sol ide redirection config 116 - Invalid Support Channel Description 117 - Invalid Service Account Number 118 - Invalid Enrollment Passcode ------------------------------------------------------------------- * Other names and brands may be claimed as the property of others.