From patchwork Thu Mar 28 22:17:50 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Eric Richter X-Patchwork-Id: 1068767 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 44VfQs650Cz9sR7 for ; Fri, 29 Mar 2019 09:18:45 +1100 (AEDT) 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 44VfQs53DkzDqRk for ; Fri, 29 Mar 2019 09:18:45 +1100 (AEDT) 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.158.5; 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 (mx0b-001b2d01.pphosted.com [148.163.158.5]) (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 44VfQC27LjzDqC8 for ; Fri, 29 Mar 2019 09:18:08 +1100 (AEDT) Received: from pps.filterd (m0098421.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x2SMC4F1058650 for ; Thu, 28 Mar 2019 18:18:06 -0400 Received: from e06smtp07.uk.ibm.com (e06smtp07.uk.ibm.com [195.75.94.103]) by mx0a-001b2d01.pphosted.com with ESMTP id 2rh6uvr5rq-1 (version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT) for ; Thu, 28 Mar 2019 18:18:06 -0400 Received: from localhost by e06smtp07.uk.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Thu, 28 Mar 2019 22:18:04 -0000 Received: from b06cxnps4076.portsmouth.uk.ibm.com (9.149.109.198) by e06smtp07.uk.ibm.com (192.168.101.137) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; (version=TLSv1/SSLv3 cipher=AES256-GCM-SHA384 bits=256/256) Thu, 28 Mar 2019 22:18:02 -0000 Received: from d06av25.portsmouth.uk.ibm.com (d06av25.portsmouth.uk.ibm.com [9.149.105.61]) by b06cxnps4076.portsmouth.uk.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id x2SMI0S337290008 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 28 Mar 2019 22:18:00 GMT Received: from d06av25.portsmouth.uk.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 4C3EF11C04C; Thu, 28 Mar 2019 22:18:00 +0000 (GMT) Received: from d06av25.portsmouth.uk.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id B9F9711C04A; Thu, 28 Mar 2019 22:17:59 +0000 (GMT) Received: from yorha.ibmmodules.com (unknown [9.80.235.135]) by d06av25.portsmouth.uk.ibm.com (Postfix) with ESMTP; Thu, 28 Mar 2019 22:17:59 +0000 (GMT) From: Eric Richter To: skiboot@lists.ozlabs.org Date: Thu, 28 Mar 2019 17:17:50 -0500 X-Mailer: git-send-email 2.17.2 In-Reply-To: <20190328221754.20838-1-erichte@linux.ibm.com> References: <20190328221754.20838-1-erichte@linux.ibm.com> X-TM-AS-GCONF: 00 x-cbid: 19032822-0028-0000-0000-00000359BF2F X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 19032822-0029-0000-0000-0000241881A4 Message-Id: <20190328221754.20838-3-erichte@linux.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-03-28_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=928 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1903280143 Subject: [Skiboot] [RFC 2/6] 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: , MIME-Version: 1.0 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. Signed-off-by: Eric Richter --- doc/opal-api/opal-secvar.rst | 199 +++++++++++++++++++++++++++++++++++ 1 file changed, 199 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..fd66e5e2 --- /dev/null +++ b/doc/opal-api/opal-secvar.rst @@ -0,0 +1,199 @@ +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 +---------- +:: + + uint64_t k_name + uint64_t k_vendor + uint64_t k_attributes + uint64_t k_data_size + uint64_t k_data + +``k_name`` + the name of the requested variable as a 16-bit char + +``k_vendor`` + the vendor guid of the requested variable + +``k_attributes`` + optional bitfield reference to be set by OPAL for attributes +related to the variable data + +``k_data_size`` + reference to the size of the ``k_data`` buffer. OPAL sets this if +the buffer size is insufficient for the requested variable + +``k_data`` + return buffer to store the data blob of the requested variable if +a match was found + +Return Values +------------- + +``OPAL_SUCCESS`` + data from the requested variable was copied successfully, or +``k_data`` was set to NULL and the ``k_data_size`` was set to the +requested variable's size + +``OPAL_PARAMETER`` + ``k_name``, ``k_vendor`` or ``k_data_size`` are invalid buffers, +contain invalid values + +``OPAL_EMPTY`` + no variable with the supplied ``k_name`` and ``k_vendor`` was found + +``OPAL_PARTIAL`` + the buffer size provided in ``k_data_size`` is too small for the +requested variable + +``OPAL_HARDWARE`` + 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 +---------- +:: + + uint64_t k_name_size + uint64_t k_name + uint64_t k_vendor + +``k_name_size`` + size of the ``k_name`` buffer. OPAL sets this to the size of the +next variable in sequence + +``k_name`` + name of the previous variable or empty. The name of the next +variable in sequence will be copied to ``k_name`` + +``k_vendor`` + vendor guid of the previous variable or empty. The vendor of the +next vendor in sequence will be copied to ``k_vendor`` + +Return Values +------------- + +``OPAL_SUCCESS`` + the name and vendor of the next variable in sequence was copied +successfully + +``OPAL_PARAMETER`` + ``k_name`` or ``k_vendor`` are invalid buffers, or were not found. +``k_name_size`` is an invalid value. A variable matching +the supplied non-empty ``k_name`` and ``k_vendor`` was not found + +``OPAL_EMPTY`` + end of list reached + +``OPAL_PARTIAL`` + the size specified in ``k_name_size`` is insufficient for the next +variable's name size + +``OPAL_HARDWARE`` + secure variable support is disabled + +OPAL_SECVAR_ENQUEUE +=================== +:: + + #define OPAL_SECVAR_ENQUEUE 172 + +``OPAL_SECVAR_ENQUEUE`` call appends the supplied variable data to the +queue for processing on next boot. + +Parameters +---------- +:: + + uint64_t k_name + uint64_t k_vendor + uint64_t k_attributes + uint64_t k_data_size + uint64_t k_data + +``k_name`` + the name of the submitted variable as a 16-bit char + +``k_vendor`` + the vendor guid of the submitted variable + +``k_attributes`` + bitfield of attributes + +``k_data_size`` + size of the buffer to copy from ``k_data`` + +``k_data`` + blob of data to be stored + +Return Values +------------- + +``OPAL_SUCCESS`` + the variable was appended to the update queue bank successfully + +``OPAL_PARAMETER`` + ``k_name``, ``k_vendor`` or ``k_data`` are invalid buffers. +``k_name`` is empty. ``k_data_size`` is an invalid value. + +``OPAL_NO_MEM`` + OPAL was unable to allocate memory for the variable + +``OPAL_UNSUPPORTED`` + ``k_data_size`` was set to zero, implying an empty ``k_data`` buffer +(may be used for variable deletion in the future) + +``OPAL_HARDWARE`` + secure variable support is disabled + +OPAL_SECVAR_INFO +================ +:: + + #define OPAL_SECVAR_INFO 173 + +``OPAL_SECVAR_INFO`` returns size information about the variable +storage. Not currently implemented. + +Parameters +---------- +:: + + uint64_t k_attributes + uint64_t k_storage_space + uint64_t k_remaining_space + uint64_t k_max_variable_size + +``k_attributes`` + TODO + +``k_storage_space`` + maximum storage space in bytes + +``k_remaining_space`` + remaining storage space in bytes + +``k_max_variable_size`` + maximum acceptable size for a data blob + +Return Values +------------- + +``OPAL_UNSUPPORTED`` + Runtime service is currently a stub, not currently implemented.