1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
|
apk-v3(5)
# NAME
*apk v3* - overview of apk v3 format
# DECRIPTION
A v3 .apk file contains a single package's contents, some metadata, and
some signatures. The .apk file contains a tree of objects, represented
in a custom binary format and conforming overall to a pre-defined
schema. This file format is referred to inside *apk*(5) as "adb".
# WIRE FORMAT
A v3 apk file is composed of sequences of serialized values, each of
which begins with a 32-bit little-endian word - the value's tag. The
high 4 bits of the tag are a type code, and the low 28 bits are used for
an immediate value. Defined type codes are:
0x0 Special (direct)
0x1 Int (direct)
0x2 Int32 (indirect)
0x3 Int64 (indirect)
0x8 Blob8 (indirect)
0x9 Blob16 (indirect)
0xa Blob32 (indirect)
0xd Array (indirect)
0xe Object (indirect)
A direct value is packed into the low 28 bits of the tag word; an
indirect value is instead stored elsewhere in the file, and the offset
of that indirect value is packed into the low 28 bits of the tag word.
Arrays and objects are represented with a sequence of numbered slots;
the value packed into their tag word is the offset at which this
sequence starts. The first slot is always the total number of slots, so
all arrays and objects contain at least one item.
The only real difference between arrays and objects in the wire encoding
is that arrays are homogenous, whereas objects are heterogenous with a
separate defined type for each slot.
The special type is used to represent three atoms:
0x0 NULL
0x1 TRUE
0x2 FALSE
# FILE SCHEMAS
A schema is a representation of what data elements are expected in an
adb file. Schemas form a tree, where nodes are either scalar schemas
(which are leaves in the tree) or array/object schemas, which themselves
have children. For example, the schema for a package object might
declare that it contains fields which themselves conform to the string
array schema, or the pkginfo schema, or similar.
The schemas themselves are not represented in the adb file in any way;
they exist in the parts of *apk*(1) that read and write such files. A
full description of all of apk's schemas would be lengthy, but as an
example, here is the schema for a single file inside a package:
ADBI_FI_NAME "name" string
ADBI_FI_ACL "acl" acl
ADBI_FI_SIZE "size" int
ADBI_FI_MTIME "mtime" int
ADBI_FI_HASHES "hash" hexblob
ADBI_FI_TARGET "target" hexblob
Here, all of the fields except for "acl" are scalars, and acl is itself
a schema looking like:
ADBI_ACL_MODE "mode" oct
ADBI_ACL_USER "user" string
ADBI_ACL_GROUP "group" string
# BLOCKS
An actual adb file is composed of a sequence of typed blocks; a block
also begins with a 32-bit little-endian tag word, which has two bits of
type and 30 bits of size. The two type bits are:
0x0 ADB
0x1 SIG
0x2 DATA
0x3 DATAX
The adb file must begin with one ADB block, then optionally one SIG
block, then one or more DATA blocks. The ADB block must begin with a
magic number indicating the schema for the entire ADB block's root
object. The ADB block also contains, outside the root object, some
metadata describing the version of the adb format in use.
The SIG block contains a signature of the ADB block. Unlike the v2
format, the key used for the signature is not explicitly specified, so
verifiers must try all trusted keys until they find one. Also unlike the
v2 format, the only supported hash algorithm is SHA512, and the
signature scheme is implied by the signing key in use rather than being
derived from the signature block.
The DATA blocks are used to store package file data only; all file
metadata, including content hashes, is stored in the ADB block instead.
The contents of the DATA blocks are therefore protected by the hashes
given in the ADB block, which is itself protected by the signature in
the SIG block.
It is currently illegal for a DATAX block to appear.
# NOTES
The v3 file format is entangled with C struct layout, since it sometimes
directly writes structs into the adb section, including any
compiler-added padding and such.
# SEE ALSO
*abuild*(1), *apk*(1), *apk-v2*(5)
|
