build: improve handling of repository signing keys

Makefile

@@ -59,30 +59,37 @@ CheckTarget := [ -n '$(GLUON_TARGET)' -a -n '$(GLUON_TARGET_$(GLUON_TARGET)_BOAR
 CheckExternal := test -d $(GLUON_ORIGOPENWRTDIR) || (echo 'You don'"'"'t seem to have obtained the external repositories needed by Gluon; please call `make update` first!'; false)
 
 
+create-key: FORCE
+	@$(CheckExternal)
+	+@$(GLUONMAKE_EARLY) create-key
+
 prepare-target: FORCE
 	@$(CheckExternal)
 	@$(CheckTarget)
 	+@$(GLUONMAKE_EARLY) prepare-target
 
-
 all: prepare-target
+	+@$(GLUONMAKE) build-key
 	+@$(GLUONMAKE) prepare
 	+@$(GLUONMAKE) images
 	+@$(GLUONMAKE) modules
 
 prepare: prepare-target
+	+@$(GLUONMAKE) build-key
 	+@$(GLUONMAKE) $@
 
 clean download images modules: FORCE
 	@$(CheckExternal)
 	@$(CheckTarget)
 	+@$(GLUONMAKE_EARLY) maybe-prepare-target
+	+@$(GLUONMAKE) build-key
 	+@$(GLUONMAKE) $@
 
 toolchain/% package/% target/% image/%: FORCE
 	@$(CheckExternal)
 	@$(CheckTarget)
 	+@$(GLUONMAKE_EARLY) maybe-prepare-target
+	+@$(GLUONMAKE) build-key
 	+@$(GLUONMAKE) $@
 
 manifest: FORCE
@@ -170,23 +177,6 @@ GLUON_$(1)_MODEL_$(2)_ALIASES += $(3)
 endef
 
 
-include $(GLUONDIR)/targets/targets.mk
-include $(GLUONDIR)/targets/$(GLUON_TARGET)/profiles.mk
-
-BOARD := $(GLUON_TARGET_$(GLUON_TARGET)_BOARD)
-override SUBTARGET := $(GLUON_TARGET_$(GLUON_TARGET)_SUBTARGET)
-
-target_prepared_stamp := $(BOARD_BUILDDIR)/target-prepared
-gluon_prepared_stamp := $(BOARD_BUILDDIR)/prepared
-
-PREPARED_RELEASE = $$(cat $(gluon_prepared_stamp))
-IMAGE_PREFIX = gluon-$(GLUON_SITE_CODE)-$(PREPARED_RELEASE)
-MODULE_PREFIX = gluon-$(GLUON_SITE_CODE)-$(PREPARED_RELEASE)
-
-
-include $(INCLUDE_DIR)/target.mk
-
-
 prereq: FORCE
 	+$(NO_TRACE_MAKE) prereq
 
@@ -214,7 +204,43 @@ feeds: FORCE
 
 gluon-tools: FORCE
 	+$(GLUONMAKE_EARLY) tools/sed/install
-	+$(GLUONMAKE_EARLY) package/lua/host/install
+	+$(GLUONMAKE_EARLY) package/lua/host/install package/usign/host/install
+
+
+prepare-early: FORCE
+	for dir in build_dir dl staging_dir; do \
+		mkdir -p $(GLUON_ORIGOPENWRTDIR)/$$dir; \
+	done
+
+	+$(GLUONMAKE_EARLY) feeds
+	+$(GLUONMAKE_EARLY) gluon-tools
+
+create-key: prepare-early
+	[ -s $(GLUON_OPKG_KEY) -a -s $(GLUON_OPKG_KEY).pub ] || \
+		$(STAGING_DIR_HOST)/bin/usign -G -s $(GLUON_OPKG_KEY) -p $(GLUON_OPKG_KEY).pub -c "Gluon opkg key"
+
+include $(GLUONDIR)/targets/targets.mk
+
+ifneq ($(GLUON_TARGET),)
+
+include $(GLUONDIR)/targets/$(GLUON_TARGET)/profiles.mk
+
+BOARD := $(GLUON_TARGET_$(GLUON_TARGET)_BOARD)
+override SUBTARGET := $(GLUON_TARGET_$(GLUON_TARGET)_SUBTARGET)
+
+target_prepared_stamp := $(BOARD_BUILDDIR)/target-prepared
+gluon_prepared_stamp := $(BOARD_BUILDDIR)/prepared
+
+PREPARED_RELEASE = $$(cat $(gluon_prepared_stamp))
+IMAGE_PREFIX = gluon-$(GLUON_SITE_CODE)-$(PREPARED_RELEASE)
+MODULE_PREFIX = gluon-$(GLUON_SITE_CODE)-$(PREPARED_RELEASE)
+
+
+include $(INCLUDE_DIR)/target.mk
+
+build-key: FORCE
+	ln -sf $(GLUON_OPKG_KEY) $(BUILD_KEY)
+	ln -sf $(GLUON_OPKG_KEY).pub $(BUILD_KEY).pub
 
 config: FORCE
 	+$(NO_TRACE_MAKE) scripts/config/conf OPENWRT_BUILD= QUIET=0
@@ -234,23 +260,18 @@ config: FORCE
 	) > $(BOARD_BUILDDIR)/config.tmp
 	scripts/config/conf --defconfig=$(BOARD_BUILDDIR)/config.tmp Config.in
 
