mkmerklefs

Build and verify a Merkle filesystem image

Syntax:

To build a Merkle filesystem:

mkmerklefs -b block_size -h hash 
  [-k hash_block_size] [-o output_image] [-p] 
  [-s salt] -t fstype [-v] [-y private_key] 
  [-z sign_cmd] filesystem_image

To verify a Merkle filesystem:

mkmerklefs [-v] -x -t fstype -y public_key filesystem_image

To calculate Merkle filesystem overhead:

mkmerklefs -c -C size filesystem_image

Runs on:

QNX Neutrino, Linux, Mac, Microsoft Windows

Options:

-b
Input filesystem (filesystem_image) block size. Valid values: 512, 1024, 2048, 4096, 8192, 16384, 32768.
-c
Calculates the size of the metadata tree using the filesystem_image size and generates no data apart from the printed statistics. This option cannot be combined with -C.
-C
Calculates the size of the metadata tree using the provided image size in bytes and generates no data apart from the printed statistics. This option cannot be combined with -c.
-h
Hash function to use in Merkle tree. Supported digests: sha256, sha512. Choosing the stronger hash function (sha512) may decrease performance.
-k
Merkle hash block size. If this option is not specified, it takes the same value as the -b option. Increasing block size may decrease performance. Valid values: 512, 1024, 2048, 4096, 8192, 16384, 32768.
-o
The optional name of the output file (output_image) in which to store the combined input filesystem (filesystem_image) with the Merkle metadata. Use this option when you want to separate the original file from the new file. If this option is not specified, Merkle metadata is appended directly to the input file (filesystem_image). This option cannot be combined with -x.
-p
Print Merkle tree statistics while building the image.
-s
The salt value to use in hash calculations. If you do not specify this value, the salt is randomly generated. The salt value must be equal or greater than the digest size of the selected hash function.
-t
The filesystem type of the filesystem_image. Supported image types: qnx6 (Power-Safe filesystem).
-v
Increase verbosity of output for additional information and debugging.
-x
Verify generated or extracted filesystem_image for errors. This option cannot be combined with -o.
-y
The key to sign (private) or verify (public) the metadata header. See Merkle filesystem documentation for more information on keys. This option cannot be combined with -z.
-z

Use sign_cmd for custom signing. Custom signing means using a custom utility that hides the private key while allowing signing to proceed. This method allows the signing operation to be done remotely through a utility. Because the key is implicit with -z, and you do not need to specify it with the -y option.

The following two tokens need to appear in the signing command. They are replaced by temporary files when the signing command is called:

<hashfile>: The path to a file containing the sha256 digest in binary format that needs to be signed.

<sigfile>: The path to a file where the custom utility writes the signature in binary format.

For example:

openssl pkeyutl -sign -in <hashfile> -inkey private_key.pem 
     -out <sigfile> -pkeyopt digest:sha256

Description:

The mkmerklefs utility builds a Merkle filesystem by taking as input the original filesystem image (for example, a Power-Safe image that has been created with tools for filesystem building) and generating metadata which is appended to the original filesystem image. This step is usually done offline on a host build machine.

The metadata is cryptographically signed using the private part of a key pair (see Merkle filesystem for additional details on keys).

Once built, the Merkle filesystem image contains both the original filesystem as well as the Merkle metadata. How this image is flashed or loaded is device specific.

Refer to fsf-merkle.so in the Utilities Referencefor details on how to mount a Merkle filesystem.

Note: Merkle filesystems are immutable and read-only.

Examples:

To build a Merkle image:

mkmerklefs -p -b 4096 -t qnx6 -h sha256 -y private_key.pem -o merkle.img fs.img

To verify a Merkle image:

mkmerklefs -x -t qnx6 -y public_key.pem merkle.img

Exit status:

0
Returns 0 if the Merkle image is built or verified successfully.
1
An error occurred.