OSX/sec/securityd/SecRevocationDb.h

   1 /*
   2  * Copyright (c) 2016 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/CFData.h>
  35 #include <CoreFoundation/CFDate.h>
  36 #include <CoreFoundation/CFDictionary.h>
  37 #include <CoreFoundation/CFString.h>
  38 #include <dispatch/dispatch.h>
  39 #include <Security/SecBase.h>
  40
  41 __BEGIN_DECLS
  42
  43 /* issuer group data format */
  44 typedef CF_ENUM(uint32_t, SecValidInfoFormat) {
  45     kSecValidInfoFormatUnknown      = 0,
  46     kSecValidInfoFormatSerial       = 1,
  47     kSecValidInfoFormatSHA256       = 2,
  48     kSecValidInfoFormatNto1         = 3
  49 };
  50
  51 /*!
  52     @typedef SecValidInfoRef
  53     @abstract Object used to return valid info lookup results.
  54  */
  55 typedef struct __SecValidInfo *SecValidInfoRef;
  56
  57 struct __SecValidInfo {
  58     SecValidInfoFormat  format;     // format of per-issuer validity data
  59     CFDataRef           certHash;   // SHA-256 hash of cert to which the following info applies
  60     CFDataRef           issuerHash; // SHA-256 hash of issuing CA certificate
  61     CFDataRef           anchorHash; // SHA-256 hash of anchor certificate (optional)
  62     bool                isOnList;   // true if this cert was found on allow list or block list
  63     bool                valid;      // true if this is an allow list, false if a block list
  64     bool                complete;   // true if list is complete (i.e. status is definitive)
  65     bool                checkOCSP;  // true if complete is false and OCSP check is required
  66     bool                knownOnly;  // true if all intermediates under issuer must be found in database
  67     bool                requireCT;  // true if this cert must have CT proof
  68     bool                noCACheck;  // true if an entry does not require an OCSP check to accept
  69 };
  70
  71 /*!
  72         @function SecValidInfoRelease
  73         @abstract Releases a SecValidInfo reference previously obtained from a call to SecRevocationDbCopyMatching.
  74         @param validInfo The SecValidInfo reference to be released.
  75  */
  76 void SecValidInfoRelease(SecValidInfoRef validInfo);
  77
  78 /*!
  79         @function SecValidInfoSetAnchor
  80         @abstract Updates a SecValidInfo reference with info about the anchor certificate in a chain.
  81         @param validInfo The SecValidInfo reference to be updated.
  82         @param anchor The certificate which anchors the chain for the certificate in this SecValidInfo reference.
  83         @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.
  84  */
  85 void SecValidInfoSetAnchor(SecValidInfoRef validInfo, SecCertificateRef anchor);
  86
  87 /*!
  88         @function SecRevocationDbCheckNextUpdate
  89         @abstract Periodic hook to poll for updates.
  90  */
  91 void SecRevocationDbCheckNextUpdate(void);
  92
  93 /*!
  94         @function SecRevocationDbCopyMatching
  95         @abstract Returns a SecValidInfo reference if matching revocation (or allow list) info was found.
  96         @param certificate The certificate whose validity status is being requested.
  97         @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.
  98         @result A SecValidInfoRef if there was matching revocation info. Caller must release this reference when finished by calling SecValidInfoRelease. NULL is returned if no matching info was found in the database.
  99  */
 100 SecValidInfoRef SecRevocationDbCopyMatching(SecCertificateRef certificate,
 101                                             SecCertificateRef issuer);
 102
 103 /*!
 104         @function SecRevocationDbGetVersion
 105         @abstract Returns a CFIndex containing the version number of the database.
 106         @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.
 107  */
 108 CFIndex SecRevocationDbGetVersion(void);
 109
 110 /*!
 111         @function SecRevocationDbGetSchemaVersion
 112         @abstract Returns a CFIndex containing the schema version number of the database.
 113         @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.
 114  */
 115 CFIndex SecRevocationDbGetSchemaVersion(void);
 116
 117 /*!
 118  @function SecValidUpdateVerifyAndIngest
 119  @abstract Callback for receiving update data.
 120  @param updateData The decompressed update data.
 121  */
 122 void SecValidUpdateVerifyAndIngest(CFDataRef updateData);
 123
 124 /*!
 125  @function readValidFile
 126  @abstract Reads data into a CFDataRef using mmap.
 127  @param fileName The file to read.
 128  @param bytes The data read from the file.
 129  @result An integer indicating failure (non-zero) or success.
 130  @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.
 131  */
 132 int readValidFile(const char *fileName, CFDataRef  *bytes);
 133
 134 /*!
 135  @function SecRevocationDbComputeAndSetNextUpdateTime
 136  @abstract Callback to push forward next update.
 137  */
 138 void SecRevocationDbComputeAndSetNextUpdateTime(void);
 139
 140 /*!
 141  @function SecRevocationDbInitialize
 142  @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.
 143  */
 144 void SecRevocationDbInitialize(void);
 145
 146
 147 __END_DECLS
 148
 149 #endif /* _SECURITY_SECREVOCATIONDB_H_ */