[IR] Define @llvm.ptrauth intrinsics.

[ab]

Summary

This defines the core @llvm.ptrauth. intrinsics: sign, auth, strip, blend, sign_generic. This also adds a docs/PointerAuth.md which goes into more detail; let me know if anything needs clarifying.

Most of the intrinsics are straightforward to define, except for blend which can be defined and implemented in various ways. To follow are straightforward codegen patches for sign, sign_generic, strip, and blend. auth and resign have a lot more complexity to them.

There are a couple open items for the long-term future. One would be to switch these to opaque pointer types instead of i64 (though i64 is really more accurate, and would hypothetically allow specialized usage on LP32 platforms, for instance).
Also, adding some more specific intrinsics might be useful for further hardening (e.g., an add-and-resign, or a way to check whether a pointer is correctly signed, without running into the llvm.ptrauth.auth UB and traps).
Finally, there are various cases where we need to treat an entire blend + sign/auth/resign sequence as a single operation, so we might want to embed the blend in all intrinsics (concretely, replacing the single i64 discriminators that the intrinsics take with a pair of i32 discriminator and i64 address discriminator - we already need to do that for the constants we use to express relocations).

For a high-level overview, see our llvm-dev RFC: http://lists.llvm.org/pipermail/llvm-dev/2019-October/136091.html, as well as the devmtg talk we did at the same time last year.
For concrete code that builds on this, see last year's staging PR in apple/llvm-project: https://github.com/apple/llvm-project/pull/14 (in particular, the higher level C/C++/Obj-C ABI usage is documented in the clang docs there). Though we've made changes downstream since then, the general concepts and added constructs are mostly identical.

[danielkiss]

llvm/docs/PointerAuth.md

84

I'd call this parameter discriminator, for me it would more intuitive than "extra data".
e.g. llvm.ptrauth.blend takes two discriminators and returns a new one that should go here.

also later we say:

// Sign an unauthenticated pointer using the specified key and discriminator,
// passed in that order.

Architecture call's it modifier because it kind a modifies the key.

[kristof.beyls]

llvm/docs/PointerAuth.md

6–9

This is a long sentence, making it somewhat hard to parse/follow. Would it help to split it into shorter sentences? Maybe something like:

Pointer Authentication is a mechanism by which certain pointers are signed.
When a pointer gets signed, a cryptographic hash of its value and other values (pepper and salt) is stored in unused bits of that pointer.
Each time before the pointer is used, it is authenticated, i.e. has its signature checked.
This prevents pointer values of unknown origin from being injected into a process.

11–13

This sentence seems to be describing a specific ABI's choice of how which pointers to sign.
At the moment, my understanding is that there are 2 ABIs making use of the pointer authentication feature in the instruction set to sign/authenticate pointers:

1. The -mbranch-protection=pac-ret scheme which only signs return addresses.
2. The arm64e scheme which, IIUC, signs as described by the sentence above.

I think it may be better to make it more explicit that the above paragraph describes the arm64e abi specifically. Alternatively, maybe a more generic description could be given. Maybe something like the following?

Different ABIs or software targets may require a different set of pointers to be signed in specific ways. For example, -mbranch-protection=pac-ret signs return addresses only. The arm64e ABI signs most code pointers, such as function pointers and vtable entries. Furthermore, it also signs certain data pointers such as vtable pointers.
The ABI-prescribed signing of these pointers is generated automatically by the compiler.

This then naturally flows to the following paragraph which starts with "Additionally, with clang extensions, users can specify that a given pointer be signed/authenticated".

18–20

Maybe it reads a bit more naturally to make this a single sentence, since the bullet list is only 1 long? For example:

