Page MenuHomeFreeBSD
Differential D16563 Diff 46170 usr.sbin/signelf/signelf.8

Changeset View

Standalone View

View Options

usr.sbin/signelf/signelf.8

  • This file was added.
.\" Copyright (c) 2017 Eric McCorkle
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD$
.\"
.Dd April 24, 2017
.Dt SIGNELF 8
.Os
.Sh NAME
.Nm signelf
.Nd "sign or verify ELF binaries"
.Sh SYNOPSIS
.Nm
.Cm sign
.Op Fl e Ar ephemeral cert
.Op Fl k Ar private key
.Op Fl p Ar public key cert
.Op Fl v
.Ar files
.Nm
.Cm verify
.Op Fl p Ar public key cert
.Ar files
.Sh DESCRIPTION
The
.Nm
utility signs binary executables and libraries in the Executable
Linkable Format (ELF) and verifies signatures on signed binaries.
Signed ELF binaries carry an additional section containing a
cryptograpic signature, which can be used to verify the contents of
the executable. For details on the format of signed ELF binaries, see the
.Xr signed-elf 5
man page.
.Ss Ephemeral Keys
The
.Nm
utility can generate an ephemeral key-pair for signing a batch of ELF
binaries. After signing is complete, the ephemeral private key will
be discarded (at which point it will be impossible to sign any more
binaries with so that the ephemeral public key can verify them), while
the public key will be written out as a PEM-encoded X509 certificate
and signed with the user-supplied key-pair.
.Sh SUBCOMMANDS
The
.Nm
utility provides two subcommands. The following is a description of
their functioning:
.Pp
.Bl -tag -width 2n
.It Xo
.Nm
.Cm sign
.Op Fl e Ar ecert
.Op Fl k Ar pkey
.Op Fl p Ar pcert
.Op Fl v
.Ar files
.Xc
.Pp
Sign each ELF binary in
.Ar files .
Any existing signatures in
.Ar files
will be overwritten.
.Bl -tag -width indent
.It Fl e
Generate an ephemeral key-pair which will be used to sign the
.Ar files .
Once signing is complete, the ephemeral private key will be destroyed,
while the public key will be output as a PEM-encoded X509 certificate
to
.Ar ecert
and will be signed with the user-supplied key-pair.
.It Fl k
Use the private key in
.Ar pkey
(which must be a PEM-encoded private key or PKCS#8 store) as the
private key for signing binaries or the ephemeral key. If this option
is not provided, the default private key
.Pa /etc/trust/root/priv/local.pem
will be used.
.It Fl p
Use the PEM-encoded X509 certificate
.Ar pcert
as the public key for signing binaries or the ephemeral key. If this
option is not provided, the default public key
.Pa /etc/trust/root/certs/local.pub.pem
will be used.
.It Fl v
Generate verbose output.
.El
.It Xo
.Nm
.Cm verify
.Op Fl p Ar pcert
.Ar files
.Xc
.Pp
Verify signatures on each ELF binary in
.Ar files .
(Note that by default, no output is generated if verification succeeds.)
.Bl -tag -width indent
.It Fl p
Use the PEM-encoded X509 certificate in
.Ar pcert
as the public key for verifying the binaries. If this option is not
provided, the default public key
.Pa /etc/trust/priv/local.pem
will be used.
.It Fl v
Generate verbose output.
.El
.El
.Sh FILES
The default location for signing keys and certificates is
.Pa /etc/trust
with private keys being stored in
.Pa /etc/trust/priv
and corresponding public key certificates in
.Pa /etc/trust/certs
(this allows differing permissions on the two directories), and with
trust root keys and certificates being stored in a similar fashion
in
.Pa /etc/trust/root/priv
and
.Pa /etc/trust/root/certs.
The default private and public keys are located at
.Pa /etc/trust/priv/local.pem
and
.Pa /etc/trust/certs/local.pub.pem
respectively. See the
.Xr trust-config 5
man page for more details.
.Sh WARNINGS
The
.Nm
utility relies on the predictable behaviors of
.Xr binutils 7 ,
.Xr ld 1 ,
and other system utilities used to produce ELF files in the normal
course of compiling and linking programs. The
.Nm
utility should operate reliably on executables and shared objects
produced in such a fashion. However, the ELF format is quite
general, and
.Nm
cannot account for all possible uses of the format. It is
not recommended to attempt to use
.Nm
on any ELF file not produced by the standard means of compiling and
linking programs.
.Pp
Also, once an ELF binary has been signed,
.Sy any
modification of the file- however slight -will cause signature
verification to fail (as intended). Furthermore, due to the nature of
the ELF format, signatures will likely be retained if a signed binary
is used as input to a tool such as
.Xr objcopy 1
or similar utilities, which will result in an ELF binary containing a
bad signature.
.Pp
It is therefore recommended to only use
.Nm
on executables and shared objects after at the end of all compilation steps.
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
The following are examples of typical usage of the
.Nm
utility:
.Ss Signing
.Dl "$ signelf sign myexe"
.Pp
Sign the executable
.Ar myexe
directly using the default key and cert (located at
.Pa /etc/trust/priv/local.pem
and
.Pa /etc/trust/certs/local.pub.pem
respectively).
.Pp
.Dl "$ signelf sign -e ephemeral myexe"
.Pp
Generate an ephemeral signing key and sign the executable
.Ar myexe
using it. The ephemeral key will be signed using the default key and
cert (located at
.Pa /etc/trust/priv/local.pem
and
.Pa /etc/trust/certs/local.pub.pem
respectively) and saved as
.Pa ephemeral
in PEM format. Note that the private key is
.Sy not
retained, meaning the
certificate is only good for verifying signatures.
.Ss Verification
.Dl "$ signelf verify myexe"
.Pp
Verify the signature in the executable
.Ar myexe
using the default cert (located at
.Pa /etc/trust/certs/local.pub.pem
).
.Pp
.Dl "$ signelf verify -p cert.pem myexe"
.Pp
Verify the signature in the executable
.Ar myexe
using the certificate located at
.Pa cert.pem
(this can be used to verify signatures using an ephemeral key's
certificate).
.Ss Removing Signatures
Lastly, signatures can be deleted from a file using the
.Xr objcopy 3
utility:
.Pp
.Dl "$ objcopy -R .sign myexe"
.Ss Using Binutils and OpenSSL
The basic functioning of
.Nm
can be replicated using the
.Xr openssl 1
and
.Xr objcopy 1
utilities. See the
.Qq UTILITIES
section of the
.Xr signed-elf 5
man page for details.
.Sh SEE ALSO
.Xr elf 5 ,
.Xr signed-elf 5 ,
.Xr trust-config 5
.Xr openssl 1 ,
.Xr cms 1
.Sh HISTORY
The
.Nm
utility first appeared in
.Fx 12.0 .
.Sh AUTHORS
This manual page was written by
.An Eric L. McCorkle Aq Mt emc2@metricspace.net .