Katana: A Userland Toolchain-Oriented Hotpatching System

Katana aims to provide a hot-patching system for userland. Further it aims to work with existing toolchains and formats so as to be easy to use and to hopefully pave the way for incorporating patching as a standard part of the toolchain. Because of this aim, Katana operates at the object level rather than requiring any access to the source code itself. This has the added bonus of making it, in theory, language agnostic (although no work has been done to test it with anything besides programs written in C). A diagram of software lifecycle with hotpatching is shown below

This document is intended to provide a users guide to Katana, insight into its inner workings, and discussion of its flaws and plans for the future. As the software is not complete, making use of Katana without understanding the inner workings and technical shortcomings is not recommended. Nevertheless, the only sections of this document necessary for "Users' Guide" purposes are "What Katana Does", "What Katana Does Not Do (Yet)", and most importantly "How to Use Katana".

This document is a work in progress. It is not a polished guide yet.

There are other hotpatching systems in existence. The curious are invited to explore Ginseng and Polus. Both of these systems parse the source code, which adds significant complexity to them and results in significant programmer annotation of the code to give hints to the systems. Ginseng uses complicated type-wrappers when patching variables which does not fit cleanly with existing executables and has some impact on the performance of the software. Ginseng is considerably more mature than Katana, however. Neither system is production ready, but Ginseng is probably closer than Katana at the moment.

The system most like Katana in many ways is KSplice, and the curious reader is definitely invited to investigate. KSplice patches the kernel and not userland, does not attempt to patch variables, and creates patches as kernel modules rather than working towards a general ELF-based patch format.

• Runs on x86 and x86-64
• Generates patches for simple programs
• Applies simple patches

• Patch any major programs: it has not yet been demonstrated on anything more than toy examples
• Provide any method to handle opaque data it cannot patch (void*, situations where which action a user would prefer is unclear, etc)
• Patch previously patched processes
• Provide robust operation
• Run on any architectures other than x86 and x86-64
• Tested on any operating system besides GNU/Linux
• Allow for calls in patched code to previously unused functions
• Work for programs which actually make use of some of the large code model features of the x86-64 ABI.
• And much more

See Roadmap for more things which are not complete

• Work on any binary formats besides ELF

Katana is intended to be used in two stages. The first stage generates a patch object from two different versions of an treee. By an object tree, we mean the set of object files (.o files) and the executable binary they comprise. Katana works completely at the object level, so the source code itself is not strictly required, although all objects must be compiled with debugging information. This step may be done by the software vendor. In the second stage, the patch is applied to a running process. The original source trees are not necessary during patch application, as the patch object contains all information necessary to patch the in-memory process at the object level. It is also possible to view the contents of a patch object in a human-readable way for the purposes of sanity-checking, determining what changes the patch makes, etc.

This section of the document is not yet written. It will provide a description and specification of the PO format used by Katana

This section of the document is not yet written. It will provide a description of the internal process that Katana uses to generate a patch. Understanding it is not necessary for using Katana.

This section of the document is not yet written. It will provide a description of the internal process that Katana uses to apply a patch. Understanding it is not necessary for using Katana.

This section is highly incomplete. Future goals include

• Better interaction with the heap and dynamically allocated variables
• Better interaction with void*
• More efficient use of .rodata
• Patching already patched processes
• Patch composition
• Patch safety checking: make sure a patch actually corresponds to the process it's being applied to
• Storing warnings from generation inside a patch

Katana is under development at Dartmouth College and Copyright 2010 Dartmouth College. It may be distributed under the terms of the GNU General Public License with attribution to Dartmouth College as specified in the file COPYING distributed with Katana. This document is Copyright 2010 Dartmouth College and may be distributed under the terms of the GNU Free Documentation License as found in the file FDL which should have been distributed with this documentation. If it was not, it may be found at http://www.gnu.org/licenses/fdl.txt.

Katana is being written by James Oakley and was designed by Sergey Bratus, Ashwin Ramaswamy, James Oakley, Michael Locasto, and Sean Smith.