[gentoo-commits] data/glep:glep-manifest commit in: /

[Michał Górny]

commit:     7f9bd9fa8aa0f21950a4c42e20fca1bc10f4c22c
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Nov 20 17:22:40 2017 +0000
Commit:     Michał Górny <mgorny <AT> gentoo <DOT> org>
CommitDate: Mon Nov 20 17:22:40 2017 +0000
URL:        https://gitweb.gentoo.org/data/glep.git/commit/?id=7f9bd9fa

glep-0074: Include suggestions from Daniel Campbell

 glep-0074.rst | 59 ++++++++++++++++++++++++++++++-----------------------------
 1 file changed, 30 insertions(+), 29 deletions(-)

diff --git a/glep-0074.rst b/glep-0074.rst
index 42c0c9e..6081937 100644
--- a/glep-0074.rst
+++ b/glep-0074.rst
@@ -19,7 +19,7 @@ Abstract
 ========
 
 This GLEP extends the Manifest file format to cover full-tree file
-integrity and authenticity checks.The format aims to be future-proof,
+integrity and authenticity checks. The format aims to be future-proof,
 efficient and provide means of backwards compatibility.
 
 
@@ -435,7 +435,7 @@ The stand-alone format has been selected because of its three
 advantages:
 
 1. It is more future-proof. If an incompatible change to the repository
-   format is introduced, only developers need to be upgrade the tools
+   format is introduced, only developers need to upgrade the tools
    they use to generate the Manifests. The tools used to verify
    the updated Manifests will continue to work.
 
@@ -498,7 +498,7 @@ the following implications:
 
 While both models have their advantages, the hierarchical model was
 selected because it reduces the number of OpenPGP operations
-which are comparatively costly to the minimum.
+(which are comparatively costly) to the minimum.
 
 
 Tree layout restrictions
@@ -606,14 +606,14 @@ the purpose of using ``MISC``.
 Finally, the non-strict mode could be used as means to an attack.
 The allowance of missing or modified documentation file could be used
 to spread misinformation, resulting in bad decisions made by the user.
-A modified file could also be used e.g. to exploit vulnerabilities
+A modified file could also be used, e.g. to exploit vulnerabilities
 of an XML parser.
 
 
 Timestamp field
 ---------------
 
-The top-level Manifests optionally allows using a ``TIMESTAMP`` tag
+The top-level Manifest optionally allows using a ``TIMESTAMP`` tag
 to include a generation timestamp in the Manifest. A similar feature
 was originally proposed in GLEP 58 [#GLEP58]_.
 
@@ -622,10 +622,10 @@ A malicious third-party may use the principles of exclusion or replay
 the identity of clients to attack. The timestamp field can be used to
 detect that.
 
-In order to provide a more complete protection, the Gentoo
-Infrastructure should provide an ability to obtain the timestamps
-of all Manifests from a recent timeframe over a secure channel
-from a trusted source for comparison.
+In order to provide more complete protection, the Gentoo Infrastructure
+should provide an ability to obtain the timestamps of all Manifests
+from a recent timeframe over a secure channel from a trusted source
+for comparison.
 
 Strictly speaking, this information is already provided by the various
 ``metadata/timestamp*`` files that are already present. However,
@@ -635,7 +635,7 @@ and provides the ability to perform the verification stand-alone.
 Furthermore, some of the timestamp files are added very late
 in the distribution process, past the Manifest generation phase. Those
 files will most likely receive ``IGNORE`` entries and therefore
-be not suitable to safe use.
+be unsafe to use.
 
 The specification permits additional timestamps in sub-Manifest files
 for local use. A generic testing tool should ignore them.
@@ -645,7 +645,7 @@ New vs deprecated tags
 ----------------------
 
 Out of the four types defined by Manifest2, only one is reused
-and the remaining three is replaced by a single, universal ``DATA``
+and the remaining three are replaced by a single, universal ``DATA``
 type.
 
 The ``DIST`` tag is reused since the specification does not change
@@ -696,11 +696,11 @@ in the top-level Manifest.
 Injecting ChangeLogs into the checkout
 --------------------------------------
 
-One of the problems considered in the new Manifest format was that
-of injecting historical and autogenerated ChangeLog into the repository.
-Normally we are not including those files to reduce the checkout size.
-However, some users have shown interest in them and Infra is working
-on providing them via an additional rsync module.
+One of the problems considered in the new Manifest format was injecting
+historical and autogenerated ChangeLog into the repository. We normally
+don't include those files, to reduce the checkout size. However, some
+users have shown interest in them and Infra is working on providing them
+via an additional rsync module.
 
 If such files were injected into the repository, they would cause
 verification failures of Manifests. To account for this, Infra could
@@ -733,9 +733,9 @@ Hash algorithms
 ---------------
 
 While maintaining a consistent supported hash set is important
-for interoperability, it is no good fit for the generic layout of this
-GLEP. Furthermore, it would require updating the GLEP in the future
-every time the used algorithms change.
+for interoperability, it is not a good fit for the generic layout
+of this GLEP. Furthermore, it would require updating the GLEP
+in the future every time the used algorithms change.
 
 Instead, the specification focuses on listing the currently used
 algorithm names for interoperability, and sets a recommendation
@@ -761,10 +761,11 @@ entries and to avoid confusion.
 
 The compression of top-level Manifest file has been prohibited
 as the specification currently does not provide any means of verifying
-the file prior to decompression. This would make it possibly for
-a malicious third party to provide a compressed Manifest exposing
-decompressor vulnerabilities, or being a zip bomb, and the tooling
-would have to unpack it before being able to verify the contents.
+the file prior to decompression. If the top-level Manifest is
+compressed, tooling will have to unpack the file before being able
+to verify the contents. This makes it possible for a malicious third
+party to attack the system by providing a compressed Manifest that
+exposes decompressor vulnerabilities, or a zip bomb.
 
 The OpenPGP cleartext signature covers the contents of the Manifest,
 and is therefore compressed along with them. The possibility of using
@@ -778,10 +779,10 @@ in a signed, uncompressed top-level Manifest.
 
 The existence of additional entries for uncompressed Manifest checksums
 was debated. However, plain entries for the uncompressed file would
-be confusing if only compressed file existed, and conflicting if both
-uncompressed and compressed variants existed. Furthermore, it has been
-pointed out that ``DIST`` entries do not have uncompressed variant
-either.
+be confusing if only the compressed file existed, and conflicting
+if both uncompressed and compressed variants existed. Furthermore,
+it has been pointed out that ``DIST`` entries do not have uncompressed
+variant either.
 
 
 Performance considerations
@@ -792,7 +793,7 @@ performance concerns for end-user systems. The initial testing has shown
 that a cold-cache verification on a btrfs file system can take up around
 4 minutes, with the process being mostly I/O bound. On the other hand,
 it can be expected that the verification will be performed directly
-after syncing, taking advantage of warm filesystem cache.
+after syncing, taking advantage of a warm filesystem cache.
 
 To improve speed on I/O and/or CPU-restrained systems even further,
 the algorithms can be easily extended to perform incremental
@@ -849,7 +850,7 @@ to the creation of this GLEP. This includes but is not limited to:
 - Ulrich Müller.
 
 Additionally, thanks to Robin Hugh Johnson for the original
-MataManifest GLEP series which served both as inspiration and source
+MetaManifest GLEP series which served both as inspiration and source
 of many concepts used in this GLEP. Recursively, also thanks to all
 the people who contributed to the original GLEPs.