From e2e8cb27e986033cf60042a7ff64498965dfdb2a Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 11:09:40 -0700 Subject: [PATCH 01/16] Create Secureboot_uefi_key_management.md Secure boot UEFI key management HLD --- .../Secureboot_uefi_key_management.md | 209 ++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 doc/secure_boot/Secureboot_uefi_key_management.md diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md new file mode 100644 index 00000000000..834f1f1484b --- /dev/null +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -0,0 +1,209 @@ + +# High Level Design Document + +***Revision*** + +| Rev | Date | Author | Change Description | +| :---: | :------------: | :---------: | ------------------ | +| 0.1 | 08/25/2023 | Sachin Naik | Initial version | + + +## Table of Contents +- [About this Manual](#about-this-manual) +- [Abbreviation](#abbreviation) +- [1 Requirements Overview](#1-requirements-overview) +- [2 Overview](#2-Overview) +- [3 UEFI components](#3-UEFI-components) + - [3.1 UEFI keys](#31-UEFI-keys) + - [3.2 UEFI key management](#32-UEFI-key-management) + - [3.3 Authenticated variable](#33-Authenticated-variable) +- [4 UEFI key management](#4-UEFI-key-management) + - [4.1 Generation of keys](#41-Generation-of-keys) + - [4.2 Enrollment of keys](#42-Enrollment-of-keys) + - [4.3 Modify key database](#43-Modify-key-database) + - [4.4 Revoke keys](#44-Revoke-keys) + - [4.5 Show keys](#45-Show-keys) +- [5 SONIC implementation](#5-SONIC-implementation) + - [5.1 Plugin class](#51-Plugin-class) + - [5.2 OVMF based platform can use Linux implementation to access UEFI variable](#52-OVMF-based-platform-can-use-Linux-implementation-to-access-UEFI-variable) +- [6 SONiC CLI commands](#6-SONiC-CLI-commands) +- [7 Test considerations](#7-Test-considerations) + + +## Abbreviation + +| Abbreviation | Description | +| ------------ | -------------------------------------------- | +| PK | Platform Key. | +| KEK | Key Exchange Key | +| db | UEFI Signature Key Database | +| dbx | Forbidden Signture Key Database | +| UEFI | Unified Extensible Firmware Interface | +| RoT | Root of Trust | +| TPM | Trusted platform module | + + +## 1 Requirements +SONiC is the most popularly growing open-source network operating system and runs on switching hardware from multiple vendors. Some of this modern switching hardware implements a hardware root of trust and UEFI firmware which helps establish a secure boot in the system. Most of the system owners would like to manage their own UEFI keys according to their own policy such as periodically changing the secure boot keys, changing ownership, etc. This requires SONiC to access UEFI keys to perform the following primitive actions. +1. Show secureboot keys +2. Add, remove, update and revoke secureboot keys. + +## 2 Ovierview +How  UEFI secure boot should be implemented is specified in UEFI spec 2.0 onwards. It is widely accepted on various Linux-based distributions including Debian distribution. The UEFI secure boot provides a mechanism to securely verify the image integrity and authenticity before loading into the system. The spec also provides details about how UEFI keys should be managed in the UEFI firmware. + +Typically the UEFI is a modern replacement for traditional BIOS. Firmware. The UEFI implementation may vary from system to system but it has to follow the core principles mentioned in the spec. The document references the OVMF UEFI implementation, which is open UEFI firmware available for virtual machines QEMU. + +## 3 UEFI components + +### 3.1 UEFI firmware +1. UEFI firmware(Ex: UEFI BIOS) is signed and supplied by hardware vendors. +2. Hardware implemented root of trust(Ex: TPM chip etc) that verifies UEFI firmware before running into CPU. +3. Root of trust is the immutable hardware part and it is the most trusted part of the system. +4. UEFI firmware verifies bootloader(shimx64.efi) of SONiC OS image against keys present in UEFI key database. +5. UEFI firmware manages UEFI keys database and verifies any update to these databases. + +### 3.2 UEFI keys +UEFI keys are cryptographic keys used in Unified Extensible Firmware Interface (UEFI) enabled systems. Typically used for secure boot purposes.  These are asymmetric cryptographic keys that come with public and private key pairs. The private keys are used for signing data and public keys are enrolled in the UEFI device. The device's secure boot uses these public keys to verify the signed bootloader and kernel during system boot time and protect early boot with any malware. Secure boot ensures integrity and trust source of the image. + +There are multiple keys involved in the UEFI secure boot implementations. The platform owner sets the policies around these keys. The UEFI firmware and its interface are typically controlled by hardware vendors depending on their UEFI firmware implementations.  However, the platform owner must be able to manage these keys which are enrolled in the UEFI devices in order to securely boot their NOS. + + + +**1. Platform Key(PK):** It’s a root of trust key that signs all other keys in the UEFI to be added. Technically PK is used to establish a trust relationship between the device owner and device UEFI firmware. The public part of the PK is enrolled in the device UEFI firmware. The enrollment happens early in manufacturing or initial provisioning time. The private part of the PK.key is used to change the device ownership by changing the existing PK and also to sign the KEK to enroll or update KEK in the device. + +**2. Key Exchange Key(KEK)**: KEK is used to establish trust between NOS and the device. It is used for enrolling secure boot or some other NOS-specific keys in the allowed key list database(Db). The public part of the KEK is enrolled in the device and the private part is used to sign the keys that are enrolled in the key list database(Db). + +**3. Signature Database (Db):** It contains secureboot verification keys that are used to verify the signed image artifacts during system boot(Ex: bootloader and kernel). + +**4. Forbidden Signature Database(Dbx):** These contain keys that are revoked. It is used during the secure boot process to prevent certain bootloaders or images from being loaded if their signature is verified with the keys that are present in this database. + +### 3.3 Authenticated variable +These are a special type of UEFI variable that supports cryptographic authentication and integrity verification. The authenticates variable enables a secure way of storing and accessing EFI variables within the UEFI environment and ensures that the UEFI variable remains tamper-proof and authentic.  Since authenticated variables are signed objects, the UEFI firmware can verify them before accessing or updating them. + +``` +Sample example how authenticated variables supports secure way of add, update, remove and revoke UEFI keys. + +uuidgen --random > GUID.txt + +**PK authenticated variable:** +openssl req -newkey rsa:4096 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 -subj "/CN=Platform key/" -out PK.crt +openssl x509 -outform DER -in PK.crt -out PK.cer +cert-to-efi-sig-list -g "$(< GUID.txt)" PK.crt PK.esl +sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt PK PK.esl PK.auth + +**KEK authenticated variable:** +openssl req -newkey rsa:4096 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt +openssl x509 -outform DER -in KEK.crt -out KEK.cer +cert-to-efi-sig-list -g "$(< GUID.txt)" KEK.crt KEK.esl +sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt KEK KEK.esl KEK.auth + +**Db authenticated variable:** +openssl req -newkey rsa:4096 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt +openssl x509 -outform DER -in db.crt -out db.cer +cert-to-efi-sig-list -g "$(< GUID.txt)" db.crt db.esl +sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db db.esl db.auth +``` +Using above example one should able to create authenticated variable to add, remove, update and revoke UEFI keys from the UEFI database. + +## 4 UEFI key management + +The key management involves following functional area +1. Generation of keys +2. Enroll keys into Machine +3. Update, remove and add new keys into the key database. +4. Revoke keys +5. Show keys from the machine. + +### 4.1 Generation of keys +The secure boot key creation happens outside of the device via openSSL or some other key generation. +``` +openssl req -newkey rsa:4096 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 -subj "/CN=Platform key/" -out PK.crt +openssl req -newkey rsa:4096 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt +openssl req -newkey rsa:4096 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt +``` +The private keys are kept secretly and used during image signing. The public keys are used to verify images signed by private keys. Public keys are wrapped with x509 format of certificate. These public certificates are enrolled in the SHIM or UEFI key database by the machine owner. + +### 4.2 Enrollment of keys +The enrollment interface depends on where the keys are stored. The UEFI keys enrollment follows specific policy. UEFI keys are PK, KEK, db and dbX. The enrollment of PK depends on access over UEFI FW's mode(Ex: Setup mode, User mode etc.). Then the owner of PK can enroll KEK since KEKs enrollment requires that KEK and create authenticated variables and it by PK. + +```` +Ex: Enroll KEK +sign-efi-sig-list -t "$(date --date='1 second' +'%Y-%m-%d %H:%M:%S')" -k PK.key -c PK.crt KEK KEK.esl KEK.auth + +Use the hardware vendor provided interface to enroll KEK.auth +```` +Similar principle used for enrolling DB keys. The DB enrollment variable should be created then signed either by PK and KEK. Typically KEK is used to avoid frequent access to PK private keys. + +### 4.3 Modify key database +For UEFI key database modification, requires authenticated variables to modify. +```` +Examples: + +To add DB key in UEFI database following are typical workflow followed + + # Create key: + openssl req -subj "/CN=SecBoot db cert/" -new -x509 -newkey rsa:2048 -nodes -days 730 -outform PEM -keyout "db.key" -out "db.pem" + + # Conver to signature list + cert-to-efi-sig-list -g db.pem db.esl + + # Sign keys using KEK + sign-efi-sig-list -g -c KEK.pem -k KEK.key db db.esl db.auth + + # Update UEFI database + efi-updatevar -k KEK.key -g -f db.auth db + +```` + +### 4.4 Revoke keys + +The revoke key is a mechanism to permanently disallow any image signed by the private key whose public key is present in DBx of UEFI database. + +### 4.5 Show keys +This is to display the PK, KEK, DB and DBx key lists. + +## 5 SONIC implementation +The access of UEFI variables may vary from platform to platform depending on the specific implementation of UEFI firmware. Sonic will provide a common layer for accessing these variables and vendors can implement platform specific parts. The SONIC will provide a plugin Python for vendors to implement these APIs and integrate them with the SONiC generic layer. + +### 5.1 Plugin class + + + + +### 5.2 OVMF based platform can use Linux implementation to access UEFI variable +The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. + +![image](https://wwwin-github.cisco.com/storage/user/4864/files/8739b223-6b2a-4f96-b42c-7fa0deec5707) + +``` +sudo mount -t efivarfs none /sys/firmware/efi/efivars + +Ex: UEFI key variables represented as sysfs file + +/sys/firmware/efi/efivars/PK- +/sys/firmware/efi/efivars/KEK- +/sys/firmware/efi/efivars/DB- +/sys/firmware/efi/efivars/DBX- +``` +The platform plugin for this OVMF type UEFI can use either sysfs or efi-readvar and efi-updatevar to implement getVariable() and setVariable() methods. + + +## 6 SONiC CLI commands +``` +1. show platform security uefi variables all +2. show platform security uefi variables pk +3. show platform security uefi variables kek +4. show platform security uefi variables db +5. show platform security uefi variables dbx + +1. platform security uefi variables update pk +2. platform security uefi variables update kek +3. platform security uefi variables update db +4. platform security uefi variables update dbx +``` + +## 7 Test considerations +The sonic-mgmt can cover UEFI keymanagement such as add, update, remove and revoke UEFI keys. + + + From c5d17ea552e2a23da43aae5a950dd0b5c52571a2 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 15:00:54 -0700 Subject: [PATCH 02/16] Update Secureboot_uefi_key_management.md --- .../Secureboot_uefi_key_management.md | 27 +++++++++---------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 834f1f1484b..b00670ad12e 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -37,7 +37,7 @@ | PK | Platform Key. | | KEK | Key Exchange Key | | db | UEFI Signature Key Database | -| dbx | Forbidden Signture Key Database | +| dbx | Forbidden Signature Key Database | | UEFI | Unified Extensible Firmware Interface | | RoT | Root of Trust | | TPM | Trusted platform module | @@ -48,7 +48,7 @@ SONiC is the most popularly growing open-source network operating system and run 1. Show secureboot keys 2. Add, remove, update and revoke secureboot keys. -## 2 Ovierview +## 2 Overview How  UEFI secure boot should be implemented is specified in UEFI spec 2.0 onwards. It is widely accepted on various Linux-based distributions including Debian distribution. The UEFI secure boot provides a mechanism to securely verify the image integrity and authenticity before loading into the system. The spec also provides details about how UEFI keys should be managed in the UEFI firmware. Typically the UEFI is a modern replacement for traditional BIOS. Firmware. The UEFI implementation may vary from system to system but it has to follow the core principles mentioned in the spec. The document references the OVMF UEFI implementation, which is open UEFI firmware available for virtual machines QEMU. @@ -81,7 +81,7 @@ There are multiple keys involved in the UEFI secure boot implementations. The pl These are a special type of UEFI variable that supports cryptographic authentication and integrity verification. The authenticates variable enables a secure way of storing and accessing EFI variables within the UEFI environment and ensures that the UEFI variable remains tamper-proof and authentic.  Since authenticated variables are signed objects, the UEFI firmware can verify them before accessing or updating them. ``` -Sample example how authenticated variables supports secure way of add, update, remove and revoke UEFI keys. +Sample example of how authenticated variables support a secure way of adding, updating, removing, and revoking UEFI keys. uuidgen --random > GUID.txt @@ -103,14 +103,14 @@ openssl x509 -outform DER -in db.crt -out db.cer cert-to-efi-sig-list -g "$(< GUID.txt)" db.crt db.esl sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db db.esl db.auth ``` -Using above example one should able to create authenticated variable to add, remove, update and revoke UEFI keys from the UEFI database. +Using the above example one should be able to create an authenticated variable to add, remove, update, and revoke UEFI keys from the UEFI database. ## 4 UEFI key management -The key management involves following functional area +The key management involves following the functional area 1. Generation of keys -2. Enroll keys into Machine -3. Update, remove and add new keys into the key database. +2. Enroll keys into the Machine +3. Update, remove, and add new keys to the key database. 4. Revoke keys 5. Show keys from the machine. @@ -121,25 +121,24 @@ openssl req -newkey rsa:4096 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 openssl req -newkey rsa:4096 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt openssl req -newkey rsa:4096 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt ``` -The private keys are kept secretly and used during image signing. The public keys are used to verify images signed by private keys. Public keys are wrapped with x509 format of certificate. These public certificates are enrolled in the SHIM or UEFI key database by the machine owner. +The private keys are kept secretly and used during image signing. The public keys are used to verify images signed by private keys. Public keys are wrapped in the x509 format of the certificate. These public certificates are enrolled in the SHIM or UEFI key database by the machine owner. ### 4.2 Enrollment of keys -The enrollment interface depends on where the keys are stored. The UEFI keys enrollment follows specific policy. UEFI keys are PK, KEK, db and dbX. The enrollment of PK depends on access over UEFI FW's mode(Ex: Setup mode, User mode etc.). Then the owner of PK can enroll KEK since KEKs enrollment requires that KEK and create authenticated variables and it by PK. +The enrollment interface depends on where the keys are stored. The UEFI keys enrollment follows a specific policy. UEFI keys are PK, KEK, db and dbX. The enrollment of PK depends on access over UEFI FW's mode(Ex: Setup mode, User mode etc.). Then the owner of PK can enroll KEK since KEK enrollment requires authenticated variables signed by PK. ```` Ex: Enroll KEK sign-efi-sig-list -t "$(date --date='1 second' +'%Y-%m-%d %H:%M:%S')" -k PK.key -c PK.crt KEK KEK.esl KEK.auth -Use the hardware vendor provided interface to enroll KEK.auth ```` -Similar principle used for enrolling DB keys. The DB enrollment variable should be created then signed either by PK and KEK. Typically KEK is used to avoid frequent access to PK private keys. +A similar principle is used for enrolling DB keys. The DB enrollment variable should be created and then signed either by PK or KEK. ### 4.3 Modify key database For UEFI key database modification, requires authenticated variables to modify. ```` Examples: -To add DB key in UEFI database following are typical workflow followed +To add DB key in UEFI database following are typical workflows followed # Create key: openssl req -subj "/CN=SecBoot db cert/" -new -x509 -newkey rsa:2048 -nodes -days 730 -outform PEM -keyout "db.key" -out "db.pem" @@ -163,7 +162,7 @@ The revoke key is a mechanism to permanently disallow any image signed by the pr This is to display the PK, KEK, DB and DBx key lists. ## 5 SONIC implementation -The access of UEFI variables may vary from platform to platform depending on the specific implementation of UEFI firmware. Sonic will provide a common layer for accessing these variables and vendors can implement platform specific parts. The SONIC will provide a plugin Python for vendors to implement these APIs and integrate them with the SONiC generic layer. +The access of UEFI variables may vary from platform to platform depending on the specific implementation of UEFI firmware. Sonic will provide a common layer for accessing these variables and vendors can implement platform-specific parts. The SONIC will provide a plugin Python for vendors to implement these APIs and integrate them with the SONiC generic layer. ### 5.1 Plugin class @@ -203,7 +202,7 @@ The platform plugin for this OVMF type UEFI can use either sysfs or efi-readvar ``` ## 7 Test considerations -The sonic-mgmt can cover UEFI keymanagement such as add, update, remove and revoke UEFI keys. +The sonic-mgmt can cover UEFI key management such as adding, updating, removing, and revoking UEFI keys. From 8b883b6afdf4c9c325e8baee0f7535fead0c8b6b Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 16:03:15 -0700 Subject: [PATCH 03/16] Update Secureboot_uefi_key_management.md --- .../Secureboot_uefi_key_management.md | 30 ++++++++----------- 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index b00670ad12e..7200d65ac6b 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -44,41 +44,35 @@ ## 1 Requirements -SONiC is the most popularly growing open-source network operating system and runs on switching hardware from multiple vendors. Some of this modern switching hardware implements a hardware root of trust and UEFI firmware which helps establish a secure boot in the system. Most of the system owners would like to manage their own UEFI keys according to their own policy such as periodically changing the secure boot keys, changing ownership, etc. This requires SONiC to access UEFI keys to perform the following primitive actions. -1. Show secureboot keys -2. Add, remove, update and revoke secureboot keys. +Sonic is the most popularly growing open-source network operating system and runs on switching hardware from multiple vendors. Some of this modern switching hardware implements a hardware root of trust and UEFI firmware which helps establish a secure boot in the system. Most of the system owners would like to manage their own UEFI keys according to their own policy such as periodically changing the secure boot keys, changing ownership, etc. This requires SONiC to access UEFI keys to perform the following primitive actions. +1. Show secure boot keys +2. Add, remove, update, and revoke secure boot keys. ## 2 Overview -How  UEFI secure boot should be implemented is specified in UEFI spec 2.0 onwards. It is widely accepted on various Linux-based distributions including Debian distribution. The UEFI secure boot provides a mechanism to securely verify the image integrity and authenticity before loading into the system. The spec also provides details about how UEFI keys should be managed in the UEFI firmware. - -Typically the UEFI is a modern replacement for traditional BIOS. Firmware. The UEFI implementation may vary from system to system but it has to follow the core principles mentioned in the spec. The document references the OVMF UEFI implementation, which is open UEFI firmware available for virtual machines QEMU. +The UEFI secure boot feature is introduced in UEFI spec version 2.3.1 onwards. The UEFI secure boot provides a mechanism to securely verify the image integrity and authenticity before loading the image into the system. The spec also provides general details about how UEFI keys should be managed. The implementation may vary for different UEFI firmware. ## 3 UEFI components ### 3.1 UEFI firmware -1. UEFI firmware(Ex: UEFI BIOS) is signed and supplied by hardware vendors. -2. Hardware implemented root of trust(Ex: TPM chip etc) that verifies UEFI firmware before running into CPU. -3. Root of trust is the immutable hardware part and it is the most trusted part of the system. -4. UEFI firmware verifies bootloader(shimx64.efi) of SONiC OS image against keys present in UEFI key database. -5. UEFI firmware manages UEFI keys database and verifies any update to these databases. +Typically the UEFI is a modern replacement for traditional BIOS. The UEFI implementation may vary from system to system but it has to follow the core principles mentioned in the UEFI spec. This document references the OVMF(Open Virtual Machine Firmware) UEFI implementation, which is the open UEFI firmware available for virtual machines like QEMU and KVM. ### 3.2 UEFI keys -UEFI keys are cryptographic keys used in Unified Extensible Firmware Interface (UEFI) enabled systems. Typically used for secure boot purposes.  These are asymmetric cryptographic keys that come with public and private key pairs. The private keys are used for signing data and public keys are enrolled in the UEFI device. The device's secure boot uses these public keys to verify the signed bootloader and kernel during system boot time and protect early boot with any malware. Secure boot ensures integrity and trust source of the image. +UEFI keys are types of UEFI variables. These are cryptographic keys used in Unified Extensible Firmware Interface (UEFI) firmware. These are asymmetric cryptographic keys that come with public and private key pairs. The private keys are used for signing data and public keys are enrolled in the UEFI device for verifying signed data. -There are multiple keys involved in the UEFI secure boot implementations. The platform owner sets the policies around these keys. The UEFI firmware and its interface are typically controlled by hardware vendors depending on their UEFI firmware implementations.  However, the platform owner must be able to manage these keys which are enrolled in the UEFI devices in order to securely boot their NOS. +There are multiple keys involved in the UEFI secure boot implementations. The platform owner sets the policies around these keys. -**1. Platform Key(PK):** It’s a root of trust key that signs all other keys in the UEFI to be added. Technically PK is used to establish a trust relationship between the device owner and device UEFI firmware. The public part of the PK is enrolled in the device UEFI firmware. The enrollment happens early in manufacturing or initial provisioning time. The private part of the PK.key is used to change the device ownership by changing the existing PK and also to sign the KEK to enroll or update KEK in the device. +**1. Platform Key(PK):** The PK is used for establishing a trust relationship between the platform owner and the platform UEFI firmware. The enrollment of the public PK key to the device happens early in manufacturing or initial provisioning time. The private part of the PK.key is used later to change the platform ownership and manage other keys in the UEFI firmware. -**2. Key Exchange Key(KEK)**: KEK is used to establish trust between NOS and the device. It is used for enrolling secure boot or some other NOS-specific keys in the allowed key list database(Db). The public part of the KEK is enrolled in the device and the private part is used to sign the keys that are enrolled in the key list database(Db). +**2. Key Exchange Key(KEK)**: KEK is used for establishing trust between NOS and the platform. It is used for enrolling NOS secure boot keys in the allowed key database(Db). The public part of the KEK is enrolled in the device and the private part is used for authorizing access to the signature key database(Db). -**3. Signature Database (Db):** It contains secureboot verification keys that are used to verify the signed image artifacts during system boot(Ex: bootloader and kernel). +**3. Signature Database (Db):** It contains secure boot verification keys that are used to verify the signed image artifacts during system boot(Ex: bootloader and kernel). -**4. Forbidden Signature Database(Dbx):** These contain keys that are revoked. It is used during the secure boot process to prevent certain bootloaders or images from being loaded if their signature is verified with the keys that are present in this database. +**4. Forbidden Signature Database(Dbx):** These contain keys that are revoked. These keys are used during the secure boot process to prevent the booting of certain bootloaders or images which are signed by the private part of these keys. ### 3.3 Authenticated variable -These are a special type of UEFI variable that supports cryptographic authentication and integrity verification. The authenticates variable enables a secure way of storing and accessing EFI variables within the UEFI environment and ensures that the UEFI variable remains tamper-proof and authentic.  Since authenticated variables are signed objects, the UEFI firmware can verify them before accessing or updating them. +These are a special type of UEFI variable that supports cryptographic authentication and integrity verification. The authenticates variable enables a secure way of storing and accessing UEFI variables within the UEFI environment and ensures that the UEFI variable remains tamper-proof and authentic.  Since authenticated variables are signed objects, the UEFI firmware can verify them before accessing or updating them. ``` Sample example of how authenticated variables support a secure way of adding, updating, removing, and revoking UEFI keys. From 9019219a576f29b375a0a318b2eaeba987394893 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 18:42:34 -0700 Subject: [PATCH 04/16] Update Secureboot_uefi_key_management.md Added picture for key hierarchies --- doc/secure_boot/Secureboot_uefi_key_management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 7200d65ac6b..07c8fcf30b0 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -61,7 +61,7 @@ UEFI keys are types of UEFI variables. These are cryptographic keys used in Unif There are multiple keys involved in the UEFI secure boot implementations. The platform owner sets the policies around these keys. - +![image](https://github.com/sacnaik/SONiC/assets/25231205/fdf6a164-6153-4c14-ba6d-b8d30475e390) **1. Platform Key(PK):** The PK is used for establishing a trust relationship between the platform owner and the platform UEFI firmware. The enrollment of the public PK key to the device happens early in manufacturing or initial provisioning time. The private part of the PK.key is used later to change the platform ownership and manage other keys in the UEFI firmware. From e38c16d8ed2c81d9321f31721892b0ec61d29534 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 18:46:45 -0700 Subject: [PATCH 05/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 07c8fcf30b0..8a39a23114b 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -160,13 +160,13 @@ The access of UEFI variables may vary from platform to platform depending on the ### 5.1 Plugin class - - +![image](https://github.com/sacnaik/SONiC/assets/25231205/a42cd039-0675-4a71-84e0-bce00eb2ca9d) ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. -![image](https://wwwin-github.cisco.com/storage/user/4864/files/8739b223-6b2a-4f96-b42c-7fa0deec5707) +![image](https://github.com/sacnaik/SONiC/assets/25231205/fc111e5f-23f9-4c10-b674-f2afc906bd54) + ``` sudo mount -t efivarfs none /sys/firmware/efi/efivars From 1b547d2c48bef5db558da06a6b14f02e88d0bc76 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 18:50:59 -0700 Subject: [PATCH 06/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 8a39a23114b..4fedc23e873 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -165,7 +165,7 @@ The access of UEFI variables may vary from platform to platform depending on the ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. -![image](https://github.com/sacnaik/SONiC/assets/25231205/fc111e5f-23f9-4c10-b674-f2afc906bd54) + ``` From fcd0784d5ee84090c3dd7cab36b1cbb56502f938 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 18:52:53 -0700 Subject: [PATCH 07/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 4fedc23e873..cdb1939d8a4 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -165,8 +165,7 @@ The access of UEFI variables may vary from platform to platform depending on the ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. - - + ``` sudo mount -t efivarfs none /sys/firmware/efi/efivars From d2eee3982d271d3cef21579e8fce2ce1e4f1e80d Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 18:56:06 -0700 Subject: [PATCH 08/16] change of image size --- doc/secure_boot/Secureboot_uefi_key_management.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index cdb1939d8a4..80c0bf7a85a 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -165,7 +165,7 @@ The access of UEFI variables may vary from platform to platform depending on the ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. - + ``` sudo mount -t efivarfs none /sys/firmware/efi/efivars From b4316812dc9d2083dedefa4f402ac4a3f2641fee Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 18:57:46 -0700 Subject: [PATCH 09/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 80c0bf7a85a..748dc6f1f6d 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -165,8 +165,6 @@ The access of UEFI variables may vary from platform to platform depending on the ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. - - ``` sudo mount -t efivarfs none /sys/firmware/efi/efivars From a90d91bd2a0b70dff4390f780c538584c1a498a1 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 19:21:32 -0700 Subject: [PATCH 10/16] Update Secureboot_uefi_key_management.md Image size change --- doc/secure_boot/Secureboot_uefi_key_management.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 748dc6f1f6d..99318bd3e84 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -162,6 +162,8 @@ The access of UEFI variables may vary from platform to platform depending on the ![image](https://github.com/sacnaik/SONiC/assets/25231205/a42cd039-0675-4a71-84e0-bce00eb2ca9d) + + ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. From f9bb3703480197296c2f564b7aad066f847a7808 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 19:25:05 -0700 Subject: [PATCH 11/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 99318bd3e84..1654869e76c 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -162,11 +162,11 @@ The access of UEFI variables may vary from platform to platform depending on the ![image](https://github.com/sacnaik/SONiC/assets/25231205/a42cd039-0675-4a71-84e0-bce00eb2ca9d) - - ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. + + ``` sudo mount -t efivarfs none /sys/firmware/efi/efivars From 841e52f3abfecf706a35c586d537710633e3916a Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 19:26:31 -0700 Subject: [PATCH 12/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 1654869e76c..1d08e5b74ab 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -165,7 +165,9 @@ The access of UEFI variables may vary from platform to platform depending on the ### 5.2 OVMF based platform can use Linux implementation to access UEFI variable The Linux kernel provides a standard mechanism to interact with UEFI variables. It provides efivarfs filesystem that exposes the EFI runtime variables as a file. In order to manage these efi variables over sysfs requires mounting efivarfs filesystem. This enables users to access these UEFI variables like a file. - + + + ``` sudo mount -t efivarfs none /sys/firmware/efi/efivars From 8e64090383defc8050b0055322c513be0b13d0e7 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 19:42:44 -0700 Subject: [PATCH 13/16] Update Secureboot_uefi_key_management.md --- .../Secureboot_uefi_key_management.md | 60 ++++++++----------- 1 file changed, 26 insertions(+), 34 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 1d08e5b74ab..d6944e8c6c7 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -74,61 +74,53 @@ There are multiple keys involved in the UEFI secure boot implementations. The pl ### 3.3 Authenticated variable These are a special type of UEFI variable that supports cryptographic authentication and integrity verification. The authenticates variable enables a secure way of storing and accessing UEFI variables within the UEFI environment and ensures that the UEFI variable remains tamper-proof and authentic.  Since authenticated variables are signed objects, the UEFI firmware can verify them before accessing or updating them. +## 4 UEFI key management + +The key management involves following the functional area +1. Generation of keys +2. Enroll keys into the Machine +3. Update, remove, and add new keys to the key database. +4. Revoke keys +5. Show keys from the machine. + +### 4.1 Generation of keys and authenticated variable +#### asymmetric key creations +The secure boot key and authenticate variable creation happens outside of the device via openSSL or some other key generation. + +``` +openssl req -newkey rsa:2048 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 -subj "/CN=Platform key/" -out PK.crt +openssl req -newkey rsa:2048 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt +openssl req -newkey rsa:2048 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt +``` +The private keys are kept secretly and used during image signing. The public keys are used to verify images signed by private keys. Public keys are wrapped in the x509 format of the certificate. These public certificates are enrolled in the SHIM or UEFI key database by the machine owner. + +#### Authenticated variable creation ``` -Sample example of how authenticated variables support a secure way of adding, updating, removing, and revoking UEFI keys. +Sample example of how authenticated variable creation uuidgen --random > GUID.txt **PK authenticated variable:** -openssl req -newkey rsa:4096 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 -subj "/CN=Platform key/" -out PK.crt openssl x509 -outform DER -in PK.crt -out PK.cer cert-to-efi-sig-list -g "$(< GUID.txt)" PK.crt PK.esl sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt PK PK.esl PK.auth **KEK authenticated variable:** -openssl req -newkey rsa:4096 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt openssl x509 -outform DER -in KEK.crt -out KEK.cer cert-to-efi-sig-list -g "$(< GUID.txt)" KEK.crt KEK.esl sign-efi-sig-list -g "$(< GUID.txt)" -k PK.key -c PK.crt KEK KEK.esl KEK.auth **Db authenticated variable:** -openssl req -newkey rsa:4096 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt openssl x509 -outform DER -in db.crt -out db.cer cert-to-efi-sig-list -g "$(< GUID.txt)" db.crt db.esl sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db db.esl db.auth ``` -Using the above example one should be able to create an authenticated variable to add, remove, update, and revoke UEFI keys from the UEFI database. - -## 4 UEFI key management -The key management involves following the functional area -1. Generation of keys -2. Enroll keys into the Machine -3. Update, remove, and add new keys to the key database. -4. Revoke keys -5. Show keys from the machine. - -### 4.1 Generation of keys -The secure boot key creation happens outside of the device via openSSL or some other key generation. -``` -openssl req -newkey rsa:4096 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 -subj "/CN=Platform key/" -out PK.crt -openssl req -newkey rsa:4096 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt -openssl req -newkey rsa:4096 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt -``` -The private keys are kept secretly and used during image signing. The public keys are used to verify images signed by private keys. Public keys are wrapped in the x509 format of the certificate. These public certificates are enrolled in the SHIM or UEFI key database by the machine owner. - -### 4.2 Enrollment of keys -The enrollment interface depends on where the keys are stored. The UEFI keys enrollment follows a specific policy. UEFI keys are PK, KEK, db and dbX. The enrollment of PK depends on access over UEFI FW's mode(Ex: Setup mode, User mode etc.). Then the owner of PK can enroll KEK since KEK enrollment requires authenticated variables signed by PK. - -```` -Ex: Enroll KEK -sign-efi-sig-list -t "$(date --date='1 second' +'%Y-%m-%d %H:%M:%S')" -k PK.key -c PK.crt KEK KEK.esl KEK.auth - -```` -A similar principle is used for enrolling DB keys. The DB enrollment variable should be created and then signed either by PK or KEK. +### 4.2 Enrollment of authenticated variables into the device +The enrollment interface depends on where the keys are stored. The UEFI keys enrollment follows a specific policy. UEFI keys are PK, KEK, db and dbX. The enrollment of PK depends on access over UEFI FW's mode(e.g.: Setup mode, User mode, etc.). Then the owner of PK can enroll KEK since KEK enrollment requires authenticated variables signed by PK. Copy the generated authenticated variable to the device using SONiC UEFI access CLI to enroll the authenticated variable. UEFI firmware checks the trust source and integrity of authenticated variables and enrolls into UEFI database. ### 4.3 Modify key database -For UEFI key database modification, requires authenticated variables to modify. +For UEFI key database modification, creation of authenticated variables. ```` Examples: @@ -153,7 +145,7 @@ To add DB key in UEFI database following are typical workflows followed The revoke key is a mechanism to permanently disallow any image signed by the private key whose public key is present in DBx of UEFI database. ### 4.5 Show keys -This is to display the PK, KEK, DB and DBx key lists. +This is to display the PK, KEK, DB, and DBx key lists. ## 5 SONIC implementation The access of UEFI variables may vary from platform to platform depending on the specific implementation of UEFI firmware. Sonic will provide a common layer for accessing these variables and vendors can implement platform-specific parts. The SONIC will provide a plugin Python for vendors to implement these APIs and integrate them with the SONiC generic layer. From 6119953ffb827aa4a2c639e70d1ffdfcfeeef768 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 22:45:59 -0700 Subject: [PATCH 14/16] Update Secureboot_uefi_key_management.md --- .../Secureboot_uefi_key_management.md | 64 +++++++++++-------- 1 file changed, 38 insertions(+), 26 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index d6944e8c6c7..1009856bb75 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -46,7 +46,7 @@ ## 1 Requirements Sonic is the most popularly growing open-source network operating system and runs on switching hardware from multiple vendors. Some of this modern switching hardware implements a hardware root of trust and UEFI firmware which helps establish a secure boot in the system. Most of the system owners would like to manage their own UEFI keys according to their own policy such as periodically changing the secure boot keys, changing ownership, etc. This requires SONiC to access UEFI keys to perform the following primitive actions. 1. Show secure boot keys -2. Add, remove, update, and revoke secure boot keys. +2. Add, remove, and revoke secure boot keys. ## 2 Overview The UEFI secure boot feature is introduced in UEFI spec version 2.3.1 onwards. The UEFI secure boot provides a mechanism to securely verify the image integrity and authenticity before loading the image into the system. The spec also provides general details about how UEFI keys should be managed. The implementation may vary for different UEFI firmware. @@ -77,17 +77,19 @@ These are a special type of UEFI variable that supports cryptographic authentica ## 4 UEFI key management The key management involves following the functional area -1. Generation of keys -2. Enroll keys into the Machine -3. Update, remove, and add new keys to the key database. +1. Generation of keys and authenticated variable +2. Add the key to the UEFI database +3. Remove the key to the UEFI database 4. Revoke keys -5. Show keys from the machine. +5. Show key list from UEFI database ### 4.1 Generation of keys and authenticated variable #### asymmetric key creations -The secure boot key and authenticate variable creation happens outside of the device via openSSL or some other key generation. +The secure boot key and authenticate variable creation happens outside of the device. ``` +Sample example of key creation: + openssl req -newkey rsa:2048 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 -subj "/CN=Platform key/" -out PK.crt openssl req -newkey rsa:2048 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt openssl req -newkey rsa:2048 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt @@ -96,7 +98,7 @@ The private keys are kept secretly and used during image signing. The public key #### Authenticated variable creation ``` -Sample example of how authenticated variable creation +Sample example of authenticated variable creation: uuidgen --random > GUID.txt @@ -117,27 +119,37 @@ sign-efi-sig-list -g "$(< GUID.txt)" -k KEK.key -c KEK.crt db db.esl db.auth ``` ### 4.2 Enrollment of authenticated variables into the device -The enrollment interface depends on where the keys are stored. The UEFI keys enrollment follows a specific policy. UEFI keys are PK, KEK, db and dbX. The enrollment of PK depends on access over UEFI FW's mode(e.g.: Setup mode, User mode, etc.). Then the owner of PK can enroll KEK since KEK enrollment requires authenticated variables signed by PK. Copy the generated authenticated variable to the device using SONiC UEFI access CLI to enroll the authenticated variable. UEFI firmware checks the trust source and integrity of authenticated variables and enrolls into UEFI database. +The enrollment interface depends on where the keys are stored. The UEFI keys enrollment follows a specific policy. UEFI keys are PK, KEK, db and dbX. The enrollment of PK depends on access over UEFI FW's mode(e.g.: Setup mode, User mode, etc.). Then the owner of PK can enroll KEK since KEK enrollment requires authenticated variables signed by PK. +1. Copy the generated authenticated variable(Ex. KEK.auth, db.auth) to the device +2. Use CLI to send the authenticated variable to UEFI firmware. +3. UEFI firmware checks the trust source and integrity of authenticated variables and enrolls into UEFI database. +4. The system requires a reboot to activate the keys for use. + +### 4.3 Remove keys from UEFI database +For removal of keys requires the removal of an authenticated variable outside of the system. -### 4.3 Modify key database -For UEFI key database modification, creation of authenticated variables. ```` -Examples: - -To add DB key in UEFI database following are typical workflows followed - - # Create key: - openssl req -subj "/CN=SecBoot db cert/" -new -x509 -newkey rsa:2048 -nodes -days 730 -outform PEM -keyout "db.key" -out "db.pem" - - # Conver to signature list - cert-to-efi-sig-list -g db.pem db.esl - - # Sign keys using KEK - sign-efi-sig-list -g -c KEK.pem -k KEK.key db db.esl db.auth - - # Update UEFI database - efi-updatevar -k KEK.key -g -f db.auth db - +Sample example of authenticated variable creation for removal of the key from the signature database list: +E.g The UEFI database has 3 entries of keys and one of them to be removed here + +1. Read the db key list from UEFI DB. + efi-readvar -v Db -o DB-orig.esl +2. Convert signature list to individual certs. This command extracts DB-orig-1.der DB-orig-2.der DB-orig-3.der so on key files + sig-list-to-certs DB-orig.esl DB-orig +3. Convert each of the certs into pem format + openssl x509 -inform der -in db-orig-1.der -out db-orig-1.pem + openssl x509 -inform der -in db-orig-2.der -out db-orig-2.pem + openssl x509 -inform der -in db-orig-3.der -out db-orig-3.pem +4. Removal of db-orig-2.pem to be discarded +5. Convert db-orig-1.pem and db-orig-3.pem to esl format + cert-to-efi-sig-list -g db-orig-1.pem db-orig-1.esl + cert-to-efi-sig-list -g db-orig-3.pem db-orig-3.esl +6. Concatenate these two esl files + cat db-orig-1.esl db-orig-3.esl > DB-new.esl +7. Create authenticated variable and sign it + sign-efi-sig-list -g "" -k KEK.key -c KEK.crt db DB-new.esl DB-new.auth +8. Copy DB-new.auth to the system and use CLI to update UEFI database + ```` ### 4.4 Revoke keys From 9bfe09ed2bdd2be0353c4a5ea18f208cdd9e57c2 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 23:09:49 -0700 Subject: [PATCH 15/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 1009856bb75..90e406b2101 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -153,8 +153,18 @@ E.g The UEFI database has 3 entries of keys and one of them to be removed here ```` ### 4.4 Revoke keys +Revoking a key from the UEFI database is done when the previously trusted key is no longer trustworthy. This action is taken when a key's security has been compromised. +It is achieved by inserting the authenticated variable for the compromised key into the forbidden key list(DBx). -The revoke key is a mechanism to permanently disallow any image signed by the private key whose public key is present in DBx of UEFI database. +``` +Sample example: +If db-orig-1.pem is compromised the generate an authenticated variable for db-orig-1.pem +1. Convert ESL of pem cert. + cert-to-efi-sig-list -g db-orig-3.pem db-orig-3.esl +2. Create authenticated variable + sign-efi-sig-list -g "" -k KEK.key -c KEK.crt dbx db-orig-3.esl DB-revoke.auth +3. Copy DB-revoke.auth to the system and use CLI to update the UEFI database +``` ### 4.5 Show keys This is to display the PK, KEK, DB, and DBx key lists. From 6f15867db65103996d05b9d365f2dd3ae0ea1186 Mon Sep 17 00:00:00 2001 From: Sachin Naik Date: Mon, 28 Aug 2023 23:29:51 -0700 Subject: [PATCH 16/16] Update Secureboot_uefi_key_management.md --- doc/secure_boot/Secureboot_uefi_key_management.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/secure_boot/Secureboot_uefi_key_management.md b/doc/secure_boot/Secureboot_uefi_key_management.md index 90e406b2101..0c643d18e80 100644 --- a/doc/secure_boot/Secureboot_uefi_key_management.md +++ b/doc/secure_boot/Secureboot_uefi_key_management.md @@ -90,11 +90,11 @@ The secure boot key and authenticate variable creation happens outside of the de ``` Sample example of key creation: -openssl req -newkey rsa:2048 -nodes -keyout PK.key -new -x509 -sha256 -days 3650 -subj "/CN=Platform key/" -out PK.crt -openssl req -newkey rsa:2048 -nodes -keyout KEK.key -new -x509 -sha256 -days 3650 -subj "/CN=Key Exchange Key/" -out KEK.crt -openssl req -newkey rsa:2048 -nodes -keyout db.key -new -x509 -sha256 -days 3650 -subj "/CN=Database key/" -out db.crt +openssl req -newkey rsa:2048 -nodes -keyout PK.key -new -x509 -sha256 -days 365 -subj "/CN=Platform key/" -out PK.crt +openssl req -newkey rsa:2048 -nodes -keyout KEK.key -new -x509 -sha256 -days 365 -subj "/CN=Key Exchange Key/" -out KEK.crt +openssl req -newkey rsa:2048 -nodes -keyout db.key -new -x509 -sha256 -days 365 -subj "/CN=Database key/" -out db.crt ``` -The private keys are kept secretly and used during image signing. The public keys are used to verify images signed by private keys. Public keys are wrapped in the x509 format of the certificate. These public certificates are enrolled in the SHIM or UEFI key database by the machine owner. +The private keys are kept secretly and used during image signing. The public keys are used to verify images signed by private keys. Public keys are wrapped in the x509 format of the certificate. These public certificates are enrolled in the UEFI key database by the platform owner. #### Authenticated variable creation ```