OSX/sec/securityd/SecRevocationDb.h

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