1/* 2 * Copyright (c) 2002-2004,2012-2013 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 35#if defined(__cplusplus) 36extern "C" { 37#endif 38 39typedef uint32_t SecCertificateEscrowRootType; 40enum { 41 kSecCertificateBaselineEscrowRoot = 0, 42 kSecCertificateProductionEscrowRoot = 1, 43}; 44 45extern CFTypeRef kSecCertificateProductionEscrowKey; 46extern CFTypeRef kSecCertificateEscrowFileName; 47 48 49/* Return a certificate for the DER representation of this certificate. 50 Return NULL if the passed-in data is not a valid DER-encoded X.509 51 certificate. */ 52SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator, 53 const UInt8 *bytes, CFIndex length); 54 55/* Return the length of the DER representation of this certificate. */ 56CFIndex SecCertificateGetLength(SecCertificateRef certificate); 57 58/* Return the bytes of the DER representation of this certificate. */ 59const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate); 60 61/* Return the SHA-1 hash of this certificate. */ 62CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate); 63 64/* Deprecated; use SecCertificateCopyCommonName() instead. */ 65OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName); 66 67/* Deprecated; use SecCertificateCopyEmailAddresses() instead. */ 68/* This should have been Copy instead of Get since the returned address is not autoreleased. */ 69OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress); 70 71/* Return an array of CFStringRefs representing the dns addresses in the 72 certificate if any. */ 73CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate); 74 75/*! 76 @function SecCertificateCopyIssuerSummary 77 @abstract Return a simple string which hopefully represents a human understandable issuer. 78 @param certificate SecCertificate object created with SecCertificateCreateWithData(). 79 @discussion All the data in this string comes from the certificate itself 80 and thus it's in whatever language the certificate itself is in. 81 @result A CFStringRef which the caller should CFRelease() once it's no longer needed. 82*/ 83CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate); 84 85/* 86 * Private API to infer a display name for a SecCertificateRef which 87 * may or may not be in a keychain. 88 */ 89OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label); 90 91/* 92 * Subset of the above, useful for both certs and CRLs. 93 * Infer printable label for a given an CSSM_X509_NAME. Returns NULL 94 * if no appropriate printable name found. 95 */ 96const CSSM_DATA *SecInferLabelFromX509Name( 97 const CSSM_X509_NAME *x509Name); 98 99/* Accessors for fields in the cached certificate */ 100 101/*! 102 @function SecCertificateCopyFieldValues 103 @abstract Retrieves the values for a particular field in a given certificate. 104 @param certificate A valid SecCertificateRef to the certificate. 105 @param field Pointer to the OID whose values should be returned. 106 @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's. 107 @result A result code. See "Security Error Codes" (SecBase.h). 108 @discussion Return a zero terminated list of CSSM_DATA_PTR's with the 109 values of the field specified by field. Caller must call 110 SecCertificateReleaseFieldValues to free the storage allocated by this call. 111*/ 112OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues); 113 114/*! 115 @function SecCertificateReleaseFieldValues 116 @abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues. 117 @param certificate A valid SecCertificateRef to the certificate. 118 @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues. 119 @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's. 120 @result A result code. See "Security Error Codes" (SecBase.h). 121 @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues. 122*/ 123OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues); 124 125/*! 126 @function SecCertificateCopyFirstFieldValue 127 @abstract Return a CSSM_DATA_PTR with the value of the first field specified by field. 128 @param certificate A valid SecCertificateRef to the certificate. 129 @param field Pointer to the OID whose value should be returned. 130 @param fieldValue On return, a CSSM_DATA_PTR to the field data. 131 @result A result code. See "Security Error Codes" (SecBase.h). 132 @discussion Return a CSSM_DATA_PTR with the value of the first field specified by field. Caller must call 133 SecCertificateReleaseFieldValue to free the storage allocated by this call. 134*/ 135OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue); 136 137/*! 138 @function SecCertificateReleaseFirstFieldValue 139 @abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue. 140 @param certificate A valid SecCertificateRef to the certificate. 141 @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue. 142 @param fieldValue The field data to release. 143 @result A result code. See "Security Error Codes" (SecBase.h). 144 @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue. 145*/ 146OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue); 147 148/*! 149 @function SecCertificateCopySubjectComponent 150 @abstract Retrieves a component of the subject distinguished name of a given certificate. 151 @param certificate A reference to the certificate from which to retrieve the common name. 152 @param component A component oid naming the component desired. See <Security/oidsattr.h>. 153 @param result On return, a reference to the string form of the component, if present in the subject. 154 Your code must release this reference by calling the CFRelease function. 155 @result A result code. See "Security Error Codes" (SecBase.h). 156 */ 157OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component, 158 CFStringRef *result); 159 160/* Return the DER encoded issuer sequence for the certificate's issuer. */ 161CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate); 162 163/* Return the DER encoded subject sequence for the certificate's subject. */ 164CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate); 165 166 167/* Convenience functions for searching. 168*/ 169 170OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer, 171 const CSSM_DATA *serialNumber, SecCertificateRef *certificate); 172 173OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID, 174 SecCertificateRef *certificate); 175 176OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress, 177 SecCertificateRef *certificate); 178 179 180/* These should go to SecKeychainSearchPriv.h. */ 181OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer, 182 const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef); 183 184OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer, 185 CFDataRef serialNumber, SecKeychainSearchRef *searchRef); 186 187OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID, 188 SecKeychainSearchRef *searchRef); 189 190OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress, 191 SecKeychainSearchRef *searchRef); 192 193/* Convenience function for generating digests; should be moved elsewhere. */ 194CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data); 195 196/* Return true iff certificate is valid as of verifyTime. */ 197/* DEPRECATED: Use SecCertificateIsValid instead. */ 198bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime) 199 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA); 200 201/*! 202 @function SecCertificateIsValid 203 @abstract Check certificate validity on a given date. 204 @param certificate A certificate reference. 205 @result Returns true if the specified date falls within the certificate's validity period, false otherwise. 206*/ 207bool SecCertificateIsValid(SecCertificateRef certificate, CFAbsoluteTime verifyTime) 208 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0); 209 210/*! 211 @function SecCertificateNotValidBefore 212 @abstract Obtain the starting date of the given certificate. 213 @param certificate A certificate reference. 214 @result Returns the absolute time at which the given certificate becomes valid, 215 or 0 if this value could not be obtained. 216*/ 217CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate) 218 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0); 219 220/*! 221 @function SecCertificateNotValidAfter 222 @abstract Obtain the expiration date of the given certificate. 223 @param certificate A certificate reference. 224 @result Returns the absolute time at which the given certificate expires, 225 or 0 if this value could not be obtained. 226*/ 227CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate) 228 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0); 229 230/*! 231 @function SecCertificateIsSelfSigned 232 @abstract Determine if the given certificate is self-signed. 233 @param certRef A certificate reference. 234 @param isSelfSigned Will be set to true on return if the certificate is self-signed, false otherwise. 235 @result A result code. Returns errSecSuccess if the certificate's status can be determined. 236*/ 237OSStatus SecCertificateIsSelfSigned(SecCertificateRef certRef, Boolean *isSelfSigned) 238 __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA); 239 240/*! 241 @function SecCertificateCopyEscrowRoots 242 @abstract Retrieve the array of valid escrow certificates for a given root type. 243 @param escrowRootType An enumerated type indicating which root type to return. 244 @result An array of zero or more escrow certificates matching the provided type. 245*/ 246CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType) 247 __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0); 248 249 250#if defined(__cplusplus) 251} 252#endif 253 254#endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */ 255