From nobody Sun Dec 22 01:45:32 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=fail(p=reject dis=none) header.from=linux.vnet.ibm.com Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1734376635327840.9147305534277; Mon, 16 Dec 2024 11:17:15 -0800 (PST) Received: by lists.libvirt.org (Postfix, from userid 996) id 2AA9914E5; Mon, 16 Dec 2024 14:17:14 -0500 (EST) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id C7D6F14B7; Mon, 16 Dec 2024 14:16:52 -0500 (EST) Received: by lists.libvirt.org (Postfix, from userid 996) id 901AF14A6; Mon, 16 Dec 2024 14:16:49 -0500 (EST) Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com [148.163.156.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id DE4EA14A4 for ; Mon, 16 Dec 2024 14:16:48 -0500 (EST) Received: from pps.filterd (m0353729.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.18.1.2/8.18.1.2) with ESMTP id 4BGClsWT008937; Mon, 16 Dec 2024 19:16:48 GMT Received: from ppma12.dal12v.mail.ibm.com (dc.9e.1632.ip4.static.sl-reverse.com [50.22.158.220]) by mx0a-001b2d01.pphosted.com (PPS) with ESMTPS id 43j98h50vc-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 16 Dec 2024 19:16:47 +0000 (GMT) Received: from pps.filterd (ppma12.dal12v.mail.ibm.com [127.0.0.1]) by ppma12.dal12v.mail.ibm.com (8.18.1.2/8.18.1.2) with ESMTP id 4BGGvsoH029329; Mon, 16 Dec 2024 19:16:46 GMT Received: from smtprelay07.dal12v.mail.ibm.com ([172.16.1.9]) by ppma12.dal12v.mail.ibm.com (PPS) with ESMTPS id 43hmbsfmam-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Mon, 16 Dec 2024 19:16:46 +0000 Received: from smtpav05.dal12v.mail.ibm.com (smtpav05.dal12v.mail.ibm.com [10.241.53.104]) by smtprelay07.dal12v.mail.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id 4BGJGk3l28639992 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 16 Dec 2024 19:16:46 GMT Received: from smtpav05.dal12v.mail.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 5C08158065; Mon, 16 Dec 2024 19:16:46 +0000 (GMT) Received: from smtpav05.dal12v.mail.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 1EFED58052; Mon, 16 Dec 2024 19:16:46 +0000 (GMT) Received: from sbct-3.pok.ibm.com (unknown [9.47.158.153]) by smtpav05.dal12v.mail.ibm.com (Postfix) with ESMTP; Mon, 16 Dec 2024 19:16:46 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-2.4 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,RCVD_IN_DNSWL_LOW, RCVD_IN_MSPIKE_H2,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ibm.com; h=cc :content-transfer-encoding:date:from:message-id:mime-version :subject:to; s=pp1; bh=JjtL+j8d7LG113crJxxkCxWYiS84K4jsjowKrgaKE +E=; b=Y7Q2oBIHot7PUEwT3+M30HGfFMjwpFSxVVjE9dNza1VzLPKayeftgIqkw XehBNR/LY0/uzeulkNoHG9HdCksNQ7+mNeqwI+wsZwx54Lf+aKjCn1Vm2khk/8nE OpoNtbIXDccbCeVmXI9eKg6O8LdHlSHIKYx768KoLzuWuU6IW9tOFcKIXKMIxqCs bFoNKxR+knMlN3YcArBp9XjvzE66WjXMLu/aNAi1IMPLXXUNerdtnI/atXe83QuK 5MHjGZRbd2gB/9Ia3UNtPLLikVFWQ7/k4iZ/RgLzZF4cKEAztRXocnHKzopXytSY kYYKTFf8wb5DwIXBDtVYPREFjRluQ== From: Stefan Berger To: devel@lists.libvirt.org Subject: [PATCH] docs: Clarify what source and name attributes of TPM profile describe Date: Mon, 16 Dec 2024 14:16:44 -0500 Message-ID: <20241216191644.172004-1-stefanb@linux.vnet.ibm.com> X-Mailer: git-send-email 2.47.1 MIME-Version: 1.0 X-TM-AS-GCONF: 00 X-Proofpoint-ORIG-GUID: lCw5P8dgYdt3rvpjBt_stBhYtXU9XKZd X-Proofpoint-GUID: lCw5P8dgYdt3rvpjBt_stBhYtXU9XKZd X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.293,Aquarius:18.0.1051,Hydra:6.0.680,FMLib:17.12.62.30 definitions=2024-10-15_01,2024-10-11_01,2024-09-30_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 phishscore=0 lowpriorityscore=0 malwarescore=0 spamscore=0 bulkscore=0 adultscore=0 mlxscore=0 impostorscore=0 mlxlogscore=999 suspectscore=0 clxscore=1011 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.19.0-2411120000 definitions=main-2412160154 Content-Transfer-Encoding: quoted-printable Message-ID-Hash: HMO7KDWTCJRZF5HD7UAIELBMU4OJEWBZ X-Message-ID-Hash: HMO7KDWTCJRZF5HD7UAIELBMU4OJEWBZ X-MailFrom: stefanb@linux.vnet.ibm.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header CC: marcandre.lureau@redhat.com X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1734376637258116600 Content-Type: text/plain; charset="utf-8" Clarify what source and name attributes of TPM profile describe and update the version placeholder to the libvirt version when profiles were first supported, v10.10. Also mention that profiles with prefix 'custom:' in their name can be modified. Signed-off-by: Stefan Berger --- docs/formatdomain.rst | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index 60bee8bd4f..0a56a96ea4 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -8303,27 +8303,32 @@ Example: usage of external TPM emulator :since:`Sin= ce 9.0.0` =20 ``profile`` The ``profile`` node is used to set a profile for a TPM 2.0 given in the - source attribute. This profile will be set when the TPM is initially - created and after that cannot be changed anymore. Once a profile has be= en - set the name attribute will be updated with the name of the profile that - is running. If no profile is provided, then swtpm will use the latest - built-in 'default' profile or the default profile set in swtpm_setup.co= nf. - Otherwise swtpm_setup will search for a profile with the given name with - appended .json suffix in a configurable local and then in a distro - directory. If none could be found in either, it will fall back trying to - use a built-in one. + ``source`` attribute. This attribute describes the name of the file und= er + which the profile is stored, e.g. 'local:restricted' describes a locally + created profile with name 'restricted.json' that is found in the direct= ory + pointed to by swtpm_setup.conf's local_profiles_dir. This profile will = be set + when the TPM is initially created and after that the profile cannot be + changed anymore. Once a profile has been set, the ``name`` attribute wi= ll be + updated with the profile's name from its JSON description, for example + 'custom:restricted'. If no profile is provided, then swtpm will use the + latest built-in 'default' profile or the default profile set in + swtpm_setup.conf. Otherwise swtpm_setup will search for a profile with = the + given name with appended .json suffix in a configurable local and then = in a + distro directory. If none could be found in either, it will fall back t= rying + to use a built-in one. =20 The built-in 'null' profile provides backwards compatibility with libtpms v0.9 but also restricts the user to use only TPM features that = were - available at the time of libtpms v0.9. The built-in 'custom' profile is= the - only profile that a user can modify and where the ``removeDisabled`` + available at the time of libtpms v0.9. The built-in 'custom' profile, or + those with the prefix 'custom:' in the name, are the + only profiles that a user can modify and where the ``removeDisabled`` attribute has any effect. This attribute is particularly useful when a = host is running in FIPS mode and therefore some crypto algorithms (camellia, tdes, unpadded RSA encryption, 1024-bit RSA keys, and others) are disabled. When it is set to ``check`` (recommended) then only those algorithms that are currently disabled will automatically be removed fr= om the 'custom' profile, while when it is set to ``fips-host`` then all - potentially disabled algorithms will be removed. :since:`Since 10.??.0` + potentially disabled algorithms will be removed. :since:`Since 10.10.0` =20 TPM profiles provided by a distro can be referenced with the 'distro:' prefix. Locally created TPM profiles can be referenced with the --=20 2.47.1