Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S964849AbbHKGTn (ORCPT ); Tue, 11 Aug 2015 02:19:43 -0400 Received: from mail-pa0-f46.google.com ([209.85.220.46]:34522 "EHLO mail-pa0-f46.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S934111AbbHKGTj (ORCPT ); Tue, 11 Aug 2015 02:19:39 -0400 From: "Lee, Chun-Yi" X-Google-Original-From: "Lee, Chun-Yi" To: linux-kernel@vger.kernel.org Cc: linux-efi@vger.kernel.org, linux-pm@vger.kernel.org, "Rafael J. Wysocki" , Matthew Garrett , Len Brown , Pavel Machek , Josh Boyer , Vojtech Pavlik , Matt Fleming , Jiri Kosina , "H. Peter Anvin" , Ingo Molnar , "Lee, Chun-Yi" Subject: [PATCH v2 16/16] PM / hibernate: Document signature verification of hibernate snapshot Date: Tue, 11 Aug 2015 14:16:36 +0800 Message-Id: <1439273796-25359-17-git-send-email-jlee@suse.com> X-Mailer: git-send-email 1.8.4.5 In-Reply-To: <1439273796-25359-1-git-send-email-jlee@suse.com> References: <1439273796-25359-1-git-send-email-jlee@suse.com> Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 4837 Lines: 108 Reviewed-by: Jiri Kosina Tested-by: Jiri Kosina Signed-off-by: Lee, Chun-Yi --- Documentation/power/swsusp-signature-verify.txt | 86 +++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 Documentation/power/swsusp-signature-verify.txt diff --git a/Documentation/power/swsusp-signature-verify.txt b/Documentation/power/swsusp-signature-verify.txt new file mode 100644 index 0000000..7ba4a3f --- /dev/null +++ b/Documentation/power/swsusp-signature-verify.txt @@ -0,0 +1,86 @@ +Signature verification of hibernate snapshot +============================================ + +1) Introduction +2) How to enable +3) How does it work +4) Trigger key re-generate + +1) Introduction +--------------------- + +The hibernate function provided by kernel was used to snapshot memory +to be a image for keeping in storage, then restored in appropriate time. +There have potential threat from hacking the memory snapshot image. +Cracker may triggers hibernating process through ioctl to grab snapshot +image, then restoring modified image back to memory. Another situation +is booting to other hacked OS to modify the snapshot image in swap +partition or file, then user may runs malware after image restored to +memory. In addition, the above weakness cause kernel is not fully trusted +in EFI secure boot environment. + +So, kernel hibernate function needs a mechanism to verify integrity of +hibernate snapshot image. + +The origin idea is from Jiri Kosina: Let EFI bootloader generates key-pair +in UEFI secure boot environment, then forwarding keys to boot kernel for +signing/verifying snapshot image. + + +2) How to enable +----------------- + +If the HIBERNATE_VERIFICATION compile option is true, kernel hibernate code +will generating and verifying the signature of memory snapshot image by +HMAC-SHA1 algorithm. Current solution relies on EFI stub on x86 architecture, +so the signature verification logic will be bypassed on legacy BIOS. + +When the snapshot image unsigned or signed with an unknown key, the signature +verification will be failed. The default behavior of verifying failed is +accept restoring image but tainting kernel with H taint flag. + +Like kernel module signature checking, there's both a config option and +a boot parameter which control whether we accept or stop whole recovery +process when verification failed. Using HIBERNATE_VERIFICATION_FORCE kernel +compile option or "sigenforce" kernel parameter to force hibernate recovery +process stop when verification failed. + + +3) How does it work +------------------- + +For signing hibernate image, kernel need a key for generating signature of +image. The origin idea is using PKI, the EFI bootloader, shim generates key +pair and forward to boot kernel for signing/verifying image. In Linux Plumbers +Conference 2013, we got response from community experts for just using +symmetric key algorithm to generate signature, that's simpler and no EFI +bootloader's involving. + +Current solution is using HMAC-SHA1 algorithm, it generating HMAC key in EFI +stub by using RDRAND, RDTSC and EFI RNG protocol to grab random number to be +the entropy of key. Then the HMAC key stored in efi boot service variable, +key's security relies on EFI secure boot: When EFI secure boot enabled, only +trusted efi program allowed accessing boot service variables. + +In every EFI stub booting stage, it loads key from variable then forward key +to boot kernel for waiting to sign snapshot image by user trigger hibernating. +The HMAC-SHA1 algorithm generates signature then kernel put signature to the +header with the memory snapshot image. The signature with image is delivered +to userspace hibernating application or direct stored in swap partition. + +When hibernate recovering, kernel will verify the image signature before +switch whole system to image kernel and image memory space. When verifying +failed, kernel is tainted or stop recovering and discarding image. + + +4) Trigger key re-generate +-------------------------- + +The hibernate signature verifying function allows user to trigger the key +re-generating process in EFI stub through SNAPSHOT_REGENERATE_KEY ioctl. + +User can raise a key-regen flag in kernel through ioctl. When system runs +normal shutdown or reboot, kernel writes a efi runtime variable as a flag +then EFI stub will query the flag in next boot cycle. To avoid the hibernation +key changes in hibernating cycle that causes hibernate restoring failed, +the regen flag will be clear in a hibernate cycle. -- 2.1.4 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/