Add mTLS instructions
Change-Id: I4ac2896fa8d46418dbb08df9d9c08466fb51fdad
diff --git a/.gitignore b/.gitignore
index e781b44..1d8baba 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,7 @@
ipxe
out/*
+
+# ignore crypto
+*.key
+*.pem
diff --git a/Makefile b/Makefile
index d8acfdb..759d9ac 100644
--- a/Makefile
+++ b/Makefile
@@ -30,19 +30,21 @@
base: | ipxe ## create bas iPXE build container using Docker
docker build . -t ipxe-builder:$(IPXE_VERSION)
-image: | out base ## create iPXE binary artifacts using Docker
+image: | out base ## create iPXE binary artifacts using Docker
docker run -v $(OUTDIR):/tmp/out --name $(BUILDER) -d ipxe-builder:$(IPXE_VERSION)
- docker cp $(COPY_FILES) $(BUILDER):/ipxe/src/
+ for file in $(COPY_FILES); do \
+ docker cp $$file $(BUILDER):/ipxe/src/ ;\
+ done
docker exec -w /ipxe/src $(BUILDER) \
bash -c "make -j4 $(TARGETS) $(OPTIONS); cp $(TARGETS) /tmp/out"
docker rm --force $(BUILDER)
test: image ## test (currently only runs an image build)
-clean: ## remove output artifacts
+clean: ## remove output artifacts
rm -rf out/*
-clean-all: clean ## full clean (delete iPXE git repo)
+clean-all: clean ## full clean (delete iPXE git repo)
rm -rf ipxe
license: ## check licenses
diff --git a/README.md b/README.md
index 6946ec7..f8f8cf6 100644
--- a/README.md
+++ b/README.md
@@ -7,32 +7,54 @@
This repo will builds an [iPXE](https://ipxe.org/) payload that can be used for
network booting of systems.
-It uses Docker to build iPXE, wrapping [all build
+
+Docker is used to build iPXE, wrapping [all build
dependencies](https://ipxe.org/download#source_code) in the Dockerfile, An
[embedded script](https://ipxe.org/embed) (`chain.ipxe`) is added which will
-chainload a complicated iPXE script with menus and other configurations.
+chainload another iPXE script from a remote HTTP server and continue the boot
+process.
-iPXE is patched to give it [HTTPS
-Support](https://ipxe.org/buildcfg/download_proto_https).
+The chainloaded iPXE script is configured in the pxeboot role repo, which
+describes the menu, downloads boot images, etc.
-# Requirements
+## Requirements
- git
- make
- Docker
-# Usage
+## Usage
Run `make image`, artifacts will be created in `out`. By default it will build:
- `undionly.kxpe` - Can be served by a DHCP server and chainloads with the
- NIC's built in PXE implementation
+ NIC's built in PXE and network driver implementation
- `ipxe.usb` - write to a USB stick with `dd if=bin/ipxe.usb of=/dev/<rawdevice>`
See also [build targets](https://ipxe.org/appnote/buildtargets).
-## TODO
+## Mutual TLS
-- Add a [TLS Server and Client cert](https://ipxe.org/crypto) into the image,
- to allow trust to be established between systems.
+Mutual TLS can be used secure the connection between the iPXE payload and
+and images.
+
+Using mTLS requires [cryptography support](https://ipxe.org/crypto) to be added
+to the generated binaries. A patch is included that enables [HTTPS
+Support](https://ipxe.org/buildcfg/download_proto_https).
+
+To use this support, the CA key, and public/private client keys must copied and
+built into the iPXE artifacts. As the private client keys are embedded, care
+must be taken with the resulting artifacts.
+
+Steps:
+
+1. Modify the chain.ipxe file to use the mTLS HTTPS URL
+
+2. Put the CA public key (ca.pem), Client public key (client.pem) and
+ private key (client.key) in the same directory
+
+2. Build the artifacts incorporating all these files using Makefile options:
+
+ make COPY_FILES="chain.ipxe ca.pem client.pem client.key" OPTIONS="EMBED=chain.ipxe CERT=ca.pem,client.pem TRUST=onfca.pem
+PRIVKEY=client.key"
diff --git a/chain.ipxe b/chain.ipxe
index fa49bb3..3d2b840 100644
--- a/chain.ipxe
+++ b/chain.ipxe
@@ -6,4 +6,4 @@
dhcp
# chainload netboot.ipxe, or drop to shell if it doesn't exist
-chain http://boot.tucson.onlab.us/boot.ipxe || shell
+chain https://boot.tucson.onlab.us:2443/boot.ipxe || shell