-prepare-target: FORCE
+prepare-target: create-key
 	rm $(GLUON_OPENWRTDIR)/tmp || true
 	mkdir -p $(GLUON_OPENWRTDIR)/tmp
 
-	for dir in build_dir dl staging_dir; do \
-		mkdir -p $(GLUON_ORIGOPENWRTDIR)/$$dir; \
-	done
 	for link in build_dir config Config.in dl include Makefile package rules.mk scripts staging_dir target toolchain tools; do \
 		ln -sf $(GLUON_ORIGOPENWRTDIR)/$$link $(GLUON_OPENWRTDIR); \
 	done
 
-	+$(GLUONMAKE_EARLY) feeds
-	+$(GLUONMAKE_EARLY) gluon-tools
 	+$(GLUONMAKE) config
 	touch $(target_prepared_stamp)
 
-$(target_prepared_stamp):
+$(target_prepared_stamp): create-key
 	+$(GLUONMAKE_EARLY) prepare-target
 
 maybe-prepare-target: $(target_prepared_stamp)
@@ -443,6 +464,7 @@ manifest: FORCE
 		) : \
 	) >> $(GLUON_BUILDDIR)/$(GLUON_BRANCH).manifest.tmp
 
-.PHONY: all images prepare modules clean gluon-tools manifest
+.PHONY: all create-key prepare images modules clean gluon-tools manifest
 
 endif
+endif

docs/user/getting_started.rst

@@ -109,22 +109,60 @@ will clean the entire tree, so the toolchain will be rebuilt as well, which is
 not necessary in most cases, and will take a while.
 
 
+opkg repositories
+-----------------
+
+Gluon is mostly compatible with OpenWrt, so the normal OpenWrt package repositories
+can be used for Gluon as well. It is advisable to setup a mirror or reverse proxy
+reachable over IPv6 and add it to ``site.conf`` as http://downloads.openwrt.org/ does
+not support IPv6.
+
+This is not true for kernel modules; the Gluon kernel is incompatible with the
+kernel of the default OpenWrt images. Therefore, Gluon will not only generate images,
+but also an opkg repositoy containing all kernel modules provided by OpenWrt/Gluon
+for the kernel of the generated images.
+
+Signing keys
+............
+
+Gluon does not support HTTPS for downloading packages; fortunately, opkg deploys
+public-key cryptography to ensure package integrity.
+
+The Gluon images will contain two public keys: the official OpenWrt signing key
+(to allow installing userspace packages) and a Gluon-specific key (which is used
+to sign the generated module repository).
+
+By default, Gluon will handle the generation and handling of the keys itself.
+When making firmware releases based on Gluon, it might make sense to store the
+the keypair, so updating the module repository later is possible.
+
+The location the keys are stored at and read from can be changed
+(see :ref:`getting-started-environment-variables`). To only generate the keypair
+at the configured location without doing a full build, use ``make create-key``.
+
+.. _getting-started-environment-variables:
+
 Environment variables
 ---------------------
 
 Gluon's build process can be controlled by various environment variables.
 
 GLUON_SITEDIR
-  Path to the site configuration. Defaults to ``site/``.
+  Path to the site configuration. Defaults to ``site``.
 
 GLUON_BUILDDIR
-  Working directory during build. Defaults to ``build/``.
+  Working directory during build. Defaults to ``build``.
+
+GLUON_OPKG_KEY
+  Path key file used to sign the module opkg repository. Defaults to ``$(GLUON_BULDDIR)/gluon-opkg-key``.
+
+  The private key will be stored as ``$(GLUON_OPKG_KEY)``, the public key as ``$(GLUON_OPKG_KEY).pub``.
 
 GLUON_OUTPUTDIR
-  Path where output files will be stored. Defaults to ``output/``.
+  Path where output files will be stored. Defaults to ``output``.
 
 GLUON_IMAGEDIR
-  Path where images will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/images/``.
+  Path where images will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/images``.
 
 GLUON_MODULEDIR
   Path where the kernel module opkg repository will be stored. Defaults to ``$(GLUON_OUTPUTDIR)/modules``.

include/gluon.mk

@@ -11,6 +11,8 @@ GLUON_OUTPUTDIR ?= $(GLUONDIR)/output
 GLUON_IMAGEDIR ?= $(GLUON_OUTPUTDIR)/images
 GLUON_MODULEDIR ?= $(GLUON_OUTPUTDIR)/modules
 
+GLUON_OPKG_KEY ?= $(GLUON_BUILDDIR)/gluon-opkg-key
+
 export GLUONDIR GLUON_SITEDIR GLUON_BUILDDIR GLUON_SITE_CONFIG GLUON_OUTPUTDIR GLUON_IMAGEDIR GLUON_MODULEDIR