trust/trustd/SecOCSPCache.h

   1 /*
   2  * Copyright (c) 2009-2010,2012-2017 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 SecOCSPCache
  27     The functions provided in SecOCSPCache.h provide an interface to
  28     an OCSP caching module.
  29 */
  30
  31 #ifndef _SECURITY_SECOCSPCACHE_H_
  32 #define _SECURITY_SECOCSPCACHE_H_
  33
  34 #include "trust/trustd/SecOCSPRequest.h"
  35 #include "trust/trustd/SecOCSPResponse.h"
  36 #include <CoreFoundation/CFURL.h>
  37
  38 __BEGIN_DECLS
  39
  40
  41 void SecOCSPCacheReplaceResponse(SecOCSPResponseRef old_response,
  42     SecOCSPResponseRef response, CFURLRef localResponderURI, CFAbsoluteTime verifyTime);
  43
  44 SecOCSPResponseRef SecOCSPCacheCopyMatching(SecOCSPRequestRef request,
  45     CFURLRef localResponderURI /* may be NULL */);
  46
  47 SecOCSPResponseRef SecOCSPCacheCopyMatchingWithMinInsertTime(SecOCSPRequestRef request,
  48     CFURLRef localResponderURI, CFAbsoluteTime minInsertTime);
  49
  50 bool SecOCSPCacheFlush(CFErrorRef *error);
  51
  52 __END_DECLS
  53
  54 #endif /* _SECURITY_SECOCSPCACHE_H_ */
  55
  56 #if 0
  57 /*
  58 Experation policy assumptions:
  59 - We never check revocation status of anchors, whether they be system anchors,
  60   passed in anchors or anchors hardcoded in a policy.
  61 - Revocation information is cached for positive reponses for a limited time.
  62 - Revocation information can be cached for negative reponses for an unlimited time.
  63 - Revocation information need never be kept around after the certificate has expired (unless we still check after the cert has expired like we were talking about for EERI).
  64 - Revocation information records that are used and still valid should be kept longer.
  65 - We can set an upper limit in number of records (or certificates) in the cache.
  66 - We can set an upper limit on total space consumed by the cache.
  67 Questions:
  68 - Remember bad server responses too?  some ocsp responders required signed requests which we don't support, so we could consider caching the 6 (Not Authorized or something) response.
  69
  70 Data needed per type of revocation record to implement this policy.
  71
  72 Caching policy:
  73 - Deleting cache should not be user option.
  74 - Cache should surrvive backups.
  75 - Negative caching as long as possible.
  76
  77 CRL certificate stati:
  78 unspecified, keyCompromise, cACompromise,
  79 affiliationChanged, superseded, cessationOfOperation,
  80 certificateHold, removeFromCRL, privilegeWithdrawn,
  81 aACompromise, the special value UNREVOKED, or the special
  82 value UNDETERMINED.  This variable is initialized to the
  83 special value UNREVOKED.
  84
  85 CRL Timestamp values:
  86 - thisUpdate
  87 - nextUpdate (optional but not really 5280 says CAs must provide it even though ASN.1 is optional)
  88 (no producedAt in CRLs, that's what thisUpdate is by definition it seems).
  89
  90
  91 OCSP Timestamp values:
  92       thisUpdate = May 1, 2005  01:00:00 GMT
  93       nextUpdate = May 3, 2005 01:00:00 GMT (optional abscence means update available any time)
  94       productedAt = May 1, 2005 01:00:00 GMT
  95
  96 PER CERTIFICATE RETURN in INFO
  97
  98 Revocation object used: OCSP Response, mapping from
  99 reasons-> (CRL + most current delta CRL), Error Object (with status code).
 100    -- good
 101    -- revoked
 102    -- unknown
 103
 104 other exceptions (unsigned responses):
 105    -- malformedRequest
 106    -- internalError
 107    -- tryLater
 108    -- sigRequired
 109    -- unauthorized (5019 The response "unauthorized" is returned in cases where the client
 110       is not authorized to make this query to this server or the server
 111       is not capable of responding authoritatively.  (Expired certs might get this answer too))
 112
 113
 114 CRL signer chain rules:
 115 1) Must use same anchor as cert itself.
 116 This implies that we can only cache the validity of a leaf or intermediate certificate for CRL checking based on the mapping:
 117 (certificate, path anchor, use_deltas) -> Revocation_status (unspecified, keyCompromise, cACompromise,
 118 affiliationChanged, superseded, cessationOfOperation,certificateHold, removeFromCRL, privilegeWithdrawn,aACompromise, UNREVOKED, UNDETERMINED).
 119
 120 OCSP signer chain rules:
 121 (Wikipedia confirmed in rfc): The key that signs a response need not be the same key that signed the certificate. The certificate's issuer may delegate another authority to be the OCSP responder. In this case, the responder's certificate (the one that is used to sign the response) must be issued by the issuer of the certificate in question, and must include a certain extension that marks it as an OCSP signing authority (more precisely, an extended key usage extension with the OID {iso(1) identified-organization(3) dod(6) internet(1) security(5) mechanisms(5) pkix(7) keyPurpose(3) ocspSigning(9)})
 122
 123 rfc text of the wikipedia: Therefore, a certificate's issuer MUST either sign the OCSP
 124    responses itself or it MUST explicitly designate this authority to
 125    another entity.  OCSP signing delegation SHALL be designated by the
 126    inclusion of id-kp-OCSPSigning in an extendedKeyUsage certificate
 127    extension included in the OCSP response signer's certificate.  This
 128    certificate MUST be issued directly by the CA that issued the
 129    certificate in question.
 130
 131 rfc: If ocsp signing cert has id-pkix-ocsp-nocheck extension we don't check it's revocation status.
 132
 133 (certificate, direct issuer certificate) -> Revocation_status good (UNREVOKED) revoked revocationTime, CRLReason (unspecified, keyCompromise, cACompromise,affiliationChanged, superseded, cessationOfOperation,certificateHold, removeFromCRL, privilegeWithdrawn,aACompromise) unknown (UNDETERMINED).
 134
 135 ocsp CertID ::= SEQUENCE {
 136        hashAlgorithm       AlgorithmIdentifier,
 137        issuerNameHash      OCTET STRING, -- Hash of Issuer's DN
 138        issuerKeyHash       OCTET STRING, -- Hash of Issuers public key
 139        serialNumber        CertificateSerialNumber }
 140 )
 141
 142 In order to accomadate the responder using a different hashAlgorithm than we used in the request we need to recalc these from the cert itself.
 143
 144 If all we have is a list of ocspresponses without knowing where they came from, we have to calculate the hashes of our issuerName and issuerKey for each hashAlgorithm we have cached ocsp responses for (optionally after limiting our candidates to those with matching serialNumbers first).
 145
 146 SELECT from ocsp_cache hashAlgorithm WHERE serialNumber = <SERIAL>
 147
 148 for hix = 0 hix < hashAlgorithms.count
 149   ALG(hix).id = hashAlgorithms(hix)
 150
 151 SELECT from ocsp_cache response WHERE serialNumber = <SERIAL> hashAlgorithm = ALG(hix).id issuerNameHash = ALG(hix).hash(issuer) issuerKeyHash = ALG(hix).hash(key)
 152
 153
 154
 155
 156
 157
 158 Notes for Matt:
 159 - ttl in amfi cache (to force recheck when ocsp response is invalid)?
 160 - Periodic check before launch to remove in band waiting for ocsp response?
 161
 162 Notes on Nonces in ocsp request and responses.  Only ask for nonce if we think server supports it (no way to know today). Fall back on time based validity checking if reponse has no nonce, even if we asked for one
 163
 164 Note on CRL checking and experation and retries of OCSP checking.
 165 Clients MAY attempt to retrieve the CRL if no
 166    OCSPResponse is received from the responder after a locally
 167    configured timeout and number of retries..
 168
 169
 170
 171 CRL/OCSP cache design idea:
 172
 173 revocation status table:
 174
 175 rowid certhash issuer-rowid lastUsed thisUpdate producedAt nextUpdate revocationTime revocationStatus
 176
 177 cacheAddOCSP(path, index_of_cert_resp_is_for, ocspResp)
 178 cacheAddCRLStatus(path, index_of_cert_in_path, nextUpdate, revocationTime, revocationStatus)
 179 (revocationTime, revocationStatus) = cacheLookupStatus(path, ix)
 180
 181 Return a list of parent certificate hashes for the current leaf.  If a result is returned, we have a candiate path leading up to an anchor, for which we already trust the signature in the chain and revocation information has been checked.
 182
 183 CFArrayRef cacheSuggestParentsHashesFor(cert)
 184
 185 for crl based status root must match root of path.  For ocsp status issuer must match issuer of leaf in path
 186
 187 presence in the cache means cert chain leading to an anchor is valid, and signed properly and trusted by the ocsp or crl policy, revocation status for cert is valid until the time indicated by nextUpdate.  Cert chain itself may or may not be valid but that's checked by the policy engine.
 188
 189 If a chain isn't properly signed or fails to satisfy the crl policy, it should not be in the cache.
 190
 191 ocsp cache
 192
 193 rowid ocspResponse (responder) lastUsed nextUpdate
 194
 195 hashAlgorithm->(issuerNameHash,issuerKeyHash,serialNumber)->response
 196
 197
 198 crl cache ()
 199
 200 crlDistributionPoint (reasons) crl thisUpdate nextUpdate isDelta
 201
 202
 203 crlEntry cache table
 204 (certHash anchorHash) crlIssuer revocationStatus revocationTime expires lastUsed
 205 crlTable
 206 (crlIssuer anchorHash distributionPointURL?) crl sigVerified expires
 207 ocspEntry cache table
 208 (certHash parentHash ocspReponderID) hashAlg revocationStatus revocationTime expires lastUsed
 209 ocspTable
 210 ((hashAlg, pubKeyHash, issuerHash, serialNum) anchorHash) ocspResponse sigVerified expires
 211
 212 or
 213 cert cache table
 214 (certHash parentHash anchorHash) crlEntryID ocspID
 215
 216 crlEntry cache table
 217 (crlEntryID anchorHash) crlIssuer revocationStatus revocationTime
 218
 219 crlIssuerTable
 220 (crlIssuer anchorHash) crl sigVerified
 221
 222 ocsp table
 223 (ocspID) ocspResponse
 224
 225
 226 but so does caching the raw response as a link to a blob table containing crls
 227 and ocsp-responses
 228 But also cache the revocationStatus for a (cert,parent) or (cert,anchor) via
 229 a link to a cached ocspResponse or revocationStatus and revocationTime entry from crl
 230 */
 231
 232 #endif