At the IR level, pointer signing and authentication is represented using a [set of intrinsics](#intrinsics)

54–59

Would it be helpful to refer to the key as being a cryptographic pepper (https://en.wikipedia.org/wiki/Pepper_(cryptography) ), since the discriminator is referred to as "salt"?

58

maybe say "pointer value" rather than "value" to remove potential ambiguity versus key value?

84

I wonder if it'd be better to call this keyid rather than key, since it is not the value of the key, but rather the id of the key that is passed?

84

I also wonder if it would be beneficial to make the name "value" more specific.
For example, here, this could be called "rawpointer"? Where a signed pointer is expected, instead of "value", "signedpointer" could be used? I think that would make the intrinsic a little bit more self-documenting.
Of course, this is bike shedding territory...

84

I agree with @danielkiss that I'd prefer a better name than "extra data". I think that yet another option that might work would be "salt", as the term cryptographic salt is already used above to explain the high-level semantics of these intrinsics.

136

I'm not entirely sure if we'd like to say behavior is undefined when the signature isn't valid.
If the "undefined" here means the same as "undefined behavior" in C/C++, wouldn't that allow the compiler to assume that it could never happen that the signature isn't valid, and e.g. optimize away signature checks based on that.
I assume that kind of behavior may be mostly theoretical at the moment, but it probably would be better to not enable elimination of signature checks by the compiler, even if only theoretical.
That being said, I'm not sure what the correct description should be for the behavior. For now, I can't come up with anything better than:

If ``value`` does not have a correct signature for ``key`` and ``extra data``,
the behavior is a target-specific side effect.

208

It seems counter-intuitive to me that resign would return an invalid poison pointer on invalid signature, whereas llvm.ptrauth.auth triggers undefined behaviour on invalid signature on the input signed pointer.
Wouldn't it be better to make the behavior consistent for both intrinsics when the signature of the signed pointer is invalid?

[rjmccall]

Before we get too far into editorial review, I think we should step back and ask what actually needs to be in this document. In particular, I'm not sure that the discussion of how pointer authentication can be used in an ABI is really appropriate for LLVM-level documentation. We should discuss the formal model we want the intrinsics/constant to provide — secret key registers, well-formed pointers, arbitrary discriminators — and just link to other documentation (e.g. the much longer white paper in the clang docs) for the benefit of people who are curious about how this can be used.

llvm/docs/PointerAuth.md

54–59

I think that's the best mapping onto the conventional terms, yeah. The correct constant/address discriminator for a particular signing purpose is publicly known, but it's supposed to be as different as possible for different purposes; that's basically a salt. The signing key is the same for all signatures (ignoring the different key registers), but it's secret and different for different "sites" (devices); that's basically a pepper. The nature of the problem is a little different, but it's close enough.

[kristof.beyls]

In D90868#2613237, @rjmccall wrote:

Before we get too far into editorial review, I think we should step back and ask what actually needs to be in this document. In particular, I'm not sure that the discussion of how pointer authentication can be used in an ABI is really appropriate for LLVM-level documentation. We should discuss the formal model we want the intrinsics/constant to provide — secret key registers, well-formed pointers, arbitrary discriminators — and just link to other documentation (e.g. the much longer white paper in the clang docs) for the benefit of people who are curious about how this can be used.

Good point, that makes sense to me. After a quick glance it seems there are only 2 short paragraphs that maybe need to be removed (or be replaced with pointers to the other documentation).

[ab]

Rewrote a good chunk of the document following reviews, responded inline to some. Thanks all for the comments!

One question: I realized this mentions the hardening constraints in a few isolated spots. Should we have a paragraph (say in "Concepts") that describes this upfront? Could be summed up as "intermediate values shouldn't be exposed", and the concrete ramifications of that for the IR design and backend impl.

llvm/docs/PointerAuth.md

18–20

Ah right, this looks weird because the list only includes the intrinsics that are defined here. The later patches add the other IR constructs (attributes, bundle, ...), each with another list item here

84

This all makes sense to me, I've removed most of the non-helpful distinctions between "extra data", "diversity" and "discriminator", to consistently use "discriminator".

I agree value is not super clear, I tried to be more specific in the argument descriptions (using "raw pointer" and "signed pointer"). I'm trying really hard to avoid "unsigned", but "signed" might be fine ;)

I've used "unauthenticated" interchangeably with "raw" before (to make it explicitly about ptrauth), but I think it's better to limit that to operations that don't authenticate (e.g., in the ptrauth_sign_unauthenticated clang builtin, as opposed to ptrauth_auth_and_resign)

105

Note that this is also described as "undefined", as in, "we assume it never happens", but I welcome any improvements to the wording.
However, this is less interesting than auth/resign, since there isn't much room for sensible behavior when signing an already-signed pointer, so we may not need to be very specific.

136

That's an interesting question. Since this was written, we've converged to making it a hard requirement for auth/resign operations to trap. In our implementation, there's currently still an escape hatch (via cl::opt and attribute) to disable that, but we're planning to get rid of that. Whether we want that upstream or not is an open question (really for all of you): it can helps with bringup, but with FPAC maybe we're better off always forcing the pre-FPAC codegen to have the SW check/trap.

Regarding:

If the "undefined" here means the same as "undefined behavior" in C/C++, wouldn't that allow the compiler to assume that it could never happen that the signature isn't valid, and e.g. optimize away signature checks based on that.

yes, it does allow that, and our implementation does optimize away auth/resigns with unused results.
Which brings up an interesting point: since we trap in the auth intrinsic itself, using it to check the signature is at best unergonomic (you'd have to do catch the trap somehow). So, for cases where the intention is only to check the signature of a pointer without using it, we've been using a different pattern: strip the original pointer, sign it with the expected scheme, and compare that with the original pointer. That's a little obscure (and has some hardening ramifications), so we've considered adding an intrinsic that does that. But it hasn't been a common pattern.

So, concretely, I'd be in favor of explicitly defining this (and resign) as trapping. "target-specific side effect" sounds reasonable and avoids over-specifying it as well, though I don't have a specific worry in mind with describing the trap.

169

Reading this again I think this "undefined" is less justifiable than the auth/resign ones. I'm expanding this a bit to explain the actual constraint, and describe this as target-specific. Depending on how exactly we define "target" this could be more than that, since it's dependent on the runtime OS setup. But I'm not sure that's helpful here.

208

It's indeed consistent, the doc is wrong ;) I will update the resign paragraph to match whatever we settle on for auth

[rjmccall]

llvm/docs/PointerAuth.md

136

I think it would be good to reserve the right to not trap if the result is unused, but otherwise, yes, I agree that this should not have undefined behavior on invalidly-signed inputs.

[ab]

Rebase; describe auth/resign as side-effect-free (matching IntrNoMem) and mention they can be eliminated.

[ab]

Thanks all so far! Any other suggestions or comments?

llvm/docs/PointerAuth.md

136

I mentioned that they are still defined to be side-effect-free (matching their IntrNoMem definition in Intrinsics.td) and can be eliminated. How does that sound?

[rjmccall]

llvm/docs/PointerAuth.md

136

SGTM

[pbarrio]

llvm/docs/PointerAuth.md

17–19

Since at least part of the implementation is independent of the architecture, would it make sense to reword to something like: "The initial/current/original implementation leverages the [ARMv8.3 Pointer Authentication Code](#armv8-3-pointer-authentication-code)
instructions on the [AArch64 back-end](#aarch64-support), and follows the rules defined in the Darwin arm64e ABI". As it stands now, it gave me the impression that it is bespoke work for AArch64 and arm64e, when in fact it is actually quite independent and extensible to other architectures and ABIs (which is great BTW).

Also ok to leave it as-is, and only change it once support for other ABIs (or architectures) appears.

22

Maybe I'm jumping a bit ahead of myself here.

I was reading the fully-patched toolchain (e.g. here: https://github.com/pcc/llvm-project/tree/apple-pac3) and I noticed most of these concepts are explained in clang/docs/PointerAuthentication.rst in more detail. Should we have them only in one place and reference the other document? I really like how the Clang document explains the high-level workings of PAuth, and this document seems more focused on the internal implementation in LLVM. Ofc you may have other plans for the two-document split :)

For example, we could just point out the correspondence with the other document in the next section:

## LLVM IR Representation

### Intrinsics

The intrinsics implement the three fundamental operations in PAuth (sign, auth, and strip), as well as a bundle (resign), a generic data signing and an operation to help generate different types of discriminators (blend). For more information on PAuth operations, check out <link to Clang document Section "Basic concepts">.  Also, <link to Clang document Section "Discriminators"> explains discriminators in detail.

Or something like that.

I would expect anyone interested in this document to have read the other document first, or at least similar Arm documents, so they should already be familiar with how PAuth works.

288

Nit: replace ARMv8.3 by Armv8.3-A to follow Arm's trademark guidelines: https://www.arm.com/company/policies/trademarks/arm-trademark-list/arm-trademark. There are a few more occurrences of this in the patch.

[pbarrio]

llvm/docs/PointerAuth.md

281–282

What does target implementation mean here? is it the target triple combination? I assume something like this but then the next paragraph says "AArch64 is currently the only target...". Maybe worth defining what we mean by target, or replace the next paragraph's "target" by "architecture".

[ab]

Rebased; updated docs following Pablo's comments.

[ab]

llvm/docs/PointerAuth.md

22

Yep, the clang page comes after, but I added a link here in the later commit that introduces it.

[apazos]

Ahmed, thanks for rebasing this patch.
Shouldn't we add a reference for the AArch64 PAuth ELF ABI document: https://github.com/ARM-software/abi-aa/tree/main/pauthabielf64
I only see reference to Darwin arm64e ABI documentation.

[apazos]

Also, did we agree on a common prefix for pointer authentication?
I see 'ptrauth' in this patch, and in Apple's arm64e ABI for pointer authentication.
But AArch64 Pointer Authentication ABI extension to ELF refers to 'pauth'.
It will be less confusing to use the same acronym.

[apazos]

Can you highlight clearer what might be specific to Apple in these intrinsics declarations?
I mean, if we want to support the intrinsics for aarch64, now that we have the AArch64 Pointer Authentication ABI extension to ELF document, we should be able to reuse the intrinsics as they are defined now.

[rjmccall]

Well, we've been using ptrauth as a keyword/prefix/etc. to write software at Apple for more than four years, and we have tens of thousands of lines of code using that scattered across several dozen projects, which is probably at least half of the pointer authentication code in the world. I did specifically reach out to the ARM ELF group in the early days of that effort asking that they standardize on ptrauth instead of introducing yet another abbreviation for the extension, but they'd already made a file with "pauth" in the name, so now for better or worse I think we're stuck with having yet another abbreviation for the extension.

I agree we should link to the ARM ELF PAuth document and explicitly mention the different names. IIRC there's a bit already in the document which talks about the other names like "PAC".

[ab]

Link to ELF PAuth ABI Extension. Refer to ISA extension as "PAuth" (and clarify relationship with "Armv8.3-a" and "Pointer Authentication Code")

[ab]

In D90868#3097845, @apazos wrote:

Shouldn't we add a reference for the AArch64 PAuth ELF ABI document: https://github.com/ARM-software/abi-aa/tree/main/pauthabielf64
I only see reference to Darwin arm64e ABI documentation.

I was thinking documentation about ELF support would be added at the same time as ELF support itself, the same way the paragraph about arm64e asm/mach-o extensions is added in later patches. But arm64e does have a mention here, so this does deserve a mention and a link as well. I'll let you folks add more detailed docs later, if needed.

In D90868#3097884, @apazos wrote:

Can you highlight clearer what might be specific to Apple in these intrinsics declarations?
I mean, if we want to support the intrinsics for aarch64, now that we have the AArch64 Pointer Authentication ABI extension to ELF document, we should be able to reuse the intrinsics as they are defined now.

I think the main bit that doesn't follow from the ISA is the implementation of @llvm.ptrauth.blend. I believe the ELF ABI does the same as arm64e, but there's always the possibility some other platform ends up with a different implementation. Either way, the intrinsic doesn't specify its implementation, so all the intrinsics defined here shouldn't be specific to the Darwin or ELF ABIs.
The concepts of "address"/"integer" "discriminators" (and thus "blend" itself) are also higher-level concepts that don't directly map to the ISA, but seem widely applicable to most usage of pointer authentication.

In D90868#3097864, @apazos wrote:

Also, did we agree on a common prefix for pointer authentication?
I see 'ptrauth' in this patch, and in Apple's arm64e ABI for pointer authentication.
But AArch64 Pointer Authentication ABI extension to ELF refers to 'pauth'.
It will be less confusing to use the same acronym.

Good point, I changed various references to Armv8.3-a/PAC to focus on "PAuth", since that's the current name of the ISA feature. Like John described, I don't think it's realistic to change "ptrauth" for our usage, and I would add that overall it seems okay that we'd have different nomenclature for different things, at the source level and in compilers, vs at lower levels (Darwin's "arm64e" is already quite different; not to mention all of our "System V" or "Itanium")

[ab]

Hey folks! Any more comments?

[apazos]

thanks Ahmed for addressing the comments. LGTM.

[danielkiss]

LGTM, I'm happy with the current state.

[ab]

Thanks all for the reviews! 68854f4e572a

llvm/docs/LangRef.rst

 
 Exception Handling Intrinsics
 -----------------------------
 
 The LLVM exception handling intrinsics (which all start with
 ``llvm.eh.`` prefix), are described in the `LLVM Exception
 Handling <ExceptionHandling.html#format-common-intrinsics>`_ document.
 
+Pointer Authentication Intrinsics
+---------------------------------
+
+The LLVM pointer authentication intrinsics (which all start with
+``llvm.ptrauth.`` prefix), are described in the `Pointer Authentication
+<PointerAuth.html#intrinsics>`_ document.
+
 .. _int_trampoline:
 
 Trampoline Intrinsics
 ---------------------
 
 These intrinsics make it possible to excise one parameter, marked with
 the :ref:`nest <nest>` attribute, from a function. The result is a
 callable function pointer lacking the nest parameter - the caller does

llvm/docs/PointerAuth.md

+# Pointer Authentication
+
+## Introduction
+
+Pointer Authentication is a mechanism by which certain pointers are signed.
+When a pointer gets signed, a cryptographic hash of its value and other values
+(pepper and salt) is stored in unused bits of that pointer.
+
+Before the pointer is used, it needs to be authenticated, i.e., have its
+signature checked.  This prevents pointer values of unknown origin from being
+used to replace the signed pointer value.
+
+At the IR level, it is represented using:
+
+* a [set of intrinsics](#intrinsics) (to sign/authenticate pointers)
+
+It is implemented by the [AArch64 target](#aarch64-support), using the
+[ARMv8.3 Pointer Authentication Code](#armv8-3-pointer-authentication-code)
+instructions, to support the Darwin arm64e ABI.
+
+
+## Concepts
+
+### Operations
+
+Pointer Authentication is based on three fundamental operations:
+
+#### Sign
+* compute a signature for a given raw pointer value using a cryptographic hash
+  function
+* embed the signature within the pointer value
+* return the signed pointer value
+
+#### Auth
+* compute a signature for a given pointer value using a cryptographic hash
+  function
+* check the embedded signature by comparing it against the computed signature
+* remove the embedded signature
+* return the raw pointer value
+
+#### Strip
+* remove the embedded signature from a signed pointer value
+* return the raw pointer value
+
+
+### Diversity
+
+To prevent the substitution of a signed pointer with any other signed
+pointer, the signatures are diversified, using additional inputs:
+
+#### Key
+One of a small, fixed set.
+The key is a secret value used as additional input to the cryptographic hash:
+as such, it's used in a way similar to cryptographic pepper.
+
+The value of the key is not directly accessible.  Instead, it's referenced
+by ptrauth operations using an identifier (represented by a small integer
+constant).
+
+Keys are not necessarily interchangeable, and keys can be specified to be
+incompatible with certain kinds of pointers (e.g., code vs data).
+Which keys are appropriate for a given kind of pointer is defined by the
+target implementation.
+
+#### Discriminator
+A 64-bit value.
+The discriminator is a publicly-known value used as additional input to the
+cryptographic hash: as such, it's used in a way similar to cryptographic salt.
+
+In the special case where the discriminator is the address of the storage
+location of the signed pointer value, the value is said to be
+"address-discriminated".
+Additionally, an arbitrary small integer can be blended into an address
+discriminator to produce a blended address discriminator.
+
+Integer discriminators intended to be blended with address discriminators are
+necessarily constrained in width, to avoid overlap.
+Additionally, object file formats can also impose constraints on the width of
+the discriminator.
+
+## LLVM IR Representation
+
+### Intrinsics
+
+These intrinsics are provided by LLVM to expose pointer authentication
+operations.
+
+
+#### '``llvm.ptrauth.sign``'
+
+##### Syntax:
+
+```llvm
+declare i64 @llvm.ptrauth.sign(i64 <value>, i32 <key>, i64 <discriminator>)
+```
+
+##### Overview:
+
+The '``llvm.ptrauth.sign``' intrinsic signs a raw pointer.
+
+
+##### Arguments:
+
+The ``value`` argument is the raw pointer value to be signed.
+The ``key`` argument is the identifier of the key to be used to generate the
+signed value.
+The ``discriminator`` argument is the additional diversity data to be used as a
+discriminator (an integer, an address, or a blend of the two).
+
+##### Semantics:
+
+The '``llvm.ptrauth.sign``' intrinsic implements the `sign`_ operation.
+It returns a signed value.
+
+If ``value`` is already a signed value, the behavior is undefined.
+
+If ``value`` is not a pointer value for which ``key`` is appropriate, the
+behavior is undefined.
+
+
+#### '``llvm.ptrauth.auth``'
+
+##### Syntax:
+
+```llvm
+declare i64 @llvm.ptrauth.auth(i64 <value>, i32 <key>, i64 <discriminator>)
+```
+
+##### Overview:
+
+The '``llvm.ptrauth.auth``' intrinsic authenticates a signed pointer.
+
+##### Arguments:
+
+The ``value`` argument is the signed pointer value to be authenticated.
+The ``key`` argument is the identifier of the key that was used to generate
+the signed value.
+The ``discriminator`` argument is the additional diversity data to be used as a
+discriminator.
+
+##### Semantics:
+
+The '``llvm.ptrauth.auth``' intrinsic implements the `auth`_ operation.
+It returns a raw pointer value.
+If ``value`` does not have a correct signature for ``key`` and ``discriminator``,
+the intrinsic traps in a target-specific way.  However, the intrinsic is
+considered free of side effects, and may thus be eliminated if the result is
+unused.
+
+
+#### '``llvm.ptrauth.strip``'
+
+##### Syntax:
+
+```llvm
+declare i64 @llvm.ptrauth.strip(i64 <value>, i32 <key>)
+```
+
+##### Overview:
+
+The '``llvm.ptrauth.strip``' intrinsic strips the embedded signature out of a
+possibly-signed pointer.
+
+
+##### Arguments:
+
+The ``value`` argument is the signed pointer value to be stripped.
+The ``key`` argument is the identifier of the key that was used to generate
+the signed value.
+
+##### Semantics:
+
+The '``llvm.ptrauth.strip``' intrinsic implements the `strip`_ operation.
+It returns a raw pointer value.  It does **not** check that the
+signature is valid.
+
+``key`` should identify a key that is appropriate for ``value``, as defined
+by the target-specific [keys](#key)).
+
+If ``value`` is a raw pointer value, it is returned as-is (provided the ``key``
+is appropriate for the pointer).
+
+If ``value`` is not a pointer value for which ``key`` is appropriate, the
+behavior is target-specific.
+
+If ``value`` is a signed pointer value, but ``key`` does not identify the
+same key that was used to generate ``value``, the behavior is
+target-specific.
+
+
+#### '``llvm.ptrauth.resign``'
+
+##### Syntax:
+
+```llvm
+declare i64 @llvm.ptrauth.resign(i64 <value>,
+                                 i32 <old key>, i64 <old discriminator>,
+                                 i32 <new key>, i64 <new discriminator>)
+```
+
+##### Overview:
+
+The '``llvm.ptrauth.resign``' intrinsic re-signs a signed pointer using
+a different key and diversity data.
+
+##### Arguments:
+
+The ``value`` argument is the signed pointer value to be authenticated.
+The ``old key`` argument is the identifier of the key that was used to generate
+the signed value.
+The ``old discriminator`` argument is the additional diversity data to be used
+as a discriminator in the auth operation.
+The ``new key`` argument is the identifier of the key to use to generate the
+resigned value.
+The ``new discriminator`` argument is the additional diversity data to be used
+as a discriminator in the sign operation.
+
+##### Semantics:
+
+The '``llvm.ptrauth.resign``' intrinsic performs a combined `auth`_ and `sign`_
+operation, without exposing the intermediate raw pointer.
+It returns a signed pointer value.
+If ``value`` does not have a correct signature for ``old key`` and
+``old discriminator``, the intrinsic traps in a target-specific way.
+However, the intrinsic is considered free of side effects, and may thus be
+eliminated if the result is unused.
+
+#### '``llvm.ptrauth.sign_generic``'
+
+##### Syntax:
+
+```llvm
+declare i64 @llvm.ptrauth.sign_generic(i64 <value>, i64 <discriminator>)
+```
+
+##### Overview:
+
+The '``llvm.ptrauth.sign_generic``' intrinsic computes a generic signature of
+arbitrary data.
+
+##### Arguments:
+
+The ``value`` argument is the arbitrary data value to be signed.
+The ``discriminator`` argument is the additional diversity data to be used as a
+discriminator.
+
+##### Semantics:
+
+The '``llvm.ptrauth.sign_generic``' intrinsic computes the signature of a given
+combination of value and additional diversity data.
+
+It returns a full signature value (as opposed to a signed pointer value, with
+an embedded partial signature).
+
+As opposed to [``llvm.ptrauth.sign``](#llvm-ptrauth-sign), it does not interpret
+``value`` as a pointer value.  Instead, it is an arbitrary data value.
+
+
+#### '``llvm.ptrauth.blend``'
+
+##### Syntax:
+
+```llvm
+declare i64 @llvm.ptrauth.blend(i64 <address discriminator>, i64 <integer discriminator>)
+```
+
+##### Overview:
+
+The '``llvm.ptrauth.blend``' intrinsic blends a pointer address discriminator
+with a small integer discriminator to produce a new "blended" discriminator.
+
+##### Arguments:
+
+The ``address discriminator`` argument is a pointer value.
+The ``integer discriminator`` argument is a small integer, as specified by the
+target.
+
+##### Semantics:
+
+The '``llvm.ptrauth.blend``' intrinsic combines a small integer discriminator
+with a pointer address discriminator, in a way that is specified by the target
+implementation.
+
+
+## AArch64 Support
+
+AArch64 is currently the only target with full support of the pointer
+authentication primitives, based on ARMv8.3 instructions.
+
+### ARMv8.3 Pointer Authentication Code
+
+ARMv8.3 is an ISA extension that includes Pointer Authentication Code (PAC)
+instructions.
+
+#### Keys
+
+5 keys are supported by ARMv8.3.
+
+Of those, 4 keys are interchangeably usable to specify the key used in IR
+constructs:
+* ``ASIA``/``ASIB`` are instruction keys (encoded as respectively 0 and 1).
+* ``ASDA``/``ASDB`` are data keys (encoded as respectively 2 and 3).
+
+``ASGA`` is a special key that cannot be explicitly specified, and is only ever
+used implicitly, to implement the
+[``llvm.ptrauth.sign_generic``](#llvm-ptrauth-sign-generic) intrinsic.
+
+#### Instructions
+
+The IR [Intrinsics](#intrinsics) described above map onto these
+instructions as such:
+* [``llvm.ptrauth.sign``](#llvm-ptrauth-sign): ``PAC{I,D}{A,B}{Z,SP,}``
+* [``llvm.ptrauth.auth``](#llvm-ptrauth-auth): ``AUT{I,D}{A,B}{Z,SP,}``
+* [``llvm.ptrauth.strip``](#llvm-ptrauth-strip): ``XPAC{I,D}``
+* [``llvm.ptrauth.blend``](#llvm-ptrauth-blend): The semantics of the
+  blend operation are, in effect, specified by the ABI.  arm64e specifies it as
+  a ``MOVK`` into the high 16-bits (thereby also limiting the integer
+  discriminator used in blends to 16 bits only).
+* [``llvm.ptrauth.sign_generic``](#llvm-ptrauth-sign-generic): ``PACGA``
+* [``llvm.ptrauth.resign``](#llvm-ptrauth-resign): ``AUT*+PAC*``.  These are
+  represented as a single pseudo-instruction in the backend to guarantee that
+  the intermediate raw pointer value is not spilled and attackable.

llvm/docs/Reference.rst

.. toctree::
    HowToUseAttributes
    InAlloca
    LangRef
    LibFuzzer
    MarkedUpDisassembly
    MIRLangRef
    OptBisect
    PDB/index
+   PointerAuth
    ScudoHardenedAllocator
    MemTagSanitizer
    Security
    SegmentedStacks
    StackMaps
    SpeculativeLoadHardening
    Statepoints
    SystemLibrary
:doc:`StackMaps`
   LLVM support for mapping instruction addresses to the location of
   values and allowing code to be patched.
 
 :doc:`Coroutines`
   LLVM support for coroutines.
 
 :doc:`YamlIO`
    A reference guide for using LLVM's YAML I/O library.
+
+:doc:`PointerAuth`
+  A description of pointer authentication, its LLVM IR representation, and its
+  support in the backend.

llvm/include/llvm/IR/Intrinsics.td

 
 //===---------- Named shufflevector intrinsics ------===//
 def int_experimental_vector_splice : DefaultAttrsIntrinsic<[llvm_anyvector_ty],
                                                            [LLVMMatchType<0>,
                                                             LLVMMatchType<0>,
                                                             llvm_i32_ty],
                                                            [IntrNoMem, ImmArg<ArgIndex<2>>]>;
 
+
+//===----------------- Pointer Authentication Intrinsics ------------------===//
+//
+
+// Sign an unauthenticated pointer using the specified key and discriminator,
+// passed in that order.
+// Returns the first argument, with some known bits replaced with a signature.
+def int_ptrauth_sign : Intrinsic<[llvm_i64_ty],
+                                 [llvm_i64_ty, llvm_i32_ty, llvm_i64_ty],
+                                 [IntrNoMem, ImmArg<ArgIndex<1>>]>;
+
+// Authenticate a signed pointer, using the specified key and discriminator.
+// Returns the first argument, with the signature bits removed.
+// The signature must be valid.
+def int_ptrauth_auth : Intrinsic<[llvm_i64_ty],
+                                 [llvm_i64_ty, llvm_i32_ty, llvm_i64_ty],
+                                 [IntrNoMem,ImmArg<ArgIndex<1>>]>;
+
+// Authenticate a signed pointer and resign it.
+// The second (key) and third (discriminator) arguments specify the signing
+// schema used for authenticating.
+// The fourth and fifth arguments specify the schema used for signing.
+// The signature must be valid.
+// This is a combined form of @llvm.ptrauth.sign and @llvm.ptrauth.auth, with
+// an additional integrity guarantee on the intermediate value.
+def int_ptrauth_resign : Intrinsic<[llvm_i64_ty],
+                                   [llvm_i64_ty, llvm_i32_ty, llvm_i64_ty,
+                                    llvm_i32_ty, llvm_i64_ty],
+                                   [IntrNoMem, ImmArg<ArgIndex<1>>,
+                                    ImmArg<ArgIndex<3>>]>;
+
+// Strip the embedded signature out of a signed pointer.
+// The second argument specifies the key.
+// This behaves like @llvm.ptrauth.auth, but doesn't require the signature to
+// be valid.
+def int_ptrauth_strip : Intrinsic<[llvm_i64_ty],
+                                  [llvm_i64_ty, llvm_i32_ty],
+                                  [IntrNoMem, ImmArg<ArgIndex<1>>]>;
+
+// Blend a small integer discriminator with an address discriminator, producing
+// a new discriminator value.
+def int_ptrauth_blend : Intrinsic<[llvm_i64_ty],
+                                  [llvm_i64_ty, llvm_i64_ty],
+                                  [IntrNoMem]>;
+
+// Compute the signature of a value, using a given discriminator.
+// This differs from @llvm.ptrauth.sign in that it doesn't embed the computed
+// signature in the pointer, but instead returns the signature as a value.
+// That allows it to be used to sign non-pointer data: in that sense, it is
+// generic.  There is no generic @llvm.ptrauth.auth: instead, the signature
+// can be computed using @llvm.ptrauth.sign_generic, and compared with icmp.
+def int_ptrauth_sign_generic : Intrinsic<[llvm_i64_ty],
+                                         [llvm_i64_ty, llvm_i64_ty],
+                                         [IntrNoMem]>;
+
 //===----------------------------------------------------------------------===//
 
 //===----------------------------------------------------------------------===//
 // Target-specific intrinsics
 //===----------------------------------------------------------------------===//
 
 include "llvm/IR/IntrinsicsPowerPC.td"
 include "llvm/IR/IntrinsicsX86.td"