[FOTA] Tech key point: metadata management

The Uptane framework provides an opensource OTA client example for reference: https://github.com/advancedtelematic/aktualizr

There are only codes and build docs in the repository. Still, when building and testing the project following the manual, you will get the metadata used for testing, which can be used as a reference to design our OTA solution.

The build steps can follow the README.adoc in the repository. The metadata examples are as below:

The directory repository

Root metadata

{
    "signatures":[
        {
            "keyid":"55a5d85a4c4a0934afcdeb5abcbce7b11bc1518cf99cdd75eb9ffb9de7c1216c",
            "method":"rsassa-pss",
            "sig":"NANsiGG+qE7xGHKwQf3EmTl38nrNkL74L2Z9QbuBRoloV6xNmtNQvCBH/3Z0XsEnBfPC6akWJf5FiF8sbDYXERhcrBtNHO5i8D7tJm+EhPAPN2YSb9FcsEcdepKhSV8IG5Gby3366BIBschjV5T2cFHNILpVg/C/Z+La6c7/ePeMtD/5eGND8HTOXjSC9SaWermvaqlU8xoEkKi5kpPhRncxdH9fooiwc2u7RVaPdWYXrIiwYLRKBB0GrAIJ44PrOTIlW/W6Ab832C/HUhGCVFu/YDkmcaDVqyA7xy5SPqIzlcnAkt7b0tnGpWk30OI5fkCS8ZhQ6jABBu7uts7Ukg=="
            }
        ],
    "signed":{
        "_type":"Root",
        "expires":"2025-07-04T16:33:27Z",
        "keys":{
            "226f2b97814a2693e760494af3492f06366bcbcafe5d6432445983954174f289":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwRgYLx73vvKci7FLv6sO\n6s0nEpd5/3okyM7SeINVEvfk7t282KNWfe6jC5q4BVq0t/fmRnkbOsNEMW/mg0xv\nSrO2mMMcLDvb4J1SBIJk30C2p4yK4wvcqOMnJy/UXMGliYKZ/qIrnb3i85rxL9LD\nQbTh3gkkx18GMWM0fdMXCeafadLWVXOcalhoonj2k4u9sUjIp3sxYqkFn6seDX1x\nmKzhFHwmbwH9/zGFdwfqE/77StyG//kv6JYpT7Bg4i1EJkSj7Yni4vCSgyOFlxES\n00PSf9SMSK6d6ZUqo4t57x8Xg+m3y0bqDfD+ZxWUM3A9g/owTJ3roCqCshHy/+IV\nXQIDAQAB\n-----END PUBLIC KEY-----\n"
                    }
            },
            "55a5d85a4c4a0934afcdeb5abcbce7b11bc1518cf99cdd75eb9ffb9de7c1216c":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyG2sqRWWQS10Ea0LY4PJ\nL439uZBYwuEenRRkgQG++efGsj8m5VyW42ov551ogPmYLr3SENKx2APEniTwcR41\nfbxKf9KJ9XYt4G7spE7rEQKd8FlyklT5enqQEwUGcXQOgOMEyzN6HZ++wixcxzAl\nFqlfX+HD3FbcQFeKv6rQs5ancvSjq9CTK+X8P2aqsA4nwx/2+77BnKM6guZpr4wX\nsZAgqgJVjR2KXk/zrsjLmhjIIMD8HkCe+KHsrTK6KIG/jje6shLAFmhVh9xZ7PKC\nuphXzz45vBK/gPXSpohQ8JgdY2/qm8O72np6w7NFeHKpoRwjzMjHM/KWOG+7BISq\nVwIDAQAB\n-----END PUBLIC KEY-----\n"
                }
            },
            "5af7f4f7658f0e8c238980d00b6f989148ed40d05871b109ae4d275d011cc3fa":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApKz/bCnKmYJEM2ihlogm\nkXjRYLrr9IPZhLr6k/HB56oSHjqBnrVdN2dNH/FlsstbGTupqvXvbHXXgb7Q/b79\nPiNZ0x5lfnI86Wcc/RMqnzjnis7JI8jWitWhGUCnqyjDgb+dL1OU0xt8WCJat+vN\nLfkq3Lvra6uf49GUNq0J2bCNswjjFsa28iDGx4Dw3tYPpuO/AnTK0c9NXlC7sD+z\nAR+CIrkzDNvg/qcvjImJ2chHEeZ9ziTs9UZWDMn9zGEkKaKVZY7VFbnHIxG2sbcq\nXb7TB2GTttdIyyUpqyUe20RBrTHTGc3d6mUDMiBsRY/FZjl2DPBXikp9YuwAnfGM\nuwIDAQAB\n-----END PUBLIC KEY-----\n"
                }
            },
            "5e00369f1576479bdd565ef58e228853f0d9d71476907d19771a3115aaa2b084":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvk+aqriQwYyHQx9IWJYS\nVVE+cmw04yA5/OTQc0eazfxV3MU38uwD0bGoznmG/mYKJBGHCayPm49DFoalWWnB\nVrAIYy6VsqpC6wMbaoiC+RccbH+esQkAgZlzo9bDo9GdajixbGLuLSYLxXYA5KLP\nL6bKfqqNd8bj4TVLg+1zTULWSPfiUT9Dt6rKt1nMEUr5F5PVkA1DqW0dfUaFa+xc\nj/hOjvCAsQ+GuAmLx6CX72qLZEyjwZwr5PlhGN+Rm9i9xYfrgjgTNUpdoJxbzPUZ\nqUlGUCTCj7VXO+G22ajfLOR6oPwiPXCYkPD8LLEVB+ZdnCdRf0veHSBexjUIvgoS\nzwIDAQAB\n-----END PUBLIC KEY-----\n"
                }
            }
        },
        "roles":{
            "root":{
                "keyids":[
                    "55a5d85a4c4a0934afcdeb5abcbce7b11bc1518cf99cdd75eb9ffb9de7c1216c"
                    ],
                "threshold":1
            },
            "snapshot":{
                "keyids":[
                    "5af7f4f7658f0e8c238980d00b6f989148ed40d05871b109ae4d275d011cc3fa"
                    ],
                "threshold":1
            },
            "targets":{
                "keyids":[
                    "226f2b97814a2693e760494af3492f06366bcbcafe5d6432445983954174f289"
                    ],
                "threshold":1
            },
            "timestamp":{
                "keyids":[
                    "5e00369f1576479bdd565ef58e228853f0d9d71476907d19771a3115aaa2b084"
                    ],
                "threshold":1
            }
        },
        "version":1
    }
}

