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