OSX/libsecurity_keychain/lib/SecCertificateInternalP.h

   1 /*
   2  * Copyright (c) 2007-2011,2013-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.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 SecCertificateGetAuthorityKeyIDP(SecCertificateRefP certificate);
  41 CFDataRef SecCertificateGetSubjectKeyIDP(SecCertificateRefP certificate);
  42
  43 /* Return an array of CFURLRefs each of which is an crl distribution point for
  44    this certificate. */
  45 CFArrayRef SecCertificateGetCRLDistributionPointsP(SecCertificateRefP certificate);
  46
  47 /* Return an array of CFURLRefs each of which is an ocspResponder for this
  48    certificate. */
  49 CFArrayRef SecCertificateGetOCSPRespondersP(SecCertificateRefP certificate);
  50
  51 /* Return an array of CFURLRefs each of which is an caIssuer for this
  52    certificate. */
  53 CFArrayRef SecCertificateGetCAIssuersP(SecCertificateRefP certificate);
  54
  55 /* Dump certificate for debugging. */
  56 void SecCertificateShowP(SecCertificateRefP certificate);
  57
  58 /* Return the DER encoded issuer sequence for the receiving certificates issuer. */
  59 CFDataRef SecCertificateCopyIssuerSequenceP(SecCertificateRefP certificate);
  60
  61 /* Return the DER encoded subject sequence for the receiving certificates subject. */
  62 CFDataRef SecCertificateCopySubjectSequenceP(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 SecCertificateGetNormalizedIssuerContentP(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 SecCertificateGetNormalizedSubjectContentP(SecCertificateRefP certificate);
  71
  72 CFDataRef SecDERItemCopySequenceP(DERItem *content);
  73
  74 /* Return true iff the certificate has a subject. */
  75 bool SecCertificateHasSubjectP(SecCertificateRefP certificate);
  76
  77 /* Return true iff the certificate has a critical subject alt name. */
  78 bool SecCertificateHasCriticalSubjectAltNameP(SecCertificateRefP certificate);
  79
  80 /* Return true if certificate contains one or more critical extensions we
  81    are unable to parse. */
  82 bool SecCertificateHasUnknownCriticalExtensionP(SecCertificateRefP certificate);
  83
  84 /* Return true iff certificate is valid as of verifyTime. */
  85 bool SecCertificateIsValidP(SecCertificateRefP certificate,
  86         CFAbsoluteTime verifyTime);
  87
  88 /* Return an attribute dictionary used to store this item in a keychain. */
  89 CFDictionaryRef SecCertificateCopyAttributeDictionaryP(
  90         SecCertificateRefP certificate);
  91
  92 /* Return a certificate from the attribute dictionary that was used to store
  93    this item in a keychain. */
  94 SecCertificateRefP SecCertificateCreateFromAttributeDictionaryP(
  95         CFDictionaryRef refAttributes);
  96
  97 /* Return a SecKeyRef for the public key embedded in the cert. */
  98 SecKeyRefP SecCertificateCopyPublicKeyP(SecCertificateRefP certificate);
  99
 100 /* Return the SecCEBasicConstraints extension for this certificate if it
 101    has one. */
 102 const SecCEBasicConstraints *
 103 SecCertificateGetBasicConstraintsP(SecCertificateRefP certificate);
 104
 105 /* Return the SecCEPolicyConstraints extension for this certificate if it
 106    has one. */
 107 const SecCEPolicyConstraints *
 108 SecCertificateGetPolicyConstraintsP(SecCertificateRefP certificate);
 109
 110 /* Return a dictionary from CFDataRef to CFArrayRef of CFDataRef
 111    representing the policyMapping extension of this certificate. */
 112 CFDictionaryRef
 113 SecCertificateGetPolicyMappingsP(SecCertificateRefP certificate);
 114
 115 /* Return the SecCECertificatePolicies extension for this certificate if it
 116    has one. */
 117 const SecCECertificatePolicies *
 118 SecCertificateGetCertificatePoliciesP(SecCertificateRefP certificate);
 119
 120 /* Returns UINT32_MAX if InhibitAnyPolicy extension is not present or invalid,
 121    returns the value of the SkipCerts field of the InhibitAnyPolicy extension
 122    otherwise. */
 123 uint32_t
 124 SecCertificateGetInhibitAnyPolicySkipCertsP(SecCertificateRefP certificate);
 125
 126 /* Return the public key algorithm and parameters for certificate.  */
 127 const DERAlgorithmId *SecCertificateGetPublicKeyAlgorithmP(
 128         SecCertificateRefP certificate);
 129
 130 /* Return the raw public key data for certificate.  */
 131 const DERItem *SecCertificateGetPublicKeyDataP(SecCertificateRefP certificate);
 132
 133 #pragma mark -
 134 #pragma mark Certificate Operations
 135
 136 OSStatus SecCertificateIsSignedByP(SecCertificateRefP certificate,
 137     SecKeyRefP issuerKey);
 138
 139 #pragma mark -
 140 #pragma mark Certificate Creation
 141
 142 #ifdef OPTIONAL_METHODS
 143 /* Return a certificate for the PEM representation of this certificate.
 144    Return NULL the passed in der_certificate is not a valid DER encoded X.509
 145    certificate, and return a CFError by reference.  It is the
 146    responsibility of the caller to release the CFError. */
 147 SecCertificateRefP SecCertificateCreateWithPEMP(CFAllocatorRef allocator,
 148         CFStringRef pem_certificate);
 149
 150 /* Return a CFStringRef containing the the pem representation of this
 151    certificate. */
 152 CFStringRef SecCertificateGetPEMP(SecCertificateRefP der_certificate);
 153
 154 #endif /* OPTIONAL_METHODS */
 155
 156 #if 0
 157 /* Complete the certificate chain of this certificate, setting the parent
 158    certificate for each certificate along they way.  Return 0 if the
 159    system is able to find all the certificates to complete the certificate
 160    chain either in the passed in other_certificates array or in the user or
 161    the systems keychain(s).
 162    If the certificate's issuer chain can not be completed, this function
 163    will return an error status code.
 164    NOTE: This function does not verify whether the certificate is trusted it's
 165    main use is just to ensure that anyone using this certificate upstream will
 166    have access to a complete (or as complete as possible in the case of
 167    something going wrong) certificate chain.  */
 168 OSStatus SecCertificateCompleteChainP(SecCertificateRefP certificate,
 169         CFArrayRef other_certificates);
 170 #endif
 171
 172 #if 0
 173
 174 /*!
 175         @function SecCertificateGetVersionNumberP
 176         @abstract Retrieves the version of a given certificate as a CFNumberRef.
 177     @param certificate A reference to the certificate from which to obtain the certificate version.
 178         @result A CFNumberRef representing the certificate version.  The following values are currently known to be returned, but more may be added in the future:
 179         1: X509v1
 180         2: X509v2
 181         3: X509v3
 182 */
 183 CFNumberRef SecCertificateGetVersionNumberP(SecCertificateRefP certificate);
 184
 185 /*!
 186         @function SecCertificateGetSerialDERP
 187         @abstract Retrieves the serial number of a given certificate in DER encoding.
 188     @param certificate A reference to the certificate from which to obtain the serial number.
 189         @result A CFDataRef containing the DER encoded serial number of the certificate, minus the tag and length fields.
 190 */
 191 CFDataRef SecCertificateGetSerialDERP(SecCertificateRefP certificate);
 192
 193
 194 /*!
 195         @function SecCertificateGetSerialStringP
 196         @abstract Retrieves the serial number of a given certificate in human readable form.
 197     @param certificate A reference to the certificate from which to obtain the serial number.
 198         @result A CFStringRef containing the human readable serial number of the certificate in decimal form.
 199 */
 200 CFStringRef SecCertificateGetSerialStringP(SecCertificateRefP certificate);
 201
 202
 203
 204 CFDataRef SecCertificateGetPublicKeyDERP(SecCertificateRefP certificate);
 205 CFDataRef SecCertificateGetPublicKeySHA1FingerPrintP(SecCertificateRefP certificate);
 206 CFDataRef SecCertificateGetPublicKeyMD5FingerPrintP(SecCertificateRefP certificate);
 207 CFDataRef SecCertificateGetSignatureAlgorithmDERP(SecCertificateRefP certificate);
 208 CFDataRef SecCertificateGetSignatureAlgorithmNameP(SecCertificateRefP certificate);
 209 CFStringRef SecCertificateGetSignatureAlgorithmOIDP(SecCertificateRefP certificate);
 210 CFDataRef SecCertificateGetSignatureDERP(SecCertificateRefP certificate);
 211 CFDataRef SecCertificateGetSignatureAlgorithmParametersDERP(SecCertificateRefP certificate);
 212
 213 /* plist top level array is orderd list of key/value pairs */
 214 CFArrayRef SecCertificateGetSignatureAlgorithmParametersArrayP(SecCertificateRefP certificate);
 215
 216 #if 0
 217 /* This cert is signed by its parent? */
 218 bool SecCertificateIsSignatureValidP(SecCertificateRefP certificate);
 219
 220 /* This cert is signed by its parent and so on until no parent certificate can be found? */
 221 bool SecCertificateIsIssuerChainValidP(SecCertificateRefP certificate, CFArrayRef additionalCertificatesToSearch);
 222
 223 /* This cert is signed by its parent and so on until no parent certificate can be found? */
 224 bool SecCertificateIsSignatureChainValidP(SecCertificateRefP certificate);
 225
 226 /* This cert is signed by its parent and so on until a certiicate in anchors can be found. */
 227 bool SecCertificateIssuerChainHasAnchorInP(SecCertificateRefP certificate, CFArrayRef anchors);
 228
 229 /* This cert is signed by its parent and so on until a certiicate in anchors can be found. */
 230 bool SecCertificateSignatureChainHasAnchorInP(SecCertificateRefP certificate, CFArrayRef anchors);
 231
 232 bool SecCertificateIsSelfSignedP(SecCertificateRefP certificate);
 233 #endif
 234
 235
 236 /* The entire certificate in DER encoding including the outer tag and length fields. */
 237 CFDataRef SecCertificateGetDERP(SecCertificateRefP certificate);
 238
 239 /* Returns the status code of the last failed call for this certificate on this thread. */
 240 OSStatus SecCertificateGetStatusP(SecCertificateRefP certificate);
 241
 242 CFDataRef SecCertificateGetIssuerDERP(SecCertificateRefP certificate);
 243 CFDataRef SecCertificateGetNormalizedIssuerDERP(SecCertificateRefP certificate);
 244
 245 /* 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. */
 246 CFArrayRef SecCertificateGetIssuerArrayP(SecCertificateRefP certificate);
 247
 248
 249 CFDataRef SecCertificateGetSubjectDERP(SecCertificateRefP certificate);
 250 CFDataRef SecCertificateGetNormalizedSubjectDERP(SecCertificateRefP certificate);
 251 /* See SecCertificateGetIssuerArray for a description of the returned array. */
 252 CFArrayRef SecCertificateGetSubjectArrayP(SecCertificateRefP certificate);
 253
 254 CFDateRef SecCertificateGetNotValidBeforeDateP(SecCertificateRefP certificate);
 255 CFDateRef SecCertificateGetNotValidDateP(SecCertificateRefP certificate);
 256
 257
 258 #if 0
 259
 260 CFIndex SecCertificateGetExtensionCountP(SecCertificateRefP certificate,  index);
 261 CFDataRef SecCertificateGetExtensionAtIndexDERP(SecCertificateRefP certificate, CFIndex index);
 262 bool SecCertificateIsExtensionAtIndexCriticalP(SecCertificateRefP certificate, CFIndex index);
 263
 264 /* array see email example. */
 265 CFArrayRef SecCertificateGetExtensionAtIndexParamsArrayP(SecCertificateRefP certificate, CFIndex index);
 266
 267 CFStringRef SecCertificateGetExtensionAtIndexNameP(SecCertificateRefP certificate, CFIndex index);
 268 CFStringRef SecCertificateGetExtensionAtIndexOIDP(SecCertificateRefP certificate, CFIndex index);
 269
 270 #else
 271
 272 /* Return an array with all of this certificates SecCertificateExtensionRefs. */
 273 CFArrayRef SecCertificateGetExtensionsP(SecCertificateRefP certificate);
 274
 275 /* 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. */
 276 SecCertificateExtensionRef SecCertificateGetExtensionWithOIDP(SecCertificateRefP certificate, CFDataRef oid);
 277
 278 CFDataRef SecCertificateExtensionGetDERP(SecCertificateExtensionRef extension, CFDataRef oid);
 279 CFStringRef SecCertificateExtensionNameP(SecCertificateExtensionRef extension);
 280 CFDataRef SecCertificateExtensionGetOIDDERP(SecCertificateExtensionRef extension, CFDataRef oid);
 281 CFStringRef SecCertificateExtensionGetOIDStringP(SecCertificateExtensionRef extension, CFDataRef oid);
 282 bool SecCertificateExtensionIsCriticalP(SecCertificateExtensionRef extension);
 283 CFArrayRef SecCertificateExtensionGetContentDERP(SecCertificateExtensionRef extension);
 284
 285 /* 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.  */
 286 CFArrayRef SecCertificateExtensionGetContentArrayP(SecCertificateExtensionRef extension);
 287
 288 #endif /* 0 */
 289
 290 #endif /* 0 */
 291
 292
 293 void appendPropertyP(CFMutableArrayRef properties,
 294     CFStringRef propertyType, CFStringRef label, CFTypeRef value);
 295
 296 /* Utility functions. */
 297 CFStringRef SecDERItemCopyOIDDecimalRepresentation(CFAllocatorRef allocator,
 298     const DERItem *oid);
 299 CFDataRef createNormalizedX501Name(CFAllocatorRef allocator,
 300         const DERItem *x501name);
 301
 302 /* Decode a choice of UTCTime or GeneralizedTime to a CFAbsoluteTime. Return
 303    an absoluteTime if the date was valid and properly decoded.  Return
 304    NULL_TIME otherwise. */
 305 CFAbsoluteTime SecAbsoluteTimeFromDateContent(DERTag tag, const uint8_t *bytes,
 306     size_t length);
 307
 308 #if defined(__cplusplus)
 309 }
 310 #endif
 311
 312 #endif /* !_SECURITY_SECCERTIFICATEINTERNAL_H_ */