The root metadata of the director repository contains the current type of the role, the expiration of existing metadata, keys of the position, other roles, and their key Ids. Besides, the metadata contains the version and a signature of the data.

Snapshot metadata

{
    "signatures":[
        {
            "keyid":"5af7f4f7658f0e8c238980d00b6f989148ed40d05871b109ae4d275d011cc3fa",
            "method":"rsassa-pss",
            "sig":"Whlr5uvHUVY+gglNH3DD6DflnnE+M36Qpt/hiNqBy9gV0jjJQspFSbT0WlM46+krK07yr4+VD0Fq4NyLd3AGhgT7JUvp43Feo8vfPLCLZuAg3GbFaFcaZSj9fJK9ET2GmtE8ts2eZQyPw63y61yv5hHL+l5ihvLLsMI9YF8HOIQeRALjoQJB+gXaLl/rnjcd3R6nJttUcdUI/2OYGnhn1daLdgLFOqPH1Y/hpXNgXR1a4XP9AUdJ9ymDh/jeCmORPvzi3mktiIyqxVY8fGChQ9kU+9V0Sg0Qcvj4ZnT2/rha8c1BBQ102DMX68DPgIQFdPitWkxWsmgwUNKqZLHWcQ=="
        }
    ],
    "signed":{
        "_type":"Snapshot",
        "expires":"2025-07-04T16:33:27Z",
        "meta":{
            "root.json":{
                "version":1
            },
            "targets.json":{
                "version":2
            }
        },
        "version":3
    }
}

Timestamp metadata

