Update format documentation in the manual #2835
Conversation
| it is used for both the Header and the Signature. The details of the | ||
| header structure are given below, and you'll want to read them so the | ||
| rest of this makes sense. The tags for the Signature are defined in | ||
| lib/signature.h. |
There was a problem hiding this comment.
Everywhere that mentioned source code previously was broken 💔
docs/manual/format.md
Outdated
| 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 |
There was a problem hiding this comment.
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)
docs/manual/format.md
Outdated
| 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 |
There was a problem hiding this comment.
Is "4.0" fine or ought we to use something along the lines of "V4" instead?
There was a problem hiding this comment.
This does not describe v4 file format, so we should not bump the number either. For v4, the by far most important item is the immutable region and that is not even mentioned anywhere here. Not surprising since most of the content is from the initial commit in 1996 (cdd4c29)
There was a problem hiding this comment.
I can add some descriptions of the immutable region. I believe that's documented somewhere, maybe it's worth merging into this document.
There was a problem hiding this comment.
Done. Any other features to mention?
docs/manual/format.md
Outdated
| 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. |
There was a problem hiding this comment.
Is it possible to define an alias for DSAHEADER such that it can be referred to as EDDSAHEADER?
Is there any particular reason to have two tags in the first place, other than that a pattern was started with RSAHEADER that might as well continue? AFAIK the PGP certificate embeds enough information to know which algorithm it was created with.
edit: actually this was discussed when they were added too #1571 (comment)
I don’t particularly care which tag is used, so long as it works. Can we eliminate the distinction in RPMv6?
We'd need some way to tell what keys are what type, but there are certainly better ways to do it. Ideally, RPMv6 would also include fixing support for multiple signatures.
There was some discussion in other threads about creating RPMTAG_OPENPGPHEADER, doesn't look like that went anywhere though.
There was a problem hiding this comment.
Possible? Technically yes but it doesn't make it any more right or any easier for the user, only more confusing.
dralley
force-pushed
the
update-manual
branch
2 times, most recently
from
a561596 to
b891bfc
Compare
| The next two bytes (8-9) form an int16 that indicates the architecture | ||
| the package was built for. While this is used by file(1), the true | ||
| architecture is stored as a string in the Header. See, lib/misc.c for | ||
| a list of architecture->int16 translations. In this case, 1 == i386. |
There was a problem hiding this comment.
I couldn't find that mapping anymore, but I don't know if we have much need to discuss it anyway.
There was a problem hiding this comment.
No wonder, the arch translations have been in the declarative rpmrc config file for over twenty years. This is one of the docs thats so old it makes you wonder if its worth trying to patch it up...
dralley
force-pushed
the
update-manual
branch
2 times, most recently
from
f446376 to
dbd7eb8
Compare
dralley
force-pushed
the
update-manual
branch
4 times, most recently
from
019b544 to
0449658
Compare
| @@ -264,3 +256,101 @@ could start at byte 589, byte that is an improper boundary for an INT32. | |||
| As a result, 3 null bytes are inserted and the date for the SIZE actually | |||
| starts at byte 592: "00 09 9b 31", which is 629553). | |||
|
|
|||
| ### Immutable header regions | |||
There was a problem hiding this comment.
I kept any changes to this document in a separate commit so they can be more easily reviewed.
There's plenty of room for improvement still, but this seems halfway reasonable?
There was a problem hiding this comment.
There's lots in the hregion text that fits neither the style or content otherwise (like lack of technical detail), but it's a start. Documenting the details is going to be quite a bit of work that I need to do anyhow sooner than later.
Make it (mostly) up to date with RPMv4 standards. Also fix some broken links, and mark old signature tags as deprecated.
dralley
force-pushed
the
update-manual
branch
from
9f3185c to
eb08565
Compare
|
Updated |
|
The more I looked at this and the existing docs, the more clear it became that the stuff needs more than a touch-up job to be credible. I ended up rewriting much of bit of it, updating and preserving the v3 docs too for historians and the like: #2861. That was quite the pile to chew out in a day, so there will be gaps and mistakes and all but I think it's now a more solid place to build on now. After that churn, this PR wont be anywhere near applicable, but. There's good stuff in this PR and I initially tried to pull as much content from this PR as possible but got nowhere with that approach, because the initial state is what it is. I'll go through this once more once the dust settles to double-check what additions I missed and apply manually. Thanks for the patch and initiative to get this updated! Getting v4 documented was one of my goals for last year and this PR was apparently the necessary kick to get started 😄 |
|
Understood, thanks! Feel free to close this once you're done with it. |
|
I'm not actually finished with this, but I do have a local backup anyway, closing is okay. |
Make it (mostly) up to date with RPMv4 standards.
Also fix some broken links, and mark old signature tags as deprecated.