OSX/sec/securityd/SecOCSPResponse.h

   1 /*
   2  * Copyright (c) 2009,2012-2018 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         @header SecOCSPResponse
  26         The functions and data types in SecOCSPResponse implement ocsp response
  27     decoding and verification.
  28 */
  29
  30 #ifndef _SECURITY_SECOCSPRESPONSE_H_
  31 #define _SECURITY_SECOCSPRESPONSE_H_
  32
  33 #include <Security/SecAsn1Coder.h>
  34 #include <CoreFoundation/CFArray.h>
  35 #include <CoreFoundation/CFData.h>
  36 #include <CoreFoundation/CFDate.h>
  37 #include <securityd/SecOCSPRequest.h>
  38 #include <security_asn1/ocspTemplates.h>
  39
  40 __BEGIN_DECLS
  41
  42 typedef enum {
  43         kSecOCSPBad = -2,
  44         kSecOCSPUnknown = -1,
  45         kSecOCSPSuccess = 0,
  46         kSecOCSPMalformedRequest = 1,
  47         kSecOCSPInternalError = 2,
  48         kSecOCSPTryLater = 3,
  49         kSecOCSPUnused = 4,
  50         kSecOCSPSigRequired = 5,
  51         kSecOCSPUnauthorized = 6
  52 } SecOCSPResponseStatus;
  53
  54 enum {
  55     kSecRevocationReasonUnrevoked               = -2,
  56     kSecRevocationReasonUndetermined            = -1,
  57     kSecRevocationReasonUnspecified             = 0,
  58     kSecRevocationReasonKeyCompromise           = 1,
  59     kSecRevocationReasonCACompromise            = 2,
  60     kSecRevocationReasonAffiliationChanged      = 3,
  61     kSecRevocationReasonSuperseded              = 4,
  62     kSecRevocationReasonCessationOfOperation    = 5,
  63     kSecRevocationReasonCertificateHold         = 6,
  64     /*         -- value 7 is not used */
  65     kSecRevocationReasonRemoveFromCRL           = 8,
  66     kSecRevocationReasonPrivilegeWithdrawn      = 9,
  67     kSecRevocationReasonAACompromise            = 10
  68 };
  69 typedef int32_t SecRevocationReason;
  70
  71
  72 /*!
  73         @typedef SecOCSPResponseRef
  74         @abstract Object used for ocsp response decoding.
  75 */
  76 typedef struct __SecOCSPResponse *SecOCSPResponseRef;
  77
  78 struct __SecOCSPResponse {
  79         CFDataRef data;
  80         SecAsn1CoderRef coder;
  81         SecOCSPResponseStatus responseStatus;
  82         CFDataRef nonce;
  83         CFAbsoluteTime producedAt;
  84         CFAbsoluteTime latestNextUpdate;
  85         CFAbsoluteTime expireTime;
  86         SecAsn1OCSPBasicResponse basicResponse;
  87         SecAsn1OCSPResponseData responseData;
  88         SecAsn1OCSPResponderIDTag responderIdTag;
  89         SecAsn1OCSPResponderID responderID;
  90         int64_t responseID;
  91 };
  92
  93 typedef struct __SecOCSPSingleResponse *SecOCSPSingleResponseRef;
  94
  95 struct __SecOCSPSingleResponse {
  96     SecAsn1OCSPCertStatusTag certStatus;
  97     CFAbsoluteTime thisUpdate;
  98     CFAbsoluteTime nextUpdate;          /* may be NULL_TIME */
  99     CFAbsoluteTime revokedTime;         /* != NULL_TIME for certStatus == CS_Revoked */
 100     SecRevocationReason crlReason;
 101     CFArrayRef scts;                /* This is parsed from an extension */
 102 };
 103
 104 /*!
 105         @function SecOCSPResponseCreate
 106         @abstract Returns a SecOCSPResponseRef from a BER encoded ocsp response.
 107         @param ocspResponse The BER encoded ocsp response.
 108         @result A SecOCSPResponseRef.
 109 */
 110 SecOCSPResponseRef SecOCSPResponseCreate(CFDataRef ocspResponse);
 111
 112 SecOCSPResponseRef SecOCSPResponseCreateWithID(CFDataRef ocspResponse, int64_t responseID);
 113
 114 int64_t SecOCSPResponseGetID(SecOCSPResponseRef ocspResponse);
 115
 116 /* Return true if response is still valid for the given age. */
 117 bool SecOCSPResponseCalculateValidity(SecOCSPResponseRef this,
 118     CFTimeInterval maxAge, CFTimeInterval defaultTTL, CFAbsoluteTime verifyTime);
 119
 120 CFDataRef SecOCSPResponseGetData(SecOCSPResponseRef this);
 121
 122 SecOCSPResponseStatus SecOCSPGetResponseStatus(SecOCSPResponseRef ocspResponse);
 123
 124 CFAbsoluteTime SecOCSPResponseGetExpirationTime(SecOCSPResponseRef ocspResponse);
 125
 126 CFDataRef SecOCSPResponseGetNonce(SecOCSPResponseRef ocspResponse);
 127
 128 CFAbsoluteTime SecOCSPResponseProducedAt(SecOCSPResponseRef ocspResponse);
 129
 130 /*!
 131         @function SecOCSPResponseCopySigners
 132         @abstract Returns an array of signers.
 133         @param ocspResponse A SecOCSPResponseRef.
 134         @result The passed in SecOCSPResponseRef is deallocated
 135 */
 136 CFArrayRef SecOCSPResponseCopySigners(SecOCSPResponseRef ocspResponse);
 137
 138 /*!
 139         @function SecOCSPResponseFinalize
 140         @abstract Frees a SecOCSPResponseRef.
 141         @param ocspResponse The BER encoded ocsp response.
 142 */
 143 void SecOCSPResponseFinalize(SecOCSPResponseRef ocspResponse);
 144
 145 SecOCSPSingleResponseRef SecOCSPResponseCopySingleResponse(
 146     SecOCSPResponseRef ocspResponse, SecOCSPRequestRef request);
 147
 148 /* DefaultTTL is how long past the thisUpdate time we trust a response without a nextUpdate field.  */
 149 bool SecOCSPSingleResponseCalculateValidity(SecOCSPSingleResponseRef this, CFAbsoluteTime defaultTTL, CFAbsoluteTime verifyTime);
 150
 151 /* Find the eventual SCTs from the single response extensions */
 152 CFArrayRef SecOCSPSingleResponseCopySCTs(SecOCSPSingleResponseRef this);
 153
 154 void SecOCSPSingleResponseDestroy(SecOCSPSingleResponseRef this);
 155
 156 /* Returns the SecCertificateRef whose leaf signed this ocspResponse if
 157    we can find one and NULL if we can't find a valid signer. The issuerPath
 158    contains the cert chain from the anchor to the certificate that issued the
 159    leaf certificate for which this ocspResponse is supposed to be valid. */
 160 SecCertificateRef SecOCSPResponseCopySigner(SecOCSPResponseRef this,
 161     SecCertificateRef issuerPath);
 162
 163 __END_DECLS
 164
 165 #endif /* !_SECURITY_SECOCSPRESPONSE_H_ */