{
    "signatures":[
        {
            "keyid":"5e00369f1576479bdd565ef58e228853f0d9d71476907d19771a3115aaa2b084",
            "method":"rsassa-pss",
            "sig":"M/PdjY32OHxM0m4fCPrNIAU/N9NLxG72ENRZ8BNH37JSKa7uNJM9rjdmGipP20BJ7EHjTyKYg6S5aapL8UUjesxefXXr/H1xZ3h1uYevJYDKVbCG2t0PSepB5L0MBs4ZtdALjbMV1u8E5euWy59o9TApYhZLMW9luIBH1BMf0rmKPUIlmeKv4Cq2GkFI4NdU3Jl+T45Brjm0IyD0VSVOR4UmzjnZSmMXmHmqBn3OBOnGGCMzK7DqUfJJn7a5RUOlKCUoHJgfkxjeWy17Uw/7LT+rpN1UKefEnzJw1eB9mG9hQhIJKt1o3jJBODrjoHAGuvMBCkM4pvlVZCu2djb7Sw=="
        }
    ],
    "signed":{
        "_type":"Timestamp",
        "expires":"2025-07-04T16:33:27Z",
        "meta":{
            "snapshot.json":{
                "hashes":{
                    "sha256":"6feda1795071efe42f475d52946bb36abbc150f96660d6295a37f830c2d85b1b","sha512":"ef0dcc86f06eb0ab98e0175025346cf81b952c15fc4e8f4b1601531dffda6ed2b655856b5bf59d30da71e105ff956f567b4f2a4af8f87a38981a76a9163dde6d"
                },
            "length":607,
            "version":3
            }
        },
        "version":3
    }
}

Targets metadata

{
    "signatures":[
        {
            "keyid":"226f2b97814a2693e760494af3492f06366bcbcafe5d6432445983954174f289",
            "method":"rsassa-pss",
            "sig":"tk4a0yvL1lhFa1a/02XMENmPYXSo8qHViWA1bFx0WJH+a+41GcOyZqzkKPiqCrsAtjdRv0mMuIhYc3EhcNHE9Uh2abkxnLKHT7YzDKrjqsrRSRCxfIJpUNQ6iCdVj3+QxM8SQLZNoXrVI6sxxwn6MGLY0ferjqiysp6hQIbPuhmg7AxUiNsqLpNyK2zmDx277ovHNPMMPZCfxz4HDRxX/HP2J+4yQ1d2kGZE0NLr9+j/ugO5OtMeJuXKNfexCdNlex3QrCIHlwNssTYYL5W6GNHQOU5e9zV6hE9EI/3O3Eud3QNGwsuxI5BzeZ781JGLai2pvHK+ZQUFOyYh1A9g3g=="
        }
    ],
    "signed":{
        "_type":"Targets",
        "expires":"2025-07-04T16:33:27Z",
        "targets":{
            "primary.txt":{
                "custom":{
                    "ecuIdentifiers":{
                        "CA:FE:A6:D2:84:9D":{
                            "hardwareId":"primary_hw"
                        }
                    },
                    "targetFormat":"BINARY"
                },
                "hashes":{
                    "sha256":"a06ac4d8f2c389dc0f919b6ba2a809324c0d3e368741ec210be34db8179eebb7","sha512":"c2f598f7cdd0c4ea8d23a277000e1ce413c2fcaa456e980134611854bf618a317f8280cf517e2df5bad73fc11666884cd8b5cadfa7f9d2c4b4b1b84e3574c4ce"
                },
                "length":8
            }
        },
        "version":2
    }
}

Image repository

Root metadata

