tree: 326bf7c9bb428c36f63abc5849c7556c9ca284bd [path history] [tgz]
  1. README.md
  2. create.go
  3. image.go
  4. image_test.go
  5. keys_test.go
  6. map.go
  7. parse.go
  8. testdata/
  9. v1.go
  10. verify.go
image/README.md

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)                    |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
FieldDescriptionNotes
MagicIdentifies the start of an image
Header size32 + the amount of padding that follows the header
Protected sizeSize, in bytes, of the protected trailer PLUS the protected TLVs0 if no protected TLVs
Body sizeSize, in bytes, of the image body
FlagsOne bit per flagSee below
Major versionThe first element of the version numbermajor.minor.revision.build
Minor versionThe second element of the version numbermajor.minor.revision.build
RevisionThe third element of the version numbermajor.minor.revision.build
Build numberThe fourth element of the version numberNo 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         |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
FieldDescriptionNotes
MagicIdentifies the start of the protected trailer
Protected sizeSize, in bytes, of the protected trailer PLUS the protected TLVsIdentical 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              |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
FieldDescriptionNotes
MagicIdentifies the start of the trailer
SizeSize, 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                              ~
    ~                                                               ~
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
FieldDescriptionNotes
TypeIdentifies the type of data in the TLV body
LengthThe length, in bytes, of the TLV body
BodyVaries 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.

ValueDescriptionNotes
0x00000004Encrypted by key in TLVImplies the presence of an “enc” TLV
0x00000010Non-bootableSecond half of a split image

TLV types

ValueDescriptionNotes
0x01Key hashSHA256 of image verification key
0x10SHA256SHA256 of parts of the image (see below)
0x20Signature: RSA2048
0x21Signature: ECDSA224
0x22Signature: ECDSA256
0x23Signature: RSA3072
0x24Signature: ED25519
0x30Key-encrypting key: RSA
0x31Key-encrypting key: KEK
0x32Key-encrypting key: EC256
0x50Encryption nonce
0x60Secret indexIndicates 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)