trust/SecCertificatePriv.h

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