{
    "signatures":[
        {
            "keyid":"fb9c0e93c0ad05bd3fd5a95d5d00ad3b2c445f3ae8e4e11cb688d3ae69212a14",
            "method":"rsassa-pss",
            "sig":"QrixwvGQgO8QerHTSAAwHU8Ir8VZQbSnD/yF0qdCYxxG4u/NyFsMwpp9L4EB3Nb0O/PPaD3FtZL2rix7lQAhK35tYQLSR9emZS7H5MaIb+06ozulnnWvlPohxR7E/vLffel5kXK6WNwOTce0ezc3Kllz5uOVnThPH8wV0YzkiJMWZL+GaCaG9bYWIKC87XYmN9WPIK1YnL8OZBNxLFO28zEaZPRNC1BqOTef2hZO0SR07oIso9mHQ59stiS9t875jJQJcCNXZ4p/GHvUjKMmRNp62wxNXVj3s7HJqmyjpmPfNnBXtq7xEsiz/EsSslvtgDuJ2BR9KfcMakwL6guJCA=="
        }
    ],
    "signed":{
        "_type":"Root",
        "expires":"2025-07-04T16:33:27Z",
        "keys":{
            "9b359f25562a8de68c719fa4909b7e3ac99dd9b16121a177b8c7a56bc83c3e16":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAxuKpnYhNvF/vE3akw2ch\nd9ZZLqwDo2Ou3bPmEdRdg2sb/XS5/LOjzZzBjdfyjfhIlEaKlDcKq0gILMwGq81r\nYjRR8zsDwbWQhYX24Z74Moyp5j1DKC0vpLbPAe6MStMPJR6XT0aAlNGJ2na8dPKZ\nk+8xDfXyYbheT3NAqq8zwAlWQPPzMvflWHtw82MHylg9XRbp2arBVicEmW2Jpola\nhWRxx6t4LH++gsAJTaQDIal4lfqebss68tM5todXYzXwg4gAE0ntkpI6fdXm+v/o\nAjmzUH+7EobR3lLqzyXKJztIHMqDndQWj5N52En10QsLOdxSBjR/PRDkEmVkQrqz\nWwIDAQAB\n-----END PUBLIC KEY-----\n"
                }
            },
            "a893177adb28c54f2725d2eacb397be12d902e7165cee44dc01a3ff3459911be":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvdFL1m8rStsXkV+mR9hv\nOEDtwcjE6/hVhLMMuwjz+o18ggO4SOLodQtO1r+3QqmzzfqYHpB0EzVOpvF9IRMc\npdaqgoczhWCIFuH/2qcEZFTQuJOp9OT9ZK9+KVMQcIlxkb0IqKP5uJ9iF2UK6108\nR/K833/X3oT9xoQxI4T/b1LW3qkkPU9ysC1WBmaFmtvX34PSVDkN9ocOBQWSo92G\nPy1NovLussOpoZT9qYaQJ6eme/DDZuyzX6scnd+q2oWxzwmCsd6pI+MHgiF9cBOu\nArEqegpgT53QlDKkzRffosLnFhPCnPk1pBwXWMgGwBzrn7+JN142OhgQ48rueHP4\n/wIDAQAB\n-----END PUBLIC KEY-----\n"
                }
            },
            "b5a9d0cd7433f0840cb7aa6b98d025bed586448e42d93bc8eee9f001976fe369":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApaQp0OIFNz24gImGFDZ2\nx7BfNaACKrvHerNg/tEyehGMw/owFqT9/N0hadcDUABfeSB5lbZH1lBvoV2Rn4+E\n47Wjp+jQanuNTStV/fle443xM3oGp7qcRTrKx/feBC2jf/dQfCI7OuZ/4Ee3HwLy\nogJt0PwgfW6Oxa5pMUCzoEAow5rRbyXmYlLmslLXnvvJKZLVDhRGYq3KyOXfBKtf\nXyaDJ2bv95Okjh4uosVP+UGdU8RN0DK2lfupJZqgWH2gVvSD/Wt64JYFGqH1Gh3i\nbjGX5ON9F3xx48mpDDRI0CKT51/bSH6Q2nMdC4e+OMpaA2ycLqRuPhWcwTslFOHI\naQIDAQAB\n-----END PUBLIC KEY-----\n"
                }
            },
            "fb9c0e93c0ad05bd3fd5a95d5d00ad3b2c445f3ae8e4e11cb688d3ae69212a14":{
                "keytype":"RSA",
                "keyval":{
                    "public":"-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwVQHAvkcHuvXbnloZpw6\nLud82BaXyOoqIgiCjej6g+J/lKNdbBwULkNZ4EVnJJMFBqStLfhrZx4xoubZV3zR\nMzL6PLbLZeSbLnl8LTjzUeJFY/uXRaYO7sDkLE9pAK5k6yjnrOpJ5uCdEw1ePEkR\nKv/6Y67bqfMxwNPkbZM2d5qjloAkPENdIXwM+ngdPNODGJwdtaYMT7iGJKvfm6zt\nMg0s+lUROqQxufu5mpE4mYIwnCtqbvOW24UTh41nFMTpQ+Xks1WHRxmlmu/LT6Su\ndZfs9SXXaUDIlWwOmC9eTKuYTaAVj6Zp6Eww7cFKs/DZnx9AeEyfXnpboJBmDiPR\nQwIDAQAB\n-----END PUBLIC KEY-----\n"
                }
            }
        },
        "roles":{
            "root":{
                "keyids":["fb9c0e93c0ad05bd3fd5a95d5d00ad3b2c445f3ae8e4e11cb688d3ae69212a14"],
                "threshold":1
            },
            "snapshot":{
                "keyids":["a893177adb28c54f2725d2eacb397be12d902e7165cee44dc01a3ff3459911be"],
                "threshold":1
            },
            "targets":{
                "keyids":["b5a9d0cd7433f0840cb7aa6b98d025bed586448e42d93bc8eee9f001976fe369"],
                "threshold":1
            },
            "timestamp":{
                "keyids":["9b359f25562a8de68c719fa4909b7e3ac99dd9b16121a177b8c7a56bc83c3e16"],
                "threshold":1
            }
        },
        "version":1
    }
}

