OSX/sec/securityd/SecOCSPResponse.h

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