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 <dispatch/dispatch.h>
  40 #include <Security/SecBase.h>
  41
  42 __BEGIN_DECLS
  43
  44 /* issuer group data format */
  45 typedef CF_ENUM(uint32_t, SecValidInfoFormat) {
  46     kSecValidInfoFormatUnknown      = 0,
  47     kSecValidInfoFormatSerial       = 1,
  48     kSecValidInfoFormatSHA256       = 2,
  49     kSecValidInfoFormatNto1         = 3
  50 };
  51
  52 /* policy types */
  53 typedef CF_ENUM(int8_t, SecValidPolicy) {
  54     kSecValidPolicyNone = -1,
  55     kSecValidPolicyAny = 0,
  56     kSecValidPolicyServerAuthentication = 1,
  57     kSecValidPolicyClientAuthentication = 2,
  58     kSecValidPolicyEmailProtection = 3,
  59     kSecValidPolicyCodeSigning = 4,
  60     kSecValidPolicyTimeStamping = 5,
  61 };
  62
  63 /*!
  64     @typedef SecValidInfoRef
  65     @abstract CFType used to return valid info lookup results.
  66  */
  67 typedef struct __SecValidInfo *SecValidInfoRef;
  68
  69 struct __SecValidInfo {
  70     CFRuntimeBase _base;
  71
  72     SecValidInfoFormat  format;               // format of per-issuer validity data
  73     CFDataRef           certHash;             // SHA-256 hash of cert to which the following info applies
  74     CFDataRef           issuerHash;           // SHA-256 hash of issuing CA certificate
  75     CFDataRef           anchorHash;           // SHA-256 hash of anchor certificate (optional)
  76     bool                isOnList;             // true if this cert was found on allow list or block list
  77     bool                valid;                // true if this is an allow list, false if a block list
  78     bool                complete;             // true if list is complete (i.e. status is definitive)
  79     bool                checkOCSP;            // true if complete is false and OCSP check is required
  80     bool                knownOnly;            // true if intermediate CAs under issuer must be found in database
  81     bool                requireCT;            // true if this cert must have CT proof
  82     bool                noCACheck;            // true if an entry does not require an OCSP check to accept
  83     bool                overridable;          // true if the trust status is recoverable and can be overridden
  84     bool                hasDateConstraints;   // true if this issuer has supplemental date constraints
  85     bool                hasNameConstraints;   // true if this issuer has supplemental name constraints
  86     bool                hasPolicyConstraints; // true if this issuer has policy constraints
  87     CFDateRef           notBeforeDate;        // minimum notBefore for this certificate (if hasDateConstraints is true)
  88     CFDateRef           notAfterDate;         // maximum notAfter for this certificate (if hasDateConstraints is true)
  89     CFDataRef           nameConstraints;      // name constraints blob (if hasNameConstraints is true)
  90     CFDataRef           policyConstraints;    // policy constraints blob (if policyConstraints is true)
  91 };
  92
  93 /*!
  94         @function SecValidInfoSetAnchor
  95         @abstract Updates a SecValidInfo reference with info about the anchor certificate in a chain.
  96         @param validInfo The SecValidInfo reference to be updated.
  97         @param anchor The certificate which anchors the chain for the certificate in this SecValidInfo reference.
  98         @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.
  99  */
 100 void SecValidInfoSetAnchor(SecValidInfoRef validInfo, SecCertificateRef anchor);
 101
 102 /*!
 103         @function SecRevocationDbCheckNextUpdate
 104         @abstract Periodic hook to poll for updates.
 105  */
 106 void SecRevocationDbCheckNextUpdate(void);
 107
 108 /*!
 109         @function SecRevocationDbCopyMatching
 110         @abstract Returns a SecValidInfo reference if matching revocation (or allow list) info was found.
 111         @param certificate The certificate whose validity status is being requested.
 112         @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.
 113         @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.
 114  */
 115 SecValidInfoRef SecRevocationDbCopyMatching(SecCertificateRef certificate,
 116                                             SecCertificateRef issuer);
 117
 118 /*!
 119  @function SecRevocationDbContainsIssuer
 120  @abstract Returns true if the database contains an entry for the specified CA certificate.
 121  @param issuer The certificate being checked.
 122  @result If a matching issuer group was found, returns true, otherwise false.
 123 */
 124 bool SecRevocationDbContainsIssuer(SecCertificateRef issuer);
 125
 126 /*!
 127         @function SecRevocationDbGetVersion
 128         @abstract Returns a CFIndex containing the version number of the database.
 129         @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.
 130  */
 131 CFIndex SecRevocationDbGetVersion(void);
 132
 133 /*!
 134         @function SecRevocationDbGetSchemaVersion
 135         @abstract Returns a CFIndex containing the schema 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 SecRevocationDbGetSchemaVersion(void);
 139
 140 /*!
 141  @function SecValidUpdateVerifyAndIngest
 142  @abstract Callback for receiving update data.
 143  @param updateData The decompressed update data.
 144  @param updateServer The source server for this data.
 145  @param fullUpdate If true, a full update was requested.
 146  */
 147 void SecValidUpdateVerifyAndIngest(CFDataRef updateData, CFStringRef updateServer, bool fullUpdate);
 148
 149 /*!
 150  @function readValidFile
 151  @abstract Reads data into a CFDataRef using mmap.
 152  @param fileName The file to read.
 153  @param bytes The data read from the file.
 154  @result An integer indicating failure (non-zero) or success.
 155  @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.
 156  */
 157 int readValidFile(const char *fileName, CFDataRef  *bytes);
 158
 159 /*!
 160  @function SecRevocationDbComputeAndSetNextUpdateTime
 161  @abstract Callback to push forward next update.
 162  */
 163 void SecRevocationDbComputeAndSetNextUpdateTime(void);
 164
 165 /*!
 166  @function SecRevocationDbInitialize
 167  @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.
 168  */
 169 void SecRevocationDbInitialize(void);
 170
 171 extern const CFStringRef kValidUpdateProdServer;
 172 extern const CFStringRef kValidUpdateSeedServer;
 173 extern const CFStringRef kValidUpdateCarryServer;
 174
 175 /*!
 176  @function SecRevocationDbCopyUpdateSource
 177  @abstract Returns the server source for updates of the revocation database.
 178  @result The base string of the server URI.
 179  */
 180 CFStringRef SecRevocationDbCopyUpdateSource(void);
 181
 182
 183 __END_DECLS
 184
 185 #endif /* _SECURITY_SECREVOCATIONDB_H_ */