OSX/sec/Security/SecCertificatePath.h

   1 /*
   2  * Copyright (c) 2007-2009,2012-2016 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         @header SecCertificatePath
  26         CoreFoundation based certificate path object
  27 */
  28
  29 #ifndef _SECURITY_SECCERTIFICATEPATH_H_
  30 #define _SECURITY_SECCERTIFICATEPATH_H_
  31
  32 #include <Security/SecCertificate.h>
  33 #include <CoreFoundation/CFArray.h>
  34 #include <CoreFoundation/CFDictionary.h>
  35 #include <CoreFoundation/CFDate.h>
  36 #include <CoreFoundation/CFError.h>
  37 #include <xpc/xpc.h>
  38
  39 __BEGIN_DECLS
  40
  41 typedef struct SecCertificatePath *SecCertificatePathRef;
  42
  43 /* SecCertificatePath API functions. */
  44 CFTypeID SecCertificatePathGetTypeID(void);
  45
  46 /* Create a new certificate path from an old one. */
  47 SecCertificatePathRef SecCertificatePathCreate(SecCertificatePathRef path,
  48         SecCertificateRef certificate, CFArrayRef usageConstraints);
  49
  50 /* Create a new certificate path from an xpc_array of datas. */
  51 SecCertificatePathRef SecCertificatePathCreateWithXPCArray(xpc_object_t xpc_path, CFErrorRef *error);
  52
  53 /* Create a new certificate path from a CFArray of datas. */
  54 SecCertificatePathRef SecCertificatePathCreateDeserialized(CFArrayRef certificates, CFErrorRef *error);
  55
  56 /* Create an array of CFDataRefs from a certificate path. */
  57 xpc_object_t SecCertificatePathCopyXPCArray(SecCertificatePathRef path, CFErrorRef *error);
  58
  59 /* Create an array of SecCertificateRefs from a certificate path. */
  60 CFArrayRef SecCertificatePathCopyCertificates(SecCertificatePathRef path, CFErrorRef *error);
  61
  62 /* Create a serialized Certificate Array from a certificate path. */
  63 CFArrayRef SecCertificatePathCreateSerialized(SecCertificatePathRef path, CFErrorRef *error);
  64
  65 SecCertificatePathRef SecCertificatePathCopyAddingLeaf(SecCertificatePathRef path,
  66 SecCertificateRef leaf);
  67
  68 /* Return a new certificate path without the first skipCount certificates. */
  69 SecCertificatePathRef SecCertificatePathCopyFromParent(SecCertificatePathRef path, CFIndex skipCount);
  70
  71 /* Record the fact that we found our own root cert as our parent
  72    certificate. */
  73 void SecCertificatePathSetSelfIssued(
  74         SecCertificatePathRef certificatePath);
  75
  76 void SecCertificatePathSetIsAnchored(
  77         SecCertificatePathRef certificatePath);
  78
  79 /* Return the index of the first non anchor certificate in the chain that is
  80    self signed counting from the leaf up.  Return -1 if there is none. */
  81 CFIndex SecCertificatePathSelfSignedIndex(
  82         SecCertificatePathRef certificatePath);
  83
  84 Boolean SecCertificatePathIsAnchored(
  85         SecCertificatePathRef certificatePath);
  86
  87 void SecCertificatePathSetNextSourceIndex(
  88         SecCertificatePathRef certificatePath, CFIndex sourceIndex);
  89
  90 CFIndex SecCertificatePathGetNextSourceIndex(
  91         SecCertificatePathRef certificatePath);
  92
  93 CFIndex SecCertificatePathGetCount(
  94         SecCertificatePathRef certificatePath);
  95
  96 SecCertificateRef SecCertificatePathGetCertificateAtIndex(
  97         SecCertificatePathRef certificatePath, CFIndex ix);
  98
  99 /* Return the index of certificate in path or kCFNotFound if certificate is
 100    not in path. */
 101 CFIndex SecCertificatePathGetIndexOfCertificate(SecCertificatePathRef path,
 102     SecCertificateRef certificate);
 103
 104 /* Return the root certificate for certificatePath.  Note that root is just
 105    the top of the path as far as it is constructed.  It may or may not be
 106    trusted or self signed.  */
 107 SecCertificateRef SecCertificatePathGetRoot(
 108         SecCertificatePathRef certificatePath);
 109
 110 CFArrayRef SecCertificatePathGetUsageConstraintsAtIndex(
 111         SecCertificatePathRef certificatePath, CFIndex ix);
 112
 113 SecKeyRef SecCertificatePathCopyPublicKeyAtIndex(
 114         SecCertificatePathRef certificatePath, CFIndex ix);
 115
 116 typedef CFIndex SecPathVerifyStatus;
 117 enum {
 118         kSecPathVerifiesUnknown = -1,
 119         kSecPathVerifySuccess = 0,
 120         kSecPathVerifyFailed = 1
 121 };
 122
 123 SecPathVerifyStatus SecCertificatePathVerify(
 124         SecCertificatePathRef certificatePath);
 125
 126 bool SecCertificatePathIsValid(SecCertificatePathRef certificatePath, CFAbsoluteTime verifyTime);
 127
 128 bool SecCertificatePathHasWeakHash(SecCertificatePathRef certificatePath);
 129
 130 bool SecCertificatePathHasWeakKeySize(SecCertificatePathRef certificatePath);
 131
 132 CFIndex SecCertificatePathScore(SecCertificatePathRef certificatePath,
 133         CFAbsoluteTime verifyTime);
 134
 135
 136 /*
 137 Node based version is possible.  We need to make sure we extract algorithm oid and parameters in the chain.  When constructing a new path (with a new parent from a path with the child at it's head), we duplicate each child node for which we could not previously establish a public key because the parameters were missing and there was no cert with the same algorithm in the chain which does have parameters.  This is because, when extended with a different parent certificate that has different parameters for the childs algorithm, the signatures in the child chain must be reverified using the new parameters and therefore might yeild a different result.
 138 We could allow more sharing if we stored the parameters found in the search up the chain in each node, and only duplicate the nodes if the parameters differ and then reset the isSigned status of each node with changed parameters. */
 139
 140 __END_DECLS
 141
 142 #endif /* !_SECURITY_SECCERTIFICATEPATH_H_ */