Snapshot metadata

{
    "signatures":[{
        "keyid":"a893177adb28c54f2725d2eacb397be12d902e7165cee44dc01a3ff3459911be",
        "method":"rsassa-pss",
        "sig":"RSiIWmAodnb1URlk8D831J37utiUyyuZ7DpqaTGmShoElxpTssJKhfvSC0qambboaIS8m8A+sOrm/OPVZhnqcLzVSNItSk9xhFba/TYcf8k2MVAB2I9Ipe+HHy3esA1TQXkH/UKvGNeQlsNpoKlTu3ky4c6Nk07HTqhRocW9cgcCNkh6JYPOwNB0OlznCFPXFxnAV0ddWyKvijyUF9dgkUGRRV57TyneuVIx65Fkv0pjW24y0TO5gBeKNj1Pukt546SSGl7l+207bvhq1We7fsYBUBclxRddB+/W5CICkIuEkAnL1yDqGM1A6A7qBshT3d2M3ZIQglS6xqrti9N8pg=="
    }],
    "signed":{
        "_type":"Snapshot",
        "expires":"2025-07-04T16:33:27Z",
        "meta":{
            "root.json":{"version":1},
            "targets.json":{"version":2}
        },
        "version":2
    }
}

Timestamp metadata

{
    "signatures":[{
        "keyid":"9b359f25562a8de68c719fa4909b7e3ac99dd9b16121a177b8c7a56bc83c3e16",
        "method":"rsassa-pss",
        "sig":"HlrPFtN+19p3Go6Op2dUH+II4ZYu9KcDKXrVgC33WWqyCt6A6KOH044XC8PbxMkRRSmLSNltUHPBRCENRKByKlUnhspeYQ1+56rFr4c5chntcxpCLY+Ga664JL7lpqMb+iI+HHed9nKMYzeIfVog0ee15sa9wmTxVwN67YaKCyniA28Ogen4YNG3yCn++RpMnN1zICjn5WElluqve64/gQUob0DARUmzQgYh/ZmdxUIQM2sa2tkprzcEpwNDT44GAaO8EDCJYm1NSlOi0EY0Y4Hy/msK/t/sowCs7Xl5gV561K/cbvpdQq3x9kjGeus9Uc4APEtlG5+7KDFzkT/+zw=="
    }],
    "signed":{
        "_type":"Timestamp",
        "expires":"2025-07-04T16:33:27Z",
        "meta":{
            "snapshot.json":{
                "hashes":{
                    "sha256":"36abec02cd6baf24f3277324d66f05c054d5982479f30383af04770de1cc736e","sha512":"84fe1060380b607bbb056ac0370678bcb6434e3bd3d589b71d4422f3c23942d60e7f21f273dc31e43f3ad52ec687b6fe92fcb4001331336cc7df8f96652487db"
                },
                "length":607,
                "version":2
            }
        },
        "version":2
    }
}

Targets metadata

