Signing the .bin File
Other versions of this page are also available for the following:
.gif "A hyphen indicates that the information in this topic is not relevant for this platform, or that the platform does not support the API that is listed.")
.gif "A checkmark indicates that the information in this topic is relevant for this platform, and that any API listed is also supported on this platform.")
8/27/2008
Use ImageHash.exe utility to sign the image.
Syntax code example
The following code example shows the syntax.
ImageHash [–raw] <file name in> <file name out> <max packet size>
Example: Using the /csp and /k options:
ImageHash [-raw] <file name in> <file name out> <max packet size>
[/csp <csp name>] [/k <private key container name>]
Example: Using the private key option:
ImageHash [-raw] <file name in> <file name out> <max packet size>
[-pvk] <private key file name>
[-pvkpasswd] <private key file password>
Example: Using the /s, /sm, /i and /n options:
ImageHash [-raw] <file name in> <file name out> <max packet size>
[/s <certificate store name>] [/sm ]
[/i <certificate issuer name>] [/n <certificate subject name>]
The supported parameters include:
| Parameter | Description |
|---|---|
/csp <csp name> |
Specifies the cryptographic service provider (CSP) that contains the private key container. |
/k <private key container name> |
Specifies the private key container name. When signing with the CSP, the /k option must follow the /csp option on the command line. When /csp and /k if any other command line options are present the tool should return an error. This is because there is ambiguity between the user intent. It is not expected to popup the UI b/c the intent of the tool is to run in a headless environment. |
/n <certificate subject name> |
Specifies the name of the subject of the signing certificate. This value can be a substring of the entire subject name. |
/s <certificate store name> |
Specifies the store to open when searching for the certificate. If this option is not specified, the My store is openend. |
/sm |
Specifies that a computer store, instead of a user store, is used. |
/i <certificate issuer name> |
Specifies the name of the issuer of the signing certificate. This value can be a substring of the entire issuer name. |
–pvk <private key file name> |
Name/path to Pkcs#12 private key file |
–pvkpassword <private key file password> |
Password protected pkcs#12 file password |
The following example code shows how to use the utility:
ImageHash NK.bin NK_Sign.bin 1024
ImageHash –raw NK.nb0 NK_Sign.nb0 128
ImageHash uses a graphical interface to select the private key. ImageHash uses the private key paired with the selected public key certificate to sign the image. ImageHash also supports several optional command line parameters which can be used to suppress the graphical interface and automate selecting the signing certificate.
ImageHash produces a signed image file with the file path specified in <file name out>. It takes as input an image file with the file path specified in <file name in>. The signed image file contains a variable number of signed packets.
If the –raw option is specified, then ImageHash makes no assumptions about the input file and enters into a simple block signing routine that creates an output image file with n signed blocks where each block is at most <max packet size> and n = (<total file size> / <max packet size>) + 1. If the –raw option is not specified, then ImageHash enters .bin hashing mode. This produces a new .bin file that has been signed on record boundaries thereby maintaining the general .bin file structure.
The –raw option should only be used on *.nb0 files.
.gif "Bb202029.collapse(en-US,WinEmbedded.60).gif")
Block formats
The following table shows the raw and the signed.bin block formats. Each signed file is composed of a variable number of blocks.
| Raw .bin block format | Signed .bin block format |
|---|---|
Header DWORD Data length DWORD Signature length BYTE Flags. See the table below for the list of flags that can appear here. Data Data Length bytes Signature Length bytes |
Header DWORD Data length DWORD Signature length BYTE Flags. See the table below for the list of flags that can appear here. Record Header DWORD Record address DWORD Record length DWORD Record checksum Data Data Length bytes Signature Length bytes |
Flag values
The following table shows the flag values that you can use in the header. Every block in a signed .bin file contains a flag.
The flags are defined in the SBL.h file located at %WINCEROOT%\Public\Common\Oak\Inc.
| Flag | Description |
|---|---|
SBL_FLAG_NORMAL |
Every block in a raw file always contains this flag. Specifies a record is not broken into chunks. |
SBL_FLAG_CHUNK_HEADER |
Specifies a chunk header. |
SBL_FLAG CHUNK |
Specifies a chunk packet. |
SBL_FLAG_END_FILE |
Specifies a final block. |
Due to device limitations, you may not be able to load the entire image into memory and flash all at once. Instead, you need to flash the image in units, such as records in a .bin file or blocks in a .nb0 file. The fact that the image must be verified creates a problem. If you append the signature to the image authenticating its entire contents, then the boot loader cannot verify the contents of the file because the entire contents cannot be loaded into memory to perform the RSA verification process.
The maximum packet size is OEM specific and refers to the largest amount of memory that the boot loader will be able to work with during verification and flashing. ImageHash takes this value into account and breaks up the image file into <max packet size> sections and individually signs each one. If an individual record is larger than <max packet size>, then ImageHash takes the extra step to break up the record into smaller chunks.
Chunk headers
In the case of a record that has been split into multiple chunks, a chunk header precedes the first broken packet.
| Chunk Header | Description |
|---|---|
DWORD |
0 (zero) |
DWORD |
Number of chunks to follow |
BYTE |
Flags set to SBL_FLAG_CHUNK_HEADER |
The chunk header is followed by the number of chunks specified in the header. Each chuck uses the normal block format, except the flag field contains SBL_FLAG_CHUNK. The record header of each chunk contains the record data for the entire record.