From patchwork Thu Apr 11 22:45:45 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Richter X-Patchwork-Id: 1084342 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 44gGNN60cnz9s5c for ; Fri, 12 Apr 2019 08:46:28 +1000 (AEST) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 44gGNN4sCWzDqTG for ; Fri, 12 Apr 2019 08:46:28 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=linux.ibm.com (client-ip=148.163.156.1; helo=mx0a-001b2d01.pphosted.com; envelope-from=erichte@linux.ibm.com; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com [148.163.156.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 44gGMx5qmTzDqSt for ; Fri, 12 Apr 2019 08:46:05 +1000 (AEST) Received: from pps.filterd (m0098399.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x3BMhsBU096097 for ; Thu, 11 Apr 2019 18:46:03 -0400 Received: from e06smtp01.uk.ibm.com (e06smtp01.uk.ibm.com [195.75.94.97]) by mx0a-001b2d01.pphosted.com with ESMTP id 2rtcc75bm7-1 (version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT) for ; Thu, 11 Apr 2019 18:46:02 -0400 Received: from localhost by e06smtp01.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Thu, 11 Apr 2019 23:46:00 +0100 Received: from b06cxnps4074.portsmouth.uk.ibm.com (9.149.109.196) by e06smtp01.uk.ibm.com (192.168.101.131) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; (version=TLSv1/SSLv3 cipher=AES256-GCM-SHA384 bits=256/256) Thu, 11 Apr 2019 23:45:59 +0100 Received: from d06av25.portsmouth.uk.ibm.com (d06av25.portsmouth.uk.ibm.com [9.149.105.61]) by b06cxnps4074.portsmouth.uk.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id x3BMjvXY52035654 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 11 Apr 2019 22:45:57 GMT Received: from d06av25.portsmouth.uk.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id A7F6511C05C; Thu, 11 Apr 2019 22:45:57 +0000 (GMT) Received: from d06av25.portsmouth.uk.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 29E4411C06C; Thu, 11 Apr 2019 22:45:57 +0000 (GMT) Received: from yorha.ibmuc.com (unknown [9.80.238.6]) by d06av25.portsmouth.uk.ibm.com (Postfix) with ESMTP; Thu, 11 Apr 2019 22:45:57 +0000 (GMT) From: Eric Richter To: skiboot@lists.ozlabs.org Date: Thu, 11 Apr 2019 17:45:45 -0500 X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190411224551.29401-1-erichte@linux.ibm.com> References: <20190411224551.29401-1-erichte@linux.ibm.com> MIME-Version: 1.0 X-TM-AS-GCONF: 00 x-cbid: 19041122-4275-0000-0000-00000326EB0D X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 19041122-4276-0000-0000-000038360D44 Message-Id: <20190411224551.29401-3-erichte@linux.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-04-11_14:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1904110145 Subject: [Skiboot] [RFC v2 2/8] doc: add opal secvar documentation X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" This patch contains all the relevant documentation for the secure variable support in OPAL. This may be split and squashed with their relevant implementations in the future, but kept separate for now. Notably missing at the moment is the documentation for the SECBOOT PNOR partition usage, which will be included in a future revision. v2: - removed k_ prefix on all parameters - changed all uint64_t types to their actual intended type - added a new overview preamble, work in progress Signed-off-by: Eric Richter --- doc/opal-api/opal-secvar.rst | 188 +++++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 doc/opal-api/opal-secvar.rst diff --git a/doc/opal-api/opal-secvar.rst b/doc/opal-api/opal-secvar.rst new file mode 100644 index 00000000..382b9eb4 --- /dev/null +++ b/doc/opal-api/opal-secvar.rst @@ -0,0 +1,188 @@ +OPAL Secure Variables +===================== + +Overview +-------- + +In order to support host OS secure boot on POWER systems, the platform needs +some form of tamper-resistant persistant storage for authorized public keys. +Furthermore, these keys must be retrieveable by the host kernel, and new +keys must be able to be submitted. + +OPAL exposes an abstracted "variable" API, in which these keys can be stored +and retrieved. At a high level, ``opal_secvar_get`` retrieves a specific +variable corresponding to a name+vendor guid pair (see "types" below). +``opal_secvar_get_next`` can be used to iterate through the stored +variables. ``opal_secvar_enqueue_update`` can be used to submit a new +variable for processing on next boot. + +Types +----- + +This document uses the following non-standard types: +:: + + char16_t - 16-bit char, in little endian ucs2 + guid_t - 16-byte UUID blob + + +OPAL_SECVAR_GET +=============== +:: + + #define OPAL_SECVAR_GET 170 + +``OPAL_SECVAR_GET`` call retrieves a data blob associated with the supplied +name and vendor guid. + +Parameters +---------- +:: + + char16_t *name + guid_t *vendor + uint32_t *attributes + uint64_t *data_size + void *data + +``name`` + the name of the requested variable as a 16-bit char + +``vendor`` + the vendor guid of the requested variable + +``attributes`` + optional bitfield reference to be set by OPAL for attributes +related to the variable data + +``data_size`` + reference to the size of the ``data`` buffer. OPAL sets this if +the buffer size is insufficient for the requested variable + +``data`` + return buffer to store the data blob of the requested variable if +a match was found. May be set to NULL to request only the size + +Return Values +------------- + +``OPAL_SUCCESS`` + data from the requested variable was copied successfully, or +``data`` was set to NULL and the ``data_size`` was set to the +requested variable's size + +``OPAL_PARAMETER`` + ``name``, ``vendor`` or ``data_size`` are invalid buffers, +contain invalid values + +``OPAL_EMPTY`` + no variable with the supplied ``name`` and ``vendor`` was found + +``OPAL_PARTIAL`` + the buffer size provided in ``data_size`` is too small for the +requested variable + +``OPAL_UNSUPPORTED`` + secure variable support is disabled + +OPAL_SECVAR_GET_NEXT +==================== +:: + + #define OPAL_SECVAR_GET_NEXT 171 + +``OPAL_SECVAR_GET_NEXT`` returns the name and vendor guid of the next +variable in the secure variable bank in sequence. + +Parameters +---------- +:: + + size_t *name_size + char16_t *name + guid_t *vendor + +``name_size`` + size of the ``name`` buffer. OPAL sets this to the size of the +next variable in sequence + +``name`` + name of the previous variable or empty. The name of the next +variable in sequence will be copied to ``name`` + +``vendor`` + vendor guid of the previous variable or empty. The vendor of the +next vendor in sequence will be copied to ``vendor`` + +Return Values +------------- + +``OPAL_SUCCESS`` + the name and vendor of the next variable in sequence was copied +successfully + +``OPAL_PARAMETER`` + ``name`` or ``vendor`` are invalid buffers, or were not found. +``name_size`` is an invalid value. A variable matching the +supplied non-empty ``name`` and ``vendor`` was not found + +``OPAL_EMPTY`` + end of list reached + +``OPAL_PARTIAL`` + the size specified in ``name_size`` is insufficient for the next +variable's name size + +``OPAL_HARDWARE`` + secure variable support is disabled + +OPAL_SECVAR_ENQUEUE_UPDATE +========================== +:: + + #define OPAL_SECVAR_ENQUEUE_UPDATE 172 + +``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the +queue for processing on next boot. + +Parameters +---------- +:: + + char16_t *name + guid_t *vendor + uint32_t attributes + size_t data_size + void *data + +``name`` + the name of the submitted variable as a 16-bit char + +``vendor`` + the vendor guid of the submitted variable + +``attributes`` + bitfield of attributes + +``data_size`` + size of the buffer to copy from ``data`` + +``data`` + blob of data to be stored + +Return Values +------------- + +``OPAL_SUCCESS`` + the variable was appended to the update queue bank successfully + +``OPAL_PARAMETER`` + ``name``, ``vendor`` or ``data`` are invalid buffers. +``name`` is empty. ``data_size`` is an invalid value. ``data_size`` +was set to zero (potentially an unsupported deletion attempt) + +``OPAL_NO_MEM`` + OPAL was unable to allocate memory for the variable + +``OPAL_UNSUPPORTED`` + secure variable support is disabled