1ANNOBIN(1)                   RPM Development Tools                  ANNOBIN(1)
2
3
4

NAME

6       annobin - Annobin
7

SYNOPSIS

DESCRIPTION

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
15       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
23       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
28       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
33       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
41       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
46       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
51       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
57       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
64       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
68       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
72       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
77       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
83               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
91       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
98       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
105       The notes are always four byte aligned, even on 64-bit systems.  This
106       does mean that consumers of the notes may have to read 8-byte wide
107       values from 4-byte aligned addresses, and that producers of the notes
108       may have to generate unaligned relocs when creating them.
109

OPTIONS

111       "disable"
112       "enable"
113           Either disable or enable the plugin.  The default is for the plugin
114           to be enabled.
115
116       "help"
117           Display a list of supported options on the standard output.  This
118           is in addition to whatever else the plugin has been instructed to
119           do.
120
121       "version"
122           Display the version of the plugin on the standard output.  This is
123           in addition to whatever else the plugin has been instructed to do.
124
125       "verbose"
126           Report the actions that the plugin is taking.  If invoked for a
127           second time on the command line the plugin will be very verbose.
128
129       "function-verbose"
130           Report the generation of function specific notes.  This indicates
131           that the named function was compiled with different options from
132           those that were globally enabled.
133
134       "no-dynamic-notes"
135       "dynamic-notes"
136           Do not, or do, record information for the dynamic loader.  The
137           default is to record this information.
138
139       "no-static-notes"
140       "static-notes"
141           Do not, or do, record information for static analysis.  The default
142           is to record this information.
143
144       "stack-size-notes"
145       "no-stack-size-notes"
146           Do, or do not, record information about the stack requirements of
147           functions in the executable.  This feature is disabled by default
148           as these notes can take up a lot of extra room if the executable
149           contains a lot of functions.
150
151       "stack-threshold=N"
152           If stack size requirements are being recorded then this option sets
153           the minimum value to record.  Functions which require less than "N"
154           bytes of static stack space will not have their requirements
155           recorded.  If not set, then "N" defaults to 1024.
156
157       "global-file-syms"
158       "no-global-file-syms"
159           If enabled the global-file-syms option will create globally
160           visible, unique symbols to mark the start and end of the compiled
161           code.  This can be desirable if a program consists of multiple
162           source files with the same name, or if it links to a library that
163           was built with source files of the same name as the program itself.
164           The disadvantage of this feature however is that the unique names
165           are based upon the time of the build, so repeated builds of the
166           same source will have different symbol names inside it.  This
167           breaks the functionality of the build-id system which is meant to
168           identify similar builds created at different times.  This feature
169           is disabled by default, and if enabled can be disabled again via
170           the no-global-file-syms option.
171
172       "attach"
173       "no-attach"
174           When gcc compiles code with the -ffunction-sections option active
175           it will place each function into its own section.  When the annobin
176           attach option is active the plugin will attempt to attach the
177           function section to a group containing the notes and relocations
178           for the function.  In that way, if the linker decides to discard
179           the function, it will also know that it should discard the notes
180           and relocations as well.
181
182           The default is to enable attach, but the inverse option is
183           available in case the host assembler does not support the
184           .attach_to_group pseudo-op.  If this feature is disabled then note
185           generation for function sections will not work properly.
186
187       "rename"
188           Adds an extra prefix to the symbol names generated by the "annobin"
189           plugin.  This allows the plugin to be run twice on the same
190           executable, which can be useful for debugging and build testing.
191
192       "active-checks"
193       "no-active-checks"
194           The active-checks option enables compile time checking by the
195           annobin plugin.  The plugin will actively examine the gcc command
196           line and generate errors if required security options are missing
197           or have the wrong value.  The default is not to perform these
198           checkes.
199
200           Note - this option is currently under development, and is not yet
201           fully functional.
202
204       Copyright (c) 2018 - 2019 Red Hat.
205
206       Permission is granted to copy, distribute and/or modify this document
207       under the terms of the GNU Free Documentation License, Version 1.3 or
208       any later version published by the Free Software Foundation; with no
209       Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
210       Texts.  A copy of the license is included in the section entitled "GNU
211       Free Documentation License".
212
213
214
215annobin-1                         2019-01-24                        ANNOBIN(1)
Impressum