trust/headers/SecCertificatePriv.h

   1 /*
   2  * Copyright (c) 2002-2004,2006-2019 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 SecCertificatePriv
  26     The functions provided in SecCertificatePriv.h implement and manage a particular
  27     type of keychain item that represents a certificate.  You can store a
  28     certificate in a keychain, but a certificate can also be a transient
  29     object.
  30
  31     You can use a certificate as a keychain item in most functions.
  32     Certificates are able to compute their parent certificates, and much more.
  33 */
  34
  35 #ifndef _SECURITY_SECCERTIFICATEPRIV_H_
  36 #define _SECURITY_SECCERTIFICATEPRIV_H_
  37
  38 #include <CoreFoundation/CFBase.h>
  39 #include <CoreFoundation/CFArray.h>
  40 #include <CoreFoundation/CFData.h>
  41 #include <CoreFoundation/CFDate.h>
  42 #include <CoreFoundation/CFDictionary.h>
  43 #include <CoreFoundation/CFError.h>
  44 #include <stdbool.h>
  45 #include <xpc/xpc.h>
  46 #include <security_libDER/libDER/libDER.h>
  47
  48 #include <Security/SecBase.h>
  49 #include <Security/SecBasePriv.h>
  50 #include <Security/SecCertificate.h>
  51
  52 __BEGIN_DECLS
  53
  54 #if SEC_OS_IPHONE
  55 typedef CF_OPTIONS(uint32_t, SecKeyUsage) {
  56     kSecKeyUsageUnspecified      = 0u,
  57     kSecKeyUsageDigitalSignature = 1u << 0,
  58     kSecKeyUsageNonRepudiation   = 1u << 1,
  59     kSecKeyUsageContentCommitment= 1u << 1,
  60     kSecKeyUsageKeyEncipherment  = 1u << 2,
  61     kSecKeyUsageDataEncipherment = 1u << 3,
  62     kSecKeyUsageKeyAgreement     = 1u << 4,
  63     kSecKeyUsageKeyCertSign      = 1u << 5,
  64     kSecKeyUsageCRLSign          = 1u << 6,
  65     kSecKeyUsageEncipherOnly     = 1u << 7,
  66     kSecKeyUsageDecipherOnly     = 1u << 8,
  67     kSecKeyUsageCritical         = 1u << 31,
  68     kSecKeyUsageAll              = 0x7FFFFFFFu
  69 };
  70 #endif /* SEC_OS_IPHONE */
  71
  72 typedef CF_ENUM(uint32_t, SecCertificateEscrowRootType) {
  73     kSecCertificateBaselineEscrowRoot = 0,
  74     kSecCertificateProductionEscrowRoot = 1,
  75     kSecCertificateBaselinePCSEscrowRoot = 2,
  76     kSecCertificateProductionPCSEscrowRoot = 3,
  77     kSecCertificateBaselineEscrowBackupRoot = 4,        // v100 and v101
  78     kSecCertificateProductionEscrowBackupRoot = 5,
  79     kSecCertificateBaselineEscrowEnrollmentRoot = 6,    // v101 only
  80     kSecCertificateProductionEscrowEnrollmentRoot = 7,
  81 };
  82
  83 /* The names of the files that contain the escrow certificates */
  84 extern const CFStringRef kSecCertificateProductionEscrowKey;
  85 extern const CFStringRef kSecCertificateProductionPCSEscrowKey;
  86 extern const CFStringRef kSecCertificateEscrowFileName;
  87
  88 /* Return a certificate for the DER representation of this certificate.
  89  Return NULL if the passed-in data is not a valid DER-encoded X.509
  90  certificate. */
  91 SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
  92                                                 const UInt8 *bytes, CFIndex length)
  93 __SEC_MAC_AND_IOS_UNKNOWN;
  94 //__OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_UNKNOWN);
  95
  96 /* Returns a certificate from a pem blob.
  97  Return NULL if the passed-in data is not a valid DER-encoded X.509
  98  certificate. */
  99 SecCertificateRef SecCertificateCreateWithPEM(CFAllocatorRef allocator, CFDataRef pem_certificate)
 100 __SEC_MAC_AND_IOS_UNKNOWN;
 101 //__OSX_AVAILABLE_STARTING(__MAC_10_12, __SEC_IPHONE_UNKNOWN);
 102
 103 /* Return the length of the DER representation of this certificate. */
 104 CFIndex SecCertificateGetLength(SecCertificateRef certificate);
 105
 106 /* Return the bytes of the DER representation of this certificate. */
 107 const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
 108
 109 /* Return the SHA-1 hash of this certificate. */
 110 CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate)
 111     __SEC_MAC_AND_IOS_UNKNOWN;
 112
 113 CFDataRef SecCertificateCopyIssuerSHA1Digest(SecCertificateRef certificate)
 114     __SEC_MAC_AND_IOS_UNKNOWN;
 115
 116 /* Return the SHA-256 hash of this certificate. */
 117 CFDataRef SecCertificateCopySHA256Digest(SecCertificateRef certificate)
 118     __SEC_MAC_AND_IOS_UNKNOWN;
 119
 120 /* Return the SHA-1 hash of the public key in this certificate. */
 121 CFDataRef SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate)
 122     __SEC_MAC_AND_IOS_UNKNOWN;
 123
 124 /* Return the SHA-1 hash of the SubjectPublicKeyInfo sequence in this certificate. */
 125 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA1Digest(SecCertificateRef certificate)
 126     __SEC_MAC_AND_IOS_UNKNOWN;
 127
 128 /* Return the SHA-256 hash of the SubjectPublicKeyInfo sequence in this certificate. */
 129 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA256Digest(SecCertificateRef certificate)
 130     __SEC_MAC_AND_IOS_UNKNOWN;
 131
 132 /* Return an array of CFStringRefs representing the dns addresses in the
 133  certificate if any. */
 134 CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate)
 135     __SEC_MAC_AND_IOS_UNKNOWN;
 136
 137 /* Return an array of CFStringRefs representing the NTPrincipalNames in the
 138  certificate if any. */
 139 CFArrayRef SecCertificateCopyNTPrincipalNames(SecCertificateRef certificate)
 140     __SEC_MAC_AND_IOS_UNKNOWN;
 141
 142 /* Create a unified SecCertificateRef from a legacy keychain item and its data. */
 143 SecCertificateRef SecCertificateCreateWithKeychainItem(CFAllocatorRef allocator,
 144                                                        CFDataRef der_certificate, CFTypeRef keychainItem)
 145     __SEC_MAC_AND_IOS_UNKNOWN;
 146
 147 /* Set a legacy item instance for a unified SecCertificateRef. */
 148 OSStatus SecCertificateSetKeychainItem(SecCertificateRef certificate, CFTypeRef keychain_item)
 149     __SEC_MAC_AND_IOS_UNKNOWN;
 150
 151 /* Return a keychain item reference, given a unified SecCertificateRef.
 152  Note: On OSX, for this function to succeed, the provided certificate must have been
 153  created by SecCertificateCreateWithKeychainItem, otherwise NULL is returned.
 154  */
 155 CFTypeRef SecCertificateCopyKeychainItem(SecCertificateRef certificate)
 156     __SEC_MAC_AND_IOS_UNKNOWN;
 157
 158 /*!
 159  @function SecCertificateCopyIssuerSummary
 160  @abstract Return a simple string which hopefully represents a human understandable issuer.
 161  @param certificate SecCertificate object created with SecCertificateCreateWithData().
 162  @discussion All the data in this string comes from the certificate itself
 163  and thus it's in whatever language the certificate itself is in.
 164  @result A CFStringRef which the caller should CFRelease() once it's no longer needed.
 165  */
 166 CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
 167
 168 /* Return a string formatted according to RFC 2253 representing the complete
 169  subject of certificate. */
 170 CFStringRef SecCertificateCopySubjectString(SecCertificateRef certificate);
 171
 172 CFMutableArrayRef SecCertificateCopySummaryProperties(
 173                                                       SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 174     __SEC_MAC_AND_IOS_UNKNOWN;
 175
 176 /* Return the content of a DER encoded X.501 name (without the tag and length
 177  fields) for the receiving certificates issuer. */
 178 CFDataRef SecCertificateGetNormalizedIssuerContent(SecCertificateRef certificate)
 179     __SEC_MAC_AND_IOS_UNKNOWN;
 180
 181 /* Return the content of a DER encoded X.501 name (without the tag and length
 182  fields) for the receiving certificates subject. */
 183 CFDataRef SecCertificateGetNormalizedSubjectContent(SecCertificateRef certificate)
 184     __SEC_MAC_AND_IOS_UNKNOWN;
 185
 186 /* Return the DER encoded issuer sequence for the certificate's issuer. */
 187 CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate);
 188
 189 /* Return the DER encoded subject sequence for the certificate's subject. */
 190 CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate);
 191
 192 /* Return an array of CFStringRefs representing the ip addresses in the
 193  certificate if any. */
 194 CFArrayRef SecCertificateCopyIPAddresses(SecCertificateRef certificate);
 195
 196 /* Return an array of CFStringRefs representing the email addresses in the
 197  certificate if any. */
 198 CFArrayRef SecCertificateCopyRFC822Names(SecCertificateRef certificate);
 199
 200 /* Return an array of CFStringRefs representing the common names in the
 201  certificates subject if any. */
 202 CFArrayRef SecCertificateCopyCommonNames(SecCertificateRef certificate);
 203
 204 /* Return an array of CFStringRefs representing the organization in the
 205  certificate's subject if any. */
 206 CFArrayRef SecCertificateCopyOrganization(SecCertificateRef certificate);
 207
 208 /* Return an array of CFStringRefs representing the organizational unit in the
 209  certificate's subject if any. */
 210 CFArrayRef SecCertificateCopyOrganizationalUnit(SecCertificateRef certificate);
 211
 212 /* Return an array of CFStringRefs representing the country in the
 213  certificate's subject if any. */
 214 CFArrayRef SecCertificateCopyCountry(SecCertificateRef certificate);
 215
 216 /* Return a string with the company name of an ev leaf certificate. */
 217 CFStringRef SecCertificateCopyCompanyName(SecCertificateRef certificate);
 218
 219 /* X.509 Certificate Version: 1, 2 or 3. */
 220 CFIndex SecCertificateVersion(SecCertificateRef certificate);
 221
 222 SecKeyUsage SecCertificateGetKeyUsage(SecCertificateRef certificate);
 223
 224 /* Returns an array of CFDataRefs for all extended key usage oids or NULL */
 225 CFArrayRef SecCertificateCopyExtendedKeyUsage(SecCertificateRef certificate);
 226
 227 /*!
 228  @function SecCertificateIsValid
 229  @abstract Check certificate validity on a given date.
 230  @param certificate A certificate reference.
 231  @result Returns true if the specified date falls within the certificate's validity period, false otherwise.
 232  */
 233 bool SecCertificateIsValid(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 234     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 235
 236 /*!
 237  @function SecCertificateNotValidBefore
 238  @abstract Obtain the starting date of the given certificate.
 239  @param certificate A certificate reference.
 240  @result Returns the absolute time at which the given certificate becomes valid,
 241  or 0 if this value could not be obtained.
 242  */
 243 CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate)
 244     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 245
 246 /*!
 247  @function SecCertificateNotValidAfter
 248  @abstract Obtain the expiration date of the given certificate.
 249  @param certificate A certificate reference.
 250  @result Returns the absolute time at which the given certificate expires,
 251  or 0 if this value could not be obtained.
 252  */
 253 CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate)
 254     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 255
 256 /*!
 257  @function SecCertificateIsSelfSigned
 258  @abstract Determine if the given certificate is self-signed.
 259  @param certRef A certificate reference.
 260  @param isSelfSigned Will be set to true on return if the certificate is self-signed, false otherwise.
 261  @result A result code. Returns errSecSuccess if the certificate's status can be determined.
 262  */
 263 OSStatus SecCertificateIsSelfSigned(SecCertificateRef certRef, Boolean *isSelfSigned)
 264     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_9_0);
 265
 266 /*!
 267  @function SecCertificateIsSelfSignedCA
 268  @abstract Determine if the given certificate is self-signed and has a basic
 269  constraints extension indicating it is a certificate authority.
 270  @param certificate A certificate reference.
 271  @result Returns true if the certificate is self-signed and has a basic
 272  constraints extension indicating it is a certificate authority, otherwise false.
 273  */
 274 bool SecCertificateIsSelfSignedCA(SecCertificateRef certificate)
 275     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 276
 277 /*!
 278  @function SecCertificateIsCA
 279  @abstract Determine if the given certificate has a basic
 280  constraints extension indicating it is a certificate authority.
 281  @param certificate A certificate reference.
 282  @result Returns true if the certificate has a basic constraints
 283  extension indicating it is a certificate authority, otherwise false.
 284  */
 285 bool SecCertificateIsCA(SecCertificateRef certificate)
 286     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 287
 288
 289 /* Append certificate to xpc_certificates. */
 290 bool SecCertificateAppendToXPCArray(SecCertificateRef certificate, xpc_object_t xpc_certificates, CFErrorRef *error);
 291
 292 /* Decode certificate from xpc_certificates[index] as encoded by SecCertificateAppendToXPCArray(). */
 293 SecCertificateRef SecCertificateCreateWithXPCArrayAtIndex(xpc_object_t xpc_certificates, size_t index, CFErrorRef *error);
 294
 295 /* Return an xpc_array of data from an array of SecCertificateRefs. */
 296 xpc_object_t SecCertificateArrayCopyXPCArray(CFArrayRef certificates, CFErrorRef *error);
 297
 298 /* Return an array of SecCertificateRefs from a xpc_object array of datas. */
 299 CFArrayRef SecCertificateXPCArrayCopyArray(xpc_object_t xpc_certificates, CFErrorRef *error);
 300
 301 /*!
 302  @function SecCertificateCopyEscrowRoots
 303  @abstract Retrieve the array of valid escrow certificates for a given root type.
 304  @param escrowRootType An enumerated type indicating which root type to return.
 305  @result An array of zero or more escrow certificates matching the provided type.
 306  */
 307 CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType)
 308     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 309
 310 /* Return an attribute dictionary used to store this item in a keychain. */
 311 CFDictionaryRef SecCertificateCopyAttributeDictionary(SecCertificateRef certificate)
 312     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 313
 314 /*
 315  * Enumerated constants for signature hash algorithms.
 316  */
 317 typedef CF_ENUM(uint32_t, SecSignatureHashAlgorithm){
 318     kSecSignatureHashAlgorithmUnknown = 0,
 319     kSecSignatureHashAlgorithmMD2 = 1,
 320     kSecSignatureHashAlgorithmMD4 = 2,
 321     kSecSignatureHashAlgorithmMD5 = 3,
 322     kSecSignatureHashAlgorithmSHA1 = 4,
 323     kSecSignatureHashAlgorithmSHA224 = 5,
 324     kSecSignatureHashAlgorithmSHA256 = 6,
 325     kSecSignatureHashAlgorithmSHA384 = 7,
 326     kSecSignatureHashAlgorithmSHA512 = 8
 327 };
 328
 329 /*!
 330  @function SecCertificateGetSignatureHashAlgorithm
 331  @abstract Determine the hash algorithm used in a certificate's signature.
 332  @param certificate A certificate reference.
 333  @result Returns an enumerated value indicating the signature hash algorithm
 334  used in a certificate. If the hash algorithm is unsupported or cannot be
 335  obtained (e.g. because the supplied certificate reference is invalid), a
 336  value of 0 (kSecSignatureHashAlgorithmUnknown) is returned.
 337  */
 338 SecSignatureHashAlgorithm SecCertificateGetSignatureHashAlgorithm(SecCertificateRef certificate)
 339     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 340
 341 /*!
 342  @function SecCertificateCopyProperties
 343  @abstract Return a property array for this certificate.
 344  @param certificate A reference to the certificate to evaluate.
 345  @result A property array. It is the caller's responsibility to CFRelease
 346  the returned array when it is no longer needed.
 347  See SecTrustCopySummaryPropertiesAtIndex on how to interpret this array.
 348  Unlike that function, this function returns a detailed description of the
 349  certificate. Note that localized description strings are returned by default.
 350  Use SecCertificateCopyLocalizedProperties if your code needs to explicitly
 351  specify whether the strings are localized.
 352  */
 353 CFArrayRef SecCertificateCopyProperties(SecCertificateRef certificate);
 354
 355 /*!
 356  @function SecCertificateCopyLocalizedProperties
 357  @abstract Return a property array for this certificate.
 358  @param certificate A reference to the certificate to evaluate.
 359  @param localized A value which specifies whether string properties
 360  are localized. If false, description strings will not be localized.
 361  @result A property array. It is the caller's responsibility to CFRelease
 362  the returned array when it is no longer needed.
 363  See SecTrustCopySummaryPropertiesAtIndex on how to interpret this array.
 364  Unlike that function, this function returns a detailed description of the
 365  certificate.
 366  */
 367 CFArrayRef SecCertificateCopyLocalizedProperties(SecCertificateRef certificate, Boolean localized)
 368     API_AVAILABLE(macos(10.15.1), ios(13.2), watchos(6.1), tvos(13.1));
 369
 370 /* Returns an array of CFDataRefs for all embedded SCTs */
 371 CFArrayRef SecCertificateCopySignedCertificateTimestamps(SecCertificateRef certificate)
 372     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 373
 374 /* Return the precert TBSCertificate DER data - used for Certificate Transparency */
 375 CFDataRef SecCertificateCopyPrecertTBS(SecCertificateRef certificate)
 376     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 377
 378 /* Returns a dictionary of dictionaries for system-trusted CT logs, indexed by the LogID */
 379 CFDictionaryRef SecCertificateCopyTrustedCTLogs(void)
 380     __OSX_AVAILABLE_STARTING(__MAC_10_15, __IPHONE_13_0);
 381
 382 /* Returns a dictionary for the CT log matching the provided
 383  * key ID, or NULL if no matching log is found.
 384  * And by keyID we mean LogID as specified in RFC 6962.
 385  */
 386 CFDictionaryRef SecCertificateCopyCTLogForKeyID(CFDataRef keyID)
 387     __OSX_AVAILABLE_STARTING(__MAC_10_15, __IPHONE_13_0);
 388
 389 /* Return the auth capabilities bitmask from the iAP marker extension */
 390 CF_RETURNS_RETAINED CFDataRef SecCertificateCopyiAPAuthCapabilities(SecCertificateRef certificate)
 391     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 392
 393 typedef CF_ENUM(uint32_t, SeciAuthVersion) {
 394     kSeciAuthInvalid = 0,
 395     kSeciAuthVersion1 = 1, /* unused */
 396     kSeciAuthVersion2 = 2,
 397     kSeciAuthVersion3 = 3,
 398     kSeciAuthVersionSW = 4,
 399 } __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 400
 401 /* Return the iAuth version indicated by the certificate. This function does
 402  * not guarantee that the certificate is valid, so the caller must still call
 403  * SecTrustEvaluate to guarantee that the certificate was properly issued */
 404 SeciAuthVersion SecCertificateGetiAuthVersion(SecCertificateRef certificate)
 405     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 406
 407 /* Return the normalized name or NULL if it fails to parse */
 408 CFDataRef SecDistinguishedNameCopyNormalizedSequence(CFDataRef distinguished_name)
 409     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 410
 411 /* Returns the Subject Key ID extension from the certificate or NULL if none */
 412 CFDataRef SecCertificateGetSubjectKeyID(SecCertificateRef certificate)
 413     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 414
 415 /* Returns an array of SecCertificateRefs containing the iPhone Device CA and
 416  * its parent certificates. This interface is meant as a workaround and should
 417  * not be used without consulting the Security team. */
 418 CFArrayRef SecCertificateCopyiPhoneDeviceCAChain(void)
 419     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 420
 421 typedef CF_ENUM(uint32_t, SeciAPSWAuthCapabilitiesType) {
 422     kSeciAPSWAuthGeneralCapabilities = 0,
 423     kSeciAPSWAuthAirPlayCapabilities = 1,
 424     kSeciAPSWAuthHomeKitCapabilities = 2,
 425 } __OSX_AVAILABLE_STARTING(__MAC_10_13_4, __IPHONE_11_3);
 426
 427 /* Return the iAP SW Auth capabilities bitmask from the specificed
 428  * SeciAPSWAuthCapabilitiesType type marker extensions. */
 429 CF_RETURNS_RETAINED
 430 CFDataRef SecCertificateCopyiAPSWAuthCapabilities(SecCertificateRef certificate,
 431                                                   SeciAPSWAuthCapabilitiesType type)
 432     __OSX_AVAILABLE_STARTING(__MAC_10_13_4, __IPHONE_11_3);
 433
 434 /*!
 435  @function SecCertificateCopyExtensionValue
 436  @abstract Return the value in an extension of a certificate.
 437  @param certificate A reference to the certificate containing the desired extension
 438  @param extensionOID A CFData containing the binary value of ObjectIdentifier of the
 439  desired extension or a CFString containing the decimal value of the ObjectIdentifier.
 440  @param isCritical On return, a boolean value representing whether the extension was critical.
 441  @result If an extension exists in the certificate with the extensionOID, the returned CFData
 442  is the (unparsed) Value of the extension.
 443  @discussion If the certificate has multiple extensions with the same extension OID, the first
 444  extension with the input OID is returned.
 445  */
 446 CF_RETURNS_RETAINED
 447 CFDataRef SecCertificateCopyExtensionValue(SecCertificateRef certificate,
 448                                            CFTypeRef extensionOID, bool *isCritical)
 449     __OSX_AVAILABLE_STARTING(__MAC_10_13_4, __IPHONE_11_3);
 450
 451 /* Return an array of CFURLRefs each of which is an ocspResponder for this
 452  certificate. */
 453 CFArrayRef SecCertificateGetOCSPResponders(SecCertificateRef certificate)
 454     API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
 455
 456
 457 /* Return the component type string in a component certificate. */
 458 CF_RETURNS_RETAINED
 459 CFStringRef SecCertificateCopyComponentType(SecCertificateRef certificate)
 460     API_AVAILABLE(macos(10.15), ios(13.0), watchos(6.0), tvos(13.0));
 461
 462 bool SecCertificateGetDeveloperIDDate(SecCertificateRef certificate, CFAbsoluteTime *time, CFErrorRef * CF_RETURNS_RETAINED error);
 463
 464 CFAbsoluteTime SecAbsoluteTimeFromDateContentWithError(DERTag tag, const uint8_t *bytes, size_t length, CFErrorRef *error);
 465
 466 /*
 467  * Legacy functions (OS X only)
 468  */
 469 #if SEC_OS_OSX
 470 #include <Security/cssmtype.h>
 471 #include <Security/x509defs.h>
 472
 473 /* Given a unified SecCertificateRef, return a copy with a legacy
 474  C++ ItemImpl-based Certificate instance. Only for internal use;
 475  legacy references cannot be used by SecCertificate API functions. */
 476 SecCertificateRef SecCertificateCreateItemImplInstance(SecCertificateRef certificate)
 477     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 478
 479 /* Inverse of above; convert legacy Certificate instance to new ref. */
 480 SecCertificateRef SecCertificateCreateFromItemImplInstance(SecCertificateRef certificate)
 481     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 482
 483
 484 /* Convenience function to determine type of certificate instance. */
 485 Boolean SecCertificateIsItemImplInstance(SecCertificateRef certificate)
 486     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 487
 488 /* Given a legacy C++ ItemImpl-based Certificate instance obtained with
 489  SecCertificateCreateItemImplInstance, return its clHandle pointer.
 490  Only for internal use. */
 491 OSStatus SecCertificateGetCLHandle_legacy(SecCertificateRef certificate, CSSM_CL_HANDLE *clHandle)
 492     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 493
 494 /* Deprecated; use SecCertificateCopyCommonName() instead. */
 495 OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName)
 496     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_5, __IPHONE_NA, __IPHONE_NA, "SecCertificateGetCommonName is deprecated. Use SecCertificateCopyCommonName instead.");
 497
 498 /* Deprecated; use SecCertificateCopyEmailAddresses() instead. */
 499 /* This should have been Copy instead of Get since the returned address is not autoreleased. */
 500 OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress)
 501     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_5, __IPHONE_NA, __IPHONE_NA, "SecCertificateGetEmailAddress is deprecated. Use SecCertificateCopyEmailAddresses instead.");
 502
 503 /*
 504  * Private API to infer a display name for a SecCertificateRef which
 505  * may or may not be in a keychain.
 506  */
 507 OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label);
 508
 509 /*
 510  * Subset of the above, useful for both certs and CRLs.
 511  * Infer printable label for a given an CSSM_X509_NAME. Returns NULL
 512  * if no appropriate printable name found.
 513  */
 514 const CSSM_DATA *SecInferLabelFromX509Name(
 515      const CSSM_X509_NAME *x509Name)
 516     DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 517
 518 /* Accessors for fields in the cached certificate */
 519
 520 /*!
 521      @function SecCertificateCopyFieldValues
 522      @abstract Retrieves the values for a particular field in a given certificate.
 523     @param certificate A valid SecCertificateRef to the certificate.
 524     @param field Pointer to the OID whose values should be returned.
 525     @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's.
 526      @result A result code.  See "Security Error Codes" (SecBase.h).
 527      @discussion Return a zero terminated list of CSSM_DATA_PTR's with the
 528      values of the field specified by field.  Caller must call
 529      SecCertificateReleaseFieldValues to free the storage allocated by this call.
 530 */
 531 OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues)
 532     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateCopyFieldValues is deprecated. Use SecCertificateCopyValues instead.");
 533
 534 /*!
 535      @function SecCertificateReleaseFieldValues
 536      @abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 537     @param certificate A valid SecCertificateRef to the certificate.
 538     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues.
 539     @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's.
 540      @result A result code.  See "Security Error Codes" (SecBase.h).
 541      @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 542 */
 543 OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues)
 544     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateReleaseFieldValues is deprecated. Use SecCertificateCopyValues instead.");
 545
 546 /*!
 547      @function SecCertificateCopyFirstFieldValue
 548      @abstract Return a CSSM_DATA_PTR with the value of the first field specified by field.
 549     @param certificate A valid SecCertificateRef to the certificate.
 550     @param field Pointer to the OID whose value should be returned.
 551     @param fieldValue On return, a CSSM_DATA_PTR to the field data.
 552      @result A result code.  See "Security Error Codes" (SecBase.h).
 553      @discussion Return a CSSM_DATA_PTR with the value of the first field specified by field.  Caller must call
 554      SecCertificateReleaseFieldValue to free the storage allocated by this call.
 555 */
 556 OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue)
 557     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateCopyFirstFieldValue is deprecated. Use SecCertificateCopyValues instead.");
 558
 559 /*!
 560      @function SecCertificateReleaseFirstFieldValue
 561      @abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue.
 562     @param certificate A valid SecCertificateRef to the certificate.
 563     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue.
 564     @param fieldValue The field data to release.
 565      @result A result code.  See "Security Error Codes" (SecBase.h).
 566      @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue.
 567 */
 568 OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue)
 569     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateReleaseFirstFieldValue is deprecated. Use SecCertificateCopyValues instead.");
 570
 571 /*!
 572     @function SecCertificateCopySubjectComponent
 573     @abstract Retrieves a component of the subject distinguished name of a given certificate.
 574     @param certificate A reference to the certificate from which to retrieve the common name.
 575      @param component A component oid naming the component desired. See <Security/oidsattr.h>.
 576     @param result On return, a reference to the string form of the component, if present in the subject.
 577           Your code must release this reference by calling the CFRelease function.
 578     @result A result code. See "Security Error Codes" (SecBase.h).
 579  */
 580 OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
 581      CFStringRef *result)
 582     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateCopySubjectComponent is deprecated. Use SecCertificateCopyCommonNames,SecCertificateCopyOrganization,SecCertificateCopyOrganizationalUnit, etc. instead.");
 583
 584 /*     Convenience functions for searching.
 585  */
 586 OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 587                                          const CSSM_DATA *serialNumber,      SecCertificateRef *certificate)
 588     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateFindByIssuerAndSN is deprecated. Use SecItemCopyMatching instead.");
 589
 590 OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 591                                           SecCertificateRef *certificate)
 592     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateFindBySubjectKeyID is deprecated. Use SecItemCopyMatching instead.");
 593
 594 OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 595                                    SecCertificateRef *certificate)
 596     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateFindByEmail is deprecated. Use SecItemCopyMatching instead.");
 597
 598 /* These should go to SecKeychainSearchPriv.h. */
 599 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 600                                                             const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef)
 601     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateByIssuerAndSN is deprecated. Use SecItemCopyMatching instead.");
 602
 603 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
 604                                                                CFDataRef serialNumber, SecKeychainSearchRef *searchRef)
 605     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateByIssuerAndSN_CF is deprecated. Use SecItemCopyMatching instead.");
 606
 607 OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 608                                                              SecKeychainSearchRef *searchRef)
 609     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateBySubjectKeyID is deprecated. Use SecItemCopyMatching instead.");
 610
 611 OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 612                                                       SecKeychainSearchRef *searchRef)
 613     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateByEmail is deprecated. Use SecItemCopyMatching instead.");
 614
 615 /* Convenience function for generating digests; should be moved elsewhere. */
 616 CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data)
 617     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA);
 618
 619 /* Return true iff certificate is valid as of verifyTime. */
 620 /* DEPRECATED: Use SecCertificateIsValid instead. */
 621 bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 622     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
 623
 624 /*!
 625   @function SecCertificateCopyPublicKeySHA1DigestFromCertificateData
 626   @abstract Returns the SHA1 hash of the public key of a certificate or NULL
 627   @param allocator CFAllocator to allocate the certificate with.
 628   @param der_certificate DER encoded X.509 certificate.
 629   @result SHA1 hash of the public key of a certificate or NULL
 630 */
 631 CFDataRef SecCertificateCopyPublicKeySHA1DigestFromCertificateData(CFAllocatorRef allocator,
 632                                                                    CFDataRef der_certificate)
 633     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_13_2, __IPHONE_NA, __IPHONE_NA); // Likely incorrect.
 634
 635 #endif /* SEC_OS_OSX */
 636
 637 __END_DECLS
 638
 639 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */