[Rpm-maint] [rpm-software-management/rpm] Update format documentation in the manual (PR #2835)

[Daniel Alley]

@dralley commented on this pull request.



> +
+The Signature can contain multiple different types of signatures, stored under
+unique tags (just like the Header). Details about these tags and the information
+they store can be found [here](signatures_digests.md).
+
+RPM v4 packages are expected to contain at least one of SHA1HEADER or SHA256HEADER
+tags, providing a cryptographic digest of the main header, and may contain one
+or both of the PAYLOADDIGEST and PAYLOADDIGESTALT tags, providing a cryptographic
+digest of the package payload in the compressed and uncompressed forms, respectively.
+
+If the package has been cryptographically signed using OpenPGP, an RSAHEADER or
+DSAHEADER tag ought to be present, which contains an OpenPGP signature of the
+package header. Which tag is present depends on which of the two (supported)
+OpenPGP algorithms was used at signing time. Using a key based upon the RSA
+algorithm to sign the package will result in the signature being stored in the
+RSAHEADER tag, whereas the use of the EdDSA (ed25519) algorithm will use the

I'm not a cryptography person, I'm unsure if this is an appropriate way to refer to an EdDSA signature that uses curve ed25519, or if it's OK to just refer to it as EdDSA (as happens in a few other places)

>  # Package format
 
-This document describes the RPM file format version 3.0, which is used
-by RPM versions 2.1 and greater.  The format is subject to change, and
-you should not assume that this document is kept up to date with the
-latest RPM code.  That said, the 3.0 format should not change for
-quite a while, and when it does, it will not be 3.0 anymore :-).
+This document describes the RPM file format version 4.0.  The format is subject

Is "4.0" fine or ought we to use something along the lines of "V4" instead?

> -header structure:
-
-```
-	Name	Tag	Header Type
-	----	----	-----------
-	SIZE	1000	INT_32
-	MD5	1001	BIN
-	PGP	1002	BIN
-```
-
-The MD5 signature is 16 bytes, and the PGP signature varies with
-the size of the PGP key used to sign the package.
-
-As of RPM 2.1, all packages carry at least SIZE and MD5 signatures,
-and the Signature section is padded to a multiple of 8 bytes.
+"Header-style" signatures (denoted by signature type 5 in the Lead), use the

Unsure if "denoted by" should stay - at this point, it should probably be assumed, regardless of what the lead says.  No reason to look at the lead at all.

> +they store can be found [here](signatures_digests.md).
+
+RPM v4 packages are expected to contain at least one of SHA1HEADER or SHA256HEADER
+tags, providing a cryptographic digest of the main header, and may contain one
+or both of the PAYLOADDIGEST and PAYLOADDIGESTALT tags, providing a cryptographic
+digest of the package payload in the compressed and uncompressed forms, respectively.
+
+If the package has been cryptographically signed using OpenPGP, an RSAHEADER or
+DSAHEADER tag ought to be present, which contains an OpenPGP signature of the
+package header. Which tag is present depends on which of the two (supported)
+OpenPGP algorithms was used at signing time. Using a key based upon the RSA
+algorithm to sign the package will result in the signature being stored in the
+RSAHEADER tag, whereas the use of the EdDSA (ed25519) algorithm will use the
+DSAHEADER tag instead.  The name of the DSAHEADER tag is a historical artifact,
+it originally referred to the long-obsolete DSA algorithm but was later reused
+for EdDSA (ed25519) signatures.

Is it possible to define an alias?

-- 
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/2835#pullrequestreview-1807604224
You are receiving this because you are subscribed to this thread.

Message ID: <rpm-software-management/rpm/pull/2835/review/1807604224 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rpm.org/pipermail/rpm-maint/attachments/20240106/face154a/attachment.html>