Powershell version of the iot-adk-addonkit extends the functionality with further validation / verification steps in the imaging process.
- Powershell version of IoT-ADK-Addonkit
-
Supports Windows 10 IoT Core version 10.0.17763.1577 (11B update) onwards.
-
Support of OEM Signed drivers for retail images : The scripts are updated to support generation of appropriate sample oem certificates and sample projects updated to showcase the oem signing process.
-
Changes to functions
- New-IoTOEMCerts
- PK is a separate root key and KEK is derived from PK.
- PK / KEK key length is 4096 and uses SHA256 digest algorithm
- New KMCI certificate with the code signing eku created for signing drivers (OEM signing) and the same is used for signing drivers and the cab files. (See RetailSignToolParam in IoTWorkspace.xml).
- Add-IoTSecureBoot - Invokes Add-IoTRootCerts to add the root certificates to image.
- Add-IoTDeviceGuard - All kernel mode signers are also added to usermode by default
- Add-IoTRootCerts - New method to add the root certs as a Security.RootCerts package. Security.RootCerts is included by default in OEMCOMMONFM.xml.
- Import-IoTOEMCertificate - Supports "Root" certificate import
- Redo-IoTCabSignature - Supports CabOnly flag to skip re-signing of the binaries inside the cab
- New-IoTOEMCerts
-
Other significant changes
- oemcustomization.cmd updated to invoke secureboot/bitlocker on every boot allowing ability to update secureboot independently
- SIPolicy_Template.xml updated to add Enabled:Inherit Default Policy. This is a place holder to enable Microsoft update Windows code signers in future.
- Custom.BCD.xml updated to enable Test signing, this is required to support the first boot scenario and once secureboot is configured, test signing is disabled by default. Flight signing removed as Windows is always retail signed.
- setup.secureboot.cmd, the registry key updated to DeviceGuardSecureBootSetupv2 to differentiate from earlier secure boot systems.
- IoTWorkspace.xml updated to use the right certificates that are generated. Note that the first update policy signer will be used for signing device guard policies.
- Support of Workspace concept : Workspace is a directory with IoTWorkspace.xml file specifying its attributes. This directory structure is similar to earlier iot-adk-addonkit without the tools and templates directory. You can now have multiple workspaces for building different products and use one common tooling directory.
- Sample Workspace : The addon kit comes with a sample workspace that you can access via the env variable SAMPLEWKS (
$env:SAMPLEWKS
). You can import oem packages, bsp and products from this workspace into your workspace for your use. - Upgrade existing iot-adk-addonkit directory : You can upgrade your existing iot-adk-addonkit directory into a workspace, see Work with Existing Workspace
- Powershell functions and equivalent cmd functions available for many new features. See Supported Functionality listing.
The pre-requisite for using this tools are same as the earlier iot-adk-addonkit projects.
Install the following pre-requisites
- Windows 10 IoT Core Packages
- Windows Assessment and Deployment Kit including Windows PE add-on for the adk
- Get your BSP for your platform. See Windows 10 IoT Core BSPs for links to get the BSPs.
- Certificates - You will need to have these certificates (with private keys) in the local cert store ( either directly installed or loaded from a smart card)
- Code signing certificate from a CA : Required for signing your drivers for building retail image
- Code signing EV certificate from a CA : Required to register with Device Update Center and sign payload for submission
- Security certificates from self : Required for the security features.
-
Launch the IoTCorePShell ( Run
IoTCorePShell.cmd
). This will launch the tool and also install the test certificates if required and opens the sample workspace present along with the tools by default. -
Create a new workspace (say
C:\MyWorkspace
) using New-IoTWorkspaceNew-IoTWorkspace C:\MyWorkspace Contoso arm (or) new-ws C:\MyWorkspace Contoso arm
The Workspace will be created and opened. It will also import few default packages required in the workspace.
-
Import the required oem packages using Import-IoTOEMPackage from the sample workspace (
$env:SAMPLEWKS
). You can either import each package selectively or import all of them.# Importing Recovery packages from sample workspace Import-IoTOEMPackage Recovery.* (or) importpkg Recovery.* # Below example imports all packages from the sample workspace Import-IoTOEMPackage * (or) importpkg *
-
Import the required BSP (for example RPi2) using Import-IoTBSP
# Importing RPi2 bsp from a folder Import-IoTBSP RPi2 C:\Myfolder\RPi_BSP (or) importbsp RPi2 C:\Myfolder\RPi_BSP (or) importbsp RPi2 C:\Downloads\RPi_BSP.zip # Importing an Intel bsp Import-IoTBSP APLx64 "C:\Program Files (x86)\Intel IoT\Source-x64\BSP" (or) importbsp APLx64 "C:\Program Files (x86)\Intel IoT\Source-x64\BSP" # Importing NXP BSPs found inside the zip or folder Import-IoTBSP * C:\BSP\NXPBSP.zip (or) importbsp * C:\BSP\NXPBSP_FOLDER (or) importbsp Sabre_iMX6Q_1GB C:\BSP\NXPBSP.zip # Importing QCDB410C BSP packages found inside the zip ## special case - this invokes Import-QCBSP internally Import-IoTBSP QCDB410C C:\BSP\db410c_bsp.zip (or) importbsp QCDB410C C:\BSP\db410c_bsp.zip # the above will import the bsp from sample wkspace and copy the prebuilt cabs to Workspace\Prebuilt directory
-
For Qualcomm BSP, after downloading the zip file, you can extract the prebuilt cabs using
# Import the QCDB410 BSP and extract the required cabs from the QC zip file Import-QCBSP C:\BSP\db410c_bsp.zip C:\MyWorkspace\Prebuilt -ImportBSP
C:\MyWorkspace\Prebuilt
will be set as BSPPkgDir in the Workspace xml.
-
-
Create a new product (MyProduct) based on the imported BSP, say RPi2 in the below example, using Add-IoTProduct
Add-IoTProduct MyProduct RPi2 (or) newproduct MyProduct RPi2
This will prompt you for the SMBIOS values to be used in the product.
DeviceInventory_MyProduct.xml
is also generated which is used to register your device on the DUC portal. -
Build all packages using New-IoTCabPackage
New-IoTCabPackage All (or) buildpkg all
-
Build the FFU image for MyProduct product, test configuration using New-IoTFFUImage
New-IoTFFUImage MyProduct Test (or) buildimage MyProduct Test
This will also build the necessary product specific packages and the fm files before starting the image creation.
-
Build the recovery FFU image using New-IoTRecoveryImage
New-IoTRecoveryImage MyProduct Test (or) buildrecovery MyProduct Test
Note that the device layout should have MMOS partition to be able to create recovery image. See Recovery for more details.
You can add an appx, driver, provisioning package, files and registry settings to your image by creating specific packages for each.
-
Add a appx package using Add-IoTAppxPackage
Add-IoTAppxPackage C:\MyTest.appx fga (or) newappxpkg C:\MyTest.appx fga
This also adds a feature id
APPX_MYTEST
in the OEMFM.xml file. You can add this feature to MyProduct using Add-IoTProductFeatureAdd-IoTProductFeature MyProduct All APPX_TEST -OEM (or) addfid MyProduct All APPX_TEST -OEM
This will edit both retail and test oeminputxml files under MyProduct to add APPX_TEST feature under OEM node. You also need to make sure that you remove any other application feature id in the oeminputxml file such as IOT_BERTHA.
-
Add a driver package using Add-IoTDriverPackage
Add-IoTDriverPackage C:\TestDriver\MyTest.inf (or) newdrvpkg C:\TestDriver\MyTest.inf
This will copy all the files in the C:\TestDriver directory and also add a feature id
DRIVERS_MYTEST
in the OEMFM.xml file. You can add this feature to MyProduct usingAdd-IoTProductFeature MyProduct All DRIVERS_MYTEST -OEM (or) addfid MyProduct All DRIVERS_MYTEST -OEM
-
Add a provisioning package using Add-IoTProvisioningPackage
Add-IoTProvisioningPackage Prov.MySettings (or) newprovpkg Prov.MySettings
You can then edit the provisioning customizations.xml file using WCD (icd.exe). Launch ICD.exe and open Prov.MySettings.icdproj.xml file that is generated to add the policies required. If you have created a ppkg file using ICD.exe already, you can import the same using
Add-IoTProvisioningPackage Prov.MySettings "C:\Users\username\Documents\Windows Imaging and Configuration Designer (WICD)\MySettings\MySettings.ppkg" (or) newprovpkg Prov.MySettings2 "C:\Users\username\Documents\Windows Imaging and Configuration Designer (WICD)\MySettings\MySettings.ppkg"
This will add a feature id
PROV_MYSETTINGS
in the OEMCOMMONFM.xml. You can add this feature to MyProduct usingAdd-IoTProductFeature MyProduct All PROV_MYSETTINGS -OEM (or) addfid MyProduct All PROV_MYSETTINGS -OEM
-
Add a file package using Add-IoTFilePackage
$myfiles = @( ("`$(runtime.system32)","C:\Temp\TestFile1.txt", ""), ("\OEMInstall","C:\Temp\TestFile2.txt", "TestFile2.txt") ) Add-IoTFilePackage Files.Configs $myfiles
This will add a feature id
FILES_CONFIGS
in the OEMCOMMONFM.xml. You can add this feature to MyProduct usingAdd-IoTProductFeature MyProduct All FILES_CONFIGS -OEM (or) addfid MyProduct All FILES_CONFIGS -OEM
-
Add a registry package using Add-IoTRegistryPackage
$myregkeys = @( ("`$(hklm.software)\`$(OEMNAME)\Test","StringValue", "REG_SZ", "Test string"), ("`$(hklm.software)\`$(OEMNAME)\Test","DWordValue", "REG_DWORD", "0x12AB34CD")) Add-IoTRegistryPackage Reg.Settings $myregkeys
This will add a feature id
REG_SETTINGS
in the OEMCOMMONFM.xml. You can add this feature to MyProduct usingAdd-IoTProductFeature MyProduct All REG_SETTINGS -OEM (or) addfid MyProduct All REG_SETTINGS -OEM
-
You can build the above packages using
buildpkg
command discussed earlier and create an FFU usingbuildimage
command.
If you require Powershell, it is recommended to add the latest Powershell available in the github in your images and you can do this easily with Import-PSCoreRelease.
Import-PSCoreRelease 7.0.0
This will download the powershell zip from the github and import the files into the workspace. It will also add a feature id OPENSRC_POWERSHELL
in the OEMFM.xml. You can add this feature to MyProduct using
# Add IOT_POWERSHELL for WinRM
Add-IoTProductFeature MyProduct All IOT_POWERSHELL
# Add Open source Powershell
Add-IoTProductFeature MyProduct All OPENSRC_POWERSHELL -OEM
(or) addfid MyProduct All OPENSRC_POWERSHELL -OEM
In order to enable security features such as Secure boot, Bitlocker and Device guard, you will require specific certificates to be created and accessible from the machine where the image is built. See Turnkey Security on IoT Core for the details on these security features and Windows Secure Boot Key Creation and Management Guidance for managing certificates.
For testing purposes, following commands are provided to create and install the certs in your machine.
-
Create OEM Certs using New-IoTOEMCerts
New-IoTOEMCerts
This will prompt you to enter password for the certs that are created. The created certificates are in the workspace certs folder and the pfx files with the private keys are in the certs\private folder.
-
Install the pfx files required for the signing process during the security package creation, using Install-IoTOEMCerts
Install-IoTOEMCerts
-
If you already have the certs to use for security packages, you can import them using Import-IoTCertificate
# PlatformKey and KeyExchangeKey mandatory for SecureBoot Import-IoTCertificate $env:SAMPLEWKS\Certs\Contoso-PK.cer PlatformKey Import-IoTCertificate $env:SAMPLEWKS\Certs\Contoso-KEK.cer KeyExchangeKey # DataRecoveryAgent mandatory for Bitlocker Import-IoTCertificate $env:SAMPLEWKS\Certs\Contoso-DRA.cer DataRecoveryAgent # Update mandatory for Device Guard # Note : use KEK as the update signer Import-IoTCertificate $env:SAMPLEWKS\Certs\Contoso-KEK.cer Update # import the oem driver signer as kernel mode signer (KMCI) Import-IoTCertificate $env:SAMPLEWKS\Certs\Contoso-KMCI.cer Kernel Import-IoTCertificate $env:SAMPLEWKS\Certs\Contoso-UMCI.cer User
-
You can now create the security packages using Add-IoTSecureBoot,Add-IoTDeviceGuard and Add-IoTBitLocker
# Create Secure boot package Add-IoTSecureBoot -Test # Create Device guard package Add-IoTDeviceGuard -Test # Create Bitlocker package Add-IoTBitLocker
(or) you can create them all using Add-IoTSecurityPackages
Add-IoTSecurityPackages
-
Now that the new security packages are created, include the Security features
SEC_BITLOCKER
,SEC_SECUREBOOT_TEST
andSEC_DEVICEGUARD_TEST
in the oeminputxml file.Add-IoTProductFeature MyProduct All SEC_BITLOCKER -OEM Add-IoTProductFeature MyProduct All SEC_SECUREBOOT_TEST -OEM Add-IoTProductFeature MyProduct All SEC_DEVICEGUARD_TEST -OEM
-
You can build the above packages using
buildpkg
command discussed earlier and create an FFU usingbuildimage
command.
To build an retail image, you will need to retail sign all your packages and then create the FFU image.
-
Configure the code signing certificate for retail signing in the Workspace xml
<!--Specify the retail signing certificate details, Format given below --> <RetailSignToolParam>/s my /i "Issuer" /n "Subject" /ac "C:\CrossCertRoot.cer" /fd SHA256</RetailSignToolParam>
You could also specify the certificate by the thumbprint
<!--Specify the retail signing certificate details, Format given below --> <RetailSignToolParam>/s my /sha1 "thumbprint" /fd SHA256</RetailSignToolParam>
-
Enable retail signing with Set-IoTRetailSign
Set-IoTRetailSign On (or) retailsign On
This will set the sign tool parameter to the certificate specified as
RetailSignToolParam
in the Workspace xml. You will also see the prompt highlighting that the Retail mode is on. -
Rebuild all your packages with
New-IoTCabPackage All (or) buildpkg all
Note : If you are using security packages, ensure to generate the retail version of the packages (without -Test flag) and include the corresponding feature id in the RetailOEMInput.xml file.
-
If you have prebuilt bsp cab packages, re-sign them using Redo-IoTCabSignature
Redo-IoTCabSignature <srccabdir> <dstcabdir> (or) re-signcabs <srccabdir> <dstcabdir>
Set the BSPPkgDir setting to the
dstcabdir
in the product settings xml for retail configuration. -
Build the image for retail configuration.
New-IoTFFUImage RPiRecovery Retail (or) buildimage RPiRecovery Retail
This will also build the necessary product specific packages and the fm files before starting the image creation.
-
Build the Retail recovery FFU image with
New-IoTRecoveryImage RPiRecovery Retail (or) buildrecovery RPiRecovery Retail
Steps to upgrade your existing iot-adk-addonkit project directory.
-
Launch the IoTCorePShell ( Run
IoTCorePShell.cmd
). This will launch the tool and also install the test certificates if required and opens the sample workspace present along with the tools by default. -
Run the migration command for the existing repo dir say
C:\Myproject\iot-adk-addonkit
, using Redo-IoTWorkspaceRedo-IoTWorkspace C:\Myproject\iot-adk-addonkit (or) migrate C:\Myproject\iot-adk-addonkit
This command will generate the workspace xml file and product specific settings file that is required for rest of the scripts to work. The SMBIOS data for the product will be set to default and you will be required to update them to the proper values. For Qualcomm based products, the SMBIOS values from the SMBIOS.cfg will be used.
-
The tools and templates directory under your repo is not required anymore. These can be deleted ( note that the above command does not delete these folders, but moves them to a ToDelete folder).
-
Open this workspace using Open-IoTWorkspace and start using this as a new workspace described above.
Open-IoTWorkspace C:\Myproject\iot-adk-addonkit\IoTWorkspace.xml (or) open-ws C:\Myproject\iot-adk-addonkit\IoTWorkspace.xml
Steps to register your device on the device update center and publish updates are given below.
- Register with the Device Update Center portal. You will require an EV cert for this process.
- Configure the EV cert used in the Device Update Center in the Workspace.
<!--Specify the ev signing certificate details, Format given below --> <EVSignToolParam>/s my /i "Issuer" /n "Subject" /fd SHA256</EVSignToolParam>
- Create a product
You will find an device inventory file
Add-IoTProduct SampleA RPi2 (or) newproduct SampleA RPi2
IoTDeviceModel_<product>.xml
. Use this file to register your device model in the DUC portal. If you change the SMBIOS fields or install a different IoTCore Kit version, you can regenerate this file usingExport-IoTDeviceModel SampleA (or) exportidm SampleA
- Once the device model is registered in the portal, you can download
CUSConfig.zip
file from the portal. You can then import this file into the product configuration usingThis will create a CUSConfig folder in the Product\Packages directory and also update the oeminput xml files.Import-IoTDUCConfig SampleA "C:\Users\MyUser\Downloads\CUSConfig.zip" (or) importcfg SampleA "C:\Users\MyUser\Downloads\CUSConfig.zip"
- Rebuild the image with the CUSConfig included. This will be the base shipping image for your device model.
New-IoTFFUImage SampleA Retail (or) buildimage SampleA Retail
- When you have new update to create, modify/update the OEM package contents and increment the BSP_VERSION
Set-IoTCabVersion 10.0.1.0 (or) setversion 10.0.1.0
- Rebuild your packages and build your ffu image with the updated packages. Validate this FFU for functionality. You can then export the update package using
This will create a cab file under
Export-IoTDUCCab SampleA Retail (or) exportpkgs SampleA Retail
$env:BUILD_DIR\<product>\<Config>\$env:BSP_VERSION
- You can upload this cab in the DUC portal.
The supported commands are listed below in logical groups.
Function Name | Alias | Description |
---|---|---|
New-IoTWorkspace | new-ws | Creates new workspace |
Open-IoTWorkspace | open-ws | Opens existing workspace |
Redo-IoTWorkspace | migrate | Converts legacy iot-adk-addonkit directory into a workspace |
Import-IoTOEMPackage | importpkg | Imports OEM package from Sample workspace |
Import-IoTProduct | importproduct | Imports Product from Sample workspace |
Import-IoTBSP | importbsp | Imports BSP from the given folder / zip file or sample workspace |
New-IoTOEMCerts | - | Creates new OEM specific certificates |
Install-IoTOEMCerts | - | Installs oem pfx files in the certs\private folder |
Import-IoTCertificate | - | Imports the certificate for security functions |
Copy-IoTOEMPackage | copypkg | Copies OEM package between workspaces |
Copy-IoTProduct | copyproduct | Copies product between workspaces |
Copy-IoTBSP | copybsp | Copies BSP between workspaces |
Add-IoTAppxPackage | newappxpkg | Creates Appx OEM package and adds featureID to OEMFM.xml |
Add-IoTDriverPackage | newdrvpkg | Creates Driver OEM package and adds featureID to OEMFM.xml |
Add-IoTCommonPackage | newcommonpkg | Creates common (file/reg) OEM package and adds featureID to OEMCOMMONFM.xml |
Add-IoTFilePackage | addfile | Adds a file package and adds the featureID to OEMCOMMONFM.xml |
Add-IoTRegistryPackage | addreg | Adds a registry package and adds the featureID to OEMCOMMONFM.xml |
Add-IoTProvisioningPackage | newprovpkg | Adds provisioning oem package and adds the featureID to OEMCOMMONFM.xml |
Add-IoTBSP | newbsp | Adds new bsp based on a template |
Add-IoTProduct | newproduct | Adds new product based on the OEMInputSamples from BSP |
Add-IoTSecurityPackages | - | Adds security packages for the product |
Add-IoTDeviceGuard | - | Adds device guard package |
Add-IoTSecureBoot | - | Adds secureboot package for the product |
Add-IoTBitLocker | - | Adds bitlocker package for the product |
Add-IoTRootCerts | - | Adds the root certificates |
Add-IoTProductFeature | addfid | Adds feature id to the product's oeminput xml file |
Remove-IoTProductFeature | removefid | Removes feature id from the product's oeminput xml file |
Add-IoTCEPAL | addcepal | Preview: Adds CEPALFM.xml into the Test and Retail OEMInput.xml files for product. See CE Migration for more details |
Import-IoTCEPAL | importcepal | Preview: This command copies $FlatReleaseDirectory\CEPAL_PKG into the workspace and generates CEPALFMFileList.xml. See CE Migration for more details |
Import-PSCoreRelease | importps | This command imports Open source Powershell release from github into the workspace |
Add-IoTZipPackage | addzip | This command adds all file contents in the zip file into a file package in the workspace |
Add-IoTDirPackage | adddir | This command adds all file contents in the directory into a file package in the workspace |
Function Name | Alias | Description |
---|---|---|
Set-IoTCabVersion | setversion | Stores the version in the IoTWorkspace.xml |
New-IoTCabPackage | buildpkg | Creates .cab files |
New-IoTProvisioningPackage | buildppkg | Creates .ppkg files |
New-IoTFIPPackage | buildfm | Creates FIP packages and merged FM files |
New-IoTFFUImage | buildimage | Creates regular FFU |
New-IoTRecoveryImage | buildrecovery | Creates recovery FFU |
New-IoTWindowsImage | newwinpe | Creates custom winpe with bsp drivers / recovery scripts |
Test-IoTRecoveryImage | verifyrecovery | Verifies if the wim files in the recovery ffu are proper |
New-IoTInf2Cab | inf2cab | Creates cab file for the given inf file |
Function Name | Alias | Description |
---|---|---|
Set-IoTEnvironment | setenv | Sets environment settings based on the config values in IoTWorkspace.xml |
Convert-IoTPkg2Wm | convertpkg | Converts pkg.xml files to wm.xml files |
Get-IoTProductFeatureIDs | gpfids | Gets features IDs supported in the IoTCore OS |
Get-IoTProductPackagesForFeature | gpfidpkgs | Gets OS packages corresponding to features ID |
Get-IoTWorkspaceProducts | gwsproducts | Gets the list of product names in the workspace |
Get-IoTWorkspaceBSPs | gwsbsps | Gets the list of BSP names in the workspace |
Function Name | Alias | Description |
---|---|---|
Export-IoTDeviceModel | exportidm | Exports the IoT Device Model for DUC registration |
Import-IoTDUCConfig | importcfg | Imports the CUSConfig.zip into the product directory |
Export-IoTDUCCab | exportpkgs | Exports the update cab for DUC upload |
Function Name | Alias | Description |
---|---|---|
Mount-IoTFFUImage | ffum | Mounts the FFU image |
Dismount-IoTFFUImage | ffud | Dismounts the FFU image |
Export-IoTFFUAsWims | ffue | Exports the EFIESP/MainOS/Data partitions as Wims |
New-IoTFFUCIPolicy | ffus | Scans the MainOS partition and generates CI policy (initialpolicy.xml ) |
Get-IoTFFUDrives | ffugd | Returns a hashtable of the drive letters for the mounted partitions |
Function Name | Alias | Description |
---|---|---|
Set-IoTSignature | setsignature | Sets the Certificate info used for signing |
Set-IoTRetailSign | retailsign | Sets/resets use of the retail code signing certificate |
Test-IoTSignature | - | Tests if the file is signed for the given config |
Test-IoTCabSignature | - | Tests if the Cab package and its contents are signed for the given config |
Test-IoTPackages | tpkgs | Tests all packages and its contents are signed, for the given product / config |
Test-IoTFeatures | tfids | Tests if all feature ids are defined, for the given product / config |
Add-IoTSignature | signbinaries | Signs files with the cert set via Set-IoTSignature |
Redo-IoTCabSignature | re-signcabs | Resigns cab and its contents using Add-IoTSignature |
Test-IoTCerts | tcerts | Checks if the certs in the workspace folder are all valid |
Class Name | Factory Method | Description |
---|---|---|
IoTDeviceLayout | New-IoTDeviceLayout | Class for managing Device Layout xml |
IoTFMXML | New-IoTFMXML | Class for managing Feature Manifest xml |
IoTProvisioningXML | New-IoTProvisioningXML | Class for managing Provisioning XML (Customisations.xml) |
IoTWorkspaceXML | New-IoTWorkspaceXML | Class for managing Workspace xml |
IoTOemInputXML | New-IoTOemInputXML | Class for managing OEMInput.xml |
IoTProductSettingsXML | New-IoTProductSettingsXML | Class for managing IoT Product settings xml |
IoTWMXML | New-IoTWMXML | Class for managing windows manifest xml |
IoTWMWriter | New-IoTWMWriter | Class for writing windows manifest xml |
IoTProduct | New-IoTProduct | Class for managing IoT Product configuration |