Differential D16563 Diff 46170 share/man/man5/signed-elf.5

Changeset View

Standalone View

share/man/man5/signed-elf.5

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 SIGNED-ELF 5
				.Os
				.Sh NAME
				.Nm signed-elf
				.Nd "cryptographically signed ELF binaries"
				.Sh DESCRIPTION
				Signed ELF binaries are files in the Executable Linkable Format
				.Pq Xr elf 5
				that contain extra metadata bearing a cryptographic signature that
				allows the contents of the file to be verified against a public key.
				.Ss Format Specification
				The signed ELF format makes use of features intrinsic to the ELF file
				format to store signatures. The signature data for a signed ELF is
				stored in a section named
				.Sy .sign .
				The
				.Sy .sign
				section is similar in
				nature to the
				.Sy .comment
				section and typically will not be included in
				any loadable segment. The signature data itself is stored as a
				DER-encoded CMS detached signature, typically without metadata such
				as certificates and chains, MIME capabilities, attributes, or other
				such extras. The signature is computed in binary mode using the
				contents of the entire file, but with the entire
				.Sy .sign
				section
				containing zero data.
				.Ss Ciphers and Hashes
				The CMS format is designed to allow for a variable selection of
				ciphers. In order to maintain strong security properties, the signed
				ELF specification imposes the following restrictions on ciphers and
				hashes:
				.Bl -bullet -offset indent
				.It
				The allowed hash algorithms are as follows: SHA256, SHA384, SHA512,
				SHA3 (Keccak), Blake-2b, Skein, and Whirlpool. The default hash is
				SHA256.
				.It
				RSA digital signatures are allowed with key lengths of 4096 bits or higher
				.It
				ECDSA/EdDSA signatures are allowed for curves satisfying all of the
				safety properties described by the SafeCurves project (at the time of
				writing, this list consists of the following curves: M-221, E-222,
				Curve1174, Curve25519, E-382, M-383, Curve383187, Curve41417,
				Goldilocks-448, M-511, and E-521).
				.El
				.Pp
				Any signature which does not use an allowed hash and cipher will be
				rejected.
				.Pp
				These restrictions may be changed at a later date, but will generally
				progress in the direction of stronger security properties.
				.Ss Creation and Verification
				The procedure for generating a signature typically requires
				modification of the ELF file. The procedure is as follows:
				.Bl -enum -offset indent
				.It
				The size of the signature is calculated. (This requires that the
				signature size be invariant with respect to the data being signed- a
				property possessed by CMS detached signatures.)
				.It
				The
				.Sy .sign
				section is added and initialized to the proper size. (Often
				times this necessitates the creation of string table and section
				header entries and some file offsets may change as a result.)
				.It
				The
				.Sy .sign
				section is filled with zeros.
				.It
				The signature is computed using the entire file as input.
				.It
				The Signature is written into the
				.Sy .sign
				section in CMS detached
				format using the DER enconding.
				.El
				.Pp
				The verification procedure is as follows:
				.Bl -enum -offset indent
				.It
				The
				.Sy .sign
				section is located, and the CMS detached signature is loaded
				.It
				The
				.Sy .sign
				section is overwritten with zeros.
				.It
				The signature is verified using the entire file as input.
				.El
				.Ss Usage
				Signed ELF files are primarily intended to be verified by mechanisms such as
				.Xr loader 8 ,
				.Xr kldload 8 ,
				.Xr execve 2 ,
				and similar mechanisms as part of a chain-of-trust security protocol
				designed to prevent tampering with executable files, shared libraries,
				kernel modules, and the like. As such, signed ELF files will almost
				always be of the executable or shared object variety, as these are
				typically not modified following their creation. While it is possible
				to sign archives and linkable objects in the same manner, it typically
				makes no sense to do so. The security properties of cryptographic
				signatures prevent even the slightest modification of the data they
				protect, and both linkable objects and archives are specifically
				designed to be modified and composed into final products.
				.Pp
				It should be noted, however, that some applications (often programming
				language runtime systems) are known to (ab)use linkable objects or
				archives in ways that more closely resemble the intended use of
				executable or shared objects: as a runtime-supported executable, as a
				kind of loadable module, or for even more exotic uses. In such cases,
				signing such files may well serve a useful purpose.
				.Sh CERTIFICATES
				Signed ELF files require public-key certificates for verification
				(note that new signatures can only be produced using the corresponding
				private key). The
				.Xr openssl 1
				tool suite provides a number of utilities for creating and managing
				private keys and public-key certificates.
				.Pp
				A FreeBSD installation maintains a set of trusted public key
				certificates to serve as a trust root, and at least one signing key to
				serve as a trust root. The default location for these certificates
				and keys is
				.Pa /etc/trust
				with signing keys being stored in
				.Pa /etc/trust/priv
				and 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
				under
				.Pa /etc/trust/root/priv
				and
				.Pa /etc/trust/root/certs.
				The default public and private keys use for signing locally-produced
				binaries are located at
				.Pa /etc/trust/priv/local.pem
				and
				.Pa /etc/trust/priv/local.pub.pem
				respectively. Additional public key certificates may be stored in
				.Pa /etc/trust/certs
				that have no corresponding private key. This can be used to grant
				trust to binaries produced by a third party.
				.Sh UTILITIES
				There are several ways of creating, modifying, and verifying signed
				ELF binaries.
				.Ss Preferred Method
				The preferred method for creating and verifying signed ELF files is the
				.Xr signelf 8
				utility. (See the man page for usage details.)
				.Ss Signing with Binutils and OpenSSL
				Signed ELF files can also be created and verified using the
				.Xr objcopy 1
				and
				.Xr openssl 1
				utilities. This method can be used in cases where
				.Xr signelf 5
				is not available for some reason, and can also be used to support
				signed ELF files on foreign operating systems.
				.Pp
				A signed ELF file can be created using
				.Xr objcopy 1
				and
				.Xr openssl 1
				with the following procedure:
				.Pp
				First, add the
				.Sy .sign
				section:
				.Pp
				.Dl "$ objcopy --add-section .sign=zeros myexe"
				.Pp
				Where
				.Pa zeros
				is a file exactly as large as a signature which contains zeros. Next,
				sign the binary:
				.Pp
				.Dl "$ openssl cms -sign -outform DER -md sha256 -binary -nosmimecap \\"
				.Dl " -nocerts -noattr -signer cert.pem \\"
				.Dl " -inkey key.pem -in myexe -out signature"
				.Pp
				Last, update the
				.Sy .sign
				section to contain the signature data:
				.Pp
				.Dl "$ objcopy --update-section .sign=signature myexe"
				.Pp
				.Ss Verification with Binutils and OpenSSL
				A signature can be verified with
				.Xr objcopy 1
				and
				.Xr openssl 1
				by the following procedure:
				.Pp
				First, extract the signature:
				.Pp
				.Dl "$ objcopy --update-section .sign=signature myexe"
				.Pp
				Now, zero out the signature:
				.Pp
				.Dl "$ objcopy --update-section .sign=zeros myexe myexe.tmp"
				.Pp
				Last, verify the signature:
				.Pp
				.Dl "$ openssl cms -verify -nointern -inform DER -binary \\"
				.Dl " -in signature -content signelf -certfile cert.pem \\"
				.Dl " -CApath /etc/trust/certs -out /dev/null"
				.Pp
				The check against the system trusted keys can be omitted as follows:
				.Pp
				.Dl "$ openssl cms -verify -nointern -noverify -inform DER -binary \\"
				.Dl " -in signature -content signelf -certfile cert.pem \\"
				.Dl " -out /dev/null"
				.Pp
				.Ss Deleting Signatures
				Lastly, signatures can be deleted from a file using the
				.Xr objcopy 3
				utility:
				.Pp
				.Dl "$ objcopy -R .sign myexe"
				.Pp
				.Sh WARNINGS
				Any modification of a signed ELF binary- 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 ELF 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 sign executables and shared
				objects after at the end of all compilation steps.
				.Pp
				As of the time of writing, it is reasonably likely that quantum
				computing devices capable of attacking public-key ciphers will become
				available in the foreseeable future. Should this become a reality, the
				security of RSA- and ECC-based public key algorithms will be compromised.
				This has major implications for any systems utilizing ELF signatures (or
				public-key cryptography generally): namely that such systems should avoid
				hardwired or burned-in keys, that they should assume keys will be
				periodically changed, and that they should incorporate key expiration
				and revocation into their designs. Additionally, users should assume that
				the cipher suite will undergo significant changes to incorporate post-quantum
				ciphers and remove quantum-vulnerable ones.
				.Sh SEE ALSO
				.Xr trust-config 7 ,
				.Xr elf 5 ,
				.Xr signelf 5 ,
				.Xr openssl 1 ,
				.Xr cms 1 ,
				.Xr objcopy 1
				.Rs
				.%A Hewlett Packard
				.%B Elf-64 Object File Format
				.Re
				.Rs
				.%A Unix System Laboratories
				.%T Object Files
				.%B "Executable and Linking Format (ELF)"
				.Re
				.Rs
				.%A Internet Engineering Task Force (IETF)
				.%B RFC 2315 (CMS)
				.Re
				.Rs
				.%A Daniel J. Bernstein and Tanja Lange.
				.%T SafeCurves: choosing safe curves for elliptic-curve cryptography.
				.%B https://safecurves.cr.yp.to/
				.Re
				.Sh HISTORY
				The signed ELF binary specification first appeared in
				.Fx 12.0 .
				.Sh AUTHORS
				This manual page was written by
				.An Eric L. McCorkle Aq Mt emc2@metricspace.net .