libkern/libkern/ptrauth_utils.h

   1 /*
   2  * Copyright (c) 2020 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 #ifndef __PTRAUTH_UTILS_H
  30 #define __PTRAUTH_UTILS_H
  31
  32 #include <ptrauth.h>
  33
  34 /* ptrauth_utils flags */
  35 #define PTRAUTH_ADDR_DIVERSIFY  0x0001  /* Mix storage address in to signature */
  36 #define PTRAUTH_NON_NULL        0x0002  /* ptr must not be NULL */
  37
  38 /* ptrauth_utils_sign_blob_generic
  39  *
  40  * Description: Sign a blob of data with the GA key and extra data, optionally
  41  * diversified by its storage address.
  42  *
  43  * Caveat: A race window exists between the blob being written to memory and its signature being
  44  * calculated by this function. In normal operation, standard thread safety semantics prevent this being
  45  * an issue, however in the malicious case it should be acknowledged that an attacker may be able to accurately
  46  * time overwriting parts/all of the blob and we would generate a signature for that modified data. It is
  47  * therefore important that users of this API minimise that window by calculating signatures immediately
  48  * after modification to the blob.
  49  *
  50  *
  51  * Parameters:  ptr                             Address of data to sign
  52  *                              len_bytes               Length in bytes of data to sign
  53  *                              data                    Salt to mix in signature when signing
  54  *                              flags               Signing options
  55  *
  56  * Returns:             ptrauth_generic_signature_t             Signature of blob
  57  *
  58  */
  59 #if __has_feature(ptrauth_calls)
  60 ptrauth_generic_signature_t
  61 ptrauth_utils_sign_blob_generic(void * ptr, size_t len_bytes, uint64_t data, int flags);
  62 #else
  63 static inline ptrauth_generic_signature_t
  64 ptrauth_utils_sign_blob_generic(__unused void * ptr, __unused size_t len_bytes, __unused uint64_t data, __unused int flags)
  65 {
  66         return 0;
  67 }
  68 #endif // __has_feature(ptrauth_calls)
  69
  70
  71 /* ptrauth_utils_auth_blob_generic
  72  *
  73  * Description: Authenticates a signature for a blob of data
  74  *
  75  * Caveat: As with ptrauth_utils_sign_blob_generic, an attacker who is able to accurately time access between
  76  * authenticating blobs and its use may be able to modify its contents. Failure to time this correctly will
  77  * result in a panic. Care should be taken to authenticate immediately before reading data from the blob to
  78  * minimise this window.
  79  *
  80  * Parameters:  ptr                             Address of data being authenticated
  81  *                              len_bytes               Length of data being authenticated
  82  *                              data                    Salt to mix with digest when authenticating
  83  *                              flags           Signing options
  84  *                              signature               The signature to verify
  85  *
  86  * Returns:             void                    If the function returns, the authentication succeeded,
  87  *                                                              else we panic as something's gone awry
  88  *
  89  */
  90 #if __has_feature(ptrauth_calls)
  91 void
  92 ptrauth_utils_auth_blob_generic(void * ptr, size_t len_bytes, uint64_t data, int flags, ptrauth_generic_signature_t signature);
  93 #else
  94 static inline void
  95 ptrauth_utils_auth_blob_generic(__unused void * ptr, __unused size_t len_bytes, __unused uint64_t data, __unused int flags, __unused ptrauth_generic_signature_t signature)
  96 {
  97         return;
  98 }
  99 #endif // __has_feature(ptrauth_calls)
 100
 101
 102 #endif // __PTRAUTH_UTILS_H