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