trust/trustd/SecRevocationDb.h

   1 /*
   2  * Copyright (c) 2016-2019 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  */
  24
  25 /*!
  26  @header SecRevocationDb
  27  The functions in SecRevocationDb.h provide an interface to look up
  28  revocation information, and refresh that information periodically.
  29  */
  30
  31 #ifndef _SECURITY_SECREVOCATIONDB_H_
  32 #define _SECURITY_SECREVOCATIONDB_H_
  33
  34 #include <CoreFoundation/CFRuntime.h>
  35 #include <CoreFoundation/CFData.h>
  36 #include <CoreFoundation/CFDate.h>
  37 #include <CoreFoundation/CFDictionary.h>
  38 #include <CoreFoundation/CFString.h>
  39 #include <CoreFoundation/CFError.h>
  40 #include <dispatch/dispatch.h>
  41 #include <Security/SecBase.h>
  42
  43 __BEGIN_DECLS
  44
  45 /* issuer group data format */
  46 typedef CF_ENUM(uint32_t, SecValidInfoFormat) {
  47     kSecValidInfoFormatUnknown      = 0,
  48     kSecValidInfoFormatSerial       = 1,
  49     kSecValidInfoFormatSHA256       = 2,
  50     kSecValidInfoFormatNto1         = 3
  51 };
  52
  53 /* policy types */
  54 typedef CF_ENUM(int8_t, SecValidPolicy) {
  55     kSecValidPolicyNone = -1,
  56     kSecValidPolicyAny = 0,
  57     kSecValidPolicyServerAuthentication = 1,
  58     kSecValidPolicyClientAuthentication = 2,
  59     kSecValidPolicyEmailProtection = 3,
  60     kSecValidPolicyCodeSigning = 4,
  61     kSecValidPolicyTimeStamping = 5,
  62 };
  63
  64 /*!
  65     @typedef SecValidInfoRef
  66     @abstract CFType used to return valid info lookup results.
  67  */
  68 typedef struct __SecValidInfo *SecValidInfoRef;
  69
  70 struct __SecValidInfo {
  71     CFRuntimeBase _base;
  72
  73     SecValidInfoFormat  format;               // format of per-issuer validity data
  74     CFDataRef           certHash;             // SHA-256 hash of cert to which the following info applies
  75     CFDataRef           issuerHash;           // SHA-256 hash of issuing CA certificate
  76     CFDataRef           anchorHash;           // SHA-256 hash of anchor certificate (optional)
  77     bool                isOnList;             // true if this cert was found on allow list or block list
  78     bool                valid;                // true if this is an allow list, false if a block list
  79     bool                complete;             // true if list is complete (i.e. status is definitive)
  80     bool                checkOCSP;            // true if complete is false and OCSP check is required
  81     bool                knownOnly;            // true if intermediate CAs under issuer must be found in database
  82     bool                requireCT;            // true if this cert must have CT proof
  83     bool                noCACheck;            // true if an entry does not require an OCSP check to accept
  84     bool                overridable;          // true if the trust status is recoverable and can be overridden
  85     bool                hasDateConstraints;   // true if this issuer has supplemental date constraints
  86     bool                hasNameConstraints;   // true if this issuer has supplemental name constraints
  87     bool                hasPolicyConstraints; // true if this issuer has policy constraints
  88     CFDateRef           notBeforeDate;        // minimum notBefore for this certificate (if hasDateConstraints is true)
  89     CFDateRef           notAfterDate;         // maximum notAfter for this certificate (if hasDateConstraints is true)
  90     CFDataRef           nameConstraints;      // name constraints blob (if hasNameConstraints is true)
  91     CFDataRef           policyConstraints;    // policy constraints blob (if policyConstraints is true)
  92 };
  93
  94 /*!
  95         @function SecValidInfoSetAnchor
  96         @abstract Updates a SecValidInfo reference with info about the anchor certificate in a chain.
  97         @param validInfo The SecValidInfo reference to be updated.
  98         @param anchor The certificate which anchors the chain for the certificate in this SecValidInfo reference.
  99         @discussion A SecValidInfo reference contains information about a single certificate and its issuer. In some cases, it may be necessary to additionally examine the anchor of the certificate chain to determine validity.
 100  */
 101 void SecValidInfoSetAnchor(SecValidInfoRef validInfo, SecCertificateRef anchor);
 102
 103 /*!
 104         @function SecRevocationDbCheckNextUpdate
 105         @abstract Periodic hook to poll for updates.
 106  */
 107 void SecRevocationDbCheckNextUpdate(void);
 108
 109 /*!
 110     @function SecRevocationDbUpdate
 111     @abstract Trigger update now. For use in testing and tools.
 112  */
 113 bool SecRevocationDbUpdate(CFErrorRef *error);
 114
 115 /*!
 116         @function SecRevocationDbCopyMatching
 117         @abstract Returns a SecValidInfo reference if matching revocation (or allow list) info was found.
 118         @param certificate The certificate whose validity status is being requested.
 119         @param issuer The issuing CA certificate. If the cert is self-signed, the same reference should be passed in both certificate and issuer parameters. Omitting either cert parameter is an error and NULL will be returned.
 120         @result A SecValidInfoRef if there was matching revocation info. Caller must release this reference when finished by calling CFRelease. NULL is returned if no matching info was found in the database.
 121  */
 122 SecValidInfoRef SecRevocationDbCopyMatching(SecCertificateRef certificate,
 123                                             SecCertificateRef issuer);
 124
 125 /*!
 126  @function SecRevocationDbContainsIssuer
 127  @abstract Returns true if the database contains an entry for the specified CA certificate.
 128  @param issuer The certificate being checked.
 129  @result If a matching issuer group was found, returns true, otherwise false.
 130 */
 131 bool SecRevocationDbContainsIssuer(SecCertificateRef issuer);
 132
 133 /*!
 134         @function SecRevocationDbGetVersion
 135         @abstract Returns a CFIndex containing the version number of the database.
 136         @result On success, the returned version will be a value greater than or equal to zero. A version of 0 indicates an empty database which has yet to be populated. If the version cannot be obtained, -1 is returned.
 137  */
 138 CFIndex SecRevocationDbGetVersion(void);
 139
 140 /*!
 141         @function SecRevocationDbGetSchemaVersion
 142         @abstract Returns a CFIndex containing the schema version number of the database.
 143         @result On success, the returned version will be a value greater than or equal to zero. A version of 0 indicates an empty database which has yet to be populated. If the version cannot be obtained, -1 is returned.
 144  */
 145 CFIndex SecRevocationDbGetSchemaVersion(void);
 146
 147 /*!
 148  @function SecValidUpdateVerifyAndIngest
 149  @abstract Callback for receiving update data.
 150  @param updateData The decompressed update data.
 151  @param updateServer The source server for this data.
 152  @param fullUpdate If true, a full update was requested.
 153  */
 154 void SecValidUpdateVerifyAndIngest(CFDataRef updateData, CFStringRef updateServer, bool fullUpdate);
 155
 156 /*!
 157  @function readValidFile
 158  @abstract Reads data into a CFDataRef using mmap.
 159  @param fileName The file to read.
 160  @param bytes The data read from the file.
 161  @result An integer indicating failure (non-zero) or success.
 162  @discussion This function mmaps the file and then makes a no-copy CFData for use of that mmapped file.  This data MUST be munmapped when the caller has finished with the data.
 163  */
 164 int readValidFile(const char *fileName, CFDataRef  *bytes);
 165
 166 /*!
 167  @function SecRevocationDbComputeAndSetNextUpdateTime
 168  @abstract Callback to push forward next update.
 169  */
 170 void SecRevocationDbComputeAndSetNextUpdateTime(void);
 171
 172 /*!
 173  @function SecRevocationDbInitialize
 174  @abstract Initializes revocation database if it doesn't exist or needs to be replaced. This should only be called once at process startup, before any database connections are established.
 175  */
 176 void SecRevocationDbInitialize(void);
 177
 178 extern const CFStringRef kValidUpdateProdServer;
 179 extern const CFStringRef kValidUpdateSeedServer;
 180 extern const CFStringRef kValidUpdateCarryServer;
 181
 182 /*!
 183  @function SecRevocationDbCopyUpdateSource
 184  @abstract Returns the server source for updates of the revocation database.
 185  @result The base string of the server URI.
 186  */
 187 CF_RETURNS_RETAINED CFStringRef SecRevocationDbCopyUpdateSource(void);
 188
 189
 190 __END_DECLS
 191
 192 #endif /* _SECURITY_SECREVOCATIONDB_H_ */