PAuth (Pointer Authentication), a security feature in software, is
relevant for both KVM and QEMU.  Relect this fact into the docs:

  - For KVM, `pauth` is a binary, "on" vs "off" option.  The host CPU
    will choose the cryptographic algorithm.

  - For TCG, however, along with `pauth`, a couple of properties can be
    controlled -- they're are related to cryptographic algorithm choice.

Thanks to Peter Maydell and Marc Zyngier for explaining more about PAuth
on IRC (#qemu, OFTC).

Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
---
 docs/system/arm/cpu-features.rst | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
index 78f18c87a81..7f99f7614b4 100644
--- a/docs/system/arm/cpu-features.rst
+++ b/docs/system/arm/cpu-features.rst
@@ -204,11 +204,26 @@ the list of KVM vCPU features and their descriptions.
   the guest scheduler behavior and/or be exposed to the guest
   userspace.
 
-TCG vCPU Features
-=================
+"PAuth" (Pointer Authentication)
+================================
+
+PAuth (Pointer Authentication) is a security feature in software that
+was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
+ROP (return-oriented programming) attacks.
+
+KVM
+---
+
+``pauth``
+
+  Enable or disable ``FEAT_Pauth``.  The host silicon will choose the
+  cryptographic algorithm.  No other properties can be controlled.
+
+TCG
+---
 
-TCG vCPU features are CPU features that are specific to TCG.
-Below is the list of TCG vCPU features and their descriptions.
+For TCG, along with ``pauth``, it is possible to control a few other
+properties of PAuth:
 
 ``pauth``
   Enable or disable ``FEAT_Pauth`` entirely.
-- 
2.48.1

On Fri, 17 Jan 2025 19:11:06 +0000,
Kashyap Chamarthy <kchamart@redhat.com> wrote:
> 
> PAuth (Pointer Authentication), a security feature in software, is
> relevant for both KVM and QEMU.  Relect this fact into the docs:
> 
>   - For KVM, `pauth` is a binary, "on" vs "off" option.  The host CPU
>     will choose the cryptographic algorithm.
> 
>   - For TCG, however, along with `pauth`, a couple of properties can be
>     controlled -- they're are related to cryptographic algorithm choice.
> 
> Thanks to Peter Maydell and Marc Zyngier for explaining more about PAuth
> on IRC (#qemu, OFTC).
> 
> Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> ---
>  docs/system/arm/cpu-features.rst | 23 +++++++++++++++++++----
>  1 file changed, 19 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
> index 78f18c87a81..7f99f7614b4 100644
> --- a/docs/system/arm/cpu-features.rst
> +++ b/docs/system/arm/cpu-features.rst
> @@ -204,11 +204,26 @@ the list of KVM vCPU features and their descriptions.
>    the guest scheduler behavior and/or be exposed to the guest
>    userspace.
>  
> -TCG vCPU Features
> -=================
> +"PAuth" (Pointer Authentication)
> +================================
> +
> +PAuth (Pointer Authentication) is a security feature in software that
> +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against

nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
feel strongly about this). I feel much strongly about the use of
capital letters, but I live in a distant past... ;-)

> +ROP (return-oriented programming) attacks.
> +
> +KVM
> +---
> +
> +``pauth``
> +
> +  Enable or disable ``FEAT_Pauth``.  The host silicon will choose the
> +  cryptographic algorithm.  No other properties can be controlled.

nit: "choose" is a an odd choice of word. The host implementation
defines, or even imposes the signature algorithm, as well as the level
of PAuth support (PAuth, EPAC, PAuth2, FPAC, FPACCOMBINE, ...), some
of which are mutually exclusive (EPAC and PAuth2 are incompatible).

Maybe it would be worth capturing some of these details, as this has a
direct influence on the ability to migrate a VM.

Thanks,

	M.

-- 
Without deviation from the norm, progress is not possible.

On Sat, Jan 18, 2025 at 10:04:37AM +0000, Marc Zyngier wrote:
> On Fri, 17 Jan 2025 19:11:06 +0000,
> Kashyap Chamarthy <kchamart@redhat.com> wrote:
> > 
> > PAuth (Pointer Authentication), a security feature in software, is
> > relevant for both KVM and QEMU.  Relect this fact into the docs:
> > 
> >   - For KVM, `pauth` is a binary, "on" vs "off" option.  The host CPU
> >     will choose the cryptographic algorithm.
> > 
> >   - For TCG, however, along with `pauth`, a couple of properties can be
> >     controlled -- they're are related to cryptographic algorithm choice.
> > 
> > Thanks to Peter Maydell and Marc Zyngier for explaining more about PAuth
> > on IRC (#qemu, OFTC).
> > 
> > Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com>
> > ---

[...]

> > -TCG vCPU Features
> > -=================
> > +"PAuth" (Pointer Authentication)
> > +================================
> > +
> > +PAuth (Pointer Authentication) is a security feature in software that
> > +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
> 
> nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
> the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
> feel strongly about this). I feel much strongly about the use of
> capital letters, but I live in a distant past... ;-)

Sure, I can keep it to just v8.3.

On capitalization, I don't feel strongly about it, I just followed this
commit[1], which explained that the rebranding changed "ARM" to "Arm":

    6fe6d6c9a95 (docs: Be consistent about capitalization of 'Arm',
    2020-03-09)

That's why I went with it.  I see you know this by your "distant past"
remark :)  To match the above, I'll keep the capitalization to "Arm".

