sec/Security/SecCertificateInternal.h

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