{
    "signatures":[{
        "keyid":"b5a9d0cd7433f0840cb7aa6b98d025bed586448e42d93bc8eee9f001976fe369",
        "method":"rsassa-pss",
        "sig":"USpeG+e3qcHv/CPJXKoYco6cBodlM4Ijp4L0Rt8k0WgixV8JDV7f9THRv9/1nVf4APZbMs0Rh6It80ZNTIhTSLDEyG9ErIQXyOAdxbLQfgcD37HIvh2+tKrrs5wlMU7rlCfvCTQ02UjgJjjvBwTaXFvisbQ78saVr5Ecr8w8L1KxnRp3naVpXRmRpjVndU2tFGM/AK4ah75mn3uKuW5eU2hVDBIo9+mIGNqcpvlzf6ZEo07TCA3pxGYowmUs0TM8C4P4LXWGsm2yz4aq9/X1A9jXZDydI/Av3J+FK+3rJHIBn4FQOTWvuNPQK9OXvyIeizVBmwpgFwujzKy4U2hmjg=="
    }],
    "signed":{
        "_type":"Targets",
        "expires":"2025-07-04T16:33:27Z",
        "targets":{
            "primary.txt":{
                "custom":{
                    "hardwareIds":["primary_hw"],
                    "targetFormat":"BINARY"
                },
                "hashes":{
                    "sha256":"a06ac4d8f2c389dc0f919b6ba2a809324c0d3e368741ec210be34db8179eebb7","sha512":"c2f598f7cdd0c4ea8d23a277000e1ce413c2fcaa456e980134611854bf618a317f8280cf517e2df5bad73fc11666884cd8b5cadfa7f9d2c4b4b1b84e3574c4ce"
                },
                "length":8
            }
        },
        "version":2
    }
}

In addition to what is required, Targets metadata files can contain extra metadata for images on the repository. This metadata can be customized for a particular use case. However, there are a few important pieces of custom metadata that SHOULD be present in most implementations. In addition, there is one element in the custom metadata that SHALL be present in the Targets metadata from the Director.

Custom metadata can also contain a demarcated field or section that SHALL match whenever two pieces of metadata are checked against each other, such as when Targets metadata from the Director repository is checked against Targets metadata from the Image repository.

The information listed below SHOULD be provided for each image on both the Image repository and the Director repository. If a “SHALL match section” is to be implemented, that is where this information SHOULD be placed.

• A release counter, to be incremented each time a new version of the image is released. This can be used to prevent rollback attacks even in cases where the Director repository is compromised.

• A hardware identifier, or list of hardware identifiers, representing models of ECUs with which the image is compatible. This can be used to ensure that an ECU cannot be ordered to install an incompatible image, even in cases where the Director repository is compromised.

The following information SHALL be provided from the Director repository for each image in the Targets metadata:

• An ECU identifier (such as a serial number), specifying the ECU that SHOULD install the image.

For Encrypted Image

The following information is CONDITIONALLY REQUIRED for each image on the Director repository IF that image is encrypted:

• Information about filenames, hashes, and file size of the encrypted image.

• Information about the encryption method, and other relevant information–for example, a symmetric encryption key encrypted by the ECU’s asymmetric key could be included in the Director repository metadata.

The management of metadata

Name of the metadata file

To avoid race conditions when reading from or writing to metadata, the Uptane framework defines a rule for naming the metadata: Metadata filenames should contain version numbers. For example, if root.json is the filename of root metadata, and the version of the metadata is 1.0, then the filename should be changed to 1.0.root.json.

How OEM or its suppliers generate the metadata

If the OEM or its suppliers want to release an image for an ECU, they must prepare the image and sign it in order to provide security against arbitrary software attacks. Here are the steps to sign and prepare the metadata:

1. Generate a number of keys to sign the metadata. The supplier or OEM should take great care to secure the keys.

2. Set the expiration timestamp on the metadata prescribed by the OEM.

3. Calculate the hash value of the image and write it to the metadata

4. Sign the metadata using the digital signature algorithm defined by the OEM.

5. Send all the metadata and images to the image repository/OEM.

Repository requirements

Image repository

The image repository provides a method for OEM and/or its suppliers to upload images and associated metadata. The image repository should expose an interface whereby the primary ECUs of vehicles can download the images and associated metadata.

When images and their associated metadata are uploaded to the image repository, the image repository should authenticate whether the action or the uploaded files is authorized. The image repository should also require authentication for read access(not only for vehicles but also humans).

Directory repository

