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 | #include <sys/cdefs.h> |
34 | __BEGIN_DECLS |
35 | |
36 | /* ptrauth_utils flags */ |
37 | #define PTRAUTH_ADDR_DIVERSIFY 0x0001 /* Mix storage address in to signature */ |
38 | #define PTRAUTH_NON_NULL 0x0002 /* ptr must not be NULL */ |
39 | |
40 | /* ptrauth_utils_sign_blob_generic |
41 | * |
42 | * Description: Sign a blob of data with the GA key and extra data, optionally |
43 | * diversified by its storage address. |
44 | * |
45 | * WARNING: Lower 32 bits are always zeroes. |
46 | * |
47 | * Caveat: A race window exists between the blob being written to memory and its signature being |
48 | * calculated by this function. In normal operation, standard thread safety semantics prevent this being |
49 | * an issue, however in the malicious case it should be acknowledged that an attacker may be able to accurately |
50 | * time overwriting parts/all of the blob and we would generate a signature for that modified data. It is |
51 | * therefore important that users of this API minimise that window by calculating signatures immediately |
52 | * after modification to the blob. |
53 | * |
54 | * |
55 | * Parameters: ptr Address of data to sign |
56 | * len_bytes Length in bytes of data to sign |
57 | * data Salt to mix in signature when signing |
58 | * flags Signing options |
59 | * |
60 | * Returns: ptrauth_generic_signature_t Signature of blob |
61 | * |
62 | */ |
63 | ptrauth_generic_signature_t |
64 | ptrauth_utils_sign_blob_generic(const void * ptr, size_t len_bytes, uint64_t data, int flags); |
65 | |
66 | |
67 | /* ptrauth_utils_auth_blob_generic |
68 | * |
69 | * Description: Authenticates a signature for a blob of data |
70 | * |
71 | * Caveat: As with ptrauth_utils_sign_blob_generic, an attacker who is able to accurately time access between |
72 | * authenticating blobs and its use may be able to modify its contents. Failure to time this correctly will |
73 | * result in a panic. Care should be taken to authenticate immediately before reading data from the blob to |
74 | * minimise this window. |
75 | * |
76 | * Parameters: ptr Address of data being authenticated |
77 | * len_bytes Length of data being authenticated |
78 | * data Salt to mix with digest when authenticating |
79 | * flags Signing options |
80 | * signature The signature to verify |
81 | * |
82 | * Returns: void If the function returns, the authentication succeeded, |
83 | * else we panic as something's gone awry |
84 | * |
85 | */ |
86 | void |
87 | ptrauth_utils_auth_blob_generic(const void * ptr, size_t len_bytes, uint64_t data, int flags, ptrauth_generic_signature_t signature); |
88 | |
89 | __END_DECLS |
90 | #endif // __PTRAUTH_UTILS_H |
91 | |