.\" Automatically generated by Pod::Man 4.12 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "ANNOBIN 1"
.TH ANNOBIN 1 "2020-01-31" "annobin-1" "RPM Development Tools"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
annobin \- Annobin
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Binary Annotation is a method for recording information about an
application inside the application itself. It is an implementation of
the \f(CW\*(C`Watermark\*(C'\fR specification defined here:
<\fBhttps://fedoraproject.org/wiki/Toolchain/Watermark\fR>
.PP
Although mainly focused on recording security information, the system
can be used to record any kind of data, even data not related to the
application. One of the main goals of the system however is the
ability to specify the address range over which a given piece of
information is valid. So for example it is possible to specify that
all of a program was compiled with the \fB\-O2\fR option except for
one special function which was compiled with \fB\-O0\fR instead.
.PP
The range information is useful because it allows third parties to
examine the binary and find out if its construction was consistent.
\&\s-1IE\s0 that there are no gaps in the recorded information, and no special
cases where a required feature was not active.
.PP
The system works by adding a special section to the application
containing individual pieces of information along with an address
range for which the information is valid. (Some effort has gone into
the storing this information in a reasonably compact format).
.PP
The information is generated by a plugin that is attached to the
compiler (either \f(CW\*(C`gcc\*(C'\fR or \f(CW\*(C`clang\*(C'\fR). The plugin is called
\&\f(CW\*(C`annobin\*(C'\fR and it extracts information from the internals of
compiler and records them in the object file(s) being produced.
.PP
Note \- the plugin method is just one way of generating the
information. Any interested party can create and add information to
the objhect file, providing that they follow the Watermark
specification.
.PP
The information can be extracted from files via the use of tools like
\&\f(CW\*(C`readelf\*(C'\fR and \f(CW\*(C`objdump\*(C'\fR. The \f(CW\*(C`annobin\*(C'\fR package itself
includes a program called \fBannocheck\fR which can can also
examine this information. Details on this program can be found
elsewhere in this documentation.
.PP
Normally the option to enable the recording of binary annotation notes
is enabled automatically by the build system, so no user intervention
is required. On Fedora and \s-1RHEL\s0 based systems this is handled by the
\&\fBredhat-rpm-config\fR package.
.PP
Currently the binary annotations are generated by a plugin to the
\&\f(CW\*(C`GCC\*(C'\fR and \f(CW\*(C`clang\*(C'\fR compilers. This does mean that files
that are not compiled with either of these compilers will not gain any
binary annotations, although there is an optional assembler switch to
add some basic notes if none are present in the input files.
.PP
If the build system being used does not automatically enabled the
\&\fBannobin\fR plugin then it can be specifically added to the compiler
command line by adding the \fB\-fplugin=annobin\fR option. It may
also be necessary to tell the compiler where to find the plugin by
adding the \fB\-iplugindir=\fR option, although this should only be
necessary if the plugin is installed in an unusual place.
.PP
If it is desired to disable the recording of binary annotations then
the \fB\-fplugin\-arg\-annobin\-disable\fR (for \f(CW\*(C`gcc\*(C'\fR) or
\&\fB\-Xclang \-plugin\-arg\-annobin\-disable\fR (for \f(CW\*(C`clang\*(C'\fR) can be
used. Note \- these options must be placed \fIafter\fR the
\&\fB\-fplugin=annobin\fR option.
.PP
On Fedora and \s-1RHEL\s0 systems the plugin can be disabled entirely for all
compilations in a package by adding
\&\fB\f(CB%undefine\fB _annotated_build\fR to the spec file.
.PP
The information is stored in the \s-1ELF\s0 Note format in a special section
called \f(CW\*(C`.gnu.build.attributes\*(C'\fR. The \f(CW\*(C`readelf\*(C'\fR program from
the \f(CW\*(C`binutils\*(C'\fR package can extract and display these notes when
the \fB\-\-notes\fR option is provided. (Adding the \fB\-\-wide\fR
option is also helpful). Here is an example of the output:
.PP
.Vb 7
\& Displaying notes found in: .gnu.build.attributes
\& Owner Data size Description
\& GA$<version>3p3 0x00000010 OPEN Applies to region from 0x8a0 to 0x8c6 (hello.c)
\& GA$<tool>gcc 7.2.1 20170915 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
\& GA*GOW:0x452b 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
\& GA*<stack prot>strong 0x00000000 OPEN Applies to region from 0x8a0 to 0x8c6
\& GA*GOW:0x412b 0x00000010 func Applies to region from 0x8c0 to 0x8c6 (baz)
.Ve
.PP
This shows various different pieces of information, including the fact
that the notes were produced using version 3 of the specification, and
version 3 of the plugin. The binary was built by gcc version 7.2.1
and the \-fstack\-protector\-strong option was enabled on the command
line. The program was compiled with \-O2 enabled except the \fBbaz()\fR
function which was compiled with \-O0 instead.
.PP
The most complicated part of the notes is the owner field. This is
used to encode the type of note as well as its value and possibly
extra data as well. The format of the field is explained in detail in
the Watermark specification, but it basically consists of the letters
\&\fBG\fR and \fBA\fR followed by an encoding character (one of
\&\fB*$!+\fR) and then a type character and finally the value.
.PP
The notes are always four byte aligned, even on 64\-bit systems. This
does mean that consumers of the notes may have to read 8\-byte wide
values from 4\-byte aligned addresses, and that producers of the
notes may have to generate unaligned relocs when creating them.
.SH "OPTIONS"
.IX Header "OPTIONS"
The plugin accepts a small selection of command line arguments,
all accessed by passing
\&\fB\-fplugin\-arg\-annobin\-<option>\fR (for \f(CW\*(C`gcc\*(C'\fR) or
\&\fB\-Xclang \-plugin\-arg\-annobin\-<option>\fR (for \f(CW\*(C`clang\*(C'\fR)
on the command line. These options must be placed on the command
line after the plugin itself is mentioned. The options are:
.ie n .IP """disable""" 4
.el .IP "\f(CWdisable\fR" 4
.IX Item "disable"
.PD 0
.ie n .IP """enable""" 4
.el .IP "\f(CWenable\fR" 4
.IX Item "enable"
.PD
Either disable or enable the plugin. The default is for the plugin to
be enabled.
.ie n .IP """help""" 4
.el .IP "\f(CWhelp\fR" 4
.IX Item "help"
Display a list of supported options on the standard output. This is
in addition to whatever else the plugin has been instructed to do.
.ie n .IP """version""" 4
.el .IP "\f(CWversion\fR" 4
.IX Item "version"
Display the version of the plugin on the standard output. This is
in addition to whatever else the plugin has been instructed to do.
.ie n .IP """verbose""" 4
.el .IP "\f(CWverbose\fR" 4
.IX Item "verbose"
Report the actions that the plugin is taking. If invoked for a second
time on the command line the plugin will be very verbose.
.ie n .IP """function\-verbose""" 4
.el .IP "\f(CWfunction\-verbose\fR" 4
.IX Item "function-verbose"
Report the generation of function specific notes. This indicates that
the named function was compiled with different options from those that
were globally enabled.
.ie n .IP """no\-dynamic\-notes""" 4
.el .IP "\f(CWno\-dynamic\-notes\fR" 4
.IX Item "no-dynamic-notes"
.PD 0
.ie n .IP """dynamic\-notes""" 4
.el .IP "\f(CWdynamic\-notes\fR" 4
.IX Item "dynamic-notes"
.PD
Do not, or do, record information for the dynamic loader. The default
is to record this information.
.ie n .IP """no\-static\-notes""" 4
.el .IP "\f(CWno\-static\-notes\fR" 4
.IX Item "no-static-notes"
.PD 0
.ie n .IP """static\-notes""" 4
.el .IP "\f(CWstatic\-notes\fR" 4
.IX Item "static-notes"
.PD
Do not, or do, record information for static analysis. The default is
to record this information.
.ie n .IP """stack\-size\-notes""" 4
.el .IP "\f(CWstack\-size\-notes\fR" 4
.IX Item "stack-size-notes"
.PD 0
.ie n .IP """no\-stack\-size\-notes""" 4
.el .IP "\f(CWno\-stack\-size\-notes\fR" 4
.IX Item "no-stack-size-notes"
.PD
Do, or do not, record information about the stack requirements of
functions in the executable. This feature is disabled by default as
these notes can take up a lot of extra room if the executable contains
a lot of functions.
.ie n .IP """stack\-threshold=\fIN\fP""" 4
.el .IP "\f(CWstack\-threshold=\f(CIN\f(CW\fR" 4
.IX Item "stack-threshold=N"
If stack size requirements are being recorded then this option sets
the minimum value to record. Functions which require less than
\&\f(CW\*(C`N\*(C'\fR bytes of static stack space will not have their requirements
recorded. If not set, then \f(CW\*(C`N\*(C'\fR defaults to 1024.
.ie n .IP """global\-file\-syms""" 4
.el .IP "\f(CWglobal\-file\-syms\fR" 4
.IX Item "global-file-syms"
.PD 0
.ie n .IP """no\-global\-file\-syms""" 4
.el .IP "\f(CWno\-global\-file\-syms\fR" 4
.IX Item "no-global-file-syms"
.PD
If enabled the \fBglobal-file-syms\fR option will create globally
visible, unique symbols to mark the start and end of the compiled
code. This can be desirable if a program consists of multiple source
files with the same name, or if it links to a library that was built
with source files of the same name as the program itself. The
disadvantage of this feature however is that the unique names are
based upon the time of the build, so repeated builds of the same
source will have different symbol names inside it. This breaks the
functionality of the build-id system which is meant to identify
similar builds created at different times. This feature is disabled
by default, and if enabled can be disabled again via the
\&\fBno-global-file-syms\fR option.
.ie n .IP """attach""" 4
.el .IP "\f(CWattach\fR" 4
.IX Item "attach"
.PD 0
.ie n .IP """no\-attach""" 4
.el .IP "\f(CWno\-attach\fR" 4
.IX Item "no-attach"
.PD
When gcc compiles code with the \fB\-ffunction\-sections\fR option
active it will place each function into its own section. When the
annobin \fBattach\fR option is active the plugin will attempt to
attach the function section to a group containing the notes and
relocations for the function. In that way, if the linker decides to
discard the function, it will also know that it should discard the
notes and relocations as well.
.Sp
The default is to enable \fBattach\fR, but the inverse option is
available in case the host assembler does not support the
\&\fB.attach_to_group\fR pseudo-op. If this feature is disabled then
note generation for function sections will not work properly.
.ie n .IP """rename""" 4
.el .IP "\f(CWrename\fR" 4
.IX Item "rename"
Adds an extra prefix to the symbol names generated by the
\&\f(CW\*(C`annobin\*(C'\fR plugin. This allows the plugin to be run twice on the
same executable, which can be useful for debugging and build testing.
.ie n .IP """active\-checks""" 4
.el .IP "\f(CWactive\-checks\fR" 4
.IX Item "active-checks"
.PD 0
.ie n .IP """no\-active\-checks""" 4
.el .IP "\f(CWno\-active\-checks\fR" 4
.IX Item "no-active-checks"
.PD
The \fBactive-checks\fR option enables compile time checking by
the annobin plugin. The plugin will actively examine the gcc command
line and generate errors if required security options are missing or
have the wrong value. The default is not to perform these checkes.
.Sp
Note \- this option is currently under development, and is not yet
fully functional.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2018 \- 2020 Red Hat.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".