The gfzcreate library

[image of the Head of a GNU]

This page is in a high state of flux.!!

Table of content

The gfzcreate library

The gfzcreate library is a free library for the creation of forensic files. The first version of this library will support only the gfzip file format, but future versions may also support AFF and possibly more (non closed) formats.

Initialization

In order to use libgfz in a program you first need to include gfz.h. 

    #include <gfzcreate.h>
Next to including the header file you will need to initialize the library. For initialization the gfz library defines the function gfzicreate_init. This function will initialize the library and create an environment for you that you must use when creating a forensic file.

gfzcreate_env *gfzcreate_init(char *tempdir);

The tempdir argument specifies a location where the library may create temporary files during operation. If gfzicreate_init fails, NULL will be returned, and errno will be set. (TODO: define errno values)

void gfzcreate_end(gfzcreate_env *env);

In order to free all memory allocated to the environment and any images opened into this environment, the function gfzicreate_end is provided. Any temporary file that was created by the library will also be deleted by this function.

Opening a new forensic file

Now what you have created your environment you can go and create a new forensic disk image into this environment. For this the gfzcreate library has the gfzcreate_open function. This function on success will return a gfzcreate_image that will be used as handle to do most further API calls on.

gfzcreate_image *gfzcreate_open(gfzcreate_env *env,char *path,size_t cblocks,inc compression,int pltype,char *warrantfile,char *reductionfile);

The first argument is the environment as created with gfzcreate_init. The second argument is the path of the file to create, the cblocks argument defines the number of 512 byte blocks that the file will use as an addressable (and separately compressed) section and the compression argument defines the type of compression to use.: The pltype argument defines the type of gfzip file that will be created: The optional argument warrantfile can be used to add meta data sections previously signed by a third party to the newly created image file. This will allow for example to add meta-data signed by the proper authority referring to the relevant a warrant used to acquire the evidence at the moment of acquirement. The optional argument reductionfile can be used to define the path of a special reduction file. This file contains a digest partition with a sorted digest table of block digests that can be left out of the image and marked with the reduction flag. Please use reduction with extreme care as this type of data reduction on acquirement must be considered experimental untill it has been formally approved as a valid forensic method of acquirement.

Opening a forensic image file for append.

One of the most essential and important features of features of the gfzip file format is its ability to be used in order to sign and add signed meta-data and flags to existing image files while retaining their usability for most tools that work on files of those formats. the gfzip creation library offers full support for appending to dd images, aff images or existing gfzip images.

gfzcreate_image *gfzcreate_open_append(gfzcreate_env *env,char *path,size_t iblocks,int filetype,int pack,char *namespace,char *casefile,char *reductionfile);

The iblocks argument will be used the same way as the cblocks argument of gfzcreate_open, but will only be used if the filetype of the original file is GFZ_FILETYPE_RAW. The filetype must be defined at one of the following values. gfz_open will return a gfz_image on success or a NULL value on failure. on failure errno will be set to one of the following values: It is important to note that a gfzcreate_image structure created with gfz_create_open_append can only be used to add meta-data and flags to the file, but no further data can be added. The pack argument if non zero indicates that if not already, the resulting file should be packed. If an existing image is opened, a new meta-data partition is created. By convention names for the newly created meta-data partition correspond to specific actions. If left unspecified the library will try to determine an appropriate namespace based on other arguments, but the namespace can optionally also be given explicitly to this function. The casefile argument is the appending equivalent of warrantfile in gfz_create_open. It will be mostly usable for use when image files cross organizational boundaries.

Adding meta-data to the gfzip file.

int gfzcreate_addmeta(gfzcreate_image *img,char *key,void *val,size_t size,char *encoding);

This function ads a key/value pair to the active meta-data partition. The key is a null terminated ascii string. The value is a string with a size of size bytes in an encoding denoted by encoding. if encoding is NULL, than "LATIN1" is implied.

Writing data and setting flags.

size_t gfzcreate_write(gfzcreate_image *img,size_t size, size_t nmemb,u_int32_t globalflags);

The following values may be defined as globalflags: It is important to note that no data may thus be appended to image files opened using gfz_create_open_append.

Appending more flags to the gfzip file.

int gfzcreate_addflags(gfzcreate_image *img,u_int64_t startoffset,u_int64_t size,u_int32_t flags,nsseg);

This function is used to add additional flags for specified ranges of data. The nsseg attribute defines if the flags will get added to the global (0) namespace and will thus represent the flags as defined for gfzcreate_write, or if the flags are defined within the current namespace for appending. If the current namespace is defined, than each value for nsseg will represent a distinct set of 32 flags that are namespace specific and can thus be defined by any tool that wishes to do so.

Signing and closing the gfzip file.

int gfzcreate_signandclose(gfzcreate_image *img,FILE *p12,char *passphrase);

The library defines closing and signing as a single action. When the file gets closed, it should get signed within the same transaction. The p12 argument is an already opened p12 file containing the private key and x509 certificate of the person signing the gfzip file partitions. The passphrase argument is used to disclose the private key for the signing process. If on open packing is defined, than this packing may be actually delayed untill the gfzcreate_signandclose function is called.

int gfzcreate_passok(FILE *p12,char *passphrase);

Convenience function for those unhapy with the logistics of gfzcreate_signandclose. Allows the validity of the p12 file passphrase to be validated prior to time consuming actions that may precede gfzcreate_signandclose.

Copyright © 2006 Rob J Meijer ., capibara@xs4all.nl

Verbatim copying and distribution of this entire article are permitted worldwide, without royalty, in any medium, provided this notice, and the copyright notice, are preserved.