OSX/libsecurity_ocspd/common/ocspdClient.h

   1 /*
   2  * Copyright (c) 2000,2002,2011,2014 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  * ocspdClient.h - Client interface to OCSP helper daemon
  26  */
  27
  28 #ifndef _OCSPD_CLIENT_H_
  29 #define _OCSPD_CLIENT_H_
  30
  31 #include <Security/cssmtype.h>
  32 #include <Security/SecTrustSettings.h>
  33 #include <security_utilities/alloc.h>
  34
  35 #ifdef  __cplusplus
  36 extern "C" {
  37 #endif
  38
  39 #pragma mark ----- OCSP routines -----
  40
  41 /*
  42  * Normal OCSP request. Depending on contents of encoded SecAsn1OCSPToolRequest,
  43  * this optionally performs cache lookup, local responder OCSP, and normal
  44  * OCSP, in that order. If OCSP response is fetched from the net the netFetch
  45  * outParam is true on return.
  46  */
  47 CSSM_RETURN ocspdFetch(
  48         Allocator                       &alloc,
  49         const CSSM_DATA         &ocspdReq,              // DER-encoded SecAsn1OCSPDRequests
  50         CSSM_DATA                       &ocspdResp);    // DER-encoded kSecAsn1OCSPDReplies
  51                                                                                 // mallocd via alloc and RETURNED
  52
  53 /*
  54  * Flush all OCSP responses associated with specifed CertID from cache.
  55  */
  56 CSSM_RETURN ocspdCacheFlush(
  57         const CSSM_DATA         &certID);
  58
  59 /*
  60  * Flush stale entries from cache.
  61  */
  62 CSSM_RETURN ocspdCacheFlushStale();
  63
  64 #pragma mark ----- CRL/Cert routines -----
  65 /*
  66  * fetch a certificate from the net.
  67  */
  68 CSSM_RETURN ocspdCertFetch(
  69         Allocator                       &alloc,
  70         const CSSM_DATA         &certURL,
  71         CSSM_DATA                       &certData);             // mallocd via alloc and RETURNED
  72
  73 /*
  74  * fetch a CRL from the net with optional cache lookup and/or store.
  75  * VerifyTime argument only used for cache lookup; it must be in
  76  * CSSM_TIMESTRING format.
  77  * crlIssuer is optional, and is only specified when the client knows
  78  * that the issuer of the CRL is the same as the issuer of the cert
  79  * being verified.
  80  */
  81 CSSM_RETURN ocspdCRLFetch(
  82         Allocator                       &alloc,
  83         const CSSM_DATA         &crlURL,
  84         const CSSM_DATA         *crlIssuer,             // optional
  85         bool                            cacheReadEnable,
  86         bool                            cacheWriteEnable,
  87         CSSM_TIMESTRING         verifyTime,
  88         CSSM_DATA                       &crlData);              // mallocd via alloc and RETURNED
  89
  90 /*
  91  * fetch CRL revocation status, given a certificate's serial number and
  92  * its issuers, along with an identifier for the CRL (either its issuer name
  93  * or distribution point URL)
  94  *
  95  * This may return one of the following result codes:
  96  *
  97  * CSSM_OK (valid CRL was found for this issuer, serial number is not on it)
  98  * CSSMERR_TP_CERT_REVOKED (valid CRL was found, serial number is revoked)
  99  * CSSMERR_APPLETP_NETWORK_FAILURE (crl not available, download in progress)
 100  * CSSMERR_APPLETP_CRL_NOT_FOUND (crl not available, and not in progress)
 101  *
 102  * The first three error codes can be considered definitive answers (with the
 103  * NETWORK_FAILURE case indicating a possible retry later if required); the
 104  * last error requires a subsequent call to ocspdCRLFetch to either retrieve
 105  * the CRL from the on-disk cache or initiate a download of the CRL.
 106  *
 107  * Note: CSSMERR_TP_INTERNAL_ERROR can also be returned if there is a problem
 108  * with the provided arguments, or an error communicating with ocspd.
 109  */
 110 CSSM_RETURN ocspdCRLStatus(
 111         const CSSM_DATA         &serialNumber,
 112         const CSSM_DATA         &certIssuers,
 113         const CSSM_DATA         *crlIssuer,             // optional if URL is supplied
 114         const CSSM_DATA         *crlURL);               // optional if issuer is supplied
 115
 116 /*
 117  * Refresh the CRL cache.
 118  */
 119 CSSM_RETURN ocspdCRLRefresh(
 120         unsigned                        staleDays,
 121         unsigned                        expireOverlapSeconds,
 122         bool                            purgeAll,
 123         bool                            fullCryptoVerify);
 124
 125 /*
 126  * Flush all CRLs obtained from specified URL from cache. Called by client when
 127  * *it* detects a bad CRL.
 128  */
 129 CSSM_RETURN ocspdCRLFlush(
 130         const CSSM_DATA         &crlURL);
 131
 132 /*
 133  * Obtain TrustSettings.
 134  */
 135 OSStatus ocspdTrustSettingsRead(
 136         Allocator                               &alloc,
 137         SecTrustSettingsDomain  domain,
 138         CSSM_DATA                               &trustSettings);                // mallocd via alloc and RETURNED
 139
 140 /*
 141  * Write TrustSettings to disk. Results in authentication dialog.
 142  */
 143 OSStatus ocspdTrustSettingsWrite(
 144         SecTrustSettingsDomain  domain,
 145         const CSSM_DATA                 &authBlob,
 146         const CSSM_DATA                 &trustSettings);
 147
 148 #ifdef  __cplusplus
 149 }
 150 #endif
 151
 152 #endif  /* _OCSPD_CLIENT_H_ */