1ANNOBIN(1) RPM Development Tools ANNOBIN(1)
2
6 annobin - Annobin
7
10 Binary Annotation is a method for recording information about an
11 application inside the application itself. It is an implementation of
12 the "Watermark" specification defined here:
13 <https://fedoraproject.org/wiki/Toolchain/Watermark>
14 Although mainly focused on recording security information, the system
16 can be used to record any kind of data, even data not related to the
17 application. One of the main goals of the system however is the
18 ability to specify the address range over which a given piece of
19 information is valid. So for example it is possible to specify that
20 all of a program was compiled with the -O2 option except for one
21 special function which was compiled with -O0 instead.
22 The range information is useful because it allows third parties to
24 examine the binary and find out if its construction was consistent. IE
25 that there are no gaps in the recorded information, and no special
26 cases where a required feature was not active.
27 The system works by adding a special section to the application
29 containing individual pieces of information along with an address range
30 for which the information is valid. (Some effort has gone into the
31 storing this information in a reasonably compact format).
32 The information is generated by a plugin that is attached to the "gcc"
34 compiler. (This is just one method for generating the information.
35 Any interested party can create and add information to the binary,
36 providing that they follow the Watermark specification). This plugin
37 is called "annobin". It uses information obtained from the compiler to
38 record details such as the ABI variant in use and the hardening options
39 applied.
40 The information can be extracted from files via the use of tools like
42 "readelf". The "annobin" package includes a program called annocheck
43 which can check various features of an application, such as its
44 conformation to the hardening requirements, or possible ABI violations.
45 Normally the option to enable the recording of binary annotation notes
47 is enabled automatically by the build system, so no user intervention
48 is required. On Fedora and RHEL based systems this is handled by the
49 redhat-rpm-config package.
50 Currently the binary annotations are generated by a plugin to the "GCC"
52 compiler called annobin. This does mean that files that are not
53 compiled with "GCC" will not gain any binary annotations, although
54 there is an optional assembler switch to add some basic notes if none
55 are present in the input files.
56 If the build system being used does not automatically enabled the
58 annobin plugin then it can be specifically added to the gcc command
59 line by adding the -fplugin=annobin option. It may also be necessary
60 to tell gcc where to find plugins by adding the -iplugindir= option,
61 although this should only be necessary if the plugin is installed in a
62 separate place from "gcc".
63 If it is desired to disable the recording of binary annotations then
65 the -fplugin-arg-annobin-disable can be used, although this must be
66 placed after the -fplugin=annobin option.
67 On Fedora and RHEL systems the plugin can be disabled entirely for all
69 compilations in a package by adding %undefine _annotated_build to the
70 spec file.
71 The plugin also accepts a small selection of command line arguments,
73 all accessed by passing -fplugin-arg-annobin-<option> on the gcc
74 command line. These options must be placed on the gcc command line
75 after the plugin itself is mentioned. The options are:
76 The information is stored in the ELF Note format in a special section
78 called ".gnu.build.attributes". The "readelf" program from the
79 "binutils" package can extract and display these notes when the --notes
80 option is provided. (Adding the --wide option is also helpful). Here
81 is an example of the output:
82 Displaying notes found in: .gnu.build.attributes
84 Owner Data size Description
85 GA$<version>3p3 0x00000010 OPEN Applies to region from 0x8a0 to 0x8c6 (hello.c)
86 GA$<tool>gcc 7.2.1 20170915 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
87 GA*GOW:0x452b 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
88 GA*<stack prot>strong 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
89 GA*GOW:0x412b 0x00000010 func Applies to region from 0x8c0 to 0x8c6 (baz)
90 This shows various different pieces of information, including the fact
92 that the notes were produced using version 3 of the specification, and
93 version 3 of the plugin. The binary was built by gcc version 7.2.1 and
94 the -fstack-protector-strong option was enabled on the command line.
95 The program was compiled with -O2 enabled except the baz() function
96 which was compiled with -O0 instead.
97 The most complicated part of the notes is the owner field. This is
99 used to encode the type of note as well as its value and possibly extra
100 data as well. The format of the field is explained in detail in the
101 Watermark specification, but it basically consists of the letters G and
102 A followed by an encoding character (one of *$!+) and then a type
103 character and finally the value.
104
106 "disable"
107 "enable"
108 Either disable or enable the plugin. The default is for the plugin
109 to be enabled.
110 "help"
112 Display a list of supported options on the standard output. This
113 is in addition to whatever else the plugin has been instructed to
114 do.
115 "version"
117 Display the version of the plugin on the standard output. This is
118 in addition to whatever else the plugin has been instructed to do.
119 "verbose"
121 Report the actions that the plugin is taking. If invoked for a
122 second time on the command line the plugin will be very verbose.
123 "function-verbose"
125 Report the generation of function specific notes. This indicates
126 that the named function was compiled with different options from
127 those that were globally enabled.
128 "no-dynamic-notes"
130 "dynamic-notes"
131 Do not, or do, record information for the dynamic loader. The
132 default is to record this information.
133 "no-static-notes"
135 "static-notes"
136 Do not, or do, record information for static analysis. The default
137 is to record this information.
138 "stack-size-notes"
140 "no-stack-size-notes"
141 Do, or do not, record information about the stack requirements of
142 functions in the executable. This feature is disabled by default
143 as these notes can take up a lot of extra room if the executable
144 contains a lot of functions.
145 "stack-threshold=N"
147 If stack size requirements are being recorded then this option sets
148 the minimum value to record. Functions which require less than "N"
149 bytes of static stack space will not have their requirements
150 recorded. If not set, then "N" defaults to 1024.
151 "global-file-syms"
153 "no-global-file-syms"
154 If enabled the global-file-syms option will create globally
155 visible, unique symbols to mark the start and end of the compiled
156 code. This can be desirable if a program consists of multiple
157 source files with the same name, or if it links to a library that
158 was built with source files of the same name as the program itself.
159 The disadvantage of this feature however is that the unique names
160 are based upon the time of the build, so repeated builds of the
161 same source will have different symbol names inside it. This
162 breaks the functionality of the build-id system which is meant to
163 identify similar builds created at different times. This feature
164 is disabled by default, and if enabled can be disabled again via
165 the no-global-file-syms option.
166
168 Copyright (c) 2018 Red Hat.
169 Permission is granted to copy, distribute and/or modify this document
171 under the terms of the GNU Free Documentation License, Version 1.3 or
172 any later version published by the Free Software Foundation; with no
173 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
174 Texts. A copy of the license is included in the section entitled "GNU
175 Free Documentation License".
176annobin-1 2018-08-07 ANNOBIN(1)