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