libsecurity_keychain/lib/SecCertificatePriv.h

   1 /*
   2  * Copyright (c) 2002-2004,2012 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 /* Return a certificate for the DER representation of this certificate.
  40    Return NULL if the passed-in data is not a valid DER-encoded X.509
  41    certificate. */
  42 SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
  43     const UInt8 *bytes, CFIndex length);
  44
  45 /* Return the length of the DER representation of this certificate. */
  46 CFIndex SecCertificateGetLength(SecCertificateRef certificate);
  47
  48 /* Return the bytes of the DER representation of this certificate. */
  49 const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
  50
  51 /* Deprecated; use SecCertificateCopyCommonName() instead. */
  52 OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName);
  53
  54 /* Deprecated; use SecCertificateCopyEmailAddresses() instead. */
  55 /* This should have been Copy instead of Get since the returned address is not autoreleased. */
  56 OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress);
  57
  58 /*
  59  * Private API to infer a display name for a SecCertificateRef which
  60  * may or may not be in a keychain.
  61  */
  62 OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label);
  63
  64 /*
  65  * Subset of the above, useful for both certs and CRLs.
  66  * Infer printable label for a given an CSSM_X509_NAME. Returns NULL
  67  * if no appropriate printable name found.
  68  */
  69 const CSSM_DATA *SecInferLabelFromX509Name(
  70         const CSSM_X509_NAME *x509Name);
  71
  72 /* Accessors for fields in the cached certificate */
  73
  74 /*!
  75         @function SecCertificateCopyFieldValues
  76         @abstract Retrieves the values for a particular field in a given certificate.
  77     @param certificate A valid SecCertificateRef to the certificate.
  78     @param field Pointer to the OID whose values should be returned.
  79     @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's.
  80         @result A result code.  See "Security Error Codes" (SecBase.h).
  81         @discussion Return a zero terminated list of CSSM_DATA_PTR's with the
  82         values of the field specified by field.  Caller must call
  83         SecCertificateReleaseFieldValues to free the storage allocated by this call.
  84 */
  85 OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues);
  86
  87 /*!
  88         @function SecCertificateReleaseFieldValues
  89         @abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues.
  90     @param certificate A valid SecCertificateRef to the certificate.
  91     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues.
  92     @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's.
  93         @result A result code.  See "Security Error Codes" (SecBase.h).
  94         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues.
  95 */
  96 OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues);
  97
  98 /*!
  99         @function SecCertificateCopyFirstFieldValue
 100         @abstract Return a CSSM_DATA_PTR with the value of the first field specified by field.
 101     @param certificate A valid SecCertificateRef to the certificate.
 102     @param field Pointer to the OID whose value should be returned.
 103     @param fieldValue On return, a CSSM_DATA_PTR to the field data.
 104         @result A result code.  See "Security Error Codes" (SecBase.h).
 105         @discussion Return a CSSM_DATA_PTR with the value of the first field specified by field.  Caller must call
 106         SecCertificateReleaseFieldValue to free the storage allocated by this call.
 107 */
 108 OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue);
 109
 110 /*!
 111         @function SecCertificateReleaseFirstFieldValue
 112         @abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue.
 113     @param certificate A valid SecCertificateRef to the certificate.
 114     @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue.
 115     @param fieldValue The field data to release.
 116         @result A result code.  See "Security Error Codes" (SecBase.h).
 117         @discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue.
 118 */
 119 OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue);
 120
 121 /*!
 122     @function SecCertificateCopySubjectComponent
 123     @abstract Retrieves a component of the subject distinguished name of a given certificate.
 124     @param certificate A reference to the certificate from which to retrieve the common name.
 125         @param component A component oid naming the component desired. See <Security/oidsattr.h>.
 126     @param result On return, a reference to the string form of the component, if present in the subject.
 127                 Your code must release this reference by calling the CFRelease function.
 128     @result A result code. See "Security Error Codes" (SecBase.h).
 129  */
 130 OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
 131         CFStringRef *result);
 132
 133
 134 /*      Convenience functions for searching.
 135 */
 136
 137 OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 138         const CSSM_DATA *serialNumber,  SecCertificateRef *certificate);
 139
 140 OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 141         SecCertificateRef *certificate);
 142
 143 OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 144         SecCertificateRef *certificate);
 145
 146
 147 /* These should go to SecKeychainSearchPriv.h. */
 148 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
 149         const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef);
 150
 151 OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
 152         CFDataRef serialNumber, SecKeychainSearchRef *searchRef);
 153
 154 OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
 155         SecKeychainSearchRef *searchRef);
 156
 157 OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
 158         SecKeychainSearchRef *searchRef);
 159
 160 /* Convenience function for generating digests; should be moved elsewhere. */
 161 CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data);
 162
 163 /* Return true iff certificate is valid as of verifyTime. */
 164 bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime);
 165
 166 /* NOT EXPORTED YET; copied from SecurityInterface but could be useful in the future.
 167 CSSM_CSP_HANDLE SecGetAppleCSPHandle();
 168 CSSM_CL_HANDLE SecGetAppleCLHandle();
 169 */
 170
 171 /* determine whether a cert is self-signed */
 172 OSStatus SecCertificateIsSelfSigned(
 173         SecCertificateRef certRef,
 174         Boolean *isSelfSigned);         /* RETURNED */
 175
 176
 177 #if defined(__cplusplus)
 178 }
 179 #endif
 180
 181 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */