Handbook Talk:AMD64/Installation/Stage
Before creating a discussion or leaving a comment, please read about using talk pages. To create a new discussion, click here. Comments on an existing discussion should be signed using
~~~~:
A comment [[User:Larry|Larry]] 13:52, 13 May 2024 (UTC) : A reply [[User:Sally|Sally]] 10:29, 5 November 2024 (UTC) :: Your reply ~~~~
Portage and stage3 security recommendations
Tip: To get this fixed sooner, use {{Proposal}}.
As outlined at bugs #597804 and #597800 portage does not operate securely by default. Changes that seem to be pending include:
- stage3 images will include cryptographic keys for the automated establishment of trust
- stage3 images will include a gentoo key management utility
While these are promising improvements, they have been pending for 4 years already and may not be completed soon, and are not enough to fully secure portage's operation, which currently requires manual processes.
Therefore, currently it would seem useful to add a pointer right here in the installation instructions to the secure portage configuration information already documented at Working with Gentoo / Portage Features / Fetching Files / Validated Portage tree snapshots. It might be better to move it here, rather than keep it there, since it's now critical.
Note that the secure sync only works for emerge-webrsync and no security is possible with traditional rsync. Walter (talk) 23:02, 29 October 2016 (UTC)
- Note that securing portage is pointless if the stage3 image downloaded has been compromised. Therefore I would suggest as a related change taking the current text regarding validation of stage3 and promoting it to its own subheading: Validating the stage tarball. In addition, the current text does not explain the problems with man in the middle attacks (in recent years well documented as utilized by state actors) that cannot be resolved with the current recommended process (ie. download stage3 and digests at same time over same network link from an official gentoo mirror - none of which are encrypted under any protocol = both digest and stage3 are compromised at the same time, therefore cannot be trusted). The current text is misleading. Suggested order of content:
- Big fat warning box saying that while the step is optional, if you skip this step there is absolutely no guarantee that you will ever have a secure system and it is highly recommended to bother.
- Rationale: Importance currently understated. New users perhaps unfamiliar with significance.
- Method of obtaining the Gentoo keys on a non-Gentoo host system being used as an install platform should be described. This uses HTTPS to obtain the key IDs, followed by the HKP GPG keyserver protocol (an unencrypted protocol based upon HTTP) to obtain the keys. Probably the keys themselves should be provided via HTTPS.
- Note: The URL for the keys is apparently the Wiki page over here.
- Rationale: Required for subsequent steps.
- Info box on additional high-assurance step of double-validating — re-fetching the same keys from another device/network connection or proxy server, preferably from a different mirror, eg. via smartphone with mobile data, Tor, a secure proxy, or an ssh tunnel (bold underlined super-obvious highlight that critically this must be run from outside the chroot - otherwise you are running potentially compromised code and giving it your remote server credentials!) to a network-geographically disparate server.
- Rationale: This protects against failures in SSL (eg. state-level attackers able to forge certificates to enable SSL MITM), locally compromised SSL certificate chains, MITM attacks on the current HKP (= HTTP = unencrypted) based GPG key acquisition process, and compromised mirrors.
- GPG validation of the stage3.
- Note: Text currently present.
- Rationale: Requirement for subsequent steps.
- Digest validation.
- Note: Currently before the above, and pointless from a security standpoint without first doing the above.
- Rationale: Validates downloaded binary.
- Immediate transition to a new top-level heading (between Installing a stage tarball and Configuring compile option) called Securing portage, with existing content from over here, and a big fat warning box that it is required to maintain system integrity (as per original point).
- -- Walter (talk) 23:18, 29 October 2016 (UTC)
- I saw your comment on bug #597800 pointing here. And I think you should also add your points as a new first chapter in the Security_Handbook even before the Pre installation concerns section.
--Charles17 (talk) 09:56, 28 December 2016 (UTC)
- Your suggestions and concerns did not go unnoticed. I did see them but have no gotten around to them at the moment. As for the present, it would probably be a good idea to capture the practical steps to integrate these changes in wiki markup in the Security Handbook as Charles17 suggested. I will review them and make determinations on each of them over the course of the next few days. Kind regards, --Maffblaster (talk) 21:53, 29 December 2016 (UTC)
Updates accordingly the signature verification process
In section Verifying and validating, the provided instructions don’t work for the verification of the DIGEST file and its (supposedly) detached signature.
user $ gpg --verify stage3-amd64-hardened-20210113T214504Z.tar.xz{.DIGESTS.asc,} gpg: not a detached signature
zsh: exit 2 gpg --verify stage3-amd64-hardened-20210113T214504Z.tar.xz{.DIGESTS.asc,}Same with the DIGEST file:
user $ gpg --verify stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS{.asc,} gpg: not a detached signature
zsh: exit 2 gpg --verify stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS{.asc,}However, it looks like this is a signature itself is valid, and holds the content of the DIGEST file, but doesn’t allow to verify the DIGEST file itself:
user $ gpg --verify stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS.asc ../.. gpg: Good signature from "Gentoo Linux Release Engineering (Automated Weekly Release Key) <releng@gentoo.org>" [unknown] ../.. gpg: WARNING: not a detached signature; file 'stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS' was NOT verified!
user $ gpg --decrypt stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS.asc # SHA512 HASH
cc4207cf06ccc0aac16664e878815f35d12fb0bb3ecb9351db0b0b144b02a969be81a6d205fef68d7f39df0d31e9499c63464d2656a6faf16e64dd8fa6aa5478 stage3-amd64-hardened-20210113T214504Z.tar.xz
# WHIRLPOOL HASH
aa25fcae36ca8497270f4a99a255dd8b6afaccb103a8d9ce7e08f646231c8475b90e7b906e2e83185414f40eb34aabd6369f2c07ee1d499410c4932252f7e144 stage3-amd64-hardened-20210113T214504Z.tar.xz
# SHA512 HASH
805fadf0205411719d992b3145ca1b45385c6fae6042c0e5f343854cc341784c5ede451cc5a220084a125bdfae5454151b4535dab0392f15cf75dd33393f679b stage3-amd64-hardened-20210113T214504Z.tar.xz.CONTENTS.gz
# WHIRLPOOL HASH
b3d475fb211344e7c5de080b1170dbb1365bd5f9ef506fe6592eef3bd3d933ddcf2011e507331f6ca7753150f9e8f1288d1e3e10d705ed6d3682666441eb2c96 stage3-amd64-hardened-20210113T214504Z.tar.xz.CONTENTS.gz
gpg: Signature made jeu. 14 janv. 2021 05:41:04 CET
gpg: using RSA key 534E4209AB49EEE1C19D96162C44695DB9F6043D
gpg: Good signature from "Gentoo Linux Release Engineering (Automated Weekly Release Key) <releng@gentoo.org>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 13EB BDBE DE7A 1277 5DFD B1BA BB57 2E0E 2D18 2910
Subkey fingerprint: 534E 4209 AB49 EEE1 C19D 9616 2C44 695D B9F6 043DTwo possible outcomes:
- Create a real detachable signature (to Infrastructure team, I guess):
When using gpg(1), the correction option to create a detachable signature is "--detach-sign", as follow (with --armor, for only ASCII content):
user $ gpg --detach-sign --armor stage3-[…].DIGESTS On its own, GnuPG will create an "asc" suffixed file (with --armor, it’s ".sig").
- Update the instructions as follow:
Currently, with this issue, we can’t check the content of the DIGEST file itself, using the "--verify" option.
user $ gpg --verify stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS.asc ../.. gpg: WARNING: not a detached signature; file 'stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS' was NOT verified!
We can fix the instruction and provide a way to see the signed content thanks to "--decrypt" option; however, "decrypt" is not an obvious way to verify a signature, but it allows to check its content when disregarding stderr (same as above):
user $ gpg --decrypt stage3-amd64-hardened-20210113T214504Z.tar.xz.DIGESTS.asc 2> /dev/null # SHA512 HASH cc4207cf06ccc0aac16664e878815f35d12fb0bb3ecb9351db0b0b144b02a969be81a6d205fef68d7f39df0d31e9499c63464d2656a6faf16e64dd8fa6aa5478 stage3-amd64-hardened-20210113T214504Z.tar.xz # WHIRLPOOL HASH aa25fcae36ca8497270f4a99a255dd8b6afaccb103a8d9ce7e08f646231c8475b90e7b906e2e83185414f40eb34aabd6369f2c07ee1d499410c4932252f7e144 stage3-amd64-hardened-20210113T214504Z.tar.xz # SHA512 HASH 805fadf0205411719d992b3145ca1b45385c6fae6042c0e5f343854cc341784c5ede451cc5a220084a125bdfae5454151b4535dab0392f15cf75dd33393f679b stage3-amd64-hardened-20210113T214504Z.tar.xz.CONTENTS.gz # WHIRLPOOL HASH b3d475fb211344e7c5de080b1170dbb1365bd5f9ef506fe6592eef3bd3d933ddcf2011e507331f6ca7753150f9e8f1288d1e3e10d705ed6d3682666441eb2c96 stage3-amd64-hardened-20210113T214504Z.tar.xz.CONTENTS.gz
For me, the fix is the solution 1; it’s not a wiki issue, it looks like a signed process fault, and I guess this discussion is not at the right place.
But I might be wrong ;-)
By the way, I might have found a link to this issue: bug #587486
Thican (talk) 00:42, 17 January 2021 (UTC)
- Looking at that bug, it seems to be closed now and after trying the instructions myself in a virtual machine I was able to successfully verify the files listed in the Handbook. Thanks for bringing it to our attention though!
- --csfore (talk) 18:49, 23 October 2024 (UTC)
Minor typo
At the very bottom of the page, there is a space missing in "Then continue withInstalling the Gentoo base system." --Dhirsbrunner (talk) 02:16, 16 June 2023 (UTC)
- Looks like this was fixed at some point, but I'm not sure when! Thanks! --Maffblaster (talk) 08:14, 3 September 2023 (UTC)
Minor typo in the verification command
This line:
root #gpg --verify stage3-amd64-<release>-<init>.tar.xz.DIGESTshould be replaced with this one (DIGEST -> DIGESTS):
root #gpg --verify stage3-amd64-<release>-<init>.tar.xz.DIGESTS-- Lars Hint (talk) 15:08, 29 January 2024 (UTC)
- Fixed in Special:Diff/1298131/1298154, thanks!
- --csfore (talk) 18:40, 11 May 2024 (UTC)
Minor clarification of pwd
Total nit--I suggest moving the "the current directory should be set to the location of the mount used for the install" comment to somewhere more appropriate. I didn't need to set up my clock manually, so I missed this comment. Maybe putting it right under the "Downloading the stage file" heading, before "Setting the date and time" would be better.
--Emptonaut (talk) 23:27, 19 February 2024 (UTC)
Change position of cd /mnt/gentoo
The section: "Before downloading the stage file, the current directory should be set to the location of the mount used for the install, (most likely /mnt/gentoo): cd /mnt/gentoo" should be moved from Setting the date and time/Manual TO BE the first step in "Downloading the stage file" (before Setting the date and time) because it is misleading in its current place. See also forums post: https://forums.gentoo.org/viewtopic-t-1167640-highlight-.html
--Pietinger 15:56, 02 March 2024 (UTC)
- As discussed in #gentoo-wiki, this is an oversight and should be resolved. I think this fix should become part of Handbook:Parts/Installation/Disks
- The fix should become:
Continue mounting additional (custom) partitions as necessary using the mount command.
If /tmp/ needs to reside on a separate partition, be sure to change its permissions after mounting:
root #chmod 1777 /tmpFinally, change the current working directory to /mnt/gentoo to make the rest of the installation easier.
root #cd /mnt/gentoo- I think even better is: Make "Setting the date and time" as a main chapter: 2. Setting the date and time -> 2.1 Automatic + 2.2 Manual and then 3 Downloading the stage file -> 3.1 Changing to /mnt/gento + 3.2 Graphical browsers + 3.3 Command-line browsers ... and so on ... --Pietinger 16:25, 04 April 2024 (UTC)
- As discussed in #gentoo-wiki, I think the discussion around changing where "cd" is described is missing the point a bit. Where to download it to is really up to the user, downloading it to the rootfs can be convenient since it's guaranteed writable and has a lot of space on it but is by no means guaranteed -- and downloading it to e.g. /tmp can mean no need to clean it up by hand. The larger issue is that passing
-C /mnt/gentoois a good idea regardless, to control the output location explicitly (even if it is the current directory). This is a general principle of using tar. Sam notes a concern that wiki editors might think the cd and the -C are duplicates and remove one or the other from the instructions -- I think the consequences of removing the cd are mild, but we could add a note explaining that the cd is because /mnt/gentoo is guaranteed to have space, and hopefully people will think twice about modifying the page.
Once the stage file has been downloaded and verified, it can be extracted using tar:
root #tar xpvf --xattrs-include='*.*' --numeric-owner -C /mnt/gentooBefore extracting verify the options:
xextract, instructs tar to extract the contents of the archive.ppreserve permissions.vverbose output.ffile, provides tar with the name of the input archive.--xattrs-include='*.*'Preserves extended attributes in all namespaces stored in the archive.--numeric-ownerEnsure that the user and group IDs of files being extracted from the tarball remain the same as Gentoo's release engineering team intended (even if adventurous users are not using official Gentoo live environments for the installation process).-C /mnt/gentooExtract files to the root partition regardless of the current directory.
- Discussed in #gentoo-wiki. Some concerns were raised:
- about how adding an explicit path to the tar command might not always work. "Might it have something to do with arches other than amd64?" -- I cannot think of a reason this could ever be an issue, the tar command should not care.
- the directory might not always be /mnt/gentoo. Perhaps this explains the non-amd64 arches thing. -- I took a quick look at the rest of the handbook, it appears all arches are consistent here. Ris pointed out that we can anyways solve this by using Project:Handbook/Handbook_Development#Architectural_parameters here, which is a very neat idea.
- --Eschwartz (talk) 18:12, 22 July 2024 (UTC)
- Discussed in #gentoo-wiki. Some concerns were raised:
- Added in Special:Diff/1305364/1317147, thanks!
- --csfore (talk) 19:20, 23 October 2024 (UTC)
Insist that the stage3 untar command must be run as root
In my testing if the stage3 untar command is run as an unprivileged user the command will complete without any worrying error message, however the permissions will be set incorrectly on the extracted files.
I know that the prompt is the indication that the command should be run as root, but this seems like an exceptional case for which we should provide more explicit indication as 1) most other commands will error out if run with insufficient privileges, 2) making the mistake at this point will ruin the whole installation 3) the only way to fix this will be to wipe the system and restart the installation from scratch, and I'm not sure at what point such a mistake will necessarily be noticed.
In the corresponding section it says that the tar command options are set to "preserve permissions" and to "ensure that the user and group IDs of files being extracted from the tarball remain the same as Gentoo's release engineering team intended", which might make it even more confusing when this is not the case if you mess up which user you run the command as.
Am I right on this, or am I doing something else wrong, or might there be something wrong with my system making this happen?
AFAICS, we don't specify at all in the handbook that the user should open a root shell - it's just implied by the prompt. This seems like a case where being more explicit about it might help catch a really painful issue.