> > +ROP (return-oriented programming) attacks.
> > +
> > +KVM
> > +---
> > +
> > +``pauth``
> > +
> > +  Enable or disable ``FEAT_Pauth``.  The host silicon will choose the
> > +  cryptographic algorithm.  No other properties can be controlled.
> 
> nit: "choose" is a an odd choice of word. The host implementation
> defines, or even imposes the signature algorithm, as well as the level
> of PAuth support (PAuth, EPAC, PAuth2, FPAC, FPACCOMBINE, ...), some
> of which are mutually exclusive (EPAC and PAuth2 are incompatible).
> 
> Maybe it would be worth capturing some of these details, as this has a
> direct influence on the ability to migrate a VM.

Yeah, I thought about it but I was not sure if it's the right place.  As
you point out, there's a live-migration impact depending on the level of
PAuth support, so mentioning these details will be useful.

I'll come up with something for v2.  Thanks for looking!

-- 
/kashyap

On Mon, 20 Jan 2025 at 09:06, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> On Sat, Jan 18, 2025 at 10:04:37AM +0000, Marc Zyngier wrote:
> > On Fri, 17 Jan 2025 19:11:06 +0000,
> > Kashyap Chamarthy <kchamart@redhat.com> wrote:
> > > +PAuth (Pointer Authentication) is a security feature in software that
> > > +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
> >
> > nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
> > the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
> > feel strongly about this). I feel much strongly about the use of
> > capital letters, but I live in a distant past... ;-)
>
> Sure, I can keep it to just v8.3.
>
> On capitalization, I don't feel strongly about it, I just followed this
> commit[1], which explained that the rebranding changed "ARM" to "Arm":
>
>     6fe6d6c9a95 (docs: Be consistent about capitalization of 'Arm',
>     2020-03-09)
>
> That's why I went with it.  I see you know this by your "distant past"
> remark :)  To match the above, I'll keep the capitalization to "Arm".

We should probably do another fix-capitalization pass on docs/,
because a bunch more "ARM" uses have crept in since 6fe6d6c9a95.
(6fe6d6c9a95's commit message says that architecture names like
"ARMv8" retain all-caps, but I think that was my personal taste
creeping in -- at any rate the current Arm ARM uses "Armv8",
"Armv9", etc. It was right that "ARM926" etc should stay all-caps,
though.)

thanks
-- PMM

On Mon, Jan 27, 2025 at 01:06:44PM +0000, Peter Maydell wrote:
> On Mon, 20 Jan 2025 at 09:06, Kashyap Chamarthy <kchamart@redhat.com> wrote:
> >
> > On Sat, Jan 18, 2025 at 10:04:37AM +0000, Marc Zyngier wrote:
> > > On Fri, 17 Jan 2025 19:11:06 +0000,
> > > Kashyap Chamarthy <kchamart@redhat.com> wrote:
> > > > +PAuth (Pointer Authentication) is a security feature in software that
> > > > +was introduced in Armv8.3-A and Armv9.0-A.  It aims to protect against
> > >
> > > nit: given that ARMv9.0 is congruent to ARMv8.5 and therefore has all
> > > the ARMv8.5 features, mentioning ARMv8.3 should be enough (but I don't
> > > feel strongly about this). I feel much strongly about the use of
> > > capital letters, but I live in a distant past... ;-)
> >
> > Sure, I can keep it to just v8.3.
> >
> > On capitalization, I don't feel strongly about it, I just followed this
> > commit[1], which explained that the rebranding changed "ARM" to "Arm":
> >
> >     6fe6d6c9a95 (docs: Be consistent about capitalization of 'Arm',
> >     2020-03-09)
> >
> > That's why I went with it.  I see you know this by your "distant past"
> > remark :)  To match the above, I'll keep the capitalization to "Arm".
> 
> We should probably do another fix-capitalization pass on docs/,
> because a bunch more "ARM" uses have crept in since 6fe6d6c9a95.

I can tack it to v2 of this.  I see about 22 occurrences in docs/:

    $> git grep "ARM " | wc -l
    22

> (6fe6d6c9a95's commit message says that architecture names like
> "ARMv8" retain all-caps, but I think that was my personal taste
> creeping in -- at any rate the current Arm ARM uses "Armv8",
> "Armv9", etc. It was right that "ARM926" etc should stay all-caps,
> though.)

Okay, so, architecture names should stick to "Armv8", etc.  (I too
would have preferred "ARMv8", but whatever the branding says.)

For all-caps: I assume you mean these should remain as-is: ARM926EJ-S,
ARM1176JZS, ARM1176, etc.

-- 
/kashyap

On Mon, 27 Jan 2025 at 13:35, Kashyap Chamarthy <kchamart@redhat.com> wrote:
>
> On Mon, Jan 27, 2025 at 01:06:44PM +0000, Peter Maydell wrote:
> > We should probably do another fix-capitalization pass on docs/,
> > because a bunch more "ARM" uses have crept in since 6fe6d6c9a95.
>
> I can tack it to v2 of this.  I see about 22 occurrences in docs/:
>
>     $> git grep "ARM " | wc -l
>     22
>
> > (6fe6d6c9a95's commit message says that architecture names like
> > "ARMv8" retain all-caps, but I think that was my personal taste
> > creeping in -- at any rate the current Arm ARM uses "Armv8",
> > "Armv9", etc. It was right that "ARM926" etc should stay all-caps,
> > though.)
>
> Okay, so, architecture names should stick to "Armv8", etc.  (I too
> would have preferred "ARMv8", but whatever the branding says.)
>
> For all-caps: I assume you mean these should remain as-is: ARM926EJ-S,
> ARM1176JZS, ARM1176, etc.

Yes.

(We also have two instances of "ARM64" which isn't an Arm
official term at all and should maybe be "AArch64". If we
leave it as-is, I have no idea what capitalization to use
for it.)

thanks
-- PMM