Difference between pages "Encase image file format" and "AFF Developers Guide"

From Forensics Wiki
(Difference between pages)
Jump to: navigation, search
(External Links)
 
(Added automake test)
 
Line 1: Line 1:
[[EnCase]] uses a proprietary format for images which is reportedly based on ASR Data's Expert Witness Compression Format. (Source?) The evidence files, or E01 files, contain a physical bitstream of an acquired disk, prefixed with a '"Case Info" header, interlaced with CRCs for every block of 64 sectors~(32 KB), and followed by a footer containing an MD5 hash for the entire bitstream. Contained in the header are the date and time of acquisition, an examiner's name, notes on the acquisition, and an optional password; the header concludes with its own CRC.
+
This document is a reference guide to the Advanced Forensics Format library. It is intended to be read by software developers seeking to use the library in their own programs. It is ''not'' intended for end users.
  
Encase can store media data into multiple evidence files, which are called segment files. Each segment file consist of multiple sections. Each section consist of a section start definition. This contains a section type.
+
End users will be better off reading the "AFF Users Guide" that comes with the library. This guide gives an introduction to the AFF format and explains the tools included with the library. The default imager, aimage, is covered in this guide.
  
At least from Encase 3 the case info header is contained in the "header" section, which is defined twice within the file and contain the same information.
+
=Introduction=
 +
Using the AFF is (hopefully) a rather transparent process. The library can handle plain files, such as those generated by dd, AFF files, and EnCase images. It is not necessary for your program to know which kind of file it is processing, the data is extracted and presented to the program transparently. All you need to do is change the basic file operations to their AFF equivalents. These simple substitutions allow you to use AFF or Encase files just like dd images.
  
With Encase 4 an additional "header2" section was added. The "header" section now appears only once, but the new "header2" section twice.
+
=Compiling AFF programs=
 +
The library currently supports the following compilers:
 +
* gcc
 +
* g++
 +
* MinGW
 +
* Microsoft Visual C++
  
Version 3 of The Encase F introduced an "error2" sections that it uses to record the location and number of bad sector chunks. The way it handles the sections it can't read is that those areas are filled with zero. Then Encase displays to the user the areas that could not be read when the image was acquired. The granularity of unreadable chunks appears to be 32K.
+
When compiling an AFF program you must include the AFF header:
  
Within Encase 5 the amount of sectors per block (chunk) can vary.
+
  #include <afflib.h>
  
Encase from at least in version 3, 4 and 5 can hash the data of the media it acquires.
+
During linking you must include the AFF library itself and the SSL library. Additionally, if you're using a C compiler, you will need the C++ standard library. Some examples using several compilers are shown below:
It does this by calculating a MD5 hash of the original media data and adds a hash section
+
to the last of the segment files.
+
  
== See Also ==
+
''Using g++''
 +
  $ g++ file.c -lafflib -lssl
  
[[EnCase]]
+
''Using gcc''
 +
  $ gcc file.c -lafflib -lssl -lstdc++
  
== External Links ==
+
''Using MinGW''
 +
  C:\> gcc file.c -lafflib -lssl -lstdc++
  
