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     bool                valid;      // true if found on allow list, false if on block list
  62     bool                complete;   // true if list is complete (i.e. status is definitive)
  63     bool                checkOCSP;  // true if complete is false and OCSP check is required
  64     bool                knownOnly;  // true if all intermediates under issuer must be found in database
  65     bool                requireCT;  // true if this cert must have CT proof
  66 };
  67
  68 /*!
  69         @function SecValidInfoRelease
  70         @abstract Releases a SecValidInfo reference previously obtained from a call to SecRevocationDbCopyMatching.
  71         @param validInfo The SecValidInfo reference to be released.
  72  */
  73 void SecValidInfoRelease(SecValidInfoRef validInfo);
  74
  75 /*!
  76         @function SecRevocationDbCheckNextUpdate
  77         @abstract Periodic hook to poll for updates.
  78     @result A boolean value indicating whether an update check was dispatched.
  79  */
  80 bool SecRevocationDbCheckNextUpdate(void);
  81
  82 /*!
  83         @function SecRevocationDbCopyMatching
  84         @abstract Returns a SecValidInfo reference if matching revocation (or allow list) info was found.
  85         @param certificate The certificate whose validity status is being requested.
  86         @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.
  87         @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.
  88  */
  89 SecValidInfoRef SecRevocationDbCopyMatching(SecCertificateRef certificate,
  90                                             SecCertificateRef issuer);
  91
  92 /*!
  93         @function SecRevocationDbGetVersion
  94         @abstract Returns a CFIndex containing the version number of the database.
  95         @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.
  96  */
  97 CFIndex SecRevocationDbGetVersion(void);
  98
  99 /*!
 100         @function SecRevocationDbGetSchemaVersion
 101         @abstract Returns a CFIndex containing the schema version number of the database.
 102         @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.
 103  */
 104 CFIndex SecRevocationDbGetSchemaVersion(void);
 105
 106
 107 __END_DECLS
 108
 109 #endif /* _SECURITY_SECREVOCATIONDB_H_ */