From patchwork Fri May 26 03:06:09 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: AKASHI Takahiro X-Patchwork-Id: 100541 Delivered-To: patch@linaro.org Received: by 10.140.96.100 with SMTP id j91csp59012qge; Thu, 25 May 2017 20:03:18 -0700 (PDT) X-Received: by 10.99.23.100 with SMTP id 36mr19891171pgx.118.1495767798821; Thu, 25 May 2017 20:03:18 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1495767798; cv=none; d=google.com; s=arc-20160816; b=EzjBrapXjWc9ntubWeEyAIkOg2qT8VpKBdz/1IkkGplApM9pcpuzRJgKe9T3QAvQmJ IMq2KO6BC9+G3TWP79JGX5xAAcwKu81uTuPoo2IzGI4XHrxmzuOKKp03ZsVcH6RZyChT hMtJxo+ipGFbLgWI2m6Su+2zIXLGegoWpG+BoDrgFbz4vMuruPP3ZL5zk7rpA1AGB/8D LeT71Jgn9167ZCJxhahWl0yVXXZ0fN2LGGJvs9urT3NkwH9XA3+jxob5FgGIqkLwgkHl 2mU/mE/9RoG5ecZNtBTZp+SMBkLuxmuhKjkGqzGgzLHs9ouWl5SRGriuqkK1Tl6Cxf3C qTPg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:references:in-reply-to:message-id:date :subject:cc:to:from:dkim-signature:arc-authentication-results; bh=1A8I2nEZmPOIpJAiQX9fzwArdqhJSImxS2uyuAXpJsU=; b=ViCKdq4GTpvzk1+Knfabb06ulJ4o74Ol+z0gmEwCsgkJ6rsZPeIEBBmppfT8265Skk 1zLqRfTQVilYPc0JypMse7aW0LHODpOzHnpxSS5SJAMCRMmsNmnZOEKwzDNB0EQDeOw4 a/lSmt4+WWfFQVYzu2cJI7GsMWhPW9IvQM3AwObcCEKuQQ8K3NVIKHUL2Io6F/9vN4Wo 4F2xUExs1/eMBrAbkopcue8rzZ9mKZmWF104Ikv7xPuLCh4zVPMvd3URX4fUPIo5tUb2 uNl7Sc6QOtc8hlCW976I83fE4FS1iPLqi9edWlhZGQ8esoQhXMHcsIPO167pr62FE2px OLPA== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id 71si10751894pgd.94.2017.05.25.20.03.18; Thu, 25 May 2017 20:03:18 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1946746AbdEZDDP (ORCPT + 25 others); Thu, 25 May 2017 23:03:15 -0400 Received: from mail-pf0-f180.google.com ([209.85.192.180]:33346 "EHLO mail-pf0-f180.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1946700AbdEZDCm (ORCPT ); Thu, 25 May 2017 23:02:42 -0400 Received: by mail-pf0-f180.google.com with SMTP id e193so184461854pfh.0 for ; Thu, 25 May 2017 20:02:42 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=1A8I2nEZmPOIpJAiQX9fzwArdqhJSImxS2uyuAXpJsU=; b=XPwqqQPbcGNi+O6AnYl+J52zLpC7t6/K2KR5l80xnqg6r384CvjvtrtRpcRlnbvwwM ASfnw5fyye7r7gnW/Hx6liKxtoh6RCmR7PIyA3UDPiYYq+BzvohdlN0uSM21Y8Ueueac gjzauj2jhSYdj2NlL4oRqGVdAZv2m+8eEjcak= X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references; bh=1A8I2nEZmPOIpJAiQX9fzwArdqhJSImxS2uyuAXpJsU=; b=YSAHzsJWWcGYbMWsMFwRAT8oIdY1FoJ5jPsGGthTHtP8+HTB4s6eJCZUuxAvCkYP11 BD1h5iygvMsScIC9xCxYnnhSJCyrwNIO5p7UZ90ImBzJXoTNek82rSVCQDnGZIjoaxpl 5XNSeXyQuDJu5e1p6S/C0SXzlxNPeFmhGlW2at6Hq9hv4rEyeYKRp2iAPmA3cK0i4YQX n7V6BSi8ti5pBvpYFNGZuq4WPRr1cP1tKNZ5ON0s1zhoMe2cnXTZwPeEvI8VeCDgtinE dQ6s2xWenMwHnFi/uqTJ85KXISAqPcMPFUfUggTcu4L+lWAkLgPE1Azu3//ICsAZ+DXm eS6Q== X-Gm-Message-State: AODbwcAbWD2ZEZNdMBrYvQTT6ZU7d0u1GqOmvguyqpCWXibwBwP0YSAk gFOE8gNhqojSP+qU X-Received: by 10.99.54.141 with SMTP id d135mr31307857pga.85.1495767761865; Thu, 25 May 2017 20:02:41 -0700 (PDT) Received: from linaro.org ([121.95.100.191]) by smtp.googlemail.com with ESMTPSA id 19sm14395266pfz.39.2017.05.25.20.02.39 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 25 May 2017 20:02:40 -0700 (PDT) From: AKASHI Takahiro To: mcgrof@kernel.org Cc: rusty@rustcorp.com.au, dhowells@redhat.com, ming.lei@canonical.com, seth.forshee@canonical.com, kyle@kernel.org, David.Woodhouse@intel.com, linux-kernel@vger.kernel.org, AKASHI Takahiro , "Luis R . Rodriguez" Subject: [PATCH 4/4] firmware: document signature verification for driver data Date: Fri, 26 May 2017 12:06:09 +0900 Message-Id: <20170526030609.1414-5-takahiro.akashi@linaro.org> X-Mailer: git-send-email 2.11.1 In-Reply-To: <20170526030609.1414-1-takahiro.akashi@linaro.org> References: <20170526030609.1414-1-takahiro.akashi@linaro.org> Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org add descriptions and usage about firmware signing in driver data APIs. Signed-off-by: AKASHI Takahiro Cc: Luis R. Rodriguez --- Documentation/driver-api/firmware/driver_data.rst | 6 ++ .../driver-api/firmware/fallback-mechanisms.rst | 5 +- Documentation/driver-api/firmware/signing.rst | 81 ++++++++++++++++++++++ 3 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 Documentation/driver-api/firmware/signing.rst -- 2.11.1 diff --git a/Documentation/driver-api/firmware/driver_data.rst b/Documentation/driver-api/firmware/driver_data.rst index be7c7ff99151..cdc47144a8b2 100644 --- a/Documentation/driver-api/firmware/driver_data.rst +++ b/Documentation/driver-api/firmware/driver_data.rst @@ -94,6 +94,12 @@ in these callbacks it frees it for you by default after callback handlers are issued. If you wish to keep the driver data around after your callbacks you must specify this through the driver data request parameter data structure. +Signature verification +====================== + + * `data signing`_ +.. _`data signing`: ./signing.rst + Driver data private internal functionality ========================================== diff --git a/Documentation/driver-api/firmware/fallback-mechanisms.rst b/Documentation/driver-api/firmware/fallback-mechanisms.rst index d19354794e67..e557d6630330 100644 --- a/Documentation/driver-api/firmware/fallback-mechanisms.rst +++ b/Documentation/driver-api/firmware/fallback-mechanisms.rst @@ -81,11 +81,12 @@ and a file upload firmware into: * /sys/$DEVPATH/loading * /sys/$DEVPATH/data + * /sys/$DEVPATH/sig_data To upload firmware you will echo 1 onto the loading file to indicate you are loading firmware. You then cat the firmware into the data file, -and you notify the kernel the firmware is ready by echo'ing 0 onto -the loading file. +optionally its signature file, and you notify the kernel the firmware is +ready by echo'ing 0 onto the loading file. The firmware device used to help load firmware using sysfs is only created if direct firmware loading fails and if the fallback mechanism is enabled for your diff --git a/Documentation/driver-api/firmware/signing.rst b/Documentation/driver-api/firmware/signing.rst new file mode 100644 index 000000000000..2dbee104700e --- /dev/null +++ b/Documentation/driver-api/firmware/signing.rst @@ -0,0 +1,81 @@ +================================ +Kernel firmware signing facility +================================ + +Overview +======== + +The kernel firmware signing facility enables to cryptographically sign +firmware files on a system using the same keys used for module signing. +Firmware files's signatures consist of PKCS#7 messages of the respective +firmware file. A firmware file named foo.bin, would have its respective +signature on the filesystem as foo.bin.p7s. When firmware signature +checking is enabled (FIRMWARE_SIG) and when one of the above APIs is used +against foo.bin, the file foo.bin.p7s will also be looked for. If +FIRMWARE_SIG_FORCE is enabled the foo.bin file will only be allowed to +be returned to callers of the above APIs if and only if the foo.bin.p7s +file is confirmed to be a valid signature of the foo.bin file. If +FIRMWARE_SIG_FORCE is not enabled and only FIRMWARE_SIG is enabled the +kernel will be permissive and enabled unsigned firmware files, or firmware +files with incorrect signatures. If FIRMWARE_SIG is not enabled the +signature file is ignored completely. + +Firmware signing increases security by making it harder to load a malicious +firmware into the kernel. The firmware signature checking is done by the +kernel so that it is not necessary to have trusted userspace bits. + +Configuring firmware signing +============================ + +The firmware signing facility is enabled by going to the section:: + + -> Device Drivers + -> Generic Driver Options + -> Userspace firmware loading support (FW_LOADER [=y]) + -> Firmware signature verification (FIRMWARE_SIG [=y]) + +If you want to not allow unsigned firmware to be loaded you should +enable:: + + -> Require all firmware to be validly signed (FIRMWARE_SIG_FORCE [=y]) + +under the same menu. + +Using signing keys +================== + +The same key types used for module signing can be used for firmware +signing. For details on that refer to `Kernel module signing`_. + +.. _`Kernel module signing`: /admin-guide/module-signing.rst + +You will need: + + A) A DER-encoded X.509 certificate containing the public key. + B) A DER-encoded PKCS#7 message containing the signatures, these are + the .p7s files. + C) A binary blob that is the detached data for the PKCS#7 message, this + is the firmware files + +A) is must be made available to the kernel. One way to do this is to provide a +DER-encoded in the source directory as .x509 when you build the kernel. + +Signing firmware files +====================== + +To generate a DER-encoded PKCS#7 signature message for each firmware file +you can use the following commands: + + scripts/sign-file -f sha256 \ + $PRIVATE_KEY_FILE_IN_PEM_FORM \ + $X509_CERT_FILE_IN_PEM_FORM \ + $FIRMWARE_BLOB_NAME + + or + + openssl smime -sign -in $FIRMWARE_BLOB_NAME \ + -outform DER \ + -inkey $PRIVATE_KEY_FILE_IN_PEM_FORM \ + -signer $X509_CERT_FILE_IN_PEM_FORM \ + -nocerts -md $DIGEST_ALGORITHM -binary > \ + $(FIRMWARE_BLOB_NAME).p7s