===================================================
OSXPMem - Mac OS X Physical Memory acquisition tool
===================================================

Version: RC3
Supported OS X versions: 10.7 - 10.9.2

Author: Johannes Stuettgen (johannes.stuettgen@gmail.com)

Summary:
========
The OSX Memory Imager is an open source tool to acquire physical memory on an
Intel based Mac. It consists of 2 components:

The usermode acquisition tool 'osxpmem', which parses the accessible sections of
physical memory and writes them to disk in a specific format.

A generic kernel extension 'pmem.kext', that provides read only
access to physical memory. After loading it into the kernel it provides
a device file ('/dev/pmem/'), from which physical memory can be read.

Usage:
======
1. You need root access for this to work so first open a root shell ('sudo su').

2. Now unpack the archive ('tar xvf OSXPMem.tar.gz'). This creates a new
directory 'OSXPMem' containing the binary 'osxpmem', as well as the
kernel extension 'pmem.kext'.

3. Enter the directory you just created ('cd OSXPMem').

4. Run the imager by passing it a file-name for the memory image.
('./osxpmem memory.dump' will create a file named 'memory.dump').

The imager supports multiple output formats, at the moment these are Mach-O, ELF
and zero-padded RAW. You can select which output format to use by passing the
'--format' option. For example to write a Mach-O image you would invoke
'./osxpmem --format mach memory.dump'. The default output format is ELF.

For more information on different command line switches run './osxpmem --help'.

Common Pitfalls:
================
1. Mac OS X only allows kernel extension to load if they are owned by the user
'root' and the group 'wheel'. The distribution package has this already set up
for you. However, if you accidentally extract the archive as a normal user (eg.
omit 'sudo su' before unpacking the tarball), permissions might become
corrupted and the loading of the driver will fail. In this case you can correct
the problem by running 'sudo chown -R root:wheel ./pmem.kext' from within the
'OSXPMem' directory.

2. If you try to run the imager from NFS or another networked file-system,
permissions might also become corrupted. If the imager reports a failure to load
the pmem driver, check the drivers permissions. If it is not owned by user
'root' and group 'wheel' and step 1 can't correct this, try copying it
somewhere else and correct permissions there.

3. When running OSXPmem from an external drive there will most certainly be
permission problems. Some file-systems (e.g. FAT) don't support ownership at all
and OSXPmem just can't load it's kernel extension from there. You will have to
copy the files onto the target system and launch it from there. If you are certain
the file-system supports it you can also enable ownership either in finder by
disabling ("Get Info" -> "Sharing and permissions" -> "Ignore ownership...") or
by running "vsdbutil -a /Volumes/DRIVENAME" where DRIVENAME is the name of the
external drive.

Compatibility:
==============
Due to the nature of physical memory access many things are very platform
dependent. The tool is designed to work on 64 bit Intel Macs. It can probably be
compiled to work in 32 bit mode, the binary distribution however only contains
64 bit binaries.

Several low-level api's have changed in recent OS X versions. We have tested the
imager and driver on OS X 10.7 through 10.9, on which they work flawlessly. It
should also work on 10.6, but might encounter problems unloading the driver, as
the unloading api in IOKit is new in 10.7.

We have also successfully tested the tool in a VMWare Fusion OS X 10.7 machine,
so it should work in virtualized environments.

Building from Source:
=====================
The project can only be built on Mac OS X, due to linking with Apple
libraries and kernel headers. You also need the Apple Developer Kit installed,
the easiest way to obtain this is by installing XCode.

Build the kext and imager with the provided Makefile by running 'make'.
This will create a directory './build' and place the resulting binaries there.

There is also a bash script called 'package.sh', which will build the
kernel extension and the imager, and package them into a compressed tarball.

You might need to adjust the 'SDK_PATH' and 'FRAMEWORK_PATH' in the Makefile, if
they reside in different locations on your build system.

Codesigning:
============
As of OS X 10.9, kernel extensions support codesigning. Unsigned extensions
still load as of 10.9.2, but trigger a warning message to the user. In future
versions, Apple plans to prevent loading of unsigned extensions. The binary
releases of Rekall/PMEM are signed by one of the developers, however, if you
build from source, you will need to supply your own signature.

Codesigning certificates are issued by Apple to members of the Mac Developer
Programme who have been explictly approved for kext development.

