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