dh_signobs.1

.TH DH_SIGNOBS: "1" "April 2018" "dh_signobs" "User Commands"
.SH NAME
dh_signobs \- sign EFI/ko files when building on SUSE's OBS.
.SH SYNOPSIS
.B dh\_signobs_pack\fR
.br
.B dh\_signobs_unpack\fR
.br
.B dh\_signobs_getcert\fR
.IR DESTINATION
.RB "[ "
.IR DER
.RB "]"
.br
.SH DESCRIPTION
.SS QUICK GUIDE FOR MAINTAINERS
Build-Depend on \fBdh\-signobs\fR.
.br
Enable by using \fBdh \-\-with=signobs\fR.
.br
If the certificate is necessary at build time, for example to include in the kernel or shim,
annotate the Source stanza of debian/control with:
.br
  \fBXS\-Obs: needssslcertforbuild\fR
.br
Then it can be fetched in PEM format with:
.br
  \fBdh\_signobs_getcert\fR
.IR DESTINATION
.br
Append
.IR DER
to retrieve it in binary format instead.
.SS NOTES
This debhelper will run in 2 steps \- first after the dh_install phase, when the source
package will have built and installed the unsigned binaries. The second step during the
followup build after OBS has signed the binaries, before dh_auto_install runs.

During the first step dh_signobs_pack will be called to get the hashes (or kernel modules)
and pack them into a cpio archive in ../OTHER that OBS can use. At the same time a new
source package for the OBS followup build will be generated, either from a source\-template
that can be specified by the package being signed or automatically generated by this debhelper.

The source template can be in any form it wants, as long as it is placed in a directory
called \fBsource\-template\fR in the debian/ directory (can be a subdirectory, and it can be
static or generated). Also a \fBfiles.json\fR list of the binaries to sign must be placed in the
same \fBparent\fR directory with the following format:
.br
 {"unsigned\-binary\-package": {
.br
	"files": [
.br
		{"sig_type": "efi", "file": "usr/lib/foo/bar.efi"},
.br
		{"sig_type": "linux-module", "file": "lib/modules/1.2.3/baz.ko"}
.br
	]
.br
 }}
.br
The advantage of the templated build is that it can sign only a subset of files \- for
example, a kernel build with CONFIG_MODULE_SIG_ALL=y does not need to sign the modules and
can save a lot of time by just signing the vmlinuz.

The autogenerated package will simply look for any .efi, .ko or vmlinuz- file in the debian
directory (excluding debian/tmp) and considers the first subdirectory to be the package name
(IOW: it covers the common case where built files are first installed in debian/tmp/path and
then moved by dh_install into debian/pkg/path), and then generates a new source package that
unpacks the packages that contain them and repacks them after signing the binaries.
The files.json can be used also with the autogenerated package, simply to restrict the set
of files that get signed, or in case there is an uncommon build directory structure.

During the second step dh_signobs_unpack will be called and it will unpack the signed
binaries that OBS places in the cpio archive in ../SOURCES and it will copy them to
debian/tmp/ respecting the subdirectories path they where picked from (eg: debian/tmp/boot/vmlinuz).

Following common conventions, if an EFI binary has an .efi suffix, a .signed suffix will be
appended. Kernel modules and images will not be renamed.
.SH "SEE ALSO"
\&\fIdh\fR\|(1)
.SH AUTHOR
.PP
Luca Boccassi <bluca@debian.org>