OSX/libsecurity_keychain/lib/SecCertificatePriv.h

   1 /*
   2  * Copyright (c) 2002-2004,2011-2016 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 #ifndef _SECURITY_SECCERTIFICATEPRIV_H_
  25 #define _SECURITY_SECCERTIFICATEPRIV_H_
  26
  27 #include <Security/SecBase.h>
  28 #include <Security/cssmtype.h>
  29 #include <Security/x509defs.h>
  30 #include <CoreFoundation/CFBase.h>
  31 #include <CoreFoundation/CFArray.h>
  32 #include <CoreFoundation/CFData.h>
  33 #include <CoreFoundation/CFDate.h>
  34 #include <CoreFoundation/CFDictionary.h>
  35
  36 #if defined(__cplusplus)
  37 extern "C" {
  38 #endif
  39
  40 typedef CF_ENUM(uint32_t, SecCertificateEscrowRootType) {
  41     kSecCertificateBaselineEscrowRoot = 0,
  42     kSecCertificateProductionEscrowRoot = 1,
  43     kSecCertificateBaselinePCSEscrowRoot = 2,
  44     kSecCertificateProductionPCSEscrowRoot = 3,
  45     kSecCertificateBaselineEscrowBackupRoot = 4,        // v100 and v101
  46     kSecCertificateProductionEscrowBackupRoot = 5,
  47     kSecCertificateBaselineEscrowEnrollmentRoot = 6,    // v101 only
  48     kSecCertificateProductionEscrowEnrollmentRoot = 7,
  49 };
  50
  51 extern const CFStringRef kSecCertificateProductionEscrowKey;
  52 extern const CFStringRef kSecCertificateProductionPCSEscrowKey;
  53 extern const CFStringRef kSecCertificateEscrowFileName;
  54
  55
  56 /* Given a unified SecCertificateRef, return a copy with a legacy
  57    C++ ItemImpl-based Certificate instance. Only for internal use;
  58    legacy references cannot be used by SecCertificate API functions. */
  59 SecCertificateRef SecCertificateCreateItemImplInstance(SecCertificateRef certificate);
  60
  61 /* Inverse of above; convert legacy Certificate instance to new ref. */
  62 SecCertificateRef SecCertificateCreateFromItemImplInstance(SecCertificateRef certificate);
  63
  64 /* Convenience function to determine type of certificate instance. */
  65 Boolean SecCertificateIsItemImplInstance(SecCertificateRef certificate);
  66
  67
  68 /* Given a legacy C++ ItemImpl-based Certificate instance obtained with
  69    SecCertificateCreateItemImplInstance, return its clHandle pointer.
  70    Only for internal use. */
  71 OSStatus SecCertificateGetCLHandle_legacy(SecCertificateRef certificate, CSSM_CL_HANDLE *clHandle);
  72
  73 /* Return a certificate for the DER representation of this certificate.
  74    Return NULL if the passed-in data is not a valid DER-encoded X.509
  75    certificate. */
  76 SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
  77     const UInt8 *bytes, CFIndex length);
  78
  79 /* Returns a certificate from a pem blob.
  80    Return NULL if the passed-in data is not a valid DER-encoded X.509
  81    certificate. */
  82 SecCertificateRef SecCertificateCreateWithPEM(CFAllocatorRef allocator,
  83     CFDataRef pem_certificate);
  84
  85 /* Return the length of the DER representation of this certificate. */
  86 CFIndex SecCertificateGetLength(SecCertificateRef certificate);
  87
  88 /* Return the bytes of the DER representation of this certificate. */
  89 const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
  90
  91 /* Return the SHA-1 hash of this certificate. */
  92 CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate);
  93
  94 /* Return the SHA-256 hash of this certificate. */
  95 CFDataRef SecCertificateCopySHA256Digest(SecCertificateRef certificate);
  96
  97 /* Return the SHA-1 hash of the public key in this certificate. */
  98 CFDataRef SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate);
  99
 100 /* Return the SHA-1 hash of the SubjectPublicKeyInfo sequence in this certificate. */
 101 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA1Digest(SecCertificateRef certificate);
 102
 103 /* Return the SHA-256 hash of the SubjectPublicKeyInfo sequence in this certificate. */
 104 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA256Digest(SecCertificateRef certificate);
 105
 106 /* Deprecated; use SecCertificateCopyCommonName() instead. */
 107 OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName);
 108
 109 /* Deprecated; use SecCertificateCopyEmailAddresses() instead. */
 110 /* This should have been Copy instead of Get since the returned address is not autoreleased. */
 111 OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress);
 112
 113 /* Return an array of CFStringRefs representing the dns addresses in the
 114    certificate if any. */
 115 CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate);
 116
 117 /* Return an array of CFStringRefs representing the NTPrincipalNames in the
 118    certificate if any. */
 119 CFArrayRef SecCertificateCopyNTPrincipalNames(SecCertificateRef certificate);
 120
 121 /* Create a unified SecCertificateRef from a legacy keychain item and its data. */
 122 SecCertificateRef SecCertificateCreateWithKeychainItem(CFAllocatorRef allocator,
 123         CFDataRef der_certificate, CFTypeRef keychainItem);
 124
 125 /* Set a legacy item instance for a unified SecCertificateRef. */
 126 OSStatus SecCertificateSetKeychainItem(SecCertificateRef certificate,
 127         CFTypeRef keychain_item);
 128
 129 /* Return a keychain item reference, given a unified SecCertificateRef.
 130    Note: for this function to succeed, the provided certificate must have been
 131    created by SecCertificateCreateWithKeychainItem, otherwise NULL is returned.
 132  */
 133 CFTypeRef SecCertificateCopyKeychainItem(SecCertificateRef certificate);
 134
 135 /*!
 136         @function SecCertificateCopyIssuerSummary
 137         @abstract Return a simple string which hopefully represents a human understandable issuer.
 138         @param certificate SecCertificate object created with SecCertificateCreateWithData().
 139         @discussion All the data in this string comes from the certificate itself
 140         and thus it's in whatever language the certificate itself is in.
 141         @result A CFStringRef which the caller should CFRelease() once it's no longer needed.
 142 */
 143 CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
 144
 145 /* Return a string formatted according to RFC 2253 representing the complete
 146    subject of certificate. */
 147 CFStringRef SecCertificateCopySubjectString(SecCertificateRef certificate);
 148
 149 CFMutableArrayRef SecCertificateCopySummaryProperties(
 150     SecCertificateRef certificate, CFAbsoluteTime verifyTime);
 151
 152 /*
 153  * Private API to infer a display name for a SecCertificateRef which
 154  * may or may not be in a keychain.
 155  */
 156 OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label);
 157
 158 /*
 159  * Subset of the above, useful for both certs and CRLs.
 160  * Infer printable label for a given an CSSM_X509_NAME. Returns NULL
 161  * if no appropriate printable name found.
 162  */
 163 const CSSM_DATA *SecInferLabelFromX509Name(
 164         const CSSM_X509_NAME *x509Name);
 165
 166 /* Accessors for fields in the cached certificate */
 167
 168 /*!
 169         @function SecCertificateCopyFieldValues
 170         @abstract Retrieves the values for a particular field in a given certificate.
 171     @param certificate A valid SecCertificateRef to the certificate.
 172     @param field Pointer to the OID whose values should be returned.
 173     @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's.
 174         @result A result code.  See "Security Error Codes" (SecBase.h).
 175         @discussion Return a zero terminated list of CSSM_DATA_PTR's with the
 176         values of the field specified by field.  Caller must call
 177         SecCertificateReleaseFieldValues to free the storage allocated by this call.
 178 */
 179 OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues);
 180
 181 /*!
 182         @function SecCertificateReleaseFieldValues
 183         @abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 184     @param certificate A valid SecCertificateRef to the certificate.
 185     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues.
 186     @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's.
 187         @result A result code.  See "Security Error Codes" (SecBase.h).
 188         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 189 */
 190 OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues);
 191
 192 /*!
 193         @function SecCertificateCopyFirstFieldValue
 194         @abstract Return a CSSM_DATA_PTR with the value of the first field specified by field.
 195     @param certificate A valid SecCertificateRef to the certificate.
 196     @param field Pointer to the OID whose value should be returned.
 197     @param fieldValue On return, a CSSM_DATA_PTR to the field data.
 198         @result A result code.  See "Security Error Codes" (SecBase.h).
 199         @discussion Return a CSSM_DATA_PTR with the value of the first field specified by field.  Caller must call
 200         SecCertificateReleaseFieldValue to free the storage allocated by this call.
 201 */
 202 OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue);
 203
 204 /*!
 205         @function SecCertificateReleaseFirstFieldValue
 206         @abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue.
 207     @param certificate A valid SecCertificateRef to the certificate.
 208     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue.
 209     @param fieldValue The field data to release.
 210         @result A result code.  See "Security Error Codes" (SecBase.h).
 211         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue.
 212 */
 213 OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue);
 214
 215 /*!
 216     @function SecCertificateCopySubjectComponent
 217     @abstract Retrieves a component of the subject distinguished name of a given certificate.
 218     @param certificate A reference to the certificate from which to retrieve the common name.
 219         @param component A component oid naming the component desired. See <Security/oidsattr.h>.
 220     @param result On return, a reference to the string form of the component, if present in the subject.
 221                 Your code must release this reference by calling the CFRelease function.
 222     @result A result code. See "Security Error Codes" (SecBase.h).
 223  */
 224 OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
 225         CFStringRef *result);
 226
 227 /* Return the DER encoded issuer sequence for the certificate's issuer. */
 228 CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate);
 229
 230 /* Return the DER encoded subject sequence for the certificate's subject. */
 231 CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate);
 232
 233 #if (SECTRUST_OSX && TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE || TARGET_IPHONE_SIMULATOR))
 234 CFDataRef SecCertificateGetNormalizedIssuerContent(SecCertificateRef certificate);
 235 CFDataRef SecCertificateGetNormalizedSubjectContent(SecCertificateRef certificate);
 236 CFDataRef SecCertificateCopyNormalizedIssuerSequence(SecCertificateRef certificate);
 237 CFDataRef SecCertificateCopyNormalizedSubjectSequence(SecCertificateRef certificate);
 238 #endif
 239
 240 /*      Convenience functions for searching.
 241 */
 242
 243 OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 244         const CSSM_DATA *serialNumber,  SecCertificateRef *certificate);
 245
 246 OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 247         SecCertificateRef *certificate);
 248
 249 OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 250         SecCertificateRef *certificate);
 251
 252
 253 /* These should go to SecKeychainSearchPriv.h. */
 254 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 255         const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef);
 256
 257 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
 258         CFDataRef serialNumber, SecKeychainSearchRef *searchRef);
 259
 260 OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 261         SecKeychainSearchRef *searchRef);
 262
 263 OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 264         SecKeychainSearchRef *searchRef);
 265
 266 /* Convenience function for generating digests; should be moved elsewhere. */
 267 CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data);
 268
 269 /* Return true iff certificate is valid as of verifyTime. */
 270 /* DEPRECATED: Use SecCertificateIsValid instead. */
 271 bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 272     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
 273
 274 /*!
 275         @function SecCertificateIsValid
 276         @abstract Check certificate validity on a given date.
 277         @param certificate A certificate reference.
 278         @result Returns true if the specified date falls within the certificate's validity period, false otherwise.
 279 */
 280 bool SecCertificateIsValid(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 281         __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 282
 283 /*!
 284         @function SecCertificateNotValidBefore
 285         @abstract Obtain the starting date of the given certificate.
 286         @param certificate A certificate reference.
 287         @result Returns the absolute time at which the given certificate becomes valid,
 288         or 0 if this value could not be obtained.
 289 */
 290 CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate)
 291     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 292
 293 /*!
 294         @function SecCertificateNotValidAfter
 295         @abstract Obtain the expiration date of the given certificate.
 296         @param certificate A certificate reference.
 297         @result Returns the absolute time at which the given certificate expires,
 298         or 0 if this value could not be obtained.
 299 */
 300 CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate)
 301     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 302
 303 /*!
 304         @function SecCertificateIsSelfSigned
 305         @abstract Determine if the given certificate is self-signed.
 306         @param certRef A certificate reference.
 307         @param isSelfSigned Will be set to true on return if the certificate is self-signed, false otherwise.
 308         @result A result code. Returns errSecSuccess if the certificate's status can be determined.
 309 */
 310 OSStatus SecCertificateIsSelfSigned(SecCertificateRef certRef, Boolean *isSelfSigned)
 311     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_9_0);
 312
 313 /*!
 314         @function SecCertificateIsSelfSignedCA
 315         @abstract Determine if the given certificate is self-signed and has a basic
 316         constraints extension indicating it is a certificate authority.
 317         @param certificate A certificate reference.
 318         @result Returns true if the certificate is self-signed and has a basic
 319         constraints extension indicating it is a certificate authority, otherwise false.
 320 */
 321 bool SecCertificateIsSelfSignedCA(SecCertificateRef certificate)
 322     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 323
 324 /*!
 325         @function SecCertificateIsCA
 326         @abstract Determine if the given certificate has a basic
 327         constraints extension indicating it is a certificate authority.
 328         @param certificate A certificate reference.
 329         @result Returns true if the certificate has a basic constraints
 330         extension indicating it is a certificate authority, otherwise false.
 331 */
 332 bool SecCertificateIsCA(SecCertificateRef certificate)
 333     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 334
 335 /*!
 336         @function SecCertificateCopyEscrowRoots
 337         @abstract Retrieve the array of valid escrow certificates for a given root type.
 338         @param escrowRootType An enumerated type indicating which root type to return.
 339         @result An array of zero or more escrow certificates matching the provided type.
 340 */
 341 CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType)
 342     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 343
 344 /* Return an attribute dictionary used to store this item in a keychain. */
 345 CFDictionaryRef SecCertificateCopyAttributeDictionary(SecCertificateRef certificate)
 346     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 347
 348 /*
 349  * Enumerated constants for signature hash algorithms.
 350  */
 351 typedef uint32_t SecSignatureHashAlgorithm;
 352 enum {
 353     kSecSignatureHashAlgorithmUnknown = 0,
 354     kSecSignatureHashAlgorithmMD2 = 1,
 355     kSecSignatureHashAlgorithmMD4 = 2,
 356     kSecSignatureHashAlgorithmMD5 = 3,
 357     kSecSignatureHashAlgorithmSHA1 = 4,
 358     kSecSignatureHashAlgorithmSHA224 = 5,
 359     kSecSignatureHashAlgorithmSHA256 = 6,
 360     kSecSignatureHashAlgorithmSHA384 = 7,
 361     kSecSignatureHashAlgorithmSHA512 = 8
 362 };
 363
 364 /*!
 365         @function SecCertificateGetSignatureHashAlgorithm
 366         @abstract Determine the hash algorithm used in a certificate's signature.
 367         @param certificate A certificate reference.
 368         @result Returns an enumerated value indicating the signature hash algorithm
 369         used in a certificate. If the hash algorithm is unsupported or cannot be
 370         obtained (e.g. because the supplied certificate reference is invalid), a
 371         value of 0 (kSecSignatureHashAlgorithmUnknown) is returned.
 372 */
 373 SecSignatureHashAlgorithm SecCertificateGetSignatureHashAlgorithm(SecCertificateRef certificate)
 374     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 375
 376 /*!
 377     @function SecCertificateCopyProperties
 378     @abstract Return a property array for this trust certificate.
 379     @param certificate A reference to the certificate to evaluate.
 380     @result A property array. It is the caller's responsability to CFRelease
 381     the returned array when it is no longer needed.
 382     See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
 383     Unlike that function call this function returns a detailed description
 384     of the certificate in question.
 385 */
 386 CFArrayRef SecCertificateCopyProperties(SecCertificateRef certificate);
 387
 388 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA256Digest(SecCertificateRef certificate);
 389
 390 /* Returns an array of CFDataRefs for all embedded SCTs */
 391 CFArrayRef SecCertificateCopySignedCertificateTimestamps(SecCertificateRef certificate)
 392         __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 393
 394 /* Return the precert TBSCertificate DER data - used for Certificate Transparency */
 395 CFDataRef SecCertificateCopyPrecertTBS(SecCertificateRef certificate)
 396         __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_9_0);
 397
 398 #if defined(__cplusplus)
 399 }
 400 #endif
 401
 402 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */