binpkg — a binary installer for Codechain secure packages
binpkg
allows to install binaries as secure packages with
Codechain.
Adding binaries directly to a Codechain secure
package would
increase its size too much and binaries cannot be reviewed in a
meaningful way anyway.
Under normal circumstances building from source is preferable, but in
the rare cases where you want to distributed binaries in a secure and
multiparty reviewed way, you can use binpkg
as follows:
- Add the
.secpkg
file of this binpkg
repository to the .secdep
directory of your package (as binpkg.secpkg
).
- Add a Makefile that calls
binpkg download
for make
,
binpkg install
for make install
, and binpkg uninstall
for
make uninstall
. Also make sure to pass through the $prefix
variable from make
to the -p
option for the binpkg install
and
binpkg uninstall
commands (see Makefile
example).
- Add the configuration file
config.binpkg
as described below.
- Add a distribution file
$GOOS_$GOARCH.binpkg
for every platform
you want to support (with the help of binpkg generate
, see below).
- Upload the distribution archives to the configured web server paths
(as displayed by
binpkg generate
).
- Add all
*.binpkg
files to Codechain, review them, and publish the
secure package.
This ensures multiparty signatures of the hashes of all installed
binaries. Without Reproducible
Builds this just records in an
unmodifiable way which binaries have been pushed by the developers. With
Reproducible Builds these binaries could be audited with the
corresponding source code, but the specifics of such a procedure are
outside of the scope of binpkg
.
Using Codechain secure dependencies allows to extend Codechain with
binary packages without blowing up Codechain itself unnecessarily.
Commands
binpkg download
Download binary package for current platform, see
specification
for details.
binpkg install
Install downloaded binary package for current platform, see
specification
for details.
binpkg uninstall
Uninstall installed binary package for current platform, see
specification
for details.
binpkg generate $bindir
Generate binary package for $bindir
directory, see
specification
for details.
Files and directories
config.binpkg
A binary package configuration file (config.binpkg
) contains a JSON
object with the following keys:
{
"URLs": [
"list of binary package download URLs"
]
}
Example config.binpkg
file:
{
"URLs": [
"http://example.com/binpkg/testpackage",
"http://example.net/binpkg/testpackage",
"http://example.org/binpkg/testpackage"
]
}
$GOOS_$GOARCH.binpkg
files
A $GOOS_$GOARCH.binpkg
file (e.g., linux_amd64.binpkg
) contains a
tree list of
all files in their relative directories and their hashes that are
installed by binpkg install
for this platform.
Example linux_amd64.binpkg
file:
x 1c9d23c245ef06a87f178c5d82221b702084540fe072b329c6a992d6036e6649 bin/testbin
x e39447e1a9d87131b62ee4f5fcfe0bd11aa5a8c545b706424d38ca7a23d24f9c bin/testbin2
.codechain/binpkg
directory tree
binpkg
uses the directory tree under .codechain/binpkg
for temporary
data. By being under the .codechain
hierarchy the temporary data is
excluded from Codechain's hash chain.
.codechain/binpkg/archives
is used for storing package archive files.
.codechain/binpkg/$GOOS_$GOARCH
directories are used to extract
package archives for the corresponding platform in order to check the
contents and prepare for the installation.
path on web server
A common path on a web server would like this:
URL/binpkg/package_name/$GOOS_$GOARCH/treehash.tar.gz
where:
binpkg
is optional.
package_name
is the name of the package (optional).
$GOOS_$GOARCH
is the platform string (mandatory, but not part of
URL in config.binpkg
).
treehash
is the tree
hash in hex
notation (lowercase) of all installed files for this platform and
treehash.tar.gz
contains the corresponding directory tree as a
.tar.gz
archive.
Makefile
example
prefix ?= /usr/local
.PHONY: all install uninstall
all:
binpkg download
install:
binpkg install -p $(prefix)
uninstall:
binpkg uninstall -p $(prefix)