Skip to content

Commit 2d8d0b6

Browse files
doanacdoanac
committed
Add documentation for manufacturing device registration
Signed-off-by: Andy Doan <[email protected]>
1 parent d4607c3 commit 2d8d0b6

File tree

2 files changed

+118
-0
lines changed

2 files changed

+118
-0
lines changed

‎source/reference-manual/security/factory-registration-ref.rst‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
.. _ref-factory-registration-ref:
2+
3+
Manufacturing Process for Device Registration
4+
=============================================
5+
6+
lmp-device-register works great when run manually and can be configured
7+
to auto register devices in **CI**
8+
:ref:`builds <ug-configure-lmp_lmp-device-auto-register>`. However,
9+
a different process is required for provisioning production devices.
10+
The key to production provisioning lies in owning the
11+
:ref:`device gateway PKI <ref-device-gateway>`. Once a customer has
12+
control of their PKI, they can create client TLS certificates for
13+
devices that will be trusted by the Foundries.io device gateway.
14+
15+
Customers all have unique requirements, so Foundries.io created a
16+
`reference implementation`_ that customers can fork and modify to
17+
their liking. Here are some common ways to use this reference.
18+
19+
Fully detached
20+
--------------
21+
In this scenario devices connect to a reference server instance on
22+
a private network. This network is isolated from the internet
23+
(api.foundries.io). Devices get a valid signed client certificate from
24+
the reference server. Each device will be created via api.foundries.io
25+
**on-the-fly** the first time they connect.
26+
27+
This scenario is handy for certain security constrained setups. However,
28+
it does have a couple of potential drawbacks:
29+
30+
* Devices don't show up on Foundries.io until the first time
31+
they connect.
32+
33+
* Devices won't have Foundries.io managed configuration data available
34+
until this first connection.
35+
36+
lmp-device-auto-register configuration
37+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
38+
lmp-device-register must be called with two environment variables
39+
set to work with the reference server::
40+
41+
DEVICE_API="http://<registration reference uri>/sign"
42+
PRODUCTION=1
43+
44+
A factory can copy `lmp-device-auto-register`_ into their
45+
meta-subscriber-overrides.git production branch as
46+
``recipes-support/lmp-device-auto-register/lmp-device-auto-register/lmp-device-auto-register``
47+
with ``DEVICE_API`` and ``PRODUCTION`` exported.
48+
49+
The factory should also make sure the
50+
``recipes-support/lmp-device-auto-register/lmp-device-auto-register/api-token``
51+
has been removed to prevent leaking a CI credential.
52+
53+
Registration reference configuration
54+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55+
The registration reference should work out-of-the box for this scenario.
56+
The operator simply needs to copy their PKI keys as described in the
57+
reference server's README.md.
58+
59+
Partially detached
60+
------------------
61+
In this scenario devices connect to a reference server instance on
62+
a private network, but the reference server has access to
63+
api.foundries.io. The reference server can create device entries via
64+
api.foundries.io as devices are registered.
65+
66+
Additionally, if devices have access to ota-lite.foundries.io:8443,
67+
they can download their initial fioconfig configuration data.
68+
69+
lmp-device-auto-register configuration
70+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71+
A factory can create a customized lmp-device-auto-register in their
72+
meta-subscriber-overrides.git production branch as
73+
``recipes-support/lmp-device-auto-register/lmp-device-auto-register/lmp-device-auto-register``.
74+
For example::
75+
76+
#!/bin/sh -e
77+
78+
if [ -f /var/sota/sql.db ] ; then
79+
echo "$0: ERROR: Device appears to already be registered"
80+
exit 1
81+
fi
82+
83+
# Done in 2 parts. This first part will remove trailing \n's and make
84+
# the output all space separated. The 2nd part makes it comma separated.
85+
[ -d /var/sota/compose-apps ] && APPS=$(ls /var/sota/compose-apps)
86+
APPS=$(echo ${APPS} | tr ' ' ',')
87+
if [ -n "${APPS}" ] ; then
88+
echo "$0: Registering with default apps = ${APPS}"
89+
APPS="-a ${APPS}"
90+
else
91+
echo "$0: Registering with all available apps"
92+
fi
93+
94+
# Register the device but don't start the daemon:
95+
DEVICE_API="http://example.com/sign" \
96+
PRODUCTION=1 \
97+
/usr/bin/lmp-device-register --start-daemon=0 -T na ${APPS}
98+
99+
# Pull down the device's initial configuration
100+
fioconfig check-in
101+
102+
# Optionally start services, or maybe just power off the device
103+
#systemctl start aktualizr-lite
104+
#systemctl start fioconfig
105+
106+
Registration reference configuration
107+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
108+
The registration reference should work out-of-the box for this scenario.
109+
The operator will need to create a Foundries.io API token with scope
110+
``devices:create``. They can take this token and configure the
111+
reference server as per the README.md.
112+
113+
.. _reference implementation:
114+
https://github.com/foundriesio/factory-registration-ref
115+
116+
.. _lmp-device-auto-register:
117+
https://github.com/foundriesio/meta-lmp/blob/master/meta-lmp-base/recipes-support/lmp-device-auto-register/lmp-device-auto-register/lmp-device-auto-register

‎source/reference-manual/security/ota-security.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,3 +10,4 @@ Over the Air Updates
1010

1111
offline-keys
1212
device-gateway
13+
factory-registration-ref

0 commit comments

Comments
 (0)