Appendix A. CrossControl demo key and certificate¶
Demo versions:
Developer key (development-1.key.pem):
-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDqfNpOnEE5Bzj8
0fRgClqDrY2hQynwphHSKrj8Gw5WXC9ndvgcjgLvqUtYiAFeHlAsqZEUyZIt+xth
7HBDIWTccZ1M427AgG2H7EQ1qdV95NuYDqMmw0b60D42DLAmZda1/IB6S/kGLEk7
VWLeoZXdkhzZVedeGEtB4HoyGU4DoMCDWtlW/D2o4RTMb1a2OkBdYK4vS+Xx9pKE
MjsxV0xdO9t7Ps2QSmMExF0UfHn0m7bbs8zPFTh8OdB9WwGVF7Wz5bPFBFSVZMij
VR7Vf37DalTLQj7SYyYDKqqJZ2Q/j+pp9vkepIpKFmQzmzWpiR9UouVKobKQnm5A
KC0FyPbpAgMBAAECggEAAYPKt78J61PE/hofn2a1uLvMak4oJVQ3UYGh5gwJMszf
6AXUWr/enDx+Xn0rcBeXSkCSrb0THw2sGrz3qTFcKNHpk5t1BdSWkI4ZzzRwiwKJ
WiE/E9MnYFuryTbaBPd7tHuD+3ZF7rCmzPWzYK+Py6mD2vITf2+9/bgU5gG0l7Cl
Hw5D4on9jf51t68LRThYlSRIPzbxU3M2bBzk958Q6GbXVw8CRMwkgpeQEUV2Q4My
yUqZhM7hHAYZJFOxbcfdq3uxpHxiQvGIXdvciiYNqY+dt5i44rVytoUoJ/c5kUPl
GbyfBp3mbhADHdTIuVoRTl3G3mBAwn31yy+56jYF8QKBgQD7nUvFDgqObPlG8qZ5
oYdo6S+wPYCVC0iBZcfb20vfcU6iN3CyuAkwpZ7Qb2DpkNw9iNoM1gqDsPSF37lO
ExMeEWv91VzWeeb2fj0pskoNSm7o17rP/zeWqyV8igwuGqbhHBhIqpuyim1BEiB/
BuywyRnZxehjkTDwUPS72bt5sQKBgQDukyMlCBfy0JGWSS/pPb7T1VJkNdsDRDqA
e5Gz53JGxYfygQsNvB2jTVcvxy2IF0ffN0GQj/eiLv2J2TcgIvuguGa9KLQd1+S6
jZALgQbY4HAuOPNztDTAuAOPulhlFlhzkelqF7d8sY/IwKRTigV48J2Jf6lt/We5
29bxUsnmuQKBgQCYegrnoImvI8SwRO2zebqYTe9zSuH38D2BBM/noO5KutxfG1+1
Pid7jnI+d7Bv+jQtKhiRfMgkZADae+hMsux75SzfRwQaiQb4yyl/cibEBR5PBiSU
VWI3cQGnhfS5n7cPZbollxYBTTfGHhkJQYX/3+5FdVRNujfA+h5FFD4zEQKBgQCT
0Iwc3Jfh9MHPSIcrzvrVyrzio8+PhY1tn6IVwhe2q5pgcP2FRAFk9X1Id/LI+Auq
zFSOGfUHAnBKIVAbVDFtUfMtzfNS7jmkMCOITSgN5Xj72oNUM9nfceObAIzWDPM+
n6/r8MfZtTXt3xWxQLnFReeFkphKMpA6wm+5U18O2QKBgDiKiUm94fEr+mxJKaXc
af99c2n/i8pxJX/OuShDCnfgzP4Ob3MaGteRNjXtYy0z9Mio3/IPWcU9YCGTr1/r
q5rS3xWU0tUEwxStd7wgn/jTdR2qPTD/WSdRDlqc9Kf1ddqs1lGBGmyl+8Lf/2sO
/kmjUPdHqjyDSiPmF+b7u5H4
-----END PRIVATE KEY-----
Developer cert (development-1.cert.pem):
Certificate:
Data:
Version: 3 (0x2)
Serial Number: 2 (0x2)
Signature Algorithm: sha256WithRSAEncryption
Issuer: O=CrossControl Test Org, CN=CrossControl Test Org rauc CA Development
Validity
Not Before: Jan 1 00:00:00 1970 GMT
Not After : Dec 31 23:59:59 9999 GMT
Subject: O=CrossControl Test Org, CN=CrossControl Test Org Development-1
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (2048 bit)
Modulus:
00:ea:7c:da:4e:9c:41:39:07:38:fc:d1:f4:60:0a:
5a:83:ad:8d:a1:43:29:f0:a6:11:d2:2a:b8:fc:1b:
0e:56:5c:2f:67:76:f8:1c:8e:02:ef:a9:4b:58:88:
01:5e:1e:50:2c:a9:91:14:c9:92:2d:fb:1b:61:ec:
70:43:21:64:dc:71:9d:4c:e3:6e:c0:80:6d:87:ec:
44:35:a9:d5:7d:e4:db:98:0e:a3:26:c3:46:fa:d0:
3e:36:0c:b0:26:65:d6:b5:fc:80:7a:4b:f9:06:2c:
49:3b:55:62:de:a1:95:dd:92:1c:d9:55:e7:5e:18:
4b:41:e0:7a:32:19:4e:03:a0:c0:83:5a:d9:56:fc:
3d:a8:e1:14:cc:6f:56:b6:3a:40:5d:60:ae:2f:4b:
e5:f1:f6:92:84:32:3b:31:57:4c:5d:3b:db:7b:3e:
cd:90:4a:63:04:c4:5d:14:7c:79:f4:9b:b6:db:b3:
cc:cf:15:38:7c:39:d0:7d:5b:01:95:17:b5:b3:e5:
b3:c5:04:54:95:64:c8:a3:55:1e:d5:7f:7e:c3:6a:
54:cb:42:3e:d2:63:26:03:2a:aa:89:67:64:3f:8f:
ea:69:f6:f9:1e:a4:8a:4a:16:64:33:9b:35:a9:89:
1f:54:a2:e5:4a:a1:b2:90:9e:6e:40:28:2d:05:c8:
f6:e9
Exponent: 65537 (0x10001)
X509v3 extensions:
X509v3 Subject Key Identifier:
21:1C:40:F5:35:E1:AC:D1:D6:01:F2:29:29:BD:3A:0B:58:24:51:06
X509v3 Authority Key Identifier:
keyid:BF:50:C0:00:37:34:CF:2B:D0:12:FB:EA:34:EB:04:15:D6:BC:52:9F
DirName:/O=CrossControl Test Org/CN=CrossControl Test Org rauc CA Development
serial:01
X509v3 Basic Constraints:
CA:FALSE
X509v3 Key Usage: critical
Digital Signature, Key Encipherment
X509v3 Extended Key Usage: critical
Code Signing
Signature Algorithm: sha256WithRSAEncryption
Signature Value:
b1:34:6b:4c:4b:de:b2:db:14:7f:70:58:bb:03:0e:92:8d:90:
a2:39:95:b3:4e:cd:e6:88:ba:0c:02:79:cc:28:94:e9:b5:8d:
ee:10:15:a2:e9:52:4b:b5:c6:6a:e6:3d:9d:b3:11:fb:94:00:
30:5b:e5:75:fb:c3:bf:a6:3b:f2:75:10:a7:8e:0f:7d:1a:c8:
57:c4:ef:d4:b9:d6:21:9e:64:06:33:ba:e6:b5:df:c3:9b:ae:
9d:04:c2:1b:23:fe:95:0a:0a:be:58:aa:29:0e:bd:1e:3f:aa:
7b:68:b8:1d:17:3a:b7:89:e8:37:84:0d:73:6f:af:92:b7:94:
6e:71:d2:f6:da:ae:62:92:82:f3:db:4c:01:b9:fc:e1:84:2c:
4d:b1:de:4f:63:6b:f6:0a:1a:55:87:2e:20:dc:43:10:24:18:
4f:41:3f:03:57:ac:d9:17:18:cc:71:69:ce:11:a1:34:af:c1:
c7:6a:3c:90:db:57:83:66:dd:2e:9e:93:3e:0f:45:8c:cd:2e:
0c:ae:ca:ee:87:f4:eb:dd:69:77:17:c3:d5:90:15:5f:0d:5e:
71:53:08:16:1f:3a:32:44:a2:47:b0:0b:7f:98:eb:d4:92:2d:
f4:e7:b8:83:66:cc:81:32:3d:eb:fb:ed:b6:57:12:7a:b0:f6:
c6:e7:79:e0
-----BEGIN CERTIFICATE-----
MIID8zCCAtugAwIBAgIBAjANBgkqhkiG9w0BAQsFADBUMR4wHAYDVQQKDBVDcm9z
c0NvbnRyb2wgVGVzdCBPcmcxMjAwBgNVBAMMKUNyb3NzQ29udHJvbCBUZXN0IE9y
ZyByYXVjIENBIERldmVsb3BtZW50MCAXDTcwMDEwMTAwMDAwMFoYDzk5OTkxMjMx
MjM1OTU5WjBOMR4wHAYDVQQKDBVDcm9zc0NvbnRyb2wgVGVzdCBPcmcxLDAqBgNV
BAMMI0Nyb3NzQ29udHJvbCBUZXN0IE9yZyBEZXZlbG9wbWVudC0xMIIBIjANBgkq
hkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6nzaTpxBOQc4/NH0YApag62NoUMp8KYR
0iq4/BsOVlwvZ3b4HI4C76lLWIgBXh5QLKmRFMmSLfsbYexwQyFk3HGdTONuwIBt
h+xENanVfeTbmA6jJsNG+tA+NgywJmXWtfyAekv5BixJO1Vi3qGV3ZIc2VXnXhhL
QeB6MhlOA6DAg1rZVvw9qOEUzG9WtjpAXWCuL0vl8faShDI7MVdMXTvbez7NkEpj
BMRdFHx59Ju227PMzxU4fDnQfVsBlRe1s+WzxQRUlWTIo1Ue1X9+w2pUy0I+0mMm
AyqqiWdkP4/qafb5HqSKShZkM5s1qYkfVKLlSqGykJ5uQCgtBcj26QIDAQABo4HT
MIHQMB0GA1UdDgQWBBQhHED1NeGs0dYB8ikpvToLWCRRBjB8BgNVHSMEdTBzgBS/
UMAANzTPK9AS++o06wQV1rxSn6FYpFYwVDEeMBwGA1UECgwVQ3Jvc3NDb250cm9s
IFRlc3QgT3JnMTIwMAYDVQQDDClDcm9zc0NvbnRyb2wgVGVzdCBPcmcgcmF1YyBD
QSBEZXZlbG9wbWVudIIBATAJBgNVHRMEAjAAMA4GA1UdDwEB/wQEAwIFoDAWBgNV
HSUBAf8EDDAKBggrBgEFBQcDAzANBgkqhkiG9w0BAQsFAAOCAQEAsTRrTEvestsU
f3BYuwMOko2QojmVs07N5oi6DAJ5zCiU6bWN7hAVoulSS7XGauY9nbMR+5QAMFvl
dfvDv6Y78nUQp44PfRrIV8Tv1LnWIZ5kBjO65rXfw5uunQTCGyP+lQoKvliqKQ69
Hj+qe2i4HRc6t4noN4QNc2+vkreUbnHS9tquYpKC89tMAbn84YQsTbHeT2Nr9goa
VYcuINxDECQYT0E/A1es2RcYzHFpzhGhNK/Bx2o8kNtXg2bdLp6TPg9FjM0uDK7K
7of0691pdxfD1ZAVXw1ecVMIFh86MkSiR7ALf5jr1JIt9Oe4g2bMgTI96/vttlcS
erD2xud54A==
-----END CERTIFICATE-----
Appendix B. Create a bundle manually¶
build-all-demo.sh, see 6.3. Build the bundle, runs the standard RAUC tools. The same steps can be run manually, for example to use another folder layout or to integrate bundle creation in an existing build system.
Set up the SDK environment, as described in 5.1. Set up the SDK, and run the commands from the root of the example repository.
B.1. Extract a bundle¶
Extracting a bundle unpacks the manifest and the images it contains. A common use case is to extract the rootfs .ext4 image from the official CrossControl system update bundle, and add it together with your own appfs image to a customer-specific system bundle, as described in 3.2. Rootfs and appfs in one bundle.
Extract the bundle:
[SDK]$ rauc extract \ --conf=rauc-host.conf \ --keyring=cc-demo-keys/ca.cert.pem \ cclinux-rauc-bundles/<bundle-name>.raucb /tmp/extracted-system-bundle
The output directory must not already exist. RAUC creates it and stops with an error if it is already there.
List the extracted content:
$ ls /tmp/extracted-system-bundle
The directory contains the bundle
manifest.raucmand the images listed in it. For example, a V700 OS update bundle containsccpilot-v700-release-v700.ext4(rootfs) andimx-boot.img(bootloader).
B.2. Create and sign the bundle¶
Prepare
release-full-1.0.0/andappfs/, as described in 6. Update bundle creation.Create an empty image file of the required size, and an ext4 filesystem in it containing the files in
appfs/:$ dd if=/dev/zero of=release-full-1.0.0/appfs.ext4 bs=1M count=800 $ mkfs.ext4 -d appfs release-full-1.0.0/appfs.ext4
Copy the rootfs image extracted in B.1. Extract a bundle to
release-full-1.0.0/:$ cp /tmp/extracted-system-bundle/ccpilot-v700-release-v700.ext4 release-full-1.0.0/
Check
compatibleand the image filenames inrelease-full-1.0.0/manifest.raucm, as shown in 6.3. Build the bundle.Create and sign the bundle with the demo key. The key and certificate in
cc-demo-keys/are the same as in Appendix A. CrossControl demo key and certificate:[SDK]$ rauc bundle \ --conf=rauc-host.conf \ --keyring=cc-demo-keys/ca.cert.pem \ --key=cc-demo-keys/development-1.key.pem \ --cert=cc-demo-keys/development-1.cert.pem \ release-full-1.0.0 install-package-1.0.0.raucb
--keyand--certselect the signing key and certificate.--keyringis used to verify the new signature. With customer keys, use the files generated in 8.1. Generate customer signing keys with--key,--cert,--keyring, and--intermediate.Check the created bundle:
[SDK]$ rauc info \ --conf=rauc-host.conf \ --keyring=cc-demo-keys/ca.cert.pem \ install-package-1.0.0.raucb
The output lists the
compatiblevalue, the bundle format, and the included images.
If bundle creation fails:
Check that all paths are correct, and that the keys and certificates are valid. The RAUC error message does not always point out the root cause.
unsuitable certificate purposemeans that the--confoption is missing.squashfs size (4096) must be larger than 4096 bytemeans that the bundle content is too small. Add more files to the appfs.
Appendix C. Create encrypted bundles manually¶
build-all-encrypted.sh, see 9.5. Build the bundles, runs the steps below. Complete 9.2. Configure the example to 9.4. Provision the OP-TEE PKCS#11 token first, and run the commands from the root of the example repository.
C.1. Build the initialization bundle¶
Replace
customer-initialization-encrypted-1.0.0/system.confwith the display’s own/etc/rauc/system.conf, and add the[encryption]section. The sample file is written for the CCpilot V700. Do not copy device nodes or slot definitions from a different display model:[encryption] key=pkcs11:token=rauc-token;id=%02;type=private cert=pkcs11:token=rauc-token;id=%02;type=cert
tokenandidmust matchPKCS11_TOKEN_LABELandPKCS11_ENC_KEY_IDinconf.sh.Set
compatibleincustomer-initialization-encrypted-1.0.0/manifest.raucmto the value in the display’s/etc/rauc/system.conf. The script stops with an error if it does not matchsystem.conf.Build the bundle. Add
--customer-keysif the display already trusts the customer CA:$ ./build-initialization-bundle-encrypted.shThe output is
initialization-encrypted-1.0.0.raucb.
C.2. Prepare the release bundle folder¶
Put the application files in
appfs/.generate-appfs-ext4.shcreates an 800 MB image by default (bs=100M count=8). Confirm that this size does not exceed the target’s appfs partition size, then create the image:$ ./generate-appfs-ext4.sh $ cp appfs.ext4 release-encrypted-1.0.0/
Download the required CrossControl OS bundle and place it in
cclinux-rauc-bundles/. Extract its rootfs and copy that image intorelease-encrypted-1.0.0/:$ cd cclinux-rauc-bundles $ ./extract-bundle.sh <CrossControl-OS-bundle.raucb> $ cp latest/<rootfs-image.ext4> ../release-encrypted-1.0.0/ $ cd ..
Check
release-encrypted-1.0.0/manifest.raucm. The repository version already usesformat=cryptand defines both images:[update] compatible=CrossControl V700 version=1.0.0 description=Encrypted Rauc example package [bundle] format=crypt [image.rootfs] filename=ccpilot-v700-release-v700.ext4 [image.appfs] filename=appfs.ext4
The
compatiblevalue must match the selected CCpilot display, and the image filenames must match the files in the release directory. For a display other than the V700, change the rootfsfilenameto the extracted image name.
Every file in release-encrypted-1.0.0/ is included in the bundle. The folder should only contain manifest.raucm and the two images.
C.3. Build the encrypted release bundle¶
$ ./build-full-release-encrypted.sh
The script first runs rauc bundle on release-encrypted-1.0.0/. The format=crypt setting in the manifest makes RAUC generate a random AES-256 key, encrypt the payload, store the AES key in the manifest, and sign the manifest with the customer developer signing key. The script then runs rauc encrypt with bundle-enc-key/rauc-enc.cert.pem. This encrypts the signed CMS manifest for the RSA public key contained in the recipient certificate. For multiple recipients, set CRYPT_CERT in build-full-release-encrypted.sh, see 9.8. Key strategies and rotation.
The final output is install-package-encrypted-1.0.0.raucb. The script sets its permissions to 0644, because RAUC refuses to open encrypted bundles with unsafe permissions, and deletes the intermediate bundle after successful encryption.