libsecurity_ocspd/client/ocspdClient.h

   1 /*
   2  * Copyright (c) 2002,2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23 /*
  24  * ocspdClient.h - Client interface to OCSP helper daemon
  25  */
  26
  27 #ifndef _OCSPD_CLIENT_H_
  28 #define _OCSPD_CLIENT_H_
  29
  30 #include <Security/cssmtype.h>
  31 #include <Security/SecTrustSettings.h>
  32 #include <security_utilities/alloc.h>
  33
  34 #ifdef  __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #pragma mark ----- OCSP routines -----
  39
  40 /*
  41  * Normal OCSP request. Depending on contents of encoded SecAsn1OCSPToolRequest,
  42  * this optionally performs cache lookup, local responder OCSP, and normal
  43  * OCSP, in that order. If OCSP response is fetched from the net the netFetch
  44  * outParam is true on return.
  45  */
  46 CSSM_RETURN ocspdFetch(
  47         Allocator                       &alloc,
  48         const CSSM_DATA         &ocspdReq,              // DER-encoded SecAsn1OCSPDRequests
  49         CSSM_DATA                       &ocspdResp);    // DER-encoded kSecAsn1OCSPDReplies
  50                                                                                 // mallocd via alloc and RETURNED
  51
  52 /*
  53  * Flush all OCSP responses associated with specifed CertID from cache.
  54  */
  55 CSSM_RETURN ocspdCacheFlush(
  56         const CSSM_DATA         &certID);
  57
  58 /*
  59  * Flush stale entries from cache.
  60  */
  61 CSSM_RETURN ocspdCacheFlushStale();
  62
  63 #pragma mark ----- CRL/Cert routines -----
  64 /*
  65  * fetch a certificate from the net.
  66  */
  67 CSSM_RETURN ocspdCertFetch(
  68         Allocator                       &alloc,
  69         const CSSM_DATA         &certURL,
  70         CSSM_DATA                       &certData);             // mallocd via alloc and RETURNED
  71
  72 /*
  73  * fetch a CRL from the net with optional cache lookup and/or store.
  74  * VerifyTime argument only used for cache lookup; it must be in
  75  * CSSM_TIMESTRING format.
  76  * crlIssuer is optional, and is only specified when the client knows
  77  * that the issuer of the CRL is the same as the issuer of the cert
  78  * being verified.
  79  */
  80 CSSM_RETURN ocspdCRLFetch(
  81         Allocator                       &alloc,
  82         const CSSM_DATA         &crlURL,
  83         const CSSM_DATA         *crlIssuer,             // optional
  84         bool                            cacheReadEnable,
  85         bool                            cacheWriteEnable,
  86         CSSM_TIMESTRING         verifyTime,
  87         CSSM_DATA                       &crlData);              // mallocd via alloc and RETURNED
  88
  89 /*
  90  * fetch CRL revocation status, given a certificate's serial number and
  91  * its issuers, along with an identifier for the CRL (either its issuer name
  92  * or distribution point URL)
  93  *
  94  * This may return one of the following result codes:
  95  *
  96  * CSSM_OK (valid CRL was found for this issuer, serial number is not on it)
  97  * CSSMERR_TP_CERT_REVOKED (valid CRL was found, serial number is revoked)
  98  * CSSMERR_APPLETP_NETWORK_FAILURE (crl not available, download in progress)
  99  * CSSMERR_APPLETP_CRL_NOT_FOUND (crl not available, and not in progress)
 100  *
 101  * The first three error codes can be considered definitive answers (with the
 102  * NETWORK_FAILURE case indicating a possible retry later if required); the
 103  * last error requires a subsequent call to ocspdCRLFetch to either retrieve
 104  * the CRL from the on-disk cache or initiate a download of the CRL.
 105  *
 106  * Note: CSSMERR_TP_INTERNAL_ERROR can also be returned if there is a problem
 107  * with the provided arguments, or an error communicating with ocspd.
 108  */
 109 CSSM_RETURN ocspdCRLStatus(
 110         const CSSM_DATA         &serialNumber,
 111         const CSSM_DATA         &certIssuers,
 112         const CSSM_DATA         *crlIssuer,             // optional if URL is supplied
 113         const CSSM_DATA         *crlURL);               // optional if issuer is supplied
 114
 115 /*
 116  * Refresh the CRL cache.
 117  */
 118 CSSM_RETURN ocspdCRLRefresh(
 119         unsigned                        staleDays,
 120         unsigned                        expireOverlapSeconds,
 121         bool                            purgeAll,
 122         bool                            fullCryptoVerify);
 123
 124 /*
 125  * Flush all CRLs obtained from specified URL from cache. Called by client when
 126  * *it* detects a bad CRL.
 127  */
 128 CSSM_RETURN ocspdCRLFlush(
 129         const CSSM_DATA         &crlURL);
 130
 131 /*
 132  * Obtain TrustSettings.
 133  */
 134 OSStatus ocspdTrustSettingsRead(
 135         Allocator                               &alloc,
 136         SecTrustSettingsDomain  domain,
 137         CSSM_DATA                               &trustSettings);                // mallocd via alloc and RETURNED
 138
 139 /*
 140  * Write TrustSettings to disk. Results in authentication dialog.
 141  */
 142 OSStatus ocspdTrustSettingsWrite(
 143         SecTrustSettingsDomain  domain,
 144         const CSSM_DATA                 &authBlob,
 145         const CSSM_DATA                 &trustSettings);
 146
 147 #ifdef  __cplusplus
 148 }
 149 #endif
 150
 151 #endif  /* _OCSPD_CLIENT_H_ */