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 special sections 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
34 compiler. The plugin extracts information from the internals of
35 compiler and records them in the object file(s) being produced.
36 Note - the plugin method is just one way of generating the information.
38 Any interested party can create and add information to the object file,
39 providing that they follow the Watermark specification.
40 The information can be extracted from files via the use of tools like
42 "readelf" and "objdump". The "annobin" package itself includes a
43 program called annocheck which can can also examine this information.
44 Details on this program can be found elsewhere in this documentation.
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
52 compiler ("GCC", "clang" or "llvm"). This does mean that files that
53 are not compiled by any of these compilers will not gain any
54 annotations, although there is an optional assembler switch to add some
55 basic notes if none are present in the input files.
56 If the build system being used does not automatically enable the
58 annobin plugin then it can be specifically added to the compiler
59 command line by adding the -fplugin=annobin (for gcc) or
60 -fplugin=annobin-for-clang (for clang) or -fplugin=annobin-for-llvm
61 (for LLVM) option. It may also be necessary to tell the compiler where
62 to find the plugin by adding the -iplugindir= option, although this
63 should only be necessary if the plugin is installed in an unusual
64 place.
65 If it is desired to disable the recording of binary annotations then
67 the -fplugin-arg-annobin-disable (for "gcc") or -Xclang
68 -plugin-arg-annobin-disable (for "clang" or "llvm") can be used. Note
69 - these options must be placed after the -fplugin=annobin option.
70 On Fedora and RHEL systems the plugin can be disabled entirely for all
72 compilations in a package by adding %undefine _annotated_build to the
73 spec file.
74 The information is stored in the ELF Note format in a special section
76 called ".gnu.build.attributes". The "readelf" program from the
77 "binutils" package can extract and display these notes when the --notes
78 option is provided. (Adding the --wide option is also helpful). Here
79 is an example of the output:
80 Displaying notes found in: .gnu.build.attributes
82 Owner Data size Description
83 GA$<version>3p3 0x00000010 OPEN Applies to region from 0x8a0 to 0x8c6 (hello.c)
84 GA$<tool>gcc 7.2.1 20170915 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
85 GA*GOW:0x452b 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
86 GA*<stack prot>strong 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
87 GA*GOW:0x412b 0x00000010 func Applies to region from 0x8c0 to 0x8c6 (baz)
88 This shows various different pieces of information, including the fact
90 that the notes were produced using version 3 of the specification, and
91 version 3 of the plugin. The binary was built by gcc version 7.2.1 and
92 the -fstack-protector-strong option was enabled on the command line.
93 The program was compiled with -O2 enabled except the baz() function
94 which was compiled with -O0 instead.
95 The most complicated part of the notes is the owner field. This is
97 used to encode the type of note as well as its value and possibly extra
98 data as well. The format of the field is explained in detail in the
99 Watermark specification, but it basically consists of the letters G and
100 A followed by an encoding character (one of *$!+) and then a type
101 character and finally the value.
102 The notes are always four byte aligned, even on 64-bit systems. This
104 does mean that consumers of the notes may have to read 8-byte wide
105 values from 4-byte aligned addresses, and that producers of the notes
106 may have to generate unaligned relocs when creating them.
107
109 The plugin accepts a small selection of command line arguments, all
110 accessed by passing -fplugin-arg-annobin-<option> (for "gcc") or
111 -Xclang -plugin-arg-annobin-<option> (for "clang" or "llvm") on the
112 command line. These options must be placed on the command line after
113 the plugin itself is mentioned. Note - not all versions of the plugin
114 accept all of these options. The options are:
115 "disable"
117 "enable"
118 Either disable or enable the plugin. The default is for the plugin
119 to be enabled.
120 "help"
122 Display a list of supported options on the standard output. This
123 is in addition to whatever else the plugin has been instructed to
124 do.
125 "version"
127 Display the version of the plugin on the standard output. This is
128 in addition to whatever else the plugin has been instructed to do.
129 "verbose"
131 Report the actions that the plugin is taking. If invoked for a
132 second time on the command line the plugin will be very verbose.
133 "function-verbose"
135 Report the generation of function specific notes. This indicates
136 that the named function was compiled with different options from
137 those that were globally enabled.
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 "attach"
168 "no-attach"
169 When gcc compiles code with the -ffunction-sections option active
170 it will place each function into its own section. When the annobin
171 attach option is active the plugin will attempt to attach the
172 function section to a group containing the notes and relocations
173 for the function. In that way, if the linker decides to discard
174 the function, it will also know that it should discard the notes
175 and relocations as well.
176 The default is attach, but this can be disabled via the no-attach
178 option. Note however that if both attach and link-order are
179 disabled then note generation for function sections will not work
180 properly.
181 "link-order"
183 "no-link-order"
184 As an alternative to using section groups and a special assembler
185 directive the plugin can use a feature of the ELF "SHF_LINK_ORDER"
186 flag which tells the linker that it should discard a section if the
187 section it is linked to is also being discarded. This behaviour is
188 enabled by the link-order option.
189 "rename"
191 Adds an extra prefix to the symbol names generated by the "annobin"
192 plugin. This allows the plugin to be run twice on the same
193 executable, which can be useful for debugging and build testing.
194 "active-checks"
196 "no-active-checks"
197 The annobin plugin will normally generate a warning message if it
198 detects that the -D_FORTIFY_SOURCE=2 has not been provided on the
199 command line and -flto has been enabled. This is because LTO
200 compilation hides preprocessor options, so information about them
201 cannot be passed on to the annocheck tool.
202 The active-checks option changes the warning message into an error
204 message, just as if -Werror had been specified.
205 The no-active-checks option disables the warning message entirely.
207 Note - in the future the annobin plugin might be extended to
209 produce warning messages for other missing command line options.
210 "dynamic-notes"
212 "no-dynamic-notes"
213 "static-notes"
214 "no-static-notes"
215 These options are deprecated.
216 "ppc64-nops"
218 "no-ppc64-nops"
219 This option either enables or disables the insertion of NOP
220 instructions in the some of the code sections of PowerPC64
221 binaries. This is necessary to avoid problems with the "elflint"
222 program which will complain about binaries built without this
223 option enabled. The option is enabled by default, but since it
224 does increase the size of compiled programs by a small amount, the
225 no-ppc64-nops is provided in order to turn it off.
226
228 Copyright (c) 2018 - 2022 Red Hat.
229 Permission is granted to copy, distribute and/or modify this document
231 under the terms of the GNU Free Documentation License, Version 1.3 or
232 any later version published by the Free Software Foundation; with no
233 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
234 Texts. A copy of the license is included in the section entitled "GNU
235 Free Documentation License".
236annobin-1 2022-03-07 ANNOBIN(1)