libsecurity_keychain/lib/SecCertificatePriv.h

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