Changes/Annobin

Annotated Binaries

Summary

This change causes extra information to be stored in binary files compiled by gcc. This information can be used by scripts to check on various features of the file, such as the hardening options used or potential ABI conflicts.

Owner

• Name: Nick Clifton
• Email: nickc@redhat.com
• Release notes ticket: #83

Current status

• Targeted release: Fedora 28
• Last updated: 2018-03-02

• Tracker bug: #1502660

Detailed Description

The plan is to use a plugin to gcc to record extra information in the object files it creates. This information can then be examined by static analysis tools. The information is recorded in a compact, extensible format, described here:

 https://fedoraproject.org/wiki/Toolchain/Watermark

The Fedora annobin package is an implementation of the plugin for gcc. It also includes some example scripts that demonstrate how the recorded information can be used to, for example, check that an executable has been compiled with the correct hardening options, or detect if any conflicting ABI options have been used when compiling various parts of the executable.

To enable this change it is proposed that the redhat-rpm-config package should be extended to add the "-fplugin=annobin" option to the __global_compiler-flags macro. In theory such a change will be completely invisible to Fedora users but should prove to be very helpful to Fedora Release Management, assuming that they like the idea of these annotated binaries.

Benefit to Fedora

The main improvement is the ability to record extra information in a binary file, beyond the actual code and data needed to make it work.

Whilst this proposal focuses on enhancements that help release engineering, the scheme is not limited to this area. Internally the project has already been used to record gcc unit test results in a binary, so that it is possible to determine which parts of the compiler ran when the binary was created.

Scope

• Proposal owners:

Make sure the annobin plugin is ready.

• Other developers:

An update is needed to the redhat-rpm-config package in order for the plugin to be invoked when gcc is used to compile programs, and to add a dependency upon the annobin package.

• Release engineering: #7069 and #7249
  • Coordination with release engineering is needed.
  • A mass rebuild will be required.

• List of deliverables: All delivered images are affected, however there no changes to the list it self.

• Policies and guidelines: No updates needed

• Trademark approval: N/A (not needed for this Change)

Upgrade/compatibility impact

On systems where the redhat-rpm-config package is installed the annobin package will now be a requirement.

There should be no other migration issues, apart from the possible issue of the size of rpms increasing, due to the extra information being recorded. Note - the rawhide version of the binutils package includes the objcopy tool which could be used to reduce the size of the information recorded in executable by removing redundant, duplicate entries. The use of objcopy in this way is not currently enabled when linking programs, but it could be added if needed.

How To Test

Special hardware is not needed, but the plugin used to record the information is architecture specific. Thus it would be a good idea to run the tests on as many different architectures as are available.

In order to run tests the annobin package will need to be installed. It is also necessary to be able to compile files, so the gcc package will be needed. There should be no need to edit any config files.

To check that the feature is working, compile the file(s) (or build the packages) that form the basis of the test. Make sure that the -fplugin=annobin gcc command line option is being used when the files are compiled. Then check the compiled files to see what information has been recorded. The command line:

 readelf --notes --wide <name-of-file>

should achieve this aim.

The annobin package does include some tests of its own, and these can be used as examples of how to create more tests.

User Experience

N/A (This is a system wide change, but it should have no user visible impact apart from slightly larger rpms).

Dependencies

annobin, gcc, gcc-plugin-devel, pkgconfig, redhat-rpm-config

Contingency Plan

• Contingency mechanism: Revert change to redhat-rpm-macros

• Contingency deadline: beta Freeze

• Blocks release? No

• Blocks product? None

Documentation

The annotation scheme is documented here:

 https://fedoraproject.org/wiki/Toolchain/Watermark

Release Notes

In theory no release notes are needed as this is not a user visible change.

This change definitely is visible to any developer of compiled binary code, which includes several percent of Fedora users. Compiled binary programs become larger by a couple percent, and .a archive libraries of compiled binary subroutines become larger by several percent. Storage space is free until it gets exhausted, and then its cost is very large. This change makes fitting software onto an EEPROM, soldered-on flash memory, mini-CD, etc., more challenging.