1 /*===---- ptrauth.h - Pointer authentication -------------------------------=== 2 * 3 * Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 * See https://llvm.org/LICENSE.txt for license information. 5 * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 * 7 *===-----------------------------------------------------------------------=== 8 */ 9 10 #ifndef __PTRAUTH_H 11 #define __PTRAUTH_H 12 13 typedef enum { 14 ptrauth_key_asia = 0, 15 ptrauth_key_asib = 1, 16 ptrauth_key_asda = 2, 17 ptrauth_key_asdb = 3, 18 19 /* A process-independent key which can be used to sign code pointers. */ 20 ptrauth_key_process_independent_code = ptrauth_key_asia, 21 22 /* A process-specific key which can be used to sign code pointers. */ 23 ptrauth_key_process_dependent_code = ptrauth_key_asib, 24 25 /* A process-independent key which can be used to sign data pointers. */ 26 ptrauth_key_process_independent_data = ptrauth_key_asda, 27 28 /* A process-specific key which can be used to sign data pointers. */ 29 ptrauth_key_process_dependent_data = ptrauth_key_asdb, 30 31 /* The key used to sign return addresses on the stack. 32 The extra data is based on the storage address of the return address. 33 On AArch64, that is always the storage address of the return address + 8 34 (or, in other words, the value of the stack pointer on function entry) */ 35 ptrauth_key_return_address = ptrauth_key_process_dependent_code, 36 37 /* The key used to sign C function pointers. 38 The extra data is always 0. */ 39 ptrauth_key_function_pointer = ptrauth_key_process_independent_code, 40 41 /* The key used to sign C++ v-table pointers. 42 The extra data is always 0. */ 43 ptrauth_key_cxx_vtable_pointer = ptrauth_key_process_independent_data, 44 45 /* Other pointers signed under the ABI use private ABI rules. */ 46 47 } ptrauth_key; 48 49 /* An integer type of the appropriate size for a discriminator argument. */ 50 typedef __UINTPTR_TYPE__ ptrauth_extra_data_t; 51 52 /* An integer type of the appropriate size for a generic signature. */ 53 typedef __UINTPTR_TYPE__ ptrauth_generic_signature_t; 54 55 /* A signed pointer value embeds the original pointer together with 56 a signature that attests to the validity of that pointer. Because 57 this signature must use only "spare" bits of the pointer, a 58 signature's validity is probabilistic in practice: it is unlikely 59 but still plausible that an invalidly-derived signature will 60 somehow equal the correct signature and therefore successfully 61 authenticate. Nonetheless, this scheme provides a strong degree 62 of protection against certain kinds of attacks. */ 63 64 /* Authenticating a pointer that was not signed with the given key 65 and extra-data value will (likely) fail by trapping. */ 66 67 /* The null function pointer is always the all-zero bit pattern. 68 Signing an all-zero bit pattern will embed a (likely) non-zero 69 signature in the result, and so the result will not seem to be 70 a null function pointer. Authenticating this value will yield 71 a null function pointer back. However, authenticating an 72 all-zero bit pattern will probably fail, because the 73 authentication will expect a (likely) non-zero signature to 74 embedded in the value. 75 76 Because of this, if a pointer may validly be null, you should 77 check for null before attempting to authenticate it with one 78 of these intrinsics. This is not necessary when using the 79 __ptrauth qualifier; the compiler will perform this check 80 automatically. */ 81 82 #if __has_feature(ptrauth_intrinsics) 83 84 /* Strip the signature from a value without authenticating it. 85 86 If the value is a function pointer, the result will not be a 87 legal function pointer because of the missing signature, and 88 attempting to call it will result in an authentication failure. 89 90 The value must be an expression of pointer type. 91 The key must be a constant expression of type ptrauth_key. 92 The result will have the same type as the original value. */ 93 #define ptrauth_strip(__value, __key) __builtin_ptrauth_strip(__value, __key) 94 95 /* Blend a constant discriminator into the given pointer-like value 96 to form a new discriminator. Not all bits of the inputs are 97 guaranteed to contribute to the result. 98 99 On arm64e, the integer must fall within the range of a uint16_t; 100 other bits may be ignored. 101 102 For the purposes of ptrauth_sign_constant, the result of calling 103 this function is considered a constant expression if the arguments 104 are constant. Some restrictions may be imposed on the pointer. 105 106 The first argument must be an expression of pointer type. 107 The second argument must be an expression of integer type. 108 The result will have type uintptr_t. */ 109 #define ptrauth_blend_discriminator(__pointer, __integer) \ 110 __builtin_ptrauth_blend_discriminator(__pointer, __integer) 111 112 /* Return a signed pointer for a constant address in a manner which guarantees 113 a non-attackable sequence. 114 115 The value must be a constant expression of pointer type which evaluates to 116 a non-null pointer. 117 The key must be a constant expression of type ptrauth_key. 118 The extra data must be a constant expression of pointer or integer type; 119 if an integer, it will be coerced to ptrauth_extra_data_t. 120 The result will have the same type as the original value. 121 122 This can be used in constant expressions. */ 123 #define ptrauth_sign_constant(__value, __key, __data) \ 124 __builtin_ptrauth_sign_constant(__value, __key, __data) 125 126 /* Add a signature to the given pointer value using a specific key, 127 using the given extra data as a salt to the signing process. 128 129 This operation does not authenticate the original value and is 130 therefore potentially insecure if an attacker could possibly 131 control that value. 132 133 The value must be an expression of pointer type. 134 The key must be a constant expression of type ptrauth_key. 135 The extra data must be an expression of pointer or integer type; 136 if an integer, it will be coerced to ptrauth_extra_data_t. 137 The result will have the same type as the original value. */ 138 #define ptrauth_sign_unauthenticated(__value, __key, __data) \ 139 __builtin_ptrauth_sign_unauthenticated(__value, __key, __data) 140 141 /* Authenticate a pointer using one scheme and resign it using another. 142 143 If the result is subsequently authenticated using the new scheme, that 144 authentication is guaranteed to fail if and only if the initial 145 authentication failed. 146 147 The value must be an expression of pointer type. 148 The key must be a constant expression of type ptrauth_key. 149 The extra data must be an expression of pointer or integer type; 150 if an integer, it will be coerced to ptrauth_extra_data_t. 151 The result will have the same type as the original value. 152 153 This operation is guaranteed to not leave the intermediate value 154 available for attack before it is re-signed. 155 156 Do not pass a null pointer to this function. A null pointer 157 will not successfully authenticate. 158 159 This operation traps if the authentication fails. */ 160 #define ptrauth_auth_and_resign(__value, __old_key, __old_data, __new_key, \ 161 __new_data) \ 162 __builtin_ptrauth_auth_and_resign(__value, __old_key, __old_data, __new_key, \ 163 __new_data) 164 165 /* Authenticate a pointer using one scheme and resign it as a C 166 function pointer. 167 168 If the result is subsequently authenticated using the new scheme, that 169 authentication is guaranteed to fail if and only if the initial 170 authentication failed. 171 172 The value must be an expression of function pointer type. 173 The key must be a constant expression of type ptrauth_key. 174 The extra data must be an expression of pointer or integer type; 175 if an integer, it will be coerced to ptrauth_extra_data_t. 176 The result will have the same type as the original value. 177 178 This operation is guaranteed to not leave the intermediate value 179 available for attack before it is re-signed. Additionally, if this 180 expression is used syntactically as the function expression in a 181 call, only a single authentication will be performed. */ 182 #define ptrauth_auth_function(__value, __old_key, __old_data) \ 183 ptrauth_auth_and_resign(__value, __old_key, __old_data, \ 184 ptrauth_key_function_pointer, 0) 185 186 /* Authenticate a data pointer. 187 188 The value must be an expression of non-function pointer type. 189 The key must be a constant expression of type ptrauth_key. 190 The extra data must be an expression of pointer or integer type; 191 if an integer, it will be coerced to ptrauth_extra_data_t. 192 The result will have the same type as the original value. 193 194 This operation traps if the authentication fails. */ 195 #define ptrauth_auth_data(__value, __old_key, __old_data) \ 196 __builtin_ptrauth_auth(__value, __old_key, __old_data) 197 198 /* Compute a constant discriminator from the given string. 199 200 The argument must be a string literal of char character type. The result 201 has type ptrauth_extra_data_t. 202 203 The result value is never zero and always within range for both the 204 __ptrauth qualifier and ptrauth_blend_discriminator. 205 206 This can be used in constant expressions. 207 */ 208 #define ptrauth_string_discriminator(__string) \ 209 __builtin_ptrauth_string_discriminator(__string) 210 211 /* Compute a constant discriminator from the given type. 212 213 The result can be used as the second argument to 214 ptrauth_blend_discriminator or the third argument to the 215 __ptrauth qualifier. It has type size_t. 216 217 If the type is a C++ member function pointer type, the result is 218 the discriminator used to signed member function pointers of that 219 type. If the type is a function, function pointer, or function 220 reference type, the result is the discriminator used to sign 221 functions of that type. It is ill-formed to use this macro with any 222 other type. 223 224 A call to this function is an integer constant expression. */ 225 #define ptrauth_type_discriminator(__type) \ 226 __builtin_ptrauth_type_discriminator(__type) 227 228 /* Compute a signature for the given pair of pointer-sized values. 229 The order of the arguments is significant. 230 231 Like a pointer signature, the resulting signature depends on 232 private key data and therefore should not be reliably reproducible 233 by attackers. That means that this can be used to validate the 234 integrity of arbitrary data by storing a signature for that data 235 alongside it, then checking that the signature is still valid later. 236 Data which exceeds two pointers in size can be signed by either 237 computing a tree of generic signatures or just signing an ordinary 238 cryptographic hash of the data. 239 240 The result has type ptrauth_generic_signature_t. However, it may 241 not have as many bits of entropy as that type's width would suggest; 242 some implementations are known to compute a compressed signature as 243 if the arguments were a pointer and a discriminator. 244 245 The arguments must be either pointers or integers; if integers, they 246 will be coerce to uintptr_t. */ 247 #define ptrauth_sign_generic_data(__value, __data) \ 248 __builtin_ptrauth_sign_generic_data(__value, __data) 249 250 /* C++ vtable pointer signing class attribute */ 251 #define ptrauth_cxx_vtable_pointer(key, address_discrimination, \ 252 extra_discrimination...) \ 253 [[clang::ptrauth_vtable_pointer(key, address_discrimination, \ 254 extra_discrimination)]] 255 256 #else 257 258 #define ptrauth_strip(__value, __key) \ 259 ({ \ 260 (void)__key; \ 261 __value; \ 262 }) 263 264 #define ptrauth_blend_discriminator(__pointer, __integer) \ 265 ({ \ 266 (void)__pointer; \ 267 (void)__integer; \ 268 ((ptrauth_extra_data_t)0); \ 269 }) 270 271 #define ptrauth_sign_constant(__value, __key, __data) \ 272 ({ \ 273 (void)__key; \ 274 (void)__data; \ 275 __value; \ 276 }) 277 278 #define ptrauth_sign_unauthenticated(__value, __key, __data) \ 279 ({ \ 280 (void)__key; \ 281 (void)__data; \ 282 __value; \ 283 }) 284 285 #define ptrauth_auth_and_resign(__value, __old_key, __old_data, __new_key, \ 286 __new_data) \ 287 ({ \ 288 (void)__old_key; \ 289 (void)__old_data; \ 290 (void)__new_key; \ 291 (void)__new_data; \ 292 __value; \ 293 }) 294 295 #define ptrauth_auth_function(__value, __old_key, __old_data) \ 296 ({ \ 297 (void)__old_key; \ 298 (void)__old_data; \ 299 __value; \ 300 }) 301 302 #define ptrauth_auth_data(__value, __old_key, __old_data) \ 303 ({ \ 304 (void)__old_key; \ 305 (void)__old_data; \ 306 __value; \ 307 }) 308 309 #define ptrauth_string_discriminator(__string) \ 310 ({ \ 311 (void)__string; \ 312 ((ptrauth_extra_data_t)0); \ 313 }) 314 315 #define ptrauth_type_discriminator(__type) ((ptrauth_extra_data_t)0) 316 317 #define ptrauth_sign_generic_data(__value, __data) \ 318 ({ \ 319 (void)__value; \ 320 (void)__data; \ 321 ((ptrauth_generic_signature_t)0); \ 322 }) 323 324 325 #define ptrauth_cxx_vtable_pointer(key, address_discrimination, \ 326 extra_discrimination...) 327 328 #endif /* __has_feature(ptrauth_intrinsics) */ 329 330 #endif /* __PTRAUTH_H */ 331