OSX/sec/securityd/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
  33 __BEGIN_DECLS
  34
  35 // Opaque type that holds the data for a specific version of the OTA PKI assets
  36 typedef struct _OpaqueSecOTAPKI *SecOTAPKIRef;
  37
  38 // Returns a boolean for whether the current instance is the system trustd
  39 bool SecOTAPKIIsSystemTrustd(void);
  40
  41 // Get a reference to the current OTA PKI asset data
  42 // Caller is responsible for releasing the returned SecOTAPKIRef
  43 CF_EXPORT
  44 SecOTAPKIRef SecOTAPKICopyCurrentOTAPKIRef(void);
  45
  46 // Accessor to retrieve a copy of the current black listed key.
  47 // Caller is responsible for releasing the returned CFSetRef
  48 CF_EXPORT
  49 CFSetRef SecOTAPKICopyBlackListSet(SecOTAPKIRef otapkiRef);
  50
  51 // Accessor to retrieve a copy of the current gray listed key.
  52 // Caller is responsible for releasing the returned CFSetRef
  53 CF_EXPORT
  54 CFSetRef SecOTAPKICopyGrayList(SecOTAPKIRef otapkiRef);
  55
  56 // Accessor to retrieve a copy of the current allow list dictionary.
  57 // Caller is responsible for releasing the returned CFDictionaryRef
  58 CF_EXPORT
  59 CFDictionaryRef SecOTAPKICopyAllowList(SecOTAPKIRef otapkiRef);
  60
  61 // Accessor to retrieve a copy of the allow list for a specific authority key ID.
  62 // Caller is responsible for releasing the returned CFArrayRef
  63 CF_EXPORT
  64 CFArrayRef SecOTAPKICopyAllowListForAuthKeyID(SecOTAPKIRef otapkiRef, CFStringRef authKeyID);
  65
  66 // Accessor to retrieve a copy of the current trusted certificate transparency logs.
  67 // Caller is responsible for releasing the returned CFArrayRef
  68 CF_EXPORT
  69 CFArrayRef SecOTAPKICopyTrustedCTLogs(SecOTAPKIRef otapkiRef);
  70
  71 // Accessor to retrieve the path of the current pinning list.
  72 // Caller is responsible for releasing the returned CFURLRef
  73 CF_EXPORT
  74 CFURLRef SecOTAPKICopyPinningList(SecOTAPKIRef otapkiRef);
  75
  76 // Accessor to retrieve the array of Escrow certificates.
  77 // Caller is responsible for releasing the returned CFArrayRef
  78 CF_EXPORT
  79 CFArrayRef SecOTAPKICopyEscrowCertificates(uint32_t escrowRootType, SecOTAPKIRef otapkiRef);
  80
  81 // Accessor to retrieve the dictionary of EV Policy OIDs to Anchor digest.
  82 // Caller is responsible for releasing the returned CFDictionaryRef
  83 CF_EXPORT
  84 CFDictionaryRef SecOTAPKICopyEVPolicyToAnchorMapping(SecOTAPKIRef otapkiRef);
  85
  86 // Accessor to retrieve the dictionary of anchor digest to file offset.
  87 // Caller is responsible for releasing the returned CFDictionaryRef
  88 CF_EXPORT
  89 CFDictionaryRef SecOTAPKICopyAnchorLookupTable(SecOTAPKIRef otapkiRef);
  90
  91 // Accessor to retrieve the pointer to the top of the anchor certs file.
  92 // Caller should NOT free the returned pointer.  The caller should hold
  93 // a reference to the SecOTAPKIRef object until finished with
  94 // the returned pointer.
  95 CF_EXPORT
  96 const char* SecOTAPKIGetAnchorTable(SecOTAPKIRef otapkiRef);
  97
  98 // Accessor to retrieve the full path to the valid update snapshot resource.
  99 // The return value may be NULL if the resource does not exist.
 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* SecOTAPKIGetValidUpdateSnapshot(SecOTAPKIRef otapkiRef);
 105
 106 // Accessor to retrieve the full path to the valid database 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* SecOTAPKIGetValidDatabaseSnapshot(SecOTAPKIRef otapkiRef);
 113
 114 // Accessor to retrieve the current valid snapshot version.
 115 CF_EXPORT
 116 CFIndex SecOTAPKIGetValidSnapshotVersion(SecOTAPKIRef otapkiRef);
 117
 118 // Accessor to retrieve the current valid snapshot format.
 119 CF_EXPORT
 120 CFIndex SecOTAPKIGetValidSnapshotFormat(SecOTAPKIRef otapkiRef);
 121
 122 // Accessor to retrieve the OTAPKI trust store version
 123 // Note: Trust store is not mutable by assets
 124 CF_EXPORT
 125 uint64_t SecOTAPKIGetTrustStoreVersion(SecOTAPKIRef otapkiRef);
 126
 127 // Accessor to retrieve the OTAPKI asset version
 128 CF_EXPORT
 129 uint64_t SecOTAPKIGetAssetVersion(SecOTAPKIRef otapkiRef);
 130
 131 // Accessors to retrieve the last check in time for the OTAPKI asset
 132 CF_EXPORT
 133 CFDateRef SecOTAPKICopyLastAssetCheckInDate(SecOTAPKIRef otapkiRef);
 134
 135 #define kSecOTAPKIAssetStalenessAtRisk (60*60*24*30) // 30 days
 136 #define kSecOTAPKIAssetStalenessWarning (60*60*24*45) // 45 days
 137 #define kSecOTAPKIAssetStalenessDisable (60*60*24*60) // 60 days
 138 bool SecOTAPKIAssetStalenessLessThanSeconds(SecOTAPKIRef otapkiRef, CFTimeInterval seconds);
 139
 140 #if __OBJC__
 141 // SPI to return the current sampling rate for the event name
 142 // This rate is actually n where we sample 1 out of every n
 143 NSNumber *SecOTAPKIGetSamplingRateForEvent(SecOTAPKIRef otapkiRef, NSString *eventName);
 144 #endif // __OBJC__
 145
 146 CFArrayRef SecOTAPKICopyAppleCertificateAuthorities(SecOTAPKIRef otapkiRef);
 147
 148 // SPI to return the array of currently trusted Escrow certificates
 149 CF_EXPORT
 150 CFArrayRef SecOTAPKICopyCurrentEscrowCertificates(uint32_t escrowRootType, CFErrorRef* error);
 151
 152 // SPI to return the current OTA PKI trust store version
 153 // Note: Trust store is not mutable by assets
 154 CF_EXPORT
 155 uint64_t SecOTAPKIGetCurrentTrustStoreVersion(CFErrorRef* CF_RETURNS_RETAINED  error);
 156
 157 // SPI to return the current OTA PKI asset version
 158 CF_EXPORT
 159 uint64_t SecOTAPKIGetCurrentAssetVersion(CFErrorRef* error);
 160
 161 // SPI to reset the current OTA PKI asset version to the version shipped
 162 // with the system
 163 CF_EXPORT
 164 uint64_t SecOTAPKIResetCurrentAssetVersion(CFErrorRef* CF_RETURNS_RETAINED  error);
 165
 166 // SPI to signal trustd to get a new set of trust data
 167 // Always returns the current asset version. Returns an error with
 168 // a reason if the update was not successful.
 169 CF_EXPORT
 170 uint64_t SecOTAPKISignalNewAsset(CFErrorRef* CF_RETURNS_RETAINED error);
 171
 172 __END_DECLS
 173
 174 #endif /* _OTATRUSTUTILITIES_H_ */