Security/libsecurity_keychain/lib/SecCertificatePriv.h

   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)
  36 extern "C" {
  37 #endif
  38
  39 typedef uint32_t SecCertificateEscrowRootType;
  40 enum {
  41     kSecCertificateBaselineEscrowRoot = 0,
  42     kSecCertificateProductionEscrowRoot = 1,
  43     kSecCertificateBaselinePCSEscrowRoot = 2,
  44     kSecCertificateProductionPCSEscrowRoot = 3,
  45 };
  46
  47 extern CFTypeRef kSecCertificateProductionEscrowKey;
  48 extern CFTypeRef kSecCertificateProductionPCSEscrowKey;
  49 extern 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. */
  55 SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
  56     const UInt8 *bytes, CFIndex length);
  57
  58 /* Return the length of the DER representation of this certificate. */
  59 CFIndex SecCertificateGetLength(SecCertificateRef certificate);
  60
  61 /* Return the bytes of the DER representation of this certificate. */
  62 const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
  63
  64 /* Return the SHA-1 hash of this certificate. */
  65 CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate);
  66
  67 /* Deprecated; use SecCertificateCopyCommonName() instead. */
  68 OSStatus 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. */
  72 OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress);
  73
  74 /* Return an array of CFStringRefs representing the dns addresses in the
  75    certificate if any. */
  76 CFArrayRef 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 */
  86 CFStringRef 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  */
  92 OSStatus 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  */
  99 const 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 */
 115 OSStatus 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 */
 126 OSStatus 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 */
 138 OSStatus 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 */
 149 OSStatus 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  */
 160 OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
 161         CFStringRef *result);
 162
 163 /* Return the DER encoded issuer sequence for the certificate's issuer. */
 164 CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate);
 165
 166 /* Return the DER encoded subject sequence for the certificate's subject. */
 167 CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate);
 168
 169
 170 /*      Convenience functions for searching.
 171 */
 172
 173 OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 174         const CSSM_DATA *serialNumber,  SecCertificateRef *certificate);
 175
 176 OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 177         SecCertificateRef *certificate);
 178
 179 OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 180         SecCertificateRef *certificate);
 181
 182
 183 /* These should go to SecKeychainSearchPriv.h. */
 184 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 185         const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef);
 186
 187 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
 188         CFDataRef serialNumber, SecKeychainSearchRef *searchRef);
 189
 190 OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 191         SecKeychainSearchRef *searchRef);
 192
 193 OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 194         SecKeychainSearchRef *searchRef);
 195
 196 /* Convenience function for generating digests; should be moved elsewhere. */
 197 CSSM_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. */
 201 bool 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 */
 210 bool 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 */
 220 CFAbsoluteTime 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 */
 230 CFAbsoluteTime 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 */
 240 OSStatus 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 */
 249 CFArrayRef 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_ */