1 |
Signed-off-by: Michał Górny <mgorny@g.o> |
2 |
--- |
3 |
glep-0074.rst | 82 ++++++++++++++++++++++++++++++++++++++++++++------- |
4 |
1 file changed, 72 insertions(+), 10 deletions(-) |
5 |
|
6 |
diff --git a/glep-0074.rst b/glep-0074.rst |
7 |
index 33f6f80..6deeaf8 100644 |
8 |
--- a/glep-0074.rst |
9 |
+++ b/glep-0074.rst |
10 |
@@ -27,7 +27,8 @@ Changes |
11 |
======= |
12 |
|
13 |
v1.3 |
14 |
- Formally specified the current set of hash algorithms supported. |
15 |
+ Formally specified the current set of hash algorithms and compressed |
16 |
+ Manifest formats supported. |
17 |
|
18 |
v1.2 |
19 |
Specified the newline convention used for Manifests. |
20 |
@@ -422,9 +423,8 @@ compression and this specification. |
21 |
|
22 |
The compressed Manifest files are required to be suffixed for their |
23 |
compression algorithm. This suffix should be used to recognize |
24 |
-the compression and decompress Manifests transparently. The exact list |
25 |
-of algorithms and their corresponding suffixes are outside the scope |
26 |
-of this specification. |
27 |
+the compression and decompress Manifests transparently. The supported |
28 |
+formats are specified in `compressed file formats`_ section. |
29 |
|
30 |
The top-level Manifest file must not be compressed. Since the OpenPGP |
31 |
signature covers the uncompressed text and is compressed itself, |
32 |
@@ -445,6 +445,47 @@ uncompressed content and the specification is free to choose either |
33 |
of the files using the same base name. |
34 |
|
35 |
|
36 |
+Compressed file formats |
37 |
+----------------------- |
38 |
+ |
39 |
+.. table:: Table 2. Defined compressed file formats |
40 |
+ :widths: auto |
41 |
+ :class: table table-bordered table-striped |
42 |
+ |
43 |
+ =========== ====== ==================== =========== |
44 |
+ Tool name Suffix Specification Notes |
45 |
+ =========== ====== ==================== =========== |
46 |
+ bzip2 .bz2 (none known) |
47 |
+ gzip .gz RFC 1952 [#RFC1952]_ Recommended |
48 |
+ lz4 .lz4 (none known) |
49 |
+ lzip .lz RFC draft [#LZIP]_ |
50 |
+ lzma .lzma (none known) Deprecated |
51 |
+ lzop .lzo (none known) |
52 |
+ xz .xz xz [#XZ]_ |
53 |
+ zstd .zst RFC 8878 [#RFC8878]_ |
54 |
+ =========== ====== ==================== =========== |
55 |
+ |
56 |
+Any new formats must be added to this specification prior to being used |
57 |
+for Manifest files. Adding a new compressed file format is considered |
58 |
+a backwards-compatible change to the GLEP. It is recommended that new |
59 |
+formats use their reference (most common) file suffixes. |
60 |
+ |
61 |
+An implementation can implement an arbitrary subset of the listed |
62 |
+formats. For best interoperability, it should implement at least |
63 |
+the recommended formats. Using deprecated formats should be avoided. |
64 |
+ |
65 |
+If multiple Manifest variants coexist using different compressed file |
66 |
+formats, the implementation may choose to use an arbitrary subset |
67 |
+of them. However, all of them must be verified against the hashes stored |
68 |
+in the containing Manifest. Should they be decompressed, the resulting |
69 |
+contents must be identical. |
70 |
+ |
71 |
+If the compressed file format is unsupported and a variant using |
72 |
+a supported format coexists, the other variant should be used. However, |
73 |
+at least one supported variant must exist for the verification |
74 |
+to succeed. |
75 |
+ |
76 |
+ |
77 |
Combining multiple Manifest trees (informational) |
78 |
------------------------------------------------- |
79 |
|
80 |
@@ -986,12 +1027,19 @@ into a compressed sub-Manifest in the top directory (e.g. |
81 |
``Manifest.sub.gz``), and including a ``MANIFEST`` entry for this file |
82 |
in a signed, uncompressed top-level Manifest. |
83 |
|
84 |
-The existence of additional entries for uncompressed Manifest checksums |
85 |
-was debated. However, plain entries for the uncompressed file would |
86 |
-be confusing if only the compressed file existed, and conflicting |
87 |
-if both uncompressed and compressed variants existed. Furthermore, |
88 |
-it has been pointed out that ``DIST`` entries do not have |
89 |
-an uncompressed variant either. |
90 |
+The existence of additional entries for checksums of Manifest contents |
91 |
+after uncompressing was debated. However, plain entries for |
92 |
+the uncompressed file would be confusing if only the compressed file |
93 |
+existed. Furthermore, it has been pointed out that ``DIST`` entries |
94 |
+do not have an uncompressed variant either. |
95 |
+ |
96 |
+The specification permits coexistence of multiple variants of the same |
97 |
+Manifest file using different compression for historical compatibility. |
98 |
+However, there does not seem to be any real benefit from including |
99 |
+a compressed Manifest file if the uncompressed variant needs to exist |
100 |
+anyway. Providing different compressed variants could technically |
101 |
+improve interoperability, though the same result could probably |
102 |
+be achieved by using a more commonly supported format (e.g. gzip). |
103 |
|
104 |
|
105 |
Performance considerations |
106 |
@@ -1123,6 +1171,20 @@ References |
107 |
.. [#WHIRLPOOL] The WHIRLPOOL Hash Function (archived at 2017-11-29) |
108 |
(https://web.archive.org/web/20171129084214/http://www.larc.usp.br/~pbarreto/WhirlpoolPage.html) |
109 |
|
110 |
+.. [#RFC1952] RFC 1952: GZIP file format specification version 4.3 |
111 |
+ (https://www.rfc-editor.org/rfc/rfc1952) |
112 |
+ |
113 |
+.. [#LZIP] RFC draft: Lzip Compressed Format and the 'application/lzip' |
114 |
+ Media Type |
115 |
+ (https://datatracker.ietf.org/doc/html/draft-diaz-lzip) |
116 |
+ |
117 |
+.. [#XZ] The .xz File Format |
118 |
+ (https://tukaani.org/xz/xz-file-format.txt) |
119 |
+ |
120 |
+.. [#RFC8878] RFC 8878: Zstandard Compression and the 'application/zstd' |
121 |
+ Media Type |
122 |
+ (https://www.rfc-editor.org/rfc/rfc8878) |
123 |
+ |
124 |
.. [#C08] Cappos, J et al. (2008). "Attacks on Package Managers" |
125 |
(https://www2.cs.arizona.edu/stork/packagemanagersecurity/attacks-on-package-managers.html) |
126 |
|
127 |
-- |
128 |
2.37.3 |