From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=195.135.221.5; helo=smtp.nue.novell.com; envelope-from=glin@suse.com; receiver=edk2-devel@lists.01.org Received: from smtp.nue.novell.com (smtp.nue.novell.com [195.135.221.5]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id AFCDE2041B260 for ; Tue, 24 Apr 2018 01:36:01 -0700 (PDT) Received: from localhost.localdomain (unknown.telstraglobal.net [134.159.103.118]) by smtp.nue.novell.com with ESMTP (NOT encrypted); Tue, 24 Apr 2018 10:35:57 +0200 From: Gary Lin To: edk2-devel@lists.01.org Cc: Ard Biesheuvel , Jordan Justen , Laszlo Ersek Date: Tue, 24 Apr 2018 16:35:44 +0800 Message-Id: <20180424083544.6614-1-glin@suse.com> X-Mailer: git-send-email 2.16.3 Subject: [PATCH v2 1/1] OvmfPkg/README: add HTTPS Boot X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 24 Apr 2018 08:36:03 -0000 Add the new section for HTTPS Boot. Changes in v2: - Fixed the typos - Added the command for p11-kit based on Laszlo's suggestion - Also added the efisiglist command - Elaborated how to create the customized cipher suite list - Mentioned the changes in QEMU in the future based on Laszlo's suggestion Cc: Ard Biesheuvel Cc: Jordan Justen Cc: Laszlo Ersek Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Gary Lin --- OvmfPkg/README | 88 ++++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/OvmfPkg/README b/OvmfPkg/README index 00fb71848200..60545ebccfad 100644 --- a/OvmfPkg/README +++ b/OvmfPkg/README @@ -254,6 +254,94 @@ longer.) VirtioNetDxe | x Intel BootUtil (X64) | x +=== HTTPS Boot === + +HTTPS Boot is an alternative solution to PXE. It replaces the tftp server +with a HTTPS server so the firmware can download the images through a trusted +and encrypted connection. + +* To enable HTTPS Boot, you have to build OVMF with -D HTTP_BOOT_ENABLE and + -D TLS_ENABLE. The former brings in the HTTP stack from NetworkPkg while + the latter enables TLS support in both NetworkPkg and CryptoPkg. + +* By default, there is no trusted certificate. The user has to import the + certificates either manually with "Tls Auth Configuration" utility in the + firmware UI or through the fw_cfg entry, etc/edk2/https/cacerts. + + -fw_cfg name=etc/edk2/https/cacerts,file= + + The blob for etc/edk2/https/cacerts has to be in the format of Signature + Database(*1). You can use p11-kit(*2) or efisiglit(*3) to create the + certificate list. + + If you want to create the certificate list based on the CA certificates + in your local host, p11-kit will be a good choice. Here is the command to + create the list: + + p11-kit extract --format=edk2-cacerts --filter=ca-anchors \ + --overwrite --purpose=server-auth + + If you only want to import one certificate, efisiglist is the tool for you: + + efisiglist -a -o + + Please note that the certificate has to be in the DER format. + + You can also append a certificate to the existed list with the following + command: + + efisiglist -i -a -o + + NOTE: You may need the patch to make efisiglist generate the correct header. + (https://github.com/rhboot/pesign/pull/40) + +* Besides the trusted certificates, it's also possible to configure the trusted + cipher suites for HTTPS through another fw_cfg entry: etc/edk2/https/ciphers. + + -fw_cfg name=etc/edk2/https/ciphers,file= + + OVMF expects a binary UINT16 array which comprises the cipher suites HEX + IDs(*4). If the cipher suite list is given, OVMF will choose the cipher + suite from the intersection of the given list and the built-in cipher + suites. Otherwise, OVMF just chooses whatever proper cipher suites from the + built-in ones. + + While the tool(*5) to create the cipher suite array is still under + development, the array can be generated with the following script: + + export LC_ALL=C + openssl ciphers -V \ + | sed -r -n \ + -e 's/^ *0x([0-9A-F]{2}),0x([0-9A-F]{2}) - .*$/\\\\x\1 \\\\x\2/p' \ + | xargs -r -- printf -- '%b' > ciphers.bin + + This script creates ciphers.bin that contains all the cipher suite IDs + supported by openssl according to the local host configuration. + + You may want to enable only a limited set of cipher suites. Then, you + should check the validity of your list first: + + openssl ciphers -V + + If all the cipher suites in your list map to the proper HEX IDs, go ahead + to modify the script and execute it: + + export LC_ALL=C + openssl ciphers -V \ + | sed -r -n \ + -e 's/^ *0x([0-9A-F]{2}),0x([0-9A-F]{2}) - .*$/\\\\x\1 \\\\x\2/p' \ + | xargs -r -- printf -- '%b' > ciphers.bin + +* In the future (after release 2.12), QEMU should populate both above fw_cfg + files automatically from the local host configuration, and enable the user + to override either with dedicated options or properties + +(*1) See "31.4.1 Signature Database" in UEFI specification 2.7 errata A. +(*2) p11-kit: https://github.com/p11-glue/p11-kit/ +(*3) efisiglist: https://github.com/rhboot/pesign/blob/master/src/efisiglist.c +(*4) https://wiki.mozilla.org/Security/Server_Side_TLS#Cipher_names_correspondence_table +(*5) update-crypto-policies: https://github.com/nmav/fedora-crypto-policies + === OVMF Flash Layout === Like all current IA32/X64 system designs, OVMF's firmware device (rom/flash) -- 2.16.3