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