[Rpm-maint] [rpm-software-management/rpm] Document rpmkeys output and the overall verify policy in some detail (PR #4170)

[Michal Domonkos]

@dmnks commented on this pull request.



>      ...
 ```
 
+	The output is on the level of individual verifiables.
+
+	Range describes the area which the verifiable covers. Possible
+	values are:
+	- *Header*: The main header of the package
+	- *Payload*: The payload of the package
+	- *Legacy*: The main header and the payload of the package
+
+	Description includes general information about this verifiable,
+	such the algorithm name and OpenPGP version of a signature.

I know this is just an enumeration ("such as"), but the real output typically starts with the OpenPGP version (followed by the algo name), so let's mention that first here as well.

Also, "as" is missing after "such" 😆 

>      ...
 ```
 
+	The output is on the level of individual verifiables.
+
+	Range describes the area which the verifiable covers. Possible
+	values are:
+	- *Header*: The main header of the package
+	- *Payload*: The payload of the package
+	- *Legacy*: The main header and the payload of the package
+
+	Description includes general information about this verifiable,
+	such the algorithm name and OpenPGP version of a signature.
+
+	*ALT* indicates the verifiable is an optional alternative to another
+	verifiable.
+
+	Class is one of *digest* or *signature*.

There's also the ", key fingerprint XYZ" suffix on signature lines, it should probably be mentioned (somewhere) as well.

> @@ -79,19 +80,87 @@ See *rpm-common*(8) for the options common to all *rpm* executables.
 	configured keystore backend.
 	This can be used to convert from one key storage to another.
 
+# VERIFICATION POLICY
+To deal with three generations of package formats and as many decades of
+cryptographic algorithms and differing system policies, the RPM package
+verification is a complicated system with many moving parts.
+
+RPM packages contain multiple individual _verifiables_ that cover different
+parts of the package: header, payload or both, using different cryptographic
+algorithms. There are two _classes_ of verifiables: digests and signatures,
+and a verification result is calculated independently for each, based on
+the results from the individual verifiables.
+For a per-class pass, passing verifiables of that class to cover

This paragraph introduces the terminology so I'd keep it at that, and move the last sentence (which talks about the *policy*) to a separate paragraph on its own. Actually, I'd maybe join all the paragraphs talking about the positive results into one, and the have another paragraph talking about the negative results.

Also, this last sentence reads a bit awkwardly 😅 How about something like:

"For a class to verify, both the header and payload verifiables of that class must verify."

That also makes me think that we should define a term for the "pass" and "fail" outcomes, which are currently used interchangeably with "verifies", "success", "OK" (and so on) in this section. Having a single term for either outcome would make it less ambiguous, I feel like...

>  ```
 
-	With *--verbose*:
+	The output is on the level of digest and signature class, which
+	often includes results from multiple individual verifiables.
+	Classes that verify are printed in lowercase, failing classes
+	in uppercase. The final package level conclusion per current

Cosmetic: I'd maybe write "uppercase" as "UPPERCASE" here, just to signify 😄 

-- 
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/4170?email_source=notifications&email_token=ADLPZU4N6PSZF4C52T5EDCL4TU7E3A5CNFSNUABKM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UKJSXM2LFO4XTIMBTGY3DOMRWGE2KM4TFMFZW63VKON2WE43DOJUWEZLEUVSXMZLOOS6XA4S7OJSXM2LFO5PW433UNFTGSY3BORUW63TTL5RWY2LDNM#pullrequestreview-4036672614
You are receiving this because you are subscribed to this thread.

Message ID: <rpm-software-management/rpm/pull/4170/review/4036672614 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rpm.org/pipermail/rpm-maint/attachments/20260401/6de8cdaa/attachment.htm>