trust/trustd/OTATrustUtilities.h

   1 /*
   2  * Copyright (c) 2003-2018 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_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. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  *
  23  * OTATrustUtilities.h
  24  */
  25
  26 #ifndef _OTATRUSTUTILITIES_H_
  27 #define _OTATRUSTUTILITIES_H_  1
  28
  29 #include <CoreFoundation/CoreFoundation.h>
  30 #include <sys/types.h>
  31 #include <stdio.h>
  32 #include <dispatch/dispatch.h>
  33
  34 __BEGIN_DECLS
  35
  36 // Opaque type that holds the data for a specific version of the OTA PKI assets
  37 typedef struct _OpaqueSecOTAPKI *SecOTAPKIRef;
  38
  39 // Returns a boolean for whether the current instance is the system trustd
  40 bool SecOTAPKIIsSystemTrustd(void);
  41
  42 // Returns the trust server workloop
  43 dispatch_queue_t SecTrustServerGetWorkloop(void);
  44
  45 // Convert a trusted CT log array to a trusted CT log dictionary, indexed by the LogID
  46 CF_RETURNS_RETAINED
  47 CFDictionaryRef SecOTAPKICreateTrustedCTLogsDictionaryFromArray(CFArrayRef trustedCTLogsArray);
  48
  49 // Get a reference to the current OTA PKI asset data
  50 // Caller is responsible for releasing the returned SecOTAPKIRef
  51 CF_EXPORT CF_RETURNS_RETAINED
  52 SecOTAPKIRef SecOTAPKICopyCurrentOTAPKIRef(void);
  53
  54 // Accessor to retrieve a copy of the current black listed key.
  55 // Caller is responsible for releasing the returned CFSetRef
  56 CF_EXPORT
  57 CFSetRef SecOTAPKICopyBlackListSet(SecOTAPKIRef otapkiRef);
  58
  59 // Accessor to retrieve a copy of the current gray listed key.
  60 // Caller is responsible for releasing the returned CFSetRef
  61 CF_EXPORT
  62 CFSetRef SecOTAPKICopyGrayList(SecOTAPKIRef otapkiRef);
  63
  64 // Accessor to retrieve a copy of the current allow list dictionary.
  65 // Caller is responsible for releasing the returned CFDictionaryRef
  66 CF_EXPORT
  67 CFDictionaryRef SecOTAPKICopyAllowList(SecOTAPKIRef otapkiRef);
  68
  69 // Accessor to retrieve a copy of the allow list for a specific authority key ID.
  70 // Caller is responsible for releasing the returned CFArrayRef
  71 CF_EXPORT
  72 CFArrayRef SecOTAPKICopyAllowListForAuthKeyID(SecOTAPKIRef otapkiRef, CFStringRef authKeyID);
  73
  74 // Accessor to retrieve a copy of the current trusted certificate transparency logs.
  75 // Caller is responsible for releasing the returned CFArrayRef
  76 CF_EXPORT
  77 CFDictionaryRef SecOTAPKICopyTrustedCTLogs(SecOTAPKIRef otapkiRef);
  78
  79 // Accessor to retrieve the path of the current pinning list.
  80 // Caller is responsible for releasing the returned CFURLRef
  81 CF_EXPORT
  82 CFURLRef SecOTAPKICopyPinningList(SecOTAPKIRef otapkiRef);
  83
  84 // Accessor to retrieve the array of Escrow certificates.
  85 // Caller is responsible for releasing the returned CFArrayRef
  86 CF_EXPORT
  87 CFArrayRef SecOTAPKICopyEscrowCertificates(uint32_t escrowRootType, SecOTAPKIRef otapkiRef);
  88
  89 // Accessor to retrieve the dictionary of EV Policy OIDs to Anchor digest.
  90 // Caller is responsible for releasing the returned CFDictionaryRef
  91 CF_EXPORT
  92 CFDictionaryRef SecOTAPKICopyEVPolicyToAnchorMapping(SecOTAPKIRef otapkiRef);
  93
  94 // Accessor to retrieve the dictionary of anchor digest to file offset.
  95 // Caller is responsible for releasing the returned CFDictionaryRef
  96 CF_EXPORT
  97 CFDictionaryRef SecOTAPKICopyAnchorLookupTable(SecOTAPKIRef otapkiRef);
  98
  99 // Accessor to retrieve the pointer to the top of the anchor certs file.
 100 // Caller should NOT free the returned pointer.  The caller should hold
 101 // a reference to the SecOTAPKIRef object until finished with
 102 // the returned pointer.
 103 CF_EXPORT
 104 const char* SecOTAPKIGetAnchorTable(SecOTAPKIRef otapkiRef);
 105
 106 // Accessor to retrieve the full path to the valid update snapshot resource.
 107 // The return value may be NULL if the resource does not exist.
 108 // Caller should NOT free the returned pointer.  The caller should hold
 109 // a reference to the SecOTAPKIRef object until finished with
 110 // the returned pointer.
 111 CF_EXPORT
 112 const char* SecOTAPKIGetValidUpdateSnapshot(SecOTAPKIRef otapkiRef);
 113
 114 // Accessor to retrieve the full path to the valid database snapshot resource.
 115 // The return value may be NULL if the resource does not exist.
 116 // Caller should NOT free the returned pointer.  The caller should hold
 117 // a reference to the SecOTAPKIRef object until finished with
 118 // the returned pointer.
 119 CF_EXPORT
 120 const char* SecOTAPKIGetValidDatabaseSnapshot(SecOTAPKIRef otapkiRef);
 121
 122 // Accessor to retrieve the current valid snapshot version.
 123 CF_EXPORT
 124 CFIndex SecOTAPKIGetValidSnapshotVersion(SecOTAPKIRef otapkiRef);
 125
 126 // Accessor to retrieve the current valid snapshot format.
 127 CF_EXPORT
 128 CFIndex SecOTAPKIGetValidSnapshotFormat(SecOTAPKIRef otapkiRef);
 129
 130 // Accessor to retrieve the OTAPKI trust store version
 131 // Note: Trust store is not mutable by assets
 132 CF_EXPORT
 133 uint64_t SecOTAPKIGetTrustStoreVersion(SecOTAPKIRef otapkiRef);
 134
 135 // Accessor to retrieve the OTAPKI asset version
 136 CF_EXPORT
 137 uint64_t SecOTAPKIGetAssetVersion(SecOTAPKIRef otapkiRef);
 138
 139 // Accessors to retrieve the last check in time for the OTAPKI asset
 140 CF_EXPORT
 141 CFDateRef SecOTAPKICopyLastAssetCheckInDate(SecOTAPKIRef otapkiRef);
 142
 143 #define kSecOTAPKIAssetStalenessAtRisk (60*60*24*30) // 30 days
 144 #define kSecOTAPKIAssetStalenessWarning (60*60*24*45) // 45 days
 145 #define kSecOTAPKIAssetStalenessDisable (60*60*24*60) // 60 days
 146 bool SecOTAPKIAssetStalenessLessThanSeconds(SecOTAPKIRef otapkiRef, CFTimeInterval seconds);
 147
 148 #if __OBJC__
 149 // SPI to return the current sampling rate for the event name
 150 // This rate is actually n where we sample 1 out of every n
 151 NSNumber *SecOTAPKIGetSamplingRateForEvent(SecOTAPKIRef otapkiRef, NSString *eventName);
 152 #endif // __OBJC__
 153
 154 CFArrayRef SecOTAPKICopyAppleCertificateAuthorities(SecOTAPKIRef otapkiRef);
 155
 156 extern const CFStringRef kOTAPKIKillSwitchCT;
 157 extern const CFStringRef kOTAPKIKillSwitchNonTLSCT;
 158 bool SecOTAPKIKillSwitchEnabled(SecOTAPKIRef otapkiRef, CFStringRef switchKey);
 159
 160 // SPI to return the array of currently trusted Escrow certificates
 161 CF_EXPORT
 162 CFArrayRef SecOTAPKICopyCurrentEscrowCertificates(uint32_t escrowRootType, CFErrorRef* error);
 163
 164 // SPI to return the array of currently (TLS) trusted CT logs
 165 CF_EXPORT
 166 CFDictionaryRef SecOTAPKICopyCurrentTrustedCTLogs(CFErrorRef* error);
 167
 168 // SPI to return the array of currently non-TLS trusted CT logs
 169 CF_EXPORT
 170 CFDictionaryRef SecOTAPKICopyNonTlsTrustedCTLogs(SecOTAPKIRef otapkiRef);
 171
 172 // SPI to return dictionary of CT log matching specified key id */
 173 CF_EXPORT
 174 CFDictionaryRef SecOTAPKICopyCTLogForKeyID(CFDataRef keyID, CFErrorRef* error);
 175
 176 // SPI to return the current OTA PKI trust store version
 177 // Note: Trust store is not mutable by assets
 178 CF_EXPORT
 179 uint64_t SecOTAPKIGetCurrentTrustStoreVersion(CFErrorRef* CF_RETURNS_RETAINED  error);
 180
 181 // SPI to return the current OTA PKI asset version
 182 CF_EXPORT
 183 uint64_t SecOTAPKIGetCurrentAssetVersion(CFErrorRef* error);
 184
 185 // SPI to return the current OTA SecExperiment asset version
 186 CF_EXPORT
 187 uint64_t SecOTASecExperimentGetCurrentAssetVersion(CFErrorRef* error);
 188
 189 // SPI to reset the current OTA PKI asset version to the version shipped
 190 // with the system
 191 CF_EXPORT
 192 uint64_t SecOTAPKIResetCurrentAssetVersion(CFErrorRef* CF_RETURNS_RETAINED  error);
 193
 194 // SPI to signal trustd to get a new set of trust data
 195 // Always returns the current asset version. Returns an error with
 196 // a reason if the update was not successful.
 197 CF_EXPORT
 198 uint64_t SecOTAPKISignalNewAsset(CFErrorRef* CF_RETURNS_RETAINED error);
 199
 200 // SPI to signal trustd to get a new set of SecExperiment data
 201 // Always returns the current asset version. Returns an error with
 202 // a reason if the update was not successful.
 203 CF_EXPORT
 204 uint64_t SecOTASecExperimentGetNewAsset(CFErrorRef* error);
 205
 206 // SPI to copy current SecExperiment asset data
 207 CF_EXPORT
 208 CFDictionaryRef SecOTASecExperimentCopyAsset(CFErrorRef* error);
 209
 210 /* "Internal" interfaces for tests */
 211 #if !TARGET_OS_BRIDGE && __OBJC__
 212 BOOL UpdateOTACheckInDate(void);
 213 void UpdateKillSwitch(NSString *key, bool value);
 214 #endif
 215
 216 __END_DECLS
 217
 218 #endif /* _OTATRUSTUTILITIES_H_ */