OSX/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 const CFStringRef kSecCertificateProductionEscrowKey;
  48 extern const CFStringRef kSecCertificateProductionPCSEscrowKey;
  49 extern const CFStringRef kSecCertificateEscrowFileName;
  50
  51
  52 /* Given a unified SecCertificateRef, return a copy with a legacy
  53    C++ ItemImpl-based Certificate instance. Only for internal use;
  54    legacy references cannot be used by SecCertificate API functions. */
  55 SecCertificateRef SecCertificateCreateItemImplInstance(SecCertificateRef certificate);
  56
  57 /* Inverse of above; convert legacy Certificate instance to new ref. */
  58 SecCertificateRef SecCertificateCreateFromItemImplInstance(SecCertificateRef certificate);
  59
  60
  61 /* Given a legacy C++ ItemImpl-based Certificate instance obtained with
  62    SecCertificateCreateItemImplInstance, return its clHandle pointer.
  63    Only for internal use. */
  64 OSStatus SecCertificateGetCLHandle_legacy(SecCertificateRef certificate, CSSM_CL_HANDLE *clHandle);
  65
  66 /* Return a certificate for the DER representation of this certificate.
  67    Return NULL if the passed-in data is not a valid DER-encoded X.509
  68    certificate. */
  69 SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
  70     const UInt8 *bytes, CFIndex length);
  71
  72 /* Return the length of the DER representation of this certificate. */
  73 CFIndex SecCertificateGetLength(SecCertificateRef certificate);
  74
  75 /* Return the bytes of the DER representation of this certificate. */
  76 const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
  77
  78 /* Return the SHA-1 hash of this certificate. */
  79 CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate);
  80
  81 /* Return the SHA-1 hash of the public key in this certificate. */
  82 CFDataRef SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate);
  83
  84 /* Deprecated; use SecCertificateCopyCommonName() instead. */
  85 OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName);
  86
  87 /* Deprecated; use SecCertificateCopyEmailAddresses() instead. */
  88 /* This should have been Copy instead of Get since the returned address is not autoreleased. */
  89 OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress);
  90
  91 /* Return an array of CFStringRefs representing the dns addresses in the
  92    certificate if any. */
  93 CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate);
  94
  95 SecCertificateRef SecCertificateCreateWithKeychainItem(CFAllocatorRef allocator,
  96         CFDataRef der_certificate, CFTypeRef keychainItem);
  97
  98 CFTypeRef SecCertificateCopyKeychainItem(SecCertificateRef certificate);
  99
 100 /*!
 101         @function SecCertificateCopyIssuerSummary
 102         @abstract Return a simple string which hopefully represents a human understandable issuer.
 103         @param certificate SecCertificate object created with SecCertificateCreateWithData().
 104         @discussion All the data in this string comes from the certificate itself
 105         and thus it's in whatever language the certificate itself is in.
 106         @result A CFStringRef which the caller should CFRelease() once it's no longer needed.
 107 */
 108 CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
 109
 110 /*
 111  * Private API to infer a display name for a SecCertificateRef which
 112  * may or may not be in a keychain.
 113  */
 114 OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label);
 115
 116 /*
 117  * Subset of the above, useful for both certs and CRLs.
 118  * Infer printable label for a given an CSSM_X509_NAME. Returns NULL
 119  * if no appropriate printable name found.
 120  */
 121 const CSSM_DATA *SecInferLabelFromX509Name(
 122         const CSSM_X509_NAME *x509Name);
 123
 124 /* Accessors for fields in the cached certificate */
 125
 126 /*!
 127         @function SecCertificateCopyFieldValues
 128         @abstract Retrieves the values for a particular field in a given certificate.
 129     @param certificate A valid SecCertificateRef to the certificate.
 130     @param field Pointer to the OID whose values should be returned.
 131     @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's.
 132         @result A result code.  See "Security Error Codes" (SecBase.h).
 133         @discussion Return a zero terminated list of CSSM_DATA_PTR's with the
 134         values of the field specified by field.  Caller must call
 135         SecCertificateReleaseFieldValues to free the storage allocated by this call.
 136 */
 137 OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues);
 138
 139 /*!
 140         @function SecCertificateReleaseFieldValues
 141         @abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 142     @param certificate A valid SecCertificateRef to the certificate.
 143     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues.
 144     @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's.
 145         @result A result code.  See "Security Error Codes" (SecBase.h).
 146         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 147 */
 148 OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues);
 149
 150 /*!
 151         @function SecCertificateCopyFirstFieldValue
 152         @abstract Return a CSSM_DATA_PTR with the value of the first field specified by field.
 153     @param certificate A valid SecCertificateRef to the certificate.
 154     @param field Pointer to the OID whose value should be returned.
 155     @param fieldValue On return, a CSSM_DATA_PTR to the field data.
 156         @result A result code.  See "Security Error Codes" (SecBase.h).
 157         @discussion Return a CSSM_DATA_PTR with the value of the first field specified by field.  Caller must call
 158         SecCertificateReleaseFieldValue to free the storage allocated by this call.
 159 */
 160 OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue);
 161
 162 /*!
 163         @function SecCertificateReleaseFirstFieldValue
 164         @abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue.
 165     @param certificate A valid SecCertificateRef to the certificate.
 166     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue.
 167     @param fieldValue The field data to release.
 168         @result A result code.  See "Security Error Codes" (SecBase.h).
 169         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue.
 170 */
 171 OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue);
 172
 173 /*!
 174     @function SecCertificateCopySubjectComponent
 175     @abstract Retrieves a component of the subject distinguished name of a given certificate.
 176     @param certificate A reference to the certificate from which to retrieve the common name.
 177         @param component A component oid naming the component desired. See <Security/oidsattr.h>.
 178     @param result On return, a reference to the string form of the component, if present in the subject.
 179                 Your code must release this reference by calling the CFRelease function.
 180     @result A result code. See "Security Error Codes" (SecBase.h).
 181  */
 182 OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
 183         CFStringRef *result);
 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
 192 /*      Convenience functions for searching.
 193 */
 194
 195 OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 196         const CSSM_DATA *serialNumber,  SecCertificateRef *certificate);
 197
 198 OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 199         SecCertificateRef *certificate);
 200
 201 OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 202         SecCertificateRef *certificate);
 203
 204
 205 /* These should go to SecKeychainSearchPriv.h. */
 206 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 207         const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef);
 208
 209 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
 210         CFDataRef serialNumber, SecKeychainSearchRef *searchRef);
 211
 212 OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 213         SecKeychainSearchRef *searchRef);
 214
 215 OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 216         SecKeychainSearchRef *searchRef);
 217
 218 /* Convenience function for generating digests; should be moved elsewhere. */
 219 CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data);
 220
 221 /* Return true iff certificate is valid as of verifyTime. */
 222 /* DEPRECATED: Use SecCertificateIsValid instead. */
 223 bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 224     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
 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 SecCertificateCopyEscrowRoots
 267         @abstract Retrieve the array of valid escrow certificates for a given root type.
 268         @param escrowRootType An enumerated type indicating which root type to return.
 269         @result An array of zero or more escrow certificates matching the provided type.
 270 */
 271 CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType)
 272     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 273
 274
 275 /*
 276  * Enumerated constants for signature hash algorithms.
 277  */
 278 typedef uint32_t SecSignatureHashAlgorithm;
 279 enum {
 280     kSecSignatureHashAlgorithmUnknown = 0,
 281     kSecSignatureHashAlgorithmMD2 = 1,
 282     kSecSignatureHashAlgorithmMD4 = 2,
 283     kSecSignatureHashAlgorithmMD5 = 3,
 284     kSecSignatureHashAlgorithmSHA1 = 4,
 285     kSecSignatureHashAlgorithmSHA224 = 5,
 286     kSecSignatureHashAlgorithmSHA256 = 6,
 287     kSecSignatureHashAlgorithmSHA384 = 7,
 288     kSecSignatureHashAlgorithmSHA512 = 8
 289 };
 290
 291 /*!
 292         @function SecCertificateGetSignatureHashAlgorithm
 293         @abstract Determine the hash algorithm used in a certificate's signature.
 294         @param certificate A certificate reference.
 295         @result Returns an enumerated value indicating the signature hash algorithm
 296         used in a certificate. If the hash algorithm is unsupported or cannot be
 297         obtained (e.g. because the supplied certificate reference is invalid), a
 298         value of 0 (kSecSignatureHashAlgorithmUnknown) is returned.
 299 */
 300 SecSignatureHashAlgorithm SecCertificateGetSignatureHashAlgorithm(SecCertificateRef certificate)
 301     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 302
 303
 304 #if defined(__cplusplus)
 305 }
 306 #endif
 307
 308 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */