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.

  1. 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.

  2. List the extracted content:

    $ ls /tmp/extracted-system-bundle
    

    The directory contains the bundle manifest.raucm and the images listed in it. For example, a V700 OS update bundle contains ccpilot-v700-release-v700.ext4 (rootfs) and imx-boot.img (bootloader).

B.2. Create and sign the bundle

  1. Prepare release-full-1.0.0/ and appfs/, as described in 6. Update bundle creation.

  2. 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
    
  3. 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/
    
  4. Check compatible and the image filenames in release-full-1.0.0/manifest.raucm, as shown in 6.3. Build the bundle.

  5. 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
    

    --key and --cert select the signing key and certificate. --keyring is 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.

  6. 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 compatible value, 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 purpose means that the --conf option is missing.

  • squashfs size (4096) must be larger than 4096 byte means 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

  1. Replace customer-initialization-encrypted-1.0.0/system.conf with 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
    

    token and id must match PKCS11_TOKEN_LABEL and PKCS11_ENC_KEY_ID in conf.sh.

  2. Set compatible in customer-initialization-encrypted-1.0.0/manifest.raucm to the value in the display’s /etc/rauc/system.conf. The script stops with an error if it does not match system.conf.

  3. Build the bundle. Add --customer-keys if the display already trusts the customer CA:

    $ ./build-initialization-bundle-encrypted.sh
    

    The output is initialization-encrypted-1.0.0.raucb.

C.2. Prepare the release bundle folder

  1. Put the application files in appfs/.

  2. generate-appfs-ext4.sh creates 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/
    
  3. Download the required CrossControl OS bundle and place it in cclinux-rauc-bundles/. Extract its rootfs and copy that image into release-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 ..
    
  4. Check release-encrypted-1.0.0/manifest.raucm. The repository version already uses format=crypt and 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 compatible value 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 rootfs filename to 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.