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 SHA2-256 hash of this certificate. */
  82 CFDataRef SecCertificateCopySHA256Digest(SecCertificateRef certificate);
  83
  84 /* Return the SHA-1 hash of the public key in this certificate. */
  85 CFDataRef SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate);
  86
  87 /* Deprecated; use SecCertificateCopyCommonName() instead. */
  88 OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName);
  89
  90 /* Deprecated; use SecCertificateCopyEmailAddresses() instead. */
  91 /* This should have been Copy instead of Get since the returned address is not autoreleased. */
  92 OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress);
  93
  94 /* Return an array of CFStringRefs representing the dns addresses in the
  95    certificate if any. */
  96 CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate);
  97
  98 SecCertificateRef SecCertificateCreateWithKeychainItem(CFAllocatorRef allocator,
  99         CFDataRef der_certificate, CFTypeRef keychainItem);
 100
 101 CFTypeRef SecCertificateCopyKeychainItem(SecCertificateRef certificate);
 102
 103 /*!
 104         @function SecCertificateCopyIssuerSummary
 105         @abstract Return a simple string which hopefully represents a human understandable issuer.
 106         @param certificate SecCertificate object created with SecCertificateCreateWithData().
 107         @discussion All the data in this string comes from the certificate itself
 108         and thus it's in whatever language the certificate itself is in.
 109         @result A CFStringRef which the caller should CFRelease() once it's no longer needed.
 110 */
 111 CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
 112
 113 /*
 114  * Private API to infer a display name for a SecCertificateRef which
 115  * may or may not be in a keychain.
 116  */
 117 OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label);
 118
 119 /*
 120  * Subset of the above, useful for both certs and CRLs.
 121  * Infer printable label for a given an CSSM_X509_NAME. Returns NULL
 122  * if no appropriate printable name found.
 123  */
 124 const CSSM_DATA *SecInferLabelFromX509Name(
 125         const CSSM_X509_NAME *x509Name);
 126
 127 /* Accessors for fields in the cached certificate */
 128
 129 /*!
 130         @function SecCertificateCopyFieldValues
 131         @abstract Retrieves the values for a particular field in a given certificate.
 132     @param certificate A valid SecCertificateRef to the certificate.
 133     @param field Pointer to the OID whose values should be returned.
 134     @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's.
 135         @result A result code.  See "Security Error Codes" (SecBase.h).
 136         @discussion Return a zero terminated list of CSSM_DATA_PTR's with the
 137         values of the field specified by field.  Caller must call
 138         SecCertificateReleaseFieldValues to free the storage allocated by this call.
 139 */
 140 OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues);
 141
 142 /*!
 143         @function SecCertificateReleaseFieldValues
 144         @abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 145     @param certificate A valid SecCertificateRef to the certificate.
 146     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues.
 147     @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's.
 148         @result A result code.  See "Security Error Codes" (SecBase.h).
 149         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues.
 150 */
 151 OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues);
 152
 153 /*!
 154         @function SecCertificateCopyFirstFieldValue
 155         @abstract Return a CSSM_DATA_PTR with the value of the first field specified by field.
 156     @param certificate A valid SecCertificateRef to the certificate.
 157     @param field Pointer to the OID whose value should be returned.
 158     @param fieldValue On return, a CSSM_DATA_PTR to the field data.
 159         @result A result code.  See "Security Error Codes" (SecBase.h).
 160         @discussion Return a CSSM_DATA_PTR with the value of the first field specified by field.  Caller must call
 161         SecCertificateReleaseFieldValue to free the storage allocated by this call.
 162 */
 163 OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue);
 164
 165 /*!
 166         @function SecCertificateReleaseFirstFieldValue
 167         @abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue.
 168     @param certificate A valid SecCertificateRef to the certificate.
 169     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue.
 170     @param fieldValue The field data to release.
 171         @result A result code.  See "Security Error Codes" (SecBase.h).
 172         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue.
 173 */
 174 OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue);
 175
 176 /*!
 177     @function SecCertificateCopySubjectComponent
 178     @abstract Retrieves a component of the subject distinguished name of a given certificate.
 179     @param certificate A reference to the certificate from which to retrieve the common name.
 180         @param component A component oid naming the component desired. See <Security/oidsattr.h>.
 181     @param result On return, a reference to the string form of the component, if present in the subject.
 182                 Your code must release this reference by calling the CFRelease function.
 183     @result A result code. See "Security Error Codes" (SecBase.h).
 184  */
 185 OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
 186         CFStringRef *result);
 187
 188 /* Return the DER encoded issuer sequence for the certificate's issuer. */
 189 CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate);
 190
 191 /* Return the DER encoded subject sequence for the certificate's subject. */
 192 CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate);
 193
 194
 195 /*      Convenience functions for searching.
 196 */
 197
 198 OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 199         const CSSM_DATA *serialNumber,  SecCertificateRef *certificate);
 200
 201 OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 202         SecCertificateRef *certificate);
 203
 204 OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 205         SecCertificateRef *certificate);
 206
 207
 208 /* These should go to SecKeychainSearchPriv.h. */
 209 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 210         const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef);
 211
 212 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
 213         CFDataRef serialNumber, SecKeychainSearchRef *searchRef);
 214
 215 OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 216         SecKeychainSearchRef *searchRef);
 217
 218 OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 219         SecKeychainSearchRef *searchRef);
 220
 221 /* Convenience function for generating digests; should be moved elsewhere. */
 222 CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data);
 223
 224 /* Return true iff certificate is valid as of verifyTime. */
 225 /* DEPRECATED: Use SecCertificateIsValid instead. */
 226 bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 227     __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
 228
 229 /*!
 230         @function SecCertificateIsValid
 231         @abstract Check certificate validity on a given date.
 232         @param certificate A certificate reference.
 233         @result Returns true if the specified date falls within the certificate's validity period, false otherwise.
 234 */
 235 bool SecCertificateIsValid(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
 236         __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 237
 238 /*!
 239         @function SecCertificateNotValidBefore
 240         @abstract Obtain the starting date of the given certificate.
 241         @param certificate A certificate reference.
 242         @result Returns the absolute time at which the given certificate becomes valid,
 243         or 0 if this value could not be obtained.
 244 */
 245 CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate)
 246     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 247
 248 /*!
 249         @function SecCertificateNotValidAfter
 250         @abstract Obtain the expiration date of the given certificate.
 251         @param certificate A certificate reference.
 252         @result Returns the absolute time at which the given certificate expires,
 253         or 0 if this value could not be obtained.
 254 */
 255 CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate)
 256     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
 257
 258 /*!
 259         @function SecCertificateIsSelfSigned
 260         @abstract Determine if the given certificate is self-signed.
 261         @param certRef A certificate reference.
 262         @param isSelfSigned Will be set to true on return if the certificate is self-signed, false otherwise.
 263         @result A result code. Returns errSecSuccess if the certificate's status can be determined.
 264 */
 265 OSStatus SecCertificateIsSelfSigned(SecCertificateRef certRef, Boolean *isSelfSigned)
 266     __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_9_0);
 267
 268 /*!
 269         @function SecCertificateCopyEscrowRoots
 270         @abstract Retrieve the array of valid escrow certificates for a given root type.
 271         @param escrowRootType An enumerated type indicating which root type to return.
 272         @result An array of zero or more escrow certificates matching the provided type.
 273 */
 274 CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType)
 275     __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
 276
 277
 278 /*
 279  * Enumerated constants for signature hash algorithms.
 280  */
 281 typedef uint32_t SecSignatureHashAlgorithm;
 282 enum {
 283     kSecSignatureHashAlgorithmUnknown = 0,
 284     kSecSignatureHashAlgorithmMD2 = 1,
 285     kSecSignatureHashAlgorithmMD4 = 2,
 286     kSecSignatureHashAlgorithmMD5 = 3,
 287     kSecSignatureHashAlgorithmSHA1 = 4,
 288     kSecSignatureHashAlgorithmSHA224 = 5,
 289     kSecSignatureHashAlgorithmSHA256 = 6,
 290     kSecSignatureHashAlgorithmSHA384 = 7,
 291     kSecSignatureHashAlgorithmSHA512 = 8
 292 };
 293
 294 /*!
 295         @function SecCertificateGetSignatureHashAlgorithm
 296         @abstract Determine the hash algorithm used in a certificate's signature.
 297         @param certificate A certificate reference.
 298         @result Returns an enumerated value indicating the signature hash algorithm
 299         used in a certificate. If the hash algorithm is unsupported or cannot be
 300         obtained (e.g. because the supplied certificate reference is invalid), a
 301         value of 0 (kSecSignatureHashAlgorithmUnknown) is returned.
 302 */
 303 SecSignatureHashAlgorithm SecCertificateGetSignatureHashAlgorithm(SecCertificateRef certificate)
 304     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 305
 306
 307 #if defined(__cplusplus)
 308 }
 309 #endif
 310
 311 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */