Translation(s): none


What is all this about?

dpkg-buildflags allows a uniform setting of default build flags for code written in C and C++. If your package is written in Java, pure Python, pure Perl or shell you don't need to do anything. Good, isn't it?

Default build flags have a number of benefits:

Enabling dpkg-buildflags in your package is two-fold. On the one hand you need to activate the flags your debian/rules file, on the other hand you need to ensure that the buildsystem of your code abides the necessary flags.

Selecting security hardening options

The standard build flags for Wheezy include the following

These hardening features are explained in more depth here.

Additionally there are two features, which are not enabled by default:

It is recommended to test, whether these two options work with your package and enable them if everything works fine. You can enable them by adding this your rules file:

export DEB_BUILD_MAINT_OPTIONS = hardening=+all

Enabling dpkg-buildflags in your debian/rules files

rules files based on debhelper and minimised dh(1)

debhelper 9

If you use debhelper dh(1) v9 format (value 9 in debian/compat), it takes care of the hardened build flags:

In case you want to add more flags to the defaults, use something like this at the top of debian/rules:

# To enable all, uncomment following line
# export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND  = -Wall -pedantic
export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

Don't use *_SET or it overwrites the default hardening flags.

This works fine with buildflags.mk as well.

Older debhelper

If you want to stay with earlier compat levels, you can still inject the build flags by passing them to dh_auto_configure, e.g.

override_dh_auto_configure:
       dh_auto_configure -- $(shell dpkg-buildflags --export=configure)

rules files based on standard debhelper or hand-written rules files

If your build file uses the standard debhelper format, the way of injecting the flags depends on your build system. If it's based on the autotools, passing the exported form of dpkg-buildflags to the configure script is usually needed, e.g.

../configure --prefix=/usr $(shell dpkg-buildflags --export=configure) 

If your build system reads the values from standard environment variables like CFLAGS, CXXFLAGS, CPPFLAGS or LDFLAGS, you often need to export these values at the beginning of your rules files. The simplest way to achieve this is to include the following snippet from dpkg at the beginning of your rules file to export all needed flags:

DPKG_EXPORT_BUILDFLAGS = 1
include /usr/share/dpkg/buildflags.mk

rules files based on cdbs

cdbs already exports all dpkg-buildflags. If your package uses cdbs you will usually only need to verify, whether your upstream buildsystem properly follows these flags. (The cdbs bug bug 651964 about missing CPPFLAGS and LDFLAGS was fixed.)

cdbs doesn't support DEB_*_MAINT_APPEND and DEB_BUILD_MAINT_OPTIONS directly, you must use buildflags.mk. For example:

export DEB_BUILD_MAINT_OPTIONS = hardening=+all
export DEB_CFLAGS_MAINT_APPEND = -Wall
include /usr/share/dpkg/buildflags.mk

Handling dpkg-buildflags in your upstream build system

To fully support all hardened build flags in your upstream buildsystem, please ensure that the following flags are supported:

buildsystems based on the autotools

If your buildsystem is based on autotools it usually requires no further modifications. If might however occur that some variables are hard-coded in one of the Makefile.in files. An examples for this can be found at bug 655870

Handwritten Makefiles

If your package uses a home-grown buildsystems you first need to check, whether it abides the above-mentioned flags. If not, you can either add the dpkg-buildflags calls directly as part of your Debian-specific modifications. Another solution would to fix the Makefiles to source an already existing environment variable.

Many home-grown Makefiles already support CFLAGS and LDFLAGS, but not CPPFLAGS. In most cases you can simply append CPPFLAGS to CFLAGS, e.g.

CFLAGS = `dpkg-buildflags --get CFLAGS`
CFLAGS += `dpkg-buildflags --get CPPFLAGS`

buildsystems for Perl modules

Debhelper has been modified so that the hardened build flags are passed to ?ExtUtils::?MakeMaker and ?ExtUtils::CBuilder, so that most Perl modules should receive hardened build flags once bumped to debhelper level 9. Note that this requires building with debhelper (>= 9.20120312). Note that the dh_auto* minimal rules files need to be used to make use of this.

See more discussion at bug 662666

buildsystems using cmake

cmake doesn't follow CPPFLAGS. A fix was briefly available in sid, but had been revoked since upstream rejected the patch. See bug 653916 for details. As a workaround appending CPPFLAGS to CFLAGS and CXXFLAGS should work in most cases. Debhelper (since 0.9.20120417, only with compat=9 and dh_auto* commands!) and cdbs (since 0.4.110) handle this automatically so the workaround is no longer necessary if they are used.

