This is an automated email from the ASF dual-hosted git repository. ccollins pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/mynewt-artifact.git
commit 7b5e1d873e28c52aa9142f0ee5194b3069a9457d Author: Christopher Collins <ccoll...@apache.org> AuthorDate: Wed Aug 12 14:33:12 2020 -0700 image/README.md: Document of Mynewt image anatomy --- image/README.md | 168 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) diff --git a/image/README.md b/image/README.md new file mode 100644 index 0000000..b839e05 --- /dev/null +++ b/image/README.md @@ -0,0 +1,168 @@ +# Mynewt Images + +## Anatomy + +``` + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Header | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + ~ Padding (optional) ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + ~ ~ + ~ ~ + ~ Body ~ + ~ ~ + ~ ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Protected Trailer (optional) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + ~ ~ + ~ Protected TLVs (optional) ~ + ~ ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Trailer | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + ~ ~ + ~ TLVs ~ + ~ ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + +All fields are in host-byte order (typically little endian). + +### Header + +``` + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Magic (0x96f3b83d) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Reserved1 (0x00000000) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Header size | Protected size | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Body size | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Flags | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Major version | Minor version | Revision | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Build number | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Reserved2 (0x00000000) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + +| Field | Description | Notes | +| ----- | ----------- | ----- | +| Magic | Identifies the start of an image | | +| Header size | 32 + the amount of padding that follows the header | | +| Protected size | Size, in bytes, of the protected trailer PLUS the protected TLVs | 0 if no protected TLVs | +| Body size | Size, in bytes, of the image body | | +| Flags | One bit per flag | See below | +| Major version | The first element of the version number | major.minor.revision.build | +| Minor version | The second element of the version number | major.minor.revision.build | +| Revision | The third element of the version number | major.minor.revision.build | +| Build number | The fourth element of the version number | No meaning in semver | + +### Body + +The executable itself. In encrypted images, this is the encrypted portion. + +### Protected trailer + +Describes the set of protected TLVs that follow. This trailer is NOT present if there are no protected TLVs. + +``` + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Magic (0x6908) | Protected size | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + +| Field | Description | Notes | +| ----- | ----------- | ----- | +| Magic | Identifies the start of the protected trailer | | +| Protected size | Size, in bytes, of the protected trailer PLUS the protected TLVs | Identical to "Protected size" in image header | + +### Protected TLVs + +A sequence of TLV structures (see "TLVs" section for specifics). The structure of these TLVs is identical to the non-protected TLVs. The difference is that these TLVs are included as input to the image hash. + +### Trailer + +Describes the set of TLVs that follow. This trailer is always present. + +``` + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Magic (0x6907) | Size | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + +| Field | Description | Notes | +| ----- | ----------- | ----- | +| Magic | Identifies the start of the trailer | | +| Size | Size, in bytes, of the trailer PLUS the TLVs | | + +### TLVs + +The TLVs (type-length-value) are a sequence of variable length structures containing image metadata. + +``` + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Type | Reserved (00) | Length | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + ~ ~ + ~ Body ~ + ~ ~ + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +``` + + +| Field | Description | Notes | +| ----- | ----------- | ----- | +| Type | Identifies the type of data in the TLV body | | +| Length | The length, in bytes, of the TLV body | | +| Body | Varies by type | | + +## Header flags + +Each header flag is represented by a single bit. As with the other numeric fields, the flags field is in host byte order. + +| Value | Description | Notes | +| ----- | ----------- | ----- | +| 0x00000004 | Encrypted by key in TLV | Implies the presence of an "enc" TLV | +| 0x00000010 | Non-bootable | Second half of a split image | + +## TLV types + +| Value | Description | Notes | +| ----- | ----------- | ----- | +| 0x01 | Key hash | SHA256 of image verification key | +| 0x10 | SHA256 | SHA256 of parts of the image (see below) | +| 0x20 | Signature: RSA2048 | | +| 0x21 | Signature: ECDSA224 | | +| 0x22 | Signature: ECDSA256 | | +| 0x23 | Signature: RSA3072 | | +| 0x24 | Signature: ED25519 | | +| 0x30 | Key-encrypting key: RSA | | +| 0x31 | Key-encrypting key: KEK | | +| 0x32 | Key-encrypting key: EC256 | | +| 0x50 | Encryption nonce | | +| 0x60 | Secret index | Indicates hardware-specific location of encryption key | + +### SHA256 + +The sha256 is calculated using the following inputs: + +* Header +* Post-header padding +* Unencrypted image body +* Protected trailer (if present) +* Protected TLVs (if present)