From Fedora Project Wiki
m (Grammar)
m (Fix the bug number)
 
(25 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<!--Todo:
<!--Todo:
* Merge and arrange 'long-term' suggestions in a coherent manner-->
• Send pull request on schedule
• Add instructions to ensure the future signing of files (kernel postinstall and maybe rpm postinstall (if next point doesn't cover it already through an rpm postinstall hook to grub scripts)) to "Detailed Description" and "How to Test"
• Review "Detailed Description" for functionality that can be presently implemented
• Has change now become system-wide?-->
<!-- Self Contained or System Wide Change Proposal?
<!-- Self Contained or System Wide Change Proposal?
Use this guide to determine to which category your proposed change belongs to.
Use this guide to determine to which category your proposed change belongs to.
Line 20: Line 23:
-->
-->
<!-- The actual name of your proposed change page should look something like: Changes/Your_Change_Proposal_Name.  This keeps all change proposals in the same namespace -->
<!-- The actual name of your proposed change page should look something like: Changes/Your_Change_Proposal_Name.  This keeps all change proposals in the same namespace -->
<!-- The actual name of your proposed change page should look something like: Changes/Include_security_modules_in_efi_Grub2. This keeps all change proposals in the same namespace -->
<!-- The actual name of your proposed change page should look something like: Changes/Include_security_modules_in_efi_Grub2. This keeps all change proposals in the same namespace -->
= Include several modules in the EFI build of Grub2 for security use-cases <!-- The name of your change proposal --> =
= Include several modules in the EFI build of Grub2 for security use-cases <!-- The name of your change proposal --> =


Line 26: Line 29:
<!-- A sentence or two summarizing what this change is and what it will do. This information is used for the overall changeset summary page for each release.  
<!-- A sentence or two summarizing what this change is and what it will do. This information is used for the overall changeset summary page for each release.  
Note that motivation for the change should be in the Motivation section below, and this part should answer the question "What?" rather than "Why?". -->
Note that motivation for the change should be in the Motivation section below, and this part should answer the question "What?" rather than "Why?". -->
Include Grub's "verify," "cryptodisk" and "luks" modules (and if necessary, relevant gcry modules) in the EFI build of Grub2.
Include Grub's "verify," "cryptodisk" and "luks" modules in grubx64.efi of the 'grub2-efi-x64' package.
 
Note: Although the build process will automatically include explicit dependencies ("mpi," "gcry_sha1," "procfs" and "archelp"), the following implicit ones must also be included: "gcry_sha256," "gcry_rsa," "gcry_rijndael," "gcry_serpent," gcry_twofish" and "gcry_whirlpool"


== Owner ==
== Owner ==
Line 33: Line 38:
This should link to your home wiki page so we know who you are.  
This should link to your home wiki page so we know who you are.  
-->
-->
* Name: [[User:pjones| Peter Jones]]
* Name: [[User:benjamind|Benjamin Doron]]
<!-- Include you email address that you can be reached should people want to contact you about helping with your change, status is requested, or technical issues need to be resolved. If the change proposal is owned by a SIG, please also add a primary contact person. -->
<!-- Include you email address that you can be reached should people want to contact you about helping with your change, status is requested, or technical issues need to be resolved. If the change proposal is owned by a SIG, please also add a primary contact person. -->
* Email: benjamin.doron00@gmail.com
* Name: [[User:pjones|Peter Jones]]
* Email: pjones@redhat.com
* Email: pjones@redhat.com
* Name: [[User:javierm| Javier Martinez Canillas]]
* Name: [[User:javierm|Javier Martinez Canillas]]
* Email: fmartine@redhat.com
* Email: fmartine@redhat.com
* Release notes owner: <!--- To be assigned by docs team [[User:FASAccountName| Release notes owner name]] <email address> -->
* Release notes owner: <!--- To be assigned by docs team [[User:FASAccountName| Release notes owner name]] <email address> -->
Line 48: Line 55:


== Current status ==
== Current status ==
* Targeted release: [[Releases/31 | Fedora 31 ]]  
* Targeted release: [[Releases/31|Fedora 31]]  
* Last updated: <!-- this is an automatic macro — you don't need to change this line -->  {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}  
* Last updated: <!-- this is an automatic macro — you don't need to change this line -->  {{REVISIONYEAR}}-{{REVISIONMONTH}}-{{REVISIONDAY2}}  
<!-- After the change proposal is accepted by FESCo, tracking bug is created in Bugzilla and linked to this page  
<!-- After the change proposal is accepted by FESCo, tracking bug is created in Bugzilla and linked to this page  
Line 58: Line 65:
CLOSED as NEXTRELEASE -> change is completed and verified and will be delivered in next release under development
CLOSED as NEXTRELEASE -> change is completed and verified and will be delivered in next release under development
-->
-->
* Tracker bug: <will be assigned by the Wrangler>
* Tracker bug: [https://bugzilla.redhat.com/show_bug.cgi?id=1722938 #1722938]
* Release notes tracker: [https://pagure.io/fedora-docs/release-notes/issue/352 #352]


== Detailed Description ==
== Detailed Description ==
<!-- Expand on the summary, if appropriate.  A couple sentences suffices to explain the goal, but the more details you can provide the better. -->
<!-- Expand on the summary, if appropriate.  A couple sentences suffices to explain the goal, but the more details you can provide the better. -->
Long-term, it may be advisable to sign the .mod files in the 'grub-efi-*-modules' package, modify grub2-mkconfig (or -install) to copy the necessary modules into the EFI partition and then allowing inserting of signed modules in secure boot instances.
Users utilising secure boot functionality on the UEFI platform cannot insert grub modules. Paradoxically, this means that security-conscious users cannot use grub's verify module for signature verification, or employ (near) full disk encryption using cryptodisk and luks.
 
The security benefits of signature verification would reach more users if Fedora automated it by incorporating the process into `grub2-mkconfig`. Similarly, it would be easier to use cryptodisk functionality if it were configurable by anaconda. This can be considered for future releases, after allowing time to straighten out the details of the implementation and analyse the benefits/costs.
 
For the long-term, to grant flexibility with grub2 modules on secure boot instances in general, it may be advisable to consider signing the .mod files in the 'grub2-efi-x64-modules' package, allow inserting of signed modules in secure boot instances and then modify `grub2-mkconfig` to copy the necessary modules into the EFI partition when required by the user's configuration.


== Benefit to Fedora ==
== Benefit to Fedora ==
Line 92: Line 104:
     https://fedoraproject.org/wiki/Changes/perl5.26 (major upgrade to a popular software stack, visible to users of that stack)
     https://fedoraproject.org/wiki/Changes/perl5.26 (major upgrade to a popular software stack, visible to users of that stack)
-->
-->
Users utilising secure boot functionality on the UEFI platform cannot insert modules that aren't in grub*.efi. Paradoxically, this means that security-conscious users cannot use grub's verify module, or employ (near) full disk encryption using cryptodisk and luks.
This change will allow users to gain trust in the integrity of early-launch code either through verification of signatures (particularly useful for the initramfs, which is particularly vulnerable to possible offline modification) or encryption of the boot partition.
 
This change will allow users to gain trust in the integrity of early-launch code either through verification of signatures (particularly useful for initramfs, which is particularly vulnerable to possibly offline modification) or encryption of the boot partition.
 
Perhaps long-term, Fedora can use the verify module to automatically provide detached signature-based verification of the boot files.


== Scope ==
== Scope ==
* Proposal owners:
* Proposal owners: Modify grub.macros file to include the above-mentioned modules in the GRUB_MODULES variable.
<!-- What work do the feature owners have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
<!-- What work do the feature owners have to accomplish to complete the feature in time for release?  Is it a large change affecting many parts of the distribution or is it a very isolated change? What are those changes?-->
Modify grub.macros file to include the above-mentioned modules in the GRUB_MODULES variable.


* Other developers: N/A (not a System Wide Change) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
* Other developers: N/A (not a System Wide Change) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
Line 109: Line 116:
<!-- Does this feature require coordination with release engineering (e.g. changes to installer image generation or update package delivery)?  Is a mass rebuild required?  include a link to the releng issue.  
<!-- Does this feature require coordination with release engineering (e.g. changes to installer image generation or update package delivery)?  Is a mass rebuild required?  include a link to the releng issue.  
The issue is required to be filed prior to feature submission, to ensure that someone is on board to do any process development work and testing, and that all changes make it into the pipeline; a bullet point in a change is not sufficient communication -->
The issue is required to be filed prior to feature submission, to ensure that someone is on board to do any process development work and testing, and that all changes make it into the pipeline; a bullet point in a change is not sufficient communication -->
This feature will not require a rebuild of any other packages nor of the installer image. If desired, change can be delivered after install as an update.
** [[Fedora_Program_Management/ReleaseBlocking/Fedora{{FedoraVersionNumber|next}}|List of deliverables]]: N/A (not a System Wide Change) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
* [[Fedora_Program_Management/ReleaseBlocking/Fedora{{FedoraVersionNumber|next}}|List of deliverables]]: N/A (not a System Wide Change) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
<!-- Please check the list of Fedora release deliverables and list all the differences the feature brings -->
<!-- Please check the list of Fedora release deliverables and list all the differences the feature brings -->


Line 139: Line 145:
-->
-->
<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
<b>Disclaimer: Commands assume that tester is root. Secure Boot must be disabled for testing purposes (`insmod` is forbidden under Secure Boot, for now. The description details a tentative plan to get us to a place where that can be changed). Ensure that the package 'grub2-efi-x64-modules' is installed, and for testing purposes, copy the contents to the EFI partition with `cp -r /usr/lib/grub/x86_64-efi/ /boot/efi/EFI/fedora/`</b>
<b>For "verify":</b>
<b>For "verify":</b>


1. Generate a signing key with "gpg --gen-key" and copy it to the EFI partition
1. Generate an RSA signing key with `gpg --full-generate-key` (option 4), then export it with `gpg --export > pubkey` and move it to the EFI partition with `mv pubkey /boot/efi/EFI/fedora`. You can also export the private key (`gpg --export-secret-keys > seckey`), but the signing process doesn't require it as gpg will get the key from its own directory.
 
2. Add "insmod verify," "insmod gcry_sha256," "insmod gcry_rsa," "trust (hd0,gpt1)/efi/fedora/pubkey" (change this based on your environment) and "set check_signatures=enforce" to /etc/grub.d/40_custom
 
3. Run `grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg`
 
4. Run `export GPG_TTY=$(tty)`. Don't ask, apparently something changed in gpg with a recent update.
 
4. Create a file, /dev/shm/pass, with the key's password and execute: `for x in $(find /boot -name "*.cfg" -or -name "*.lst" -or -name "*.mod" -or -name "vmlinuz*" -or -name "initramfs*" -or -name "grubenv"); do gpg --batch --pinentry-mode loopback --detach-sign --passphrase-fd 0 $x < /dev/shm/pass; done`. Then, `shred /dev/shm/pass`
 
5. Reboot. If the system starts, backup and remove .sig files. If the system does not start this time, change is successful


2. Add "trust <gpg key>" (but grub may inherit this from shim's MOK) and "set check_signatures=enforce" to /etc/default/40_custom.
(To recover from a now non-booting system, open the grub terminal and execute `set check_signatures=no`. The system should then boot, and .sig files can be replaced or regenerated.)


3. Run grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg


4. Create a file, /tmp/pass, with the key's passphrase, then execute: for x in $(find /boot -name "*.cfg" -or -name "*.mod" -or -name "vmlinuz*" -or -name "initrd*" -or -name "grubenv"); do gpg --batch --detach-sign --passphrase-fd 0 $x < /tmp/pass; done. Then, shred /tmp/pass.
<b>For cryptodisk functionality:</b>


5. Reboot. If system starts, change is successful.
1. Backup the files in your boot partition


2. Run `cryptsetup luksFormat /dev/sda2 --type luks1` (change this based on your environment to /boot's block device)


<b>For cryptography modules:</b>
Note: If filesystem root is also encrypted, it is recommended that the same password be used for boot as for root to decrease the amount of engagement required at start-up. Consider using --iter-time with low time in milliseconds (default is 2000ms)


1. Backup boot partition
3. Open luks container with `cryptsetup luksOpen /dev/sda2 --type luks1 crypt_boot` (change this to match your environment) and run `mkfs.ext4 /dev/mapper/crypt_boot`, then mount and restore backup


2. Run cryptsetup luksFormat <boot partition's block device, for example, /dev/sda2> --type luks1
4. Add "GRUB_ENABLE_CRYPTODISK=y" to /etc/default/grub


3. Open luks container and restore backup
5. Correct /etc/fstab to the correct UUID for /boot


4. Add GRUB_ENABLE_CRYPTODISK=y to /etc/default/grub
6. Add an entry for the boot container to /etc/crypttab (i.e. "luks-<your luks UUID> UUID=<your luks UUID> none discard"), then run `dracut -vf --regenerate-all`


5. Confirm that /etc/fstab has the correct UUID for /boot
7. Run `grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg`


6. Run grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
8. Reboot. Grub should ask for the password created in step 2. If the system then starts, change is successful


7. Reboot. Grub should ask for the password created in step 2. If system then starts, change is successful. (If filesystem root is also encrypted, user may be asked for a password twice. This can be mitigated with a keyfile for filesystem root, or use of the clevis package, and likely, a tpm)
(If filesystem root is also encrypted, the user will be asked for a password twice. This can be mitigated with a keyfile for filesystem root, or use of the clevis package and likely, a tpm.)


== User Experience ==
== User Experience ==
Line 179: Line 197:
  - Green has been scientifically proven to be the most relaxing color. The move to a default background color of green with green text will result in Fedora users being the most relaxed users of any operating system.
  - Green has been scientifically proven to be the most relaxing color. The move to a default background color of green with green text will result in Fedora users being the most relaxed users of any operating system.
-->
-->
Users may optionally elect to verify the integrity of early-launch code either through verification of signatures or encryption of the boot partition.
Users may optionally elect to guarantee the integrity of boot code either through verification of digital signatures or encryption of the boot partition.


== Dependencies ==
== Dependencies ==
<!-- What other packages (RPMs) depend on this package?  Are there changes outside the developers' control on which completion of this change depends?  In other words, completion of another change owned by someone else and might cause you to not be able to finish on time or that you would need to coordinate?  Other upstream projects like the kernel (if this is not a kernel change)? -->
<!-- What other packages (RPMs) depend on this package?  Are there changes outside the developers' control on which completion of this change depends?  In other words, completion of another change owned by someone else and might cause you to not be able to finish on time or that you would need to coordinate?  Other upstream projects like the kernel (if this is not a kernel change)? -->
<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
<!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
Grub-efi-*-modules and grub-tools-* depend on this package, but require no change.
'Grub2-efi-x64-modules' and 'grub2-tools-*' depend upon/are a part of this package, but require no change.


== Contingency Plan ==
== Contingency Plan ==
<!-- If you cannot complete your feature by the final development freeze, what is the backup plan?  This might be as simple as "Revert the shipped configuration".  Or it might not (e.g. rebuilding a number of dependent packages).  If your feature is not completed in time we want to assure others that other parts of Fedora will not be in jeopardy.  -->
<!-- If you cannot complete your feature by the final development freeze, what is the backup plan?  This might be as simple as "Revert the shipped configuration".  Or it might not (e.g. rebuilding a number of dependent packages).  If your feature is not completed in time we want to assure others that other parts of Fedora will not be in jeopardy.  -->
* Contingency mechanism: (What to do?  Who will do it?) Revert the shipped configuration <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
* Contingency mechanism: Revert the shipped configuration <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
<!-- When is the last time the contingency mechanism can be put in place?  This will typically be the beta freeze. -->
<!-- When is the last time the contingency mechanism can be put in place?  This will typically be the beta freeze. -->
* Contingency deadline: Beta freeze <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
* Contingency deadline: Beta freeze <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
<!-- Does finishing this feature block the release, or can we ship with the feature in incomplete state? -->
<!-- Does finishing this feature block the release, or can we ship with the feature in incomplete state? -->
* Blocks release? N/A (not a System Wide Change) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
* Blocks release? N/A (not a System Wide Change) <!-- REQUIRED FOR SYSTEM WIDE CHANGES -->
Line 210: Line 228:
Fedora now supports Grub's detached verify and cryptodisk functionality natively, even on secure boot systems.
Fedora now supports Grub's detached verify and cryptodisk functionality natively, even on secure boot systems.


[[Category:ChangePageIncomplete]]
[[Category:ChangeAcceptedF31]]
<!-- When your change proposal page is completed and ready for review and announcement -->
<!-- When your change proposal page is completed and ready for review and announcement -->
<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->
<!-- remove Category:ChangePageIncomplete and change it to Category:ChangeReadyForWrangler -->

Latest revision as of 18:32, 21 June 2019

Include several modules in the EFI build of Grub2 for security use-cases

Summary

Include Grub's "verify," "cryptodisk" and "luks" modules in grubx64.efi of the 'grub2-efi-x64' package.

Note: Although the build process will automatically include explicit dependencies ("mpi," "gcry_sha1," "procfs" and "archelp"), the following implicit ones must also be included: "gcry_sha256," "gcry_rsa," "gcry_rijndael," "gcry_serpent," gcry_twofish" and "gcry_whirlpool"

Owner

Current status

Detailed Description

Users utilising secure boot functionality on the UEFI platform cannot insert grub modules. Paradoxically, this means that security-conscious users cannot use grub's verify module for signature verification, or employ (near) full disk encryption using cryptodisk and luks.

The security benefits of signature verification would reach more users if Fedora automated it by incorporating the process into grub2-mkconfig. Similarly, it would be easier to use cryptodisk functionality if it were configurable by anaconda. This can be considered for future releases, after allowing time to straighten out the details of the implementation and analyse the benefits/costs.

For the long-term, to grant flexibility with grub2 modules on secure boot instances in general, it may be advisable to consider signing the .mod files in the 'grub2-efi-x64-modules' package, allow inserting of signed modules in secure boot instances and then modify grub2-mkconfig to copy the necessary modules into the EFI partition when required by the user's configuration.

Benefit to Fedora

This change will allow users to gain trust in the integrity of early-launch code either through verification of signatures (particularly useful for the initramfs, which is particularly vulnerable to possible offline modification) or encryption of the boot partition.

Scope

  • Proposal owners: Modify grub.macros file to include the above-mentioned modules in the GRUB_MODULES variable.
  • Other developers: N/A (not a System Wide Change)
  • Policies and guidelines: N/A (not a System Wide Change)
  • Trademark approval: N/A (not needed for this Change)

Upgrade/compatibility impact

Change only adds modules, so existing users should have no problems.

How To Test

Disclaimer: Commands assume that tester is root. Secure Boot must be disabled for testing purposes (insmod is forbidden under Secure Boot, for now. The description details a tentative plan to get us to a place where that can be changed). Ensure that the package 'grub2-efi-x64-modules' is installed, and for testing purposes, copy the contents to the EFI partition with cp -r /usr/lib/grub/x86_64-efi/ /boot/efi/EFI/fedora/

For "verify":

1. Generate an RSA signing key with gpg --full-generate-key (option 4), then export it with gpg --export > pubkey and move it to the EFI partition with mv pubkey /boot/efi/EFI/fedora. You can also export the private key (gpg --export-secret-keys > seckey), but the signing process doesn't require it as gpg will get the key from its own directory.

2. Add "insmod verify," "insmod gcry_sha256," "insmod gcry_rsa," "trust (hd0,gpt1)/efi/fedora/pubkey" (change this based on your environment) and "set check_signatures=enforce" to /etc/grub.d/40_custom

3. Run grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg

4. Run export GPG_TTY=$(tty). Don't ask, apparently something changed in gpg with a recent update.

4. Create a file, /dev/shm/pass, with the key's password and execute: for x in $(find /boot -name "*.cfg" -or -name "*.lst" -or -name "*.mod" -or -name "vmlinuz*" -or -name "initramfs*" -or -name "grubenv"); do gpg --batch --pinentry-mode loopback --detach-sign --passphrase-fd 0 $x < /dev/shm/pass; done. Then, shred /dev/shm/pass

5. Reboot. If the system starts, backup and remove .sig files. If the system does not start this time, change is successful

(To recover from a now non-booting system, open the grub terminal and execute set check_signatures=no. The system should then boot, and .sig files can be replaced or regenerated.)


For cryptodisk functionality:

1. Backup the files in your boot partition

2. Run cryptsetup luksFormat /dev/sda2 --type luks1 (change this based on your environment to /boot's block device)

Note: If filesystem root is also encrypted, it is recommended that the same password be used for boot as for root to decrease the amount of engagement required at start-up. Consider using --iter-time with low time in milliseconds (default is 2000ms)

3. Open luks container with cryptsetup luksOpen /dev/sda2 --type luks1 crypt_boot (change this to match your environment) and run mkfs.ext4 /dev/mapper/crypt_boot, then mount and restore backup

4. Add "GRUB_ENABLE_CRYPTODISK=y" to /etc/default/grub

5. Correct /etc/fstab to the correct UUID for /boot

6. Add an entry for the boot container to /etc/crypttab (i.e. "luks-<your luks UUID> UUID=<your luks UUID> none discard"), then run dracut -vf --regenerate-all

7. Run grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg

8. Reboot. Grub should ask for the password created in step 2. If the system then starts, change is successful

(If filesystem root is also encrypted, the user will be asked for a password twice. This can be mitigated with a keyfile for filesystem root, or use of the clevis package and likely, a tpm.)

User Experience

Users may optionally elect to guarantee the integrity of boot code either through verification of digital signatures or encryption of the boot partition.

Dependencies

'Grub2-efi-x64-modules' and 'grub2-tools-*' depend upon/are a part of this package, but require no change.

Contingency Plan

  • Contingency mechanism: Revert the shipped configuration
  • Contingency deadline: Beta freeze
  • Blocks release? N/A (not a System Wide Change)
  • Blocks product? No

Documentation

https://www.gnu.org/software/grub/manual/grub/html_node/Using-digital-signatures.html

https://wiki.archlinux.org/index.php/Dm-crypt/Encrypting_an_entire_system#Encrypted_boot_partition_(GRUB)

Release Notes

Fedora now supports Grub's detached verify and cryptodisk functionality natively, even on secure boot systems.