OSX/sec/Security/SecCertificateInternal.h

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