* A great deal of information about the format has been documented by the [http://libewf.sourceforge.net libewf project], including some of the [http://downloads.sourceforge.net/libewf/ewf_file_format.pdf E01 file format specifications].
+
''Using Microsoft Visual C++''
* [http://www.cfreds.nist.gov/v2/Basic_Mac_Image.html Sample image in EnCase, iLook, and dd format] - From the [[Computer Forensic Reference Data Sets]] Project
+
  c:\> LINK file.obj afflib.lib
  
[[Category:Forensics File Format]]
+
== Testing for the AFF using Automake ==
 +
 
 +
If you're using the GNU Automake and other tools to check for the AFF, we recommend the following tests to determine if the AFF is present on the system:
 +
 
 +
<pre>###########################################################
 +
## Test for AFF Support
 +
###########################################################
 +
AC_ARG_ENABLE([aff],
 +
  AC_HELP_STRING([--enable-aff],[Use AFF for reading files (default yes)]),
 +
                  [enable_aff=$enableval], [enable_aff=yes])
 +
if test "${enable_aff}" = "yes" ; then
 +
  AC_CHECK_HEADERS([afflib.h],,[enable_aff=no])
 +
  AC_CHECK_LIB([aff],[af_open],,[enable_aff=no])
 +
fi
 +
if test "${enable_aff}" = "yes" ; then
 +
  AC_DEFINE([USE_AFF],1,[Use the AFF library to read files])
 +
 
 +
  AC_MSG_RESULT([Found Advanced Forensics Format (AFF), good!])
 +
  AC_MSG_RESULT([Checking for AFF specific features...])
 +
 
 +
  AC_CHECK_LIB([aff],[af_open_stdin],
 +
    AC_DEFINE([USE_AFF_STDIN],1,[The AFF can be used to open standard input]))   
 +
fi</pre>
 +
 
 +
These tests will define two variables in the config.h file for you. First, the value USE_AFF is defined the AFF is found on the development system. Second, the value USE_AFF_STDIN is defined if the function af_open_stdin is supported. That function was not present in early versions of the library.
 +
 
 +
 
 +
=Your First AFF program=
 +
The first program we will examine the command line arguments to determine if they are valid AFF files. If so, it will attempt to open them and display the size of their uncompressed data. The complete source code is below. 
 +
 
 +
<pre>
 +
#include <stdio.h>
 +
#include <stdlib.h>
 +
#include <inttypes.h>
 +
#include <fcntl.h>
 +
#include <afflib.h>
 +
 
 +
#define FALSE 0
 +
#define TRUE  1
 +
 
 +
int process_file(char *fn)
 +
{
 +
  AFFILE *af = af_open(fn,O_RDONLY,0);
 +
  if (NULL == af)
 +
  {
 +
    perror(fn);
 +
    return TRUE;
 +
  }
 +
 
 +
  printf ("The uncompressed size of this file is %"PRId64" bytes\n",
 +
          af_get_imagesize(af));
 +
 
 +
  af_close(af);
 +
  return FALSE;
 +
}
 +
 
 +
 
 +
int main(int argc, char **argv)
 +
{
 +
  if (argc < 2)
 +
  {
 +
    printf ("Usage: %s [FILES]\n", argv[0]);
 +
    return EXIT_FAILURE;
 +
  }
 +
 
 +
  argc++;
 +
  argv--;
 +
 
 +
  while(*argv)
 +
  {
 +
    process_file(*argv);
 +
    ++argv;
 +
    --argc;
 +
  }
 +
  return EXIT_SUCCESS;
 +
}
 +
</pre>
 +
 
 +
We will go through the important parts of the program.
 +
 
 +
  #include <fcntl.h>
 +
  #include <afflib.h>
 +
 
 +
These two lines include the necessary headers to use the AFF. Although fcntl.h is not actually required, it provides several macros that are highly recommended.
 +
 
 +
  AFFILE * af = af_open(fn,O_RDONLY,0);
 +
  if (NULL == af)
 +
  {
 +
    perror(fn);
 +
    return TRUE;
 +
  }
 +
 
 +
This line attempts to open the given file using the af_open command. The O_RDONLY is one of many macros defined in fcntl.h that can be used when opening files. The final parameter specifies whether or not the file must be created. This normally only applies when writing AFF files, so it's safe to leave it as zero here. The function returns a pointer to an AFFILE structure. There are some public data fields in that structure defined in afflib.h.
 +
 
 +
  printf ("The uncompressed size of this file is %"PRId64" bytes\n",
 +
          af_get_imagesize(af));
 +
 
 +
 
 +
This line uses one of the miscellaneous functions included with the AFF to display the size of the uncompressed image stored in the file. Compare the value displayed by this line to the size of the AFF image on the disk and you can see how much the library compresses. The example file zeros.aff shows an extreme case!
 +
 
 +
  af_close(af);
 +
 
 +
This final line closes the file handle and destroys the AFFILE structure.
 +
 
 +
=AFF Concepts=
 +
 
 +
==Segments==
 +
AFF files can be viewed as a series of name/value pairs.
 +
 
 +
==Pages==
 +
 
 +
==AFF Return Values==
 +
The following status codes can be returned by AFF functions.
 +
 
 +
{|
 +
|-
 +
!Code
 +
!Description
 +
|-
 +
| AF_ERROR_EOF
 +
| The end of the AFF file has been reached
 +
|-
 +
| AF_ERROR_DATASMALL
 +
| The buffer provided for the requested AFF segment is not large enough to hold the data that would be returned.
 +
|-
 +
| AF_ERROR_TAIL
 +
| There is no tail or an error occurred trying to read the tail of an AFF segment. This indicates that the file is corrupt (probably truncated).
 +
|-
 +
| AF_ERROR_SEGH
 +
| There is no head or an error occurred trying to read the head. This indicates that the AFF file is corrupt.
 +
|-
 +
| AF_ERROR_NAME
 +
| Invalid segment name
 +
|-
 +
| AF_ERROR_INVALID_ARG
 +
| The argument was invalid
 +
|-
 +
| AF_ERROR_NO_AES
 +
| This version of the library was compiled without AES support and the program is attempting to read an AES-encrypted segment.
 +
|-
 +
| AF_ERROR_AES_TOO_SMALL
 +
| The decrypted AES segment is too small for the amount of data that it was supposed to contain. The segment is probably corrupt.
 +
|-
 +
| AF_ERROR_KEY_SET
 +
| A key was previously set. (You can only have one AES encryption key per file.)
 +
|}
 +
 
 +
=AFF Function Reference=
 +
 
 +
==Stream Functions==
 +
 
 +
===af_open===
 +
 
 +
  AFFILE * af_open(const char *filename, int flags, int mode);
 +
 
 +
The af_open function is used to open a handle to a new or existing file.
 +
 
 +
The flags
 +
 
 +
The mode parameter is only used when creating a new file.
 +
 
 +
See open(2)
 +
 
 +
===af_open_stdin===
 +
 
 +
  AFFILE * af_open_stdin(void);
 +
 
 +
A special case of af_open, this function an AFF handle on standard input. Note that this function did not appear until AFF version 2.3. Also note that if you are working on the Windows platform (or plan to support the Windows platform) you need to explicitly tell the compiler to treat standard input as a stream of binary data. For example, using MinGW you can set:
 +
 
 +
  int _CRT_fmode = _O_BINARY;
 +
 
 +
somewhere in your code. See http://gnuwin32.sf.net/compile.html for more
 +
 
 +
===af_popen===
 +
 
 +
  AFFILE * af_popen(const char *command, const char *type)
 +
 
 +
This function is currently on supported on UNIX variants, Cygwin and MinGW (which are really both Unix variants).
 +
 
 +
See popen(2)
 +
 
 +
===af_close===
 +
 
 +
  int af_close(AFFILE *af);
 +
 
 +
Closes an AFF file handle and frees all resources associated with it. You can use this function regardless if you opened the file with af_open or af_popen.
 +
 
 +
 
 +
 
 +
===af_read===
 +
 
 +
  int af_read(AFFILE *af, unsigned char *buf, size_t count);
 +
 
 +
Note: the size of a read is size_t, not uint64_t, because size_t defines the maximum data segment size on the current platform.
 +
 
 +
 
 +
===af_seek===
 +
 
 +
uint64_t af_seek(AFFILE *af, int64 pos, int whence);
 +
 
 +
Similar to fseeko (a 64-bit version of fseek).
 +
 
 +
Advances the file pointer into the decompressed data to the offset given by pos depending on whence.
 +
SEEK_SET, SEEK_CUR, or SEEK_END.
 +
 
 +
 
 +
 
 +
===af_tell===
 +
 
 +
  uint64 af_tell(AFFILE *af);
 +
 
 +
Similar to ftello (a 64-bit version of ftell), this function returns the offset into the decompressed data
 +
 
 +
===af_eof===
 +
 
 +
int af_eof(AFFILE *af);
 +
 
 +
Returns TRUE if the file pointer into the decompressed data is at the end of the decompressed data. Otherwise, returns FALSE.
 +
 
 +
 
 +
af_reopen
 +
 
 +
 
 +
==Writing AFF Files==
 +
 
 +
===af_enable_writing===
 +
 
 +
  void af_enable_writing(AFFILE *af, int flag);
 +
If flag is TRUE, enables the user to write to the file AF.
 +
 
 +
 
 +
===af_set_callback===
 +
  void af_set_callback(AFFILE *af,
 +
                    void (*wcb)(struct affcallback_info *));
 +
Sets a callback function that is called during each of the four phases of the segment write operation.
 +
 
 +
===af_enable_compression===
 +
  void af_enable_compression(AFFILE *af, int type, int level);
 +
Enables compression on the given AFF file. The type of compression must be an AFF compression algorithm as shown in Table 2. The compression level can be any integer between AF_COMPRESSION_MIN and AF_COMPRESSION_MAX. These values are currently these are one and nine, respectively, but could change in future versions.
 +
 
 +
For example, to enable maximum LZMA compression:
 +
  af_enable_compression(af,AF_COMPRESSION_ALG_LZMA,AF_COMPRESSION_MAX);
 +
{|
 +
! Flag
 +
! Algorithm
 +
|-
 +
| AF_COMPRESSION_ALG_NONE
 +
| No compression
 +
|-
 +
| AF_COMPRESSION_ALG_ZLIB
 +
| zlib
 +
|-
 +
| AF_COMPRESSION_ALG_LZMA
 +
| LZMA. Dramatically slower than zlib, this algorithm can produce image files that are significantly smaller.
 +
|}
 +
 
 +
===af_compression_type===
 +
  int af_compression_type(AFFILE *af);
 +
Returns the compression algorithm being used by the file in question. The algorithms are given in Table 2.
 +
 
 +
===af_write===
 +
  int af_write(AFFILE *af, unsigned char *buf, size_t count);
 +
 
 +
Note that you must call af_enable_writing on af before using this function.
 +
 
 +
===af_badflag===
 +
 
 +
const unsigned char * af_badflag(AFFILE *af);
 +
 
 +
Returns the pattern used to identify bad sectors in this file.
 +
 
 +
===af_is_badsector===
 +
 
 +
af_is_badsector(AFFILE *af, unsigned char *buf);
 +
 
 +
Returns TRUE if buf is the pattern used to mark a bad sector, Otherwise, returns FALSE.
 +
 
 +
===af_stats===
 +
 
 +
===af_set_cache_size===
 +
 
 +
 
 +
==Segment Functions==
 +
 
 +
===af_rewind_seg===
 +
  af_rewind_seg(AFFILE *af);
 +
Returns the segment pointer to the beginning the file. This function should be used before any segments are examined.
 +
 
 +
===af_get_seg===
 +
  int af_get_seg(AFFILE *af, const char *name, unsigned long *arg, unsigned char *data, size_t *datalen);
 +
 
 +
 
 +
===af_get_next_seg===
 +
  int af_get_next_seg(AFFILE *af, char *segname, size_t segname_len, unsigned long *arg, unsigned char *data, size_t *datalen);
 +
 
 +
 
 +
===af_update_seg===
 +
 
 +
 
 +
===af_del_seg===
 +
  int af_del_seg (AFFILE *af, const char *name); 
 +
Deletes the first segment of the given name from the file. Returns zero on success, -1 on error.
 +
 
 +
 
 +
 
 +
==Miscellaneous Functions==
 +
 
 +
===af_filename===
 +
 
 +
  const char * af_filename(AFFILE *af);
 +
 
 +
Returns the filename associated with an opened file.
 +
 
 +
===af_identify===
 +
  int af_identify(AFFILE *af);
 +
Returns the type of file associated with the given handle. The types are defined in Table 3.
 +
 
 +
 
 +
{|
 +
! Type
 +
! Description
 +
|-
 +
| AF_IDENTIFY_RAW
 +
| A raw file, sometimes also called a dd image or flat file
 +
|-
 +
| AF_IDENTIFY_AFF
 +
| A standard AFF archive
 +
|-
 +
| AF_IDENTIFY_AFD
 +
| A directory of AFD files, or a split AFF file
 +
|-
 +
| AF_IDENTIFY_EVF
 +
| An EnCase file read with the original AFF EnCase implementation; now deprecated.
 +
|-
 +
| AF_IDENTIFY_EVD
 +
| An EnCase file read with the original AFF EnCase implementation; now deprecated.
 +
|-
 +
| AF_IDENTIFY_SPLIT_RAW
 +
| A split raw file
 +
|-
 +
| AF_IDENTIFY_AFM
 +
| A raw file with metadata
 +
|-
 +
| AF_IDENTIFY_EWF
 +
| An EnCase file read with libewf.
 +
|}
 +
 
 +
af_get_imagesize
 +
 
 +
  int64 af_get_imagesize(AFFILE *af);
 +
 
 +
Returns the number of bytes in the decompressed data. On an error, returns -1.
 +
 
 +
=Segment Names=
 +
Although segment names and values can be defined by the user at any time, here is a list of the segments that are included in the AFF library. Those values set by aimage are noted.
 +
 
 +
{|
 +
! Name
 +
! Aimage
 +
! Description
 +
|-
 +
| AF_IGNORE
 +
|
 +
| Ignore segments with a zero length name
 +
|-
 +
| AF_PAGESIZE
 +
| Y
 +
| The size of each page, in bytes
 +
|-
 +
| AF_BADFLAG
 +
| Y
 +
| Data that is inserted into the image file to mark a bad sector.
 +
|-
 +
| AF_DMESG
 +
| Y
 +
| The results of the 'dmesg' command are stored in the AFF file.
 +
|-
 +
| AF_ACQUISITION_COMMAND_LINE
 +
| Y
 +
| The command line used to run the disk imaging program.
 +
|-
 +
| AF_ACQUISITION_ISO_COUNTRY
 +
| Y
 +
| The ISO country code of the computer used to create the image; set manually at imaging time.
 +
|-
 +
| AF_PAGE_MD5
 +
| Y
 +
| The MD5 hash of the current page
 +
|-
 +
| AF_ACQUISITION_SECONDS
 +
| Y
 +
| The number of seconds used to create the image file.
 +
|}

Revision as of 07:25, 26 July 2007

This document is a reference guide to the Advanced Forensics Format library. It is intended to be read by software developers seeking to use the library in their own programs. It is not intended for end users.

End users will be better off reading the "AFF Users Guide" that comes with the library. This guide gives an introduction to the AFF format and explains the tools included with the library. The default imager, aimage, is covered in this guide.

Contents

Introduction

Using the AFF is (hopefully) a rather transparent process. The library can handle plain files, such as those generated by dd, AFF files, and EnCase images. It is not necessary for your program to know which kind of file it is processing, the data is extracted and presented to the program transparently. All you need to do is change the basic file operations to their AFF equivalents. These simple substitutions allow you to use AFF or Encase files just like dd images.

Compiling AFF programs

The library currently supports the following compilers:

  • gcc
  • g++
  • MinGW
  • Microsoft Visual C++

When compiling an AFF program you must include the AFF header:

 #include <afflib.h>

During linking you must include the AFF library itself and the SSL library. Additionally, if you're using a C compiler, you will need the C++ standard library. Some examples using several compilers are shown below:

Using g++

 $ g++ file.c -lafflib -lssl

Using gcc

 $ gcc file.c -lafflib -lssl -lstdc++ 

Using MinGW

 C:\> gcc file.c -lafflib -lssl -lstdc++

Using Microsoft Visual C++

 c:\> LINK file.obj afflib.lib

Testing for the AFF using Automake

If you're using the GNU Automake and other tools to check for the AFF, we recommend the following tests to determine if the AFF is present on the system:

###########################################################
## Test for AFF Support
###########################################################
AC_ARG_ENABLE([aff],
   AC_HELP_STRING([--enable-aff],[Use AFF for reading files (default yes)]),
                  [enable_aff=$enableval], [enable_aff=yes])
if test "${enable_aff}" = "yes" ; then
   AC_CHECK_HEADERS([afflib.h],,[enable_aff=no])
   AC_CHECK_LIB([aff],[af_open],,[enable_aff=no])
fi
if test "${enable_aff}" = "yes" ; then
   AC_DEFINE([USE_AFF],1,[Use the AFF library to read files])

   AC_MSG_RESULT([Found Advanced Forensics Format (AFF), good!])
   AC_MSG_RESULT([Checking for AFF specific features...])

   AC_CHECK_LIB([aff],[af_open_stdin],
     AC_DEFINE([USE_AFF_STDIN],1,[The AFF can be used to open standard input]))     
fi

These tests will define two variables in the config.h file for you. First, the value USE_AFF is defined the AFF is found on the development system. Second, the value USE_AFF_STDIN is defined if the function af_open_stdin is supported. That function was not present in early versions of the library.


Your First AFF program

The first program we will examine the command line arguments to determine if they are valid AFF files. If so, it will attempt to open them and display the size of their uncompressed data. The complete source code is below.

#include <stdio.h>
#include <stdlib.h>
#include <inttypes.h>
#include <fcntl.h> 
#include <afflib.h>

#define FALSE 0
#define TRUE  1

int process_file(char *fn)
{
  AFFILE *af = af_open(fn,O_RDONLY,0);
  if (NULL == af)
  {
    perror(fn);
    return TRUE;
  }

  printf ("The uncompressed size of this file is %"PRId64" bytes\n",
          af_get_imagesize(af));

  af_close(af);
  return FALSE;
}


int main(int argc, char **argv)
{
  if (argc < 2)
  {
    printf ("Usage: %s [FILES]\n", argv[0]);
    return EXIT_FAILURE;
  }

  argc++;
  argv--;

  while(*argv)
  {
    process_file(*argv);
    ++argv; 
    --argc;
  }
  return EXIT_SUCCESS;
}

We will go through the important parts of the program.

 #include <fcntl.h> 
 #include <afflib.h>

These two lines include the necessary headers to use the AFF. Although fcntl.h is not actually required, it provides several macros that are highly recommended.

 AFFILE * af = af_open(fn,O_RDONLY,0);
 if (NULL == af)
 {
   perror(fn);
   return TRUE;
 }

This line attempts to open the given file using the af_open command. The O_RDONLY is one of many macros defined in fcntl.h that can be used when opening files. The final parameter specifies whether or not the file must be created. This normally only applies when writing AFF files, so it's safe to leave it as zero here. The function returns a pointer to an AFFILE structure. There are some public data fields in that structure defined in afflib.h.

 printf ("The uncompressed size of this file is %"PRId64" bytes\n",
          af_get_imagesize(af));


This line uses one of the miscellaneous functions included with the AFF to display the size of the uncompressed image stored in the file. Compare the value displayed by this line to the size of the AFF image on the disk and you can see how much the library compresses. The example file zeros.aff shows an extreme case!

 af_close(af);

This final line closes the file handle and destroys the AFFILE structure.

AFF Concepts

Segments

AFF files can be viewed as a series of name/value pairs.

Pages

AFF Return Values

The following status codes can be returned by AFF functions.

Code Description
AF_ERROR_EOF The end of the AFF file has been reached
AF_ERROR_DATASMALL The buffer provided for the requested AFF segment is not large enough to hold the data that would be returned.
AF_ERROR_TAIL There is no tail or an error occurred trying to read the tail of an AFF segment. This indicates that the file is corrupt (probably truncated).
AF_ERROR_SEGH There is no head or an error occurred trying to read the head. This indicates that the AFF file is corrupt.
AF_ERROR_NAME Invalid segment name
AF_ERROR_INVALID_ARG The argument was invalid
AF_ERROR_NO_AES This version of the library was compiled without AES support and the program is attempting to read an AES-encrypted segment.
AF_ERROR_AES_TOO_SMALL The decrypted AES segment is too small for the amount of data that it was supposed to contain. The segment is probably corrupt.
AF_ERROR_KEY_SET A key was previously set. (You can only have one AES encryption key per file.)

AFF Function Reference

Stream Functions

af_open

 AFFILE * af_open(const char *filename, int flags, int mode);

The af_open function is used to open a handle to a new or existing file.

The flags

The mode parameter is only used when creating a new file.

See open(2)

af_open_stdin

 AFFILE * af_open_stdin(void);

A special case of af_open, this function an AFF handle on standard input. Note that this function did not appear until AFF version 2.3. Also note that if you are working on the Windows platform (or plan to support the Windows platform) you need to explicitly tell the compiler to treat standard input as a stream of binary data. For example, using MinGW you can set:

 int _CRT_fmode = _O_BINARY;

somewhere in your code. See http://gnuwin32.sf.net/compile.html for more

af_popen

 AFFILE * af_popen(const char *command, const char *type)

This function is currently on supported on UNIX variants, Cygwin and MinGW (which are really both Unix variants).

See popen(2)

af_close

 int af_close(AFFILE *af);

Closes an AFF file handle and frees all resources associated with it. You can use this function regardless if you opened the file with af_open or af_popen.


af_read

 int af_read(AFFILE *af, unsigned char *buf, size_t count);

Note: the size of a read is size_t, not uint64_t, because size_t defines the maximum data segment size on the current platform.


af_seek

uint64_t af_seek(AFFILE *af, int64 pos, int whence);

Similar to fseeko (a 64-bit version of fseek).

Advances the file pointer into the decompressed data to the offset given by pos depending on whence. SEEK_SET, SEEK_CUR, or SEEK_END.


af_tell

 uint64 af_tell(AFFILE *af);

Similar to ftello (a 64-bit version of ftell), this function returns the offset into the decompressed data

af_eof

int af_eof(AFFILE *af);

Returns TRUE if the file pointer into the decompressed data is at the end of the decompressed data. Otherwise, returns FALSE.


af_reopen


Writing AFF Files

af_enable_writing

 void af_enable_writing(AFFILE *af, int flag);

If flag is TRUE, enables the user to write to the file AF.


af_set_callback

 void af_set_callback(AFFILE *af, 
                    void (*wcb)(struct affcallback_info *));

Sets a callback function that is called during each of the four phases of the segment write operation.

af_enable_compression

 void af_enable_compression(AFFILE *af, int type, int level);

Enables compression on the given AFF file. The type of compression must be an AFF compression algorithm as shown in Table 2. The compression level can be any integer between AF_COMPRESSION_MIN and AF_COMPRESSION_MAX. These values are currently these are one and nine, respectively, but could change in future versions.

For example, to enable maximum LZMA compression:

 af_enable_compression(af,AF_COMPRESSION_ALG_LZMA,AF_COMPRESSION_MAX);
Flag Algorithm
AF_COMPRESSION_ALG_NONE No compression
AF_COMPRESSION_ALG_ZLIB zlib
AF_COMPRESSION_ALG_LZMA LZMA. Dramatically slower than zlib, this algorithm can produce image files that are significantly smaller.

af_compression_type

 int af_compression_type(AFFILE *af);

Returns the compression algorithm being used by the file in question. The algorithms are given in Table 2.

af_write

 int af_write(AFFILE *af, unsigned char *buf, size_t count);

Note that you must call af_enable_writing on af before using this function.

af_badflag

const unsigned char * af_badflag(AFFILE *af);

Returns the pattern used to identify bad sectors in this file.

af_is_badsector

af_is_badsector(AFFILE *af, unsigned char *buf);

Returns TRUE if buf is the pattern used to mark a bad sector, Otherwise, returns FALSE.

af_stats

af_set_cache_size

Segment Functions

af_rewind_seg

 af_rewind_seg(AFFILE *af);

Returns the segment pointer to the beginning the file. This function should be used before any segments are examined.

af_get_seg

 int af_get_seg(AFFILE *af, const char *name, unsigned long *arg, unsigned char *data, size_t *datalen);


af_get_next_seg

 int af_get_next_seg(AFFILE *af, char *segname, size_t segname_len, unsigned long *arg, unsigned char *data, size_t *datalen);


af_update_seg

af_del_seg

 int af_del_seg (AFFILE *af, const char *name);  

Deletes the first segment of the given name from the file. Returns zero on success, -1 on error.


Miscellaneous Functions

af_filename

 const char * af_filename(AFFILE *af);

Returns the filename associated with an opened file.

af_identify

 int af_identify(AFFILE *af);

Returns the type of file associated with the given handle. The types are defined in Table 3.


Type Description
AF_IDENTIFY_RAW A raw file, sometimes also called a dd image or flat file
AF_IDENTIFY_AFF A standard AFF archive
AF_IDENTIFY_AFD A directory of AFD files, or a split AFF file
AF_IDENTIFY_EVF An EnCase file read with the original AFF EnCase implementation; now deprecated.
AF_IDENTIFY_EVD An EnCase file read with the original AFF EnCase implementation; now deprecated.
AF_IDENTIFY_SPLIT_RAW A split raw file
AF_IDENTIFY_AFM A raw file with metadata
AF_IDENTIFY_EWF An EnCase file read with libewf.

af_get_imagesize

 int64 af_get_imagesize(AFFILE *af);

Returns the number of bytes in the decompressed data. On an error, returns -1.

Segment Names

Although segment names and values can be defined by the user at any time, here is a list of the segments that are included in the AFF library. Those values set by aimage are noted.

Name Aimage Description
AF_IGNORE Ignore segments with a zero length name
AF_PAGESIZE Y The size of each page, in bytes
AF_BADFLAG Y Data that is inserted into the image file to mark a bad sector.
AF_DMESG Y The results of the 'dmesg' command are stored in the AFF file.
AF_ACQUISITION_COMMAND_LINE Y The command line used to run the disk imaging program.
AF_ACQUISITION_ISO_COUNTRY Y The ISO country code of the computer used to create the image; set manually at imaging time.
AF_PAGE_MD5 Y The MD5 hash of the current page
AF_ACQUISITION_SECONDS Y The number of seconds used to create the image file.