A private API should be defined for the directory repository to update the inventory database, whereby the directory repository has the knowledge of the latest image of ECUs. When it receives a vehicle version manifest from a vehicle, it can generate the right metadata and send them to the vehicle.

The figure above can be divided into 4 steps:

1. A primary ECU of a vehicle receives an update notification, collects its vehicle version manifest and sends it to the directory repository.

2. The directory repository checks the vehicle version manifest with its database.

3. The directory generates the metadata telling the vehicle which ECU should be updated and where to download the image and the image metadata.

4. The primary ECU downloads the directory metadata, checks the validity and applies them if valid.

Vehicle requirements

Primary ECU

The primary ECU is responsible for downloading metadata for all targets and performing a full verification on them. The full verification of metadata means the primary ECU checks that the metadata downloaded from the directory as below:

1. Verify the current time or the most recent securely attested time, which can refer to https://carloss-organization-4.gitbook.io/tech/design/fota/fota-module-of-ecus-fota-unit-design/fota-tech-key-point-time-server
2. Check the Root metadata file from the directory repository:

   1. Load the previous Root metadata file.

   2. Update to the latest Root metadata file.

      1. Let N denote the version number of the latest Root metadata file (which at first could be the same as the previous Root metadata file).

      2. Try downloading a new version N+1 of the Root metadata file, up to some X number of bytes. The value for X is set by the implementer. For example, X could be tens of kilobytes. The filename used to download the Root metadata file is of the fixed form VERSION_NUMBER.FILENAME.EXT (e.g., 42.root.json). If this file is not available, the current Root metadata file is the latest; continue with step 3.

      3. Version N+1 of the Root metadata file SHALL have been signed by the following: (1) a threshold of unique keys specified in the latest Root metadata file (version N), and (2) a threshold of unique keys specified in the new Root metadata file being validated (version N+1). If version N+1 is not signed as required, discard it, abort the update cycle, and report the signature failure. On the next update cycle, begin at version N of the Root metadata file. (Checks for an arbitrary software attack.)

      4. The version number of the latest Root metadata file (version N) SHALL be less than or equal to the version number of the new Root metadata file (version N+1). Effectively, this means checking that the version number signed in the new Root metadata file is indeed N+1. If the version of the new Root metadata file is less than the latest metadata file, discard it, abort the update cycle, and report the rollback attack. On the next update cycle, begin at step 1 and version N of the Root metadata file. (Checks for a rollback attack.)

      5. Set the latest Root metadata file to the new Root metadata file.

      6. Repeat steps 2.1 to 2.6.

   3. Check that the current (or latest securely attested) time is lower than the expiration timestamp in the latest Root metadata file. (Checks for a freeze attack.)

   4. If the Timestamp and/or Snapshot keys have been rotated, delete the previous Timestamp and Snapshot metadata files. (Checks for recovery from fast-forward attacks

3. Check the Timestamp metadata file from the directory repository.

   1. Download up to Y number of bytes. The value for Y is set by the implementer. For example, Y could be tens of kilobytes. The filename used to download the Timestamp metadata file is of the fixed form FILENAME.EXT (e.g., timestamp.json).

   2. Check that it has been signed by the threshold of unique keys specified in the latest Root metadata file. If the new Timestamp metadata file is not properly signed, discard it, abort the update cycle, and report the signature failure. (Checks for an arbitrary software attack.)

   3. Check that the version number of the previous Timestamp metadata file, if any, is less than or equal to the version number of this Timestamp metadata file. If the new Timestamp metadata file is older than the trusted Timestamp metadata file, discard it, abort the update cycle, and report the potential rollback attack. (Checks for a rollback attack.)

   4. Check that the current (or latest securely attested) time is lower than the expiration timestamp in this Timestamp metadata file. If the new Timestamp metadata file has expired, discard it, abort the update cycle, and report the potential freeze attack. (Checks for a freeze attack.)

4. Check the previously downloaded Snapshot metadata file from the Directory repository (if available). If the hashes and version number of that file match the hashes and version number listed in the new Timestamp metadata, there are no new updates and the verification process SHALL be stopped and considered complete. Otherwise, download and check the Snapshot metadata file from the Director repository.

   1. Download up to the number of bytes specified in the Timestamp metadata file, constructing the metadata filename.

   2. The hashes and version number of the new Snapshot metadata file SHALL match the hashes and version number listed in the Timestamp metadata. If the hashes and version number do not match, discard the new Snapshot metadata, abort the update cycle, and report the failure. (Checks for a mix-and-match attack.)

   3. Check that it has been signed by the threshold of unique keys specified in the latest Root metadata file. If the new Snapshot metadata file is not signed as required, discard it, abort the update cycle, and report the signature failure. (Checks for an arbitrary software attack.)

   4. Check that the version number of the previous Snapshot metadata file, if any, is less than or equal to the version number of this Snapshot metadata file. If this Snapshot metadata file is older than the previous Snapshot metadata file, discard it, abort the update cycle, and report the potential rollback attack. (Checks for a rollback attack.)

   5. Check that the version number listed by the previous Snapshot metadata file for each Targets metadata file is less than or equal to its version number in this Snapshot metadata file. If this condition is not met, discard the new Snapshot metadata file, abort the update cycle, and report the failure. (Checks for a rollback attack.)

   6. Check that each Targets metadata filename listed in the previous Snapshot metadata file is also listed in this Snapshot metadata file. If this condition is not met, discard the new Snapshot metadata file, abort the update cycle, and report the failure. (Checks for a rollback attack.)

   7. Check that the current (or latest securely attested) time is lower than the expiration timestamp in this Snapshot metadata file. If the new Snapshot metadata file is expired, discard it, abort the update cycle, and report the potential freeze attack. (Checks for a freeze attack.)

5. Check the targets metadata file from the Director repository:

   1. checks whether the version number of the Targets metadata matches the version number listed in the latest Snapshot metadata. if it doesn’t match, discard it and abort the update cycle, report the event if necessary.

   2. Check that the Targets metadata has been signed by the threshold of unique keys specified in the relevant metadata file. (Checks for an arbitrary software attack.):

      1. If checking top-level Targets metadata, the threshold of keys is specified in the Root metadata.

      2. If checking delegated Targets metadata, the threshold of keys is specified in the Targets metadata file that delegated authority to this role.

   3. Check the version number of the previous Targets metadata file, if any of them is less than or equal to the version number of the latest Targets metadata file. (Checks for a rollback attack)

   4. Check that the current (or latest securely attested) time is lower than the expiration timestamp in this Targets metadata file.

   5. If checking Targets metadata from the Director repository, verify that there are no delegations.

   6. If checking Targets metadata from the Director repository, check that no ECU identifier is represented more than once.

   7. If checking Targets metadata from the Director repository, and the ECU performing the verification is the Primary ECU, check that all listed ECU identifiers correspond to ECUs that are actually present in the vehicle.

6. If the Targets metadata from the Directory repository indicates that there are no new targets that are not already currently installed, the verification process SHALL be stopped and considered complete. Otherwise, download and check the Root metadata file from the Image repository and check it refers to Step 2.

7. Download and check the Timestamp metadata file from the Image repository, following the procedure in Step 3.

8. Check the previously downloaded Snapshot metadata file from the Image repository (if available). If the hashes and version number of that file match the hashes and version number listed in the new Timestamp metadata, the ECU SHALL skip to the last step. Otherwise, download and check the Snapshot metadata file from the Image repository, following the procedure in Step 4.

9. Download and check the top-level Targets metadata file from the Image repository, following the procedure in Step 5.

10. Verify that Targets metadata from the Director and Image repositories match. The Primary ECU SHALL perform this check on metadata for all images listed in the Targets metadata file from the Director repository downloaded in step 6, To check that the metadata for an image matches, complete the following procedure:

    1. Locate and download a Targets metadata file from the Image repository that contains an image with exactly the same filename listed in the Director metadata

    2. Check that the Targets metadata from the Image repository matches the Targets metadata from the Director repository:

       1. Check that the non-custom metadata (i.e., length and hashes) of the unencrypted or encrypted image are the same in both sets of metadata. Note: the Primary is responsible for validating encrypted images and associated metadata. The target ECU (Primary or Secondary) is responsible for validating the unencrypted image and associated metadata.

       2. Check that all SHALL match custom metadata (e.g., hardware identifier and release counter) are the same in both sets of metadata.

       3. Check that the release counter, if one is used, in the previous Targets metadata file is less than or equal to the release counter in this Targets metadata file.