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 /* Return the auth capabilities bitmask from the iAP marker extension */
 361 CF_RETURNS_RETAINED CFDataRef SecCertificateCopyiAPAuthCapabilities(SecCertificateRef certificate)
 362     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 363
 364 typedef CF_ENUM(uint32_t, SeciAuthVersion) {
 365     kSeciAuthInvalid = 0,
 366     kSeciAuthVersion1 = 1, /* unused */
 367     kSeciAuthVersion2 = 2,
 368     kSeciAuthVersion3 = 3,
 369     kSeciAuthVersionSW = 4,
 370 } __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 371
 372 /* Return the iAuth version indicated by the certificate. This function does
 373  * not guarantee that the certificate is valid, so the caller must still call
 374  * SecTrustEvaluate to guarantee that the certificate was properly issued */
 375 SeciAuthVersion SecCertificateGetiAuthVersion(SecCertificateRef certificate)
 376     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 377
 378 /* Return the normalized name or NULL if it fails to parse */
 379 CFDataRef SecDistinguishedNameCopyNormalizedSequence(CFDataRef distinguished_name)
 380     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 381
 382 /* Returns the Subject Key ID extension from the certificate or NULL if none */
 383 CFDataRef SecCertificateGetSubjectKeyID(SecCertificateRef certificate)
 384     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 385
 386 /* Returns an array of SecCertificateRefs containing the iPhone Device CA and
 387  * its parent certificates. This interface is meant as a workaround and should
 388  * not be used without consulting the Security team. */
 389 CFArrayRef SecCertificateCopyiPhoneDeviceCAChain(void)
 390     __OSX_AVAILABLE_STARTING(__MAC_10_13, __IPHONE_11_0);
 391
 392
 393 /*!
 394  @function SecCertificateCopyExtensionValue
 395  @abstract Return the value in an extension of a certificate.
 396  @param certificate A reference to the certificate containing the desired extension
 397  @param extensionOID A CFData containing the binary value of ObjectIdentifier of the
 398  desired extension or a CFString containing the decimal value of the ObjectIdentifier.
 399  @param isCritical On return, a boolean value representing whether the extension was critical.
 400  @result If an extension exists in the certificate with the extensionOID, the returned CFData
 401  is the (unparsed) Value of the extension.
 402  @discussion If the certificate has multiple extensions with the same extension OID, the first
 403  extension with the input OID is returned.
 404  */
 405 CF_RETURNS_RETAINED
 406 CFDataRef SecCertificateCopyExtensionValue(SecCertificateRef certificate,
 407                                            CFTypeRef extensionOID, bool *isCritical)
 408     __OSX_AVAILABLE_STARTING(__MAC_10_13_4, __IPHONE_11_3);
 409
 410 /* Return a (modern) SecKeyRef for the public key embedded in the cert. */
 411 #if TARGET_OS_OSX
 412     SecKeyRef SecCertificateCopyPublicKey_ios(SecCertificateRef certificate);
 413 #endif
 414
 415 /*
 416  * Legacy functions (OS X only)
 417  */
 418 #if SEC_OS_OSX
 419 #include <Security/cssmtype.h>
 420 #include <Security/x509defs.h>
 421
 422 /* Given a unified SecCertificateRef, return a copy with a legacy
 423  C++ ItemImpl-based Certificate instance. Only for internal use;
 424  legacy references cannot be used by SecCertificate API functions. */
 425 SecCertificateRef SecCertificateCreateItemImplInstance(SecCertificateRef certificate)
 426     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 427
 428 /* Inverse of above; convert legacy Certificate instance to new ref. */
 429 SecCertificateRef SecCertificateCreateFromItemImplInstance(SecCertificateRef certificate)
 430     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 431
 432
 433 /* Convenience function to determine type of certificate instance. */
 434 Boolean SecCertificateIsItemImplInstance(SecCertificateRef certificate)
 435     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 436
 437 /* Given a legacy C++ ItemImpl-based Certificate instance obtained with
 438  SecCertificateCreateItemImplInstance, return its clHandle pointer.
 439  Only for internal use. */
 440 OSStatus SecCertificateGetCLHandle_legacy(SecCertificateRef certificate, CSSM_CL_HANDLE *clHandle)
 441     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_NA);
 442
 443 /* Deprecated; use SecCertificateCopyCommonName() instead. */
 444 OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName)
 445     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_5, __IPHONE_NA, __IPHONE_NA, "SecCertificateGetCommonName is deprecated. Use SecCertificateCopyCommonName instead.");
 446
 447 /* Deprecated; use SecCertificateCopyEmailAddresses() instead. */
 448 /* This should have been Copy instead of Get since the returned address is not autoreleased. */
 449 OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress)
 450     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_5, __IPHONE_NA, __IPHONE_NA, "SecCertificateGetEmailAddress is deprecated. Use SecCertificateCopyEmailAddresses instead.");
 451
 452 /*
 453  * Private API to infer a display name for a SecCertificateRef which
 454  * may or may not be in a keychain.
 455  */
 456 OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label);
 457
 458 /*
 459  * Subset of the above, useful for both certs and CRLs.
 460  * Infer printable label for a given an CSSM_X509_NAME. Returns NULL
 461  * if no appropriate printable name found.
 462  */
 463 const CSSM_DATA *SecInferLabelFromX509Name(
 464      const CSSM_X509_NAME *x509Name);
 465
 466 /* Accessors for fields in the cached certificate */
 467
 468 /*!
 469      @function SecCertificateCopyFieldValues
 470      @abstract Retrieves the values for a particular field in a given certificate.
 471     @param certificate A valid SecCertificateRef to the certificate.
 472     @param field Pointer to the OID whose values should be returned.
 473     @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's.
 474      @result A result code.  See "Security Error Codes" (SecBase.h).
 475      @discussion Return a zero terminated list of CSSM_DATA_PTR's with the
 476      values of the field specified by field.  Caller must call
 477      SecCertificateReleaseFieldValues to free the storage allocated by this call.
 478 */
 479 OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues)
 480     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateCopyFieldValues is deprecated. Use SecCertificateCopyValues instead.");
 481
 482 /*!
 483      @function SecCertificateReleaseFieldValues
 484      @abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 485     @param certificate A valid SecCertificateRef to the certificate.
 486     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues.
 487     @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's.
 488      @result A result code.  See "Security Error Codes" (SecBase.h).
 489      @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 490 */
 491 OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues)
 492     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateReleaseFieldValues is deprecated. Use SecCertificateCopyValues instead.");
 493
 494 /*!
 495      @function SecCertificateCopyFirstFieldValue
 496      @abstract Return a CSSM_DATA_PTR with the value of the first field specified by field.
 497     @param certificate A valid SecCertificateRef to the certificate.
 498     @param field Pointer to the OID whose value should be returned.
 499     @param fieldValue On return, a CSSM_DATA_PTR to the field data.
 500      @result A result code.  See "Security Error Codes" (SecBase.h).
 501      @discussion Return a CSSM_DATA_PTR with the value of the first field specified by field.  Caller must call
 502      SecCertificateReleaseFieldValue to free the storage allocated by this call.
 503 */
 504 OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue)
 505     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateCopyFirstFieldValue is deprecated. Use SecCertificateCopyValues instead.");
 506
 507 /*!
 508      @function SecCertificateReleaseFirstFieldValue
 509      @abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue.
 510     @param certificate A valid SecCertificateRef to the certificate.
 511     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue.
 512     @param fieldValue The field data to release.
 513      @result A result code.  See "Security Error Codes" (SecBase.h).
 514      @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue.
 515 */
 516 OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue)
 517     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateReleaseFirstFieldValue is deprecated. Use SecCertificateCopyValues instead.");
 518
 519 /*!
 520     @function SecCertificateCopySubjectComponent
 521     @abstract Retrieves a component of the subject distinguished name of a given certificate.
 522     @param certificate A reference to the certificate from which to retrieve the common name.
 523      @param component A component oid naming the component desired. See <Security/oidsattr.h>.
 524     @param result On return, a reference to the string form of the component, if present in the subject.
 525           Your code must release this reference by calling the CFRelease function.
 526     @result A result code. See "Security Error Codes" (SecBase.h).
 527  */
 528 OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
 529      CFStringRef *result)
 530     __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.");
 531
 532 /*     Convenience functions for searching.
 533  */
 534 OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 535                                          const CSSM_DATA *serialNumber,      SecCertificateRef *certificate)
 536     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateFindByIssuerAndSN is deprecated. Use SecItemCopyMatching instead.");
 537
 538 OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 539                                           SecCertificateRef *certificate)
 540     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateFindBySubjectKeyID is deprecated. Use SecItemCopyMatching instead.");
 541
 542 OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 543                                    SecCertificateRef *certificate)
 544     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecCertificateFindByEmail is deprecated. Use SecItemCopyMatching instead.");
 545
 546 /* These should go to SecKeychainSearchPriv.h. */
 547 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 548                                                             const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef)
 549     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateByIssuerAndSN is deprecated. Use SecItemCopyMatching instead.");
 550
 551 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
 552                                                                CFDataRef serialNumber, SecKeychainSearchRef *searchRef)
 553     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateByIssuerAndSN_CF is deprecated. Use SecItemCopyMatching instead.");
 554
 555 OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 556                                                              SecKeychainSearchRef *searchRef)
 557     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateBySubjectKeyID is deprecated. Use SecItemCopyMatching instead.");
 558
 559 OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 560                                                       SecKeychainSearchRef *searchRef)
 561     __OSX_AVAILABLE_BUT_DEPRECATED_MSG(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA, "SecKeychainSearchCreateForCertificateByEmail is deprecated. Use SecItemCopyMatching instead.");
 562
 563 /* Convenience function for generating digests; should be moved elsewhere. */
 564 CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data)
 565     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_0, __MAC_10_12_4, __IPHONE_NA, __IPHONE_NA);
 566
 567 /* Return true iff certificate is valid as of verifyTime. */
 568 /* DEPRECATED: Use SecCertificateIsValid instead. */
 569 bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 570     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
 571
 572 /*!
 573   @function SecCertificateCopyPublicKeySHA1DigestFromCertificateData
 574   @abstract Returns the SHA1 hash of the public key of a certificate or NULL
 575   @param allocator CFAllocator to allocate the certificate with.
 576   @param der_certificate DER encoded X.509 certificate.
 577   @result SHA1 hash of the public key of a certificate or NULL
 578 */
 579 CFDataRef SecCertificateCopyPublicKeySHA1DigestFromCertificateData(CFAllocatorRef allocator,
 580                                                                    CFDataRef der_certificate)
 581     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_13_2, __IPHONE_NA, __IPHONE_NA); // Likely incorrect.
 582
 583 #endif /* SEC_OS_OSX */
 584
 585 __END_DECLS
 586
 587 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */