The gfzcreate library
This page is in a high state of flux.!!
Table of content
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.
In order to use libgfz in a program you first need to include gfz.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.
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.
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.
- GFZ_PLTYPE_GFZIPAFF : Data partition in native order AFF style segments.
- GFZ_PLTYPE_GFZIPAFFBE : Data partition (and all other partitions) in BE order (compatibility) AFF style segments.
- GFZ_PLTYPE_GFZIPDD : Data partition is a raw dd image or raw concatenated compressed chunks of in order data..
- GFZ_PLTYPE_GFZPACK : On close, the data section will be packed.
- GFZ_PLTYPE_GFZIPMETA : Meta data partition only in native order AFF style segments.
- GFZ_PLTYPE_GFZIPMETABE : Meta data partition only in BE order (compatibility) AFF style segments.
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:
- GFZ_FILETYPE_GFZIP : assume the gfzip file format.
- GFZ_FILETYPE_RAW : assume a raw dd image.
- GFZ_FILETYPE_AFF : assume the the advanced forensic format (will not be supported untill version 2, maybe later)
- GFZ_FILETYPE_AUTO : try all known types in arbitrary sequence (GFZ_FILETYPE_DD will always be tried as last resort)
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.
- GFZ_ERR_OPEN : unable to open the file due to file access rights.
- GFZ_ERR_INVENV : environment is invalid.
- GFZ_ERR_UNSUP: the file format is currently not (yet) supported by the gfz library.
- GFZ_ERR_FATAL: a fatal error has occurred, for example no physical memory available.
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.
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.
- GFZ_FLAG_BAD : This flag indicates the data was marked BAD during acquisition
- GFZ_FLAG_REDUCTION : This flag indicates that the data is marked as uninteresting.
- GFZ_FLAG_NOSHARE : This flag indicates that the data may never be made part of a multi case archive.
- GFZ_FLAG_INSUB : This flag indicates that the data and any derived data must be recognized and treated as non submissible as evidence.
- GFZ_FLAG_CORRUPTED : This flag indicates that in some stage in its live a section of the gfzip file got corrupted, and the gfzip file
got repaired by marking the appropriate section as corrupted.
- GFZ_FLAG_RUNTIME : This flag indicates that the read action should have normally failed due to runtime digest checks or decompression errors.
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.
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.
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.