sec/Security/SecCertificateInternal.h

   1 /*
   2  * Copyright (c) 2007-2010 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 /*
  25    SecCertificateInternal
  26 */
  27
  28 #ifndef _SECURITY_SECCERTIFICATEINTERNAL_H_
  29 #define _SECURITY_SECCERTIFICATEINTERNAL_H_
  30
  31 #include <Security/SecCertificatePriv.h>
  32 #include <Security/certextensions.h>
  33 #include <libDER/DER_Keys.h>
  34
  35 #if defined(__cplusplus)
  36 extern "C" {
  37 #endif
  38
  39 CFDataRef SecCertificateGetAuthorityKeyID(SecCertificateRef certificate);
  40 CFDataRef SecCertificateGetSubjectKeyID(SecCertificateRef certificate);
  41
  42 /* Return an array of CFURLRefs each of which is an crl distribution point for
  43    this certificate. */
  44 CFArrayRef SecCertificateGetCRLDistributionPoints(SecCertificateRef certificate);
  45
  46 /* Return an array of CFURLRefs each of which is an ocspResponder for this
  47    certificate. */
  48 CFArrayRef SecCertificateGetOCSPResponders(SecCertificateRef certificate);
  49
  50 /* Return an array of CFURLRefs each of which is an caIssuer for this
  51    certificate. */
  52 CFArrayRef SecCertificateGetCAIssuers(SecCertificateRef certificate);
  53
  54 /* Dump certificate for debugging. */
  55 void SecCertificateShow(SecCertificateRef certificate);
  56
  57 /* Return the DER encoded issuer sequence for the receiving certificates issuer. */
  58 CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate);
  59
  60 /* Return the DER encoded subject sequence for the receiving certificates subject. */
  61 CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate);
  62
  63 /* Return the content of a DER encoded X.501 name (without the tag and length
  64    fields) for the receiving certificates issuer. */
  65 CFDataRef SecCertificateGetNormalizedIssuerContent(SecCertificateRef certificate);
  66
  67 /* Return the content of a DER encoded X.501 name (without the tag and length
  68    fields) for the receiving certificates subject. */
  69 CFDataRef SecCertificateGetNormalizedSubjectContent(SecCertificateRef certificate);
  70
  71 /* Return true iff the certificate has a subject. */
  72 bool SecCertificateHasSubject(SecCertificateRef certificate);
  73 /* Return true iff the certificate has a critical subject alt name. */
  74 bool SecCertificateHasCriticalSubjectAltName(SecCertificateRef certificate);
  75
  76 /* Return true if certificate contains one or more critical extensions we
  77    are unable to parse. */
  78 bool SecCertificateHasUnknownCriticalExtension(SecCertificateRef certificate);
  79
  80 /* Return true iff certificate is valid as of verifyTime. */
  81 bool SecCertificateIsValid(SecCertificateRef certificate,
  82         CFAbsoluteTime verifyTime);
  83
  84 /* Return an attribute dictionary used to store this item in a keychain. */
  85 CFDictionaryRef SecCertificateCopyAttributeDictionary(
  86         SecCertificateRef certificate);
  87
  88 /* Return a certificate from the attribute dictionary that was used to store
  89    this item in a keychain. */
  90 SecCertificateRef SecCertificateCreateFromAttributeDictionary(
  91         CFDictionaryRef refAttributes);
  92
  93 /* Return a SecKeyRef for the public key embedded in the cert. */
  94 SecKeyRef SecCertificateCopyPublicKey(SecCertificateRef certificate);
  95
  96 /* Return the SecCEBasicConstraints extension for this certificate if it
  97    has one. */
  98 const SecCEBasicConstraints *
  99 SecCertificateGetBasicConstraints(SecCertificateRef certificate);
 100
 101 /* Return the SecCEPolicyConstraints extension for this certificate if it
 102    has one. */
 103 const SecCEPolicyConstraints *
 104 SecCertificateGetPolicyConstraints(SecCertificateRef certificate);
 105
 106 /* Return a dictionary from CFDataRef to CFArrayRef of CFDataRef
 107    representing the policyMapping extension of this certificate. */
 108 CFDictionaryRef
 109 SecCertificateGetPolicyMappings(SecCertificateRef certificate);
 110
 111 /* Return the SecCECertificatePolicies extension for this certificate if it
 112    has one. */
 113 const SecCECertificatePolicies *
 114 SecCertificateGetCertificatePolicies(SecCertificateRef certificate);
 115
 116 /* Returns UINT32_MAX if InhibitAnyPolicy extension is not present or invalid,
 117    returns the value of the SkipCerts field of the InhibitAnyPolicy extension
 118    otherwise. */
 119 uint32_t
 120 SecCertificateGetInhibitAnyPolicySkipCerts(SecCertificateRef certificate);
 121
 122 /* Return the public key algorithm and parameters for certificate.  */
 123 const DERAlgorithmId *SecCertificateGetPublicKeyAlgorithm(
 124         SecCertificateRef certificate);
 125
 126 /* Return the raw public key data for certificate.  */
 127 const DERItem *SecCertificateGetPublicKeyData(SecCertificateRef certificate);
 128
 129 #pragma mark -
 130 #pragma mark Certificate Operations
 131
 132 OSStatus SecCertificateIsSignedBy(SecCertificateRef certificate,
 133     SecKeyRef issuerKey);
 134
 135 #pragma mark -
 136 #pragma mark Certificate Creation
 137
 138 #ifdef OPTIONAL_METHODS
 139 /* Return a certificate for the PEM representation of this certificate.
 140    Return NULL the passed in der_certificate is not a valid DER encoded X.509
 141    certificate, and return a CFError by reference.  It is the
 142    responsibility of the caller to release the CFError. */
 143 SecCertificateRef SecCertificateCreateWithPEM(CFAllocatorRef allocator,
 144         CFStringRef pem_certificate);
 145
 146 /* Return a CFStringRef containing the the pem representation of this
 147    certificate. */
 148 CFStringRef SecCertificateGetPEM(SecCertificateRef der_certificate);
 149
 150 #endif /* OPTIONAL_METHODS */
 151
 152 #if 0
 153 /* Complete the certificate chain of this certificate, setting the parent
 154    certificate for each certificate along they way.  Return 0 if the
 155    system is able to find all the certificates to complete the certificate
 156    chain either in the passed in other_certificates array or in the user or
 157    the systems keychain(s).
 158    If the certifcates issuer chain can not be completed, this function
 159    will return an error status code.
 160    NOTE: This function does not verify whether the certificate is trusted it's
 161    main use is just to ensure that anyone using this certificate upstream will
 162    have access to a complete (or as complete as possible in the case of
 163    something going wrong) certificate chain.  */
 164 OSStatus SecCertificateCompleteChain(SecCertificateRef certificate,
 165         CFArrayRef other_certificates);
 166 #endif
 167
 168 #if 0
 169
 170 /*!
 171         @function SecCertificateGetVersionNumber
 172         @abstract Retrieves the version of a given certificate as a CFNumberRef.
 173     @param certificate A reference to the certificate from which to obtain the certificate version.
 174         @result A CFNumberRef representing the certificate version.  The following values are currently known to be returned, but more may be added in the future:
 175         1: X509v1
 176         2: X509v2
 177         3: X509v3
 178 */
 179 CFNumberRef SecCertificateGetVersionNumber(SecCertificateRef certificate);
 180
 181 /*!
 182         @function SecCertificateGetSerialDER
 183         @abstract Retrieves the serial number of a given certificate in DER encoding.
 184     @param certificate A reference to the certificate from which to obtain the serial number.
 185         @result A CFDataRef containing the DER encoded serial number of the certificate, minus the tag and length fields.
 186 */
 187 CFDataRef SecCertificateGetSerialDER(SecCertificateRef certificate);
 188
 189
 190 /*!
 191         @function SecCertificateGetSerialString
 192         @abstract Retrieves the serial number of a given certificate in human readable form.
 193     @param certificate A reference to the certificate from which to obtain the serial number.
 194         @result A CFStringRef containing the human readable serial number of the certificate in decimal form.
 195 */
 196 CFStringRef SecCertificateGetSerialString(SecCertificateRef certificate);
 197
 198
 199
 200 CFDataRef SecCertificateGetPublicKeyDER(SecCertificateRef certificate);
 201 CFDataRef SecCertificateGetPublicKeySHA1FingerPrint(SecCertificateRef certificate);
 202 CFDataRef SecCertificateGetPublicKeyMD5FingerPrint(SecCertificateRef certificate);
 203 CFDataRef SecCertificateGetSignatureAlgorithmDER(SecCertificateRef certificate);
 204 CFDataRef SecCertificateGetSignatureAlgorithmName(SecCertificateRef certificate);
 205 CFStringRef SecCertificateGetSignatureAlgorithmOID(SecCertificateRef certificate);
 206 CFDataRef SecCertificateGetSignatureDER(SecCertificateRef certificate);
 207 CFDataRef SecCertificateGetSignatureAlgorithmParametersDER(SecCertificateRef certificate);
 208
 209 /* plist top level array is orderd list of key/value pairs */
 210 CFArrayRef SecCertificateGetSignatureAlgorithmParametersArray(SecCertificateRef certificate);
 211
 212 #if 0
 213 /* This cert is signed by it's parent? */
 214 bool SecCertificateIsSignatureValid(SecCertificateRef certificate);
 215
 216 /* This cert is signed by it's parent and so on until no parent certificate can be found? */
 217 bool SecCertificateIsIssuerChainValid(SecCertificateRef certificate, CFArrayRef additionalCertificatesToSearch);
 218
 219 /* This cert is signed by it's parent and so on until no parent certificate can be found? */
 220 bool SecCertificateIsSignatureChainValid(SecCertificateRef certificate);
 221
 222 /* This cert is signed by it's parent and so on until a certiicate in anchors can be found. */
 223 bool SecCertificateIssuerChainHasAnchorIn(SecCertificateRef certificate, CFArrayRef anchors);
 224
 225 /* This cert is signed by it's parent and so on until a certiicate in anchors can be found. */
 226 bool SecCertificateSignatureChainHasAnchorIn(SecCertificateRef certificate, CFArrayRef anchors);
 227
 228 bool SecCertificateIsSelfSigned(SecCertificateRef certificate);
 229 #endif
 230
 231
 232 /* The entire certificate in DER encoding including the outer tag and length fields. */
 233 CFDataRef SecCertificateGetDER(SecCertificateRef certificate);
 234
 235 /* Returns the status code of the last failed call for this certificate on this thread. */
 236 OSStatus SecCertificateGetStatus(SecCertificateRef certificate);
 237
 238 CFDataRef SecCertificateGetIssuerDER(SecCertificateRef certificate);
 239 CFDataRef SecCertificateGetNormalizedIssuerDER(SecCertificateRef certificate);
 240
 241 /* Return the issuer as an X509 name encoded in an array.  Each element in this array is an array.  Each inner array has en even number of elements.  Each pair of elements in the inner array represents a key and a value.  The key is a string and the value is also a string.  Elements in the outer array should be considered ordered while pairs in the inner array should not. */
 242 CFArrayRef SecCertificateGetIssuerArray(SecCertificateRef certificate);
 243
 244
 245 CFDataRef SecCertificateGetSubjectDER(SecCertificateRef certificate);
 246 CFDataRef SecCertificateGetNormalizedSubjectDER(SecCertificateRef certificate);
 247 /* See SecCertificateGetIssuerArray for a description of the returned array. */
 248 CFArrayRef SecCertificateGetSubjectArray(SecCertificateRef certificate);
 249
 250 CFDateRef SecCertificateGetNotValidBeforeDate(SecCertificateRef certificate);
 251 CFDateRef SecCertificateGetNotValidDateDate(SecCertificateRef certificate);
 252
 253
 254 #if 0
 255
 256 CFIndex SecCertificateGetExtensionCount(SecCertificateRef certificate,  index);
 257 CFDataRef SecCertificateGetExtensionAtIndexDER(SecCertificateRef certificate, CFIndex index);
 258 bool SecCertificateIsExtensionAtIndexCritical(SecCertificateRef certificate, CFIndex index);
 259
 260 /* array see email example. */
 261 CFArrayRef SecCertificateGetExtensionAtIndexParamsArray(SecCertificateRef certificate, CFIndex index);
 262
 263 CFStringRef SecCertificateGetExtensionAtIndexName(SecCertificateRef certificate, CFIndex index);
 264 CFStringRef SecCertificateGetExtensionAtIndexOID(SecCertificateRef certificate, CFIndex index);
 265
 266 #else
 267
 268 /* Return an array with all of this certificates SecCertificateExtensionRefs. */
 269 CFArrayRef SecCertificateGetExtensions(SecCertificateRef certificate);
 270
 271 /* Return the SecCertificateExtensionRef for the extension with the given oid.  Return NULL if it does not exist or if an error occours call SecCertificateGetStatus() to see if an error occured or not. */
 272 SecCertificateExtensionRef SecCertificateGetExtensionWithOID(SecCertificateRef certificate, CFDataRef oid);
 273
 274 CFDataRef SecCertificateExtensionGetDER(SecCertificateExtensionRef extension, CFDataRef oid);
 275 CFStringRef SecCertificateExtensionName(SecCertificateExtensionRef extension);
 276 CFDataRef SecCertificateExtensionGetOIDDER(SecCertificateExtensionRef extension, CFDataRef oid);
 277 CFStringRef SecCertificateExtensionGetOIDString(SecCertificateExtensionRef extension, CFDataRef oid);
 278 bool SecCertificateExtensionIsCritical(SecCertificateExtensionRef extension);
 279 CFArrayRef SecCertificateExtensionGetContentDER(SecCertificateExtensionRef extension);
 280
 281 /* Return the content of extension as an array.  The array has en even number of elements.  Each pair of elements in the array represents a key and a value.  The key is a string and the value is either a string, or dictionary or an array of key value pairs like the outer array.  */
 282 CFArrayRef SecCertificateExtensionGetContentArray(SecCertificateExtensionRef extension);
 283
 284 #endif /* 0 */
 285
 286 #endif /* 0 */
 287
 288
 289 void appendProperty(CFMutableArrayRef properties, CFStringRef propertyType,
 290     CFStringRef label, CFStringRef localizedLabel, CFTypeRef value);
 291
 292 /* Utility functions. */
 293 CFStringRef SecDERItemCopyOIDDecimalRepresentation(CFAllocatorRef allocator,
 294     const DERItem *oid);
 295 CFDataRef createNormalizedX501Name(CFAllocatorRef allocator,
 296         const DERItem *x501name);
 297
 298 /* Decode a choice of UTCTime or GeneralizedTime to a CFAbsoluteTime. Return
 299    an absoluteTime if the date was valid and properly decoded.  Return
 300    NULL_TIME otherwise. */
 301 CFAbsoluteTime SecAbsoluteTimeFromDateContent(DERTag tag, const uint8_t *bytes,
 302     size_t length);
 303
 304 bool SecCertificateHasMarkerExtension(SecCertificateRef certificate, CFTypeRef oid);
 305
 306 #if defined(__cplusplus)
 307 }
 308 #endif
 309
 310 #endif /* !_SECURITY_SECCERTIFICATEINTERNAL_H_ */