Testing your packages after conversion

"hardening-check" from the "hardening-includes" allows testing a binary, whether hardening options have been properly enabled. If you're using only the default flags emitted by dpkg-buildflags, you should see "Stack protected", "Fortify Source functions" and "Read-only relocations" marked as "Yes", e.g.

jmm@pisco:~$ hardening-check /usr/bin/emacs23
/usr/bin/emacs23:
 Position Independent Executable: no, normal executable!
 Stack protected: yes
 Fortify Source functions: yes (some protected functions found)
 Read-only relocations: yes
 Immediate binding: no not found!

In some cases, "Stack protected" and "Fortify Source functions" emit false positives, see these notes from hardening-check's manpage:

If a package has enabled all flags, the output should look like this:

jmm@pisco:~$ hardening-check /usr/sbin/sshd
/usr/sbin/sshd:
 Position Independent Executable: yes
 Stack protected: yes
 Fortify Source functions: yes (some protected functions found)
 Read-only relocations: yes
 Immediate binding: yes

hardening-check can only check the resulting binaries and thus might not catch missing hardening flags if they are only missing in a few places. blhc is a small parser written in Perl which checks the build logs for missing hardening flags. It can be used on build logs created by dpkg-buildpackage or buildd.

Example usage:

$ blhc /path/to/log/file

Common questions / problems

My package already uses hardening-wrapper or hardening-includes. Should I switch to dpkg-buildflags?

Yes. Both are still available, but it is advised to convert to dpkg-buildflags instead, since it's a more generalised solution to the problem and is also useful beyond security hardening.

My package builds with optimisation flags other than -O2, e.g. -Os

You can add the following to your rules before before invoking dpkg-buildflags

DEB_CFLAGS_MAINT_APPEND=-Os

How can I use additional flags?

To set additional flags, e.g. -Wl,--as--needed for LDFLAGS, use the new DEB_*_MAINT_APPEND variables (man dpkg-buildflags for more information). Don't use DEB_*_MAINT_SET as it overwrites the default hardening flags. DEB_*_APPEND (without the _MAINT) is not for debian/rules, always use *_MAINT_*.

debhelper 9/buildflags.mk

export DEB_LDFLAGS_MAINT_APPEND = -Wl,--as-needed

Don't use something like export LDFLAGS += -Wl,--as-needed, the export will overwrite the default LDFLAGS hardening flags.

dpkg-buildflags

make's $(shell) doesn't use local variables, thus you have to define a custom command:

dpkg_buildflags = DEB_LDFLAGS_MAINT_APPEND="-Wl,--as-needed" dpkg-buildflags
...
./configure $(shell $(dpkg_buildflags) --export=configure)

Are there example patches?

Many of the bugs filed for the hardening flags Wheezy release goal have patches attached.

And more hardening details are explained in Hardening.

How can I use this and keep my packages backportable to Squeeze?

squeeze-backports includes a backport of 1.16.1.1, so all should be fine.

Additionally, dpkg-buildflags already existed in plain Squeeze (emitting only flags w/o hardening:

$ dpkg-buildflags --get CFLAGS
-g -O2
$ dpkg-buildflags --get CPPFLAGS

$ dpkg-buildflags --get LDFLAGS

$ dpkg-buildflags --get CXXFLAGS
-g -O2

Most of the convenience functions (/usr/share/dpkg/buildflags.mk and dpkg-buildflags --export=configure) don't exist yet, though. As such, you need to export your flags like this:

CFLAGS:=$(shell dpkg-buildflags --get CFLAGS)
CPPFLAGS:=$(shell dpkg-buildflags --get CPPFLAGS)
LDFLAGS:=$(shell dpkg-buildflags --get LDFLAGS)

Is there a lintian test?

A lintian test is in preparation, see this bug to monitor the progress.

My package isn't security-sensitive, should I still convert it?

Yes. dpkg-buildflags easies rebuilding Debian with modified build flags and is useful to spot long-standing bugs in your packages, see this blog posting on Planet Debian for an example.

My package is (partly) written in OCaml

The OCaml runtime itself must be hardened first. For the time being, do nothing elsewhere (especially do not override Lintian tags).

See http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=702349#19