OSX/sec/Security/SecCertificatePriv.h

   1 /*
   2  * Copyright (c) 2006-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         @header SecCertificatePriv
  26         The functions provided in SecCertificatePriv.h implement and manage a particular
  27         type of keychain item that represents a certificate.  You can store a
  28         certificate in a keychain, but a certificate can also be a transient
  29         object.
  30
  31         You can use a certificate as a keychain item in most functions.
  32         Certificates are able to compute their parent certificates, and much more.
  33 */
  34
  35 #ifndef _SECURITY_SECCERTIFICATEPRIV_H_
  36 #define _SECURITY_SECCERTIFICATEPRIV_H_
  37
  38 #include <Security/SecCertificate.h>
  39 #include <CoreFoundation/CFArray.h>
  40 #include <CoreFoundation/CFData.h>
  41 #include <CoreFoundation/CFDate.h>
  42 #include <CoreFoundation/CFDictionary.h>
  43 #include <CoreFoundation/CFError.h>
  44 #include <stdbool.h>
  45 #include <xpc/xpc.h>
  46
  47 __BEGIN_DECLS
  48
  49 typedef CF_OPTIONS(uint32_t, SecKeyUsage) {
  50     kSecKeyUsageUnspecified      = 0,
  51     kSecKeyUsageDigitalSignature = 1 << 0,
  52     kSecKeyUsageNonRepudiation   = 1 << 1,
  53     kSecKeyUsageContentCommitment= 1 << 1,
  54     kSecKeyUsageKeyEncipherment  = 1 << 2,
  55     kSecKeyUsageDataEncipherment = 1 << 3,
  56     kSecKeyUsageKeyAgreement     = 1 << 4,
  57     kSecKeyUsageKeyCertSign      = 1 << 5,
  58     kSecKeyUsageCRLSign          = 1 << 6,
  59     kSecKeyUsageEncipherOnly     = 1 << 7,
  60     kSecKeyUsageDecipherOnly     = 1 << 8,
  61     kSecKeyUsageCritical         = 1 << 31,
  62     kSecKeyUsageAll              = 0x7FFFFFFF
  63 };
  64
  65 typedef CF_ENUM(uint32_t, SecCertificateEscrowRootType) {
  66     kSecCertificateBaselineEscrowRoot = 0,
  67     kSecCertificateProductionEscrowRoot = 1,
  68     kSecCertificateBaselinePCSEscrowRoot = 2,
  69     kSecCertificateProductionPCSEscrowRoot = 3,
  70     kSecCertificateBaselineEscrowBackupRoot = 4,        // v100 and v101
  71     kSecCertificateProductionEscrowBackupRoot = 5,
  72     kSecCertificateBaselineEscrowEnrollmentRoot = 6,    // v101 only
  73     kSecCertificateProductionEscrowEnrollmentRoot = 7,
  74 };
  75
  76 /* The names of the files that contain the escrow certificates */
  77 extern const CFStringRef kSecCertificateProductionEscrowKey;
  78 extern const CFStringRef kSecCertificateProductionPCSEscrowKey;
  79 extern const CFStringRef kSecCertificateEscrowFileName;
  80
  81
  82 /* Return a certificate for the DER representation of this certificate.
  83    Return NULL if the passed-in data is not a valid DER-encoded X.509
  84    certificate. */
  85 SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
  86         const UInt8 *bytes, CFIndex length);
  87
  88 /* Return the length of the DER representation of this certificate. */
  89 CFIndex SecCertificateGetLength(SecCertificateRef certificate);
  90
  91 /* Return the bytes of the DER representation of this certificate. */
  92 const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
  93
  94 // MARK: -
  95 // MARK: Certificate Accessors
  96
  97 CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate);
  98
  99 CFDataRef SecCertificateCopyIssuerSHA1Digest(SecCertificateRef certificate);
 100
 101 CFDataRef SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate);
 102
 103 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA1Digest(SecCertificateRef certificate);
 104
 105 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA256Digest(SecCertificateRef certificate);
 106
 107 CFDataRef SecCertificateCopySHA256Digest(SecCertificateRef certificate);
 108
 109 SecKeyRef SecCertificateCopyPublicKey(SecCertificateRef certificate);
 110
 111 SecCertificateRef SecCertificateCreateWithKeychainItem(CFAllocatorRef allocator,
 112         CFDataRef der_certificate, CFTypeRef keychainItem);
 113
 114 OSStatus SecCertificateSetKeychainItem(SecCertificateRef certificate,
 115         CFTypeRef keychain_item);
 116
 117 CFTypeRef SecCertificateCopyKeychainItem(SecCertificateRef certificate);
 118
 119 /*!
 120         @function SecCertificateCopyIssuerSummary
 121         @abstract Return a simple string which hopefully represents a human understandable issuer.
 122     @param certificate SecCertificate object created with SecCertificateCreateWithData().
 123     @discussion All the data in this string comes from the certificate itself
 124     and thus it's in whatever language the certificate itself is in.
 125         @result A CFStringRef which the caller should CFRelease() once it's no longer needed.
 126 */
 127 CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
 128
 129 /*!
 130         @function SecCertificateCopyProperties
 131         @abstract Return a property array for this trust certificate.
 132         @param certificate A reference to the certificate to evaluate.
 133     @result A property array. It is the caller's responsability to CFRelease
 134     the returned array when it is no longer needed.
 135     See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
 136         Unlike that function call this function returns a detailed description
 137     of the certificate in question.
 138 */
 139 CFArrayRef SecCertificateCopyProperties(SecCertificateRef certificate);
 140
 141 CFMutableArrayRef SecCertificateCopySummaryProperties(
 142     SecCertificateRef certificate, CFAbsoluteTime verifyTime);
 143
 144 /* Return the content of a DER-encoded integer (without the tag and length
 145    fields) for this certificate's serial number.   The caller must CFRelease
 146    the value returned.  */
 147 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
 148 CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate, CFErrorRef *error);
 149 #else
 150 CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate);
 151 #endif
 152
 153 /* Return an array of CFStringRefs representing the ip addresses in the
 154    certificate if any. */
 155 CFArrayRef SecCertificateCopyIPAddresses(SecCertificateRef certificate);
 156
 157 /* Return an array of CFStringRefs representing the dns addresses in the
 158    certificate if any. */
 159 CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate);
 160
 161 /* Return an array of CFStringRefs representing the email addresses in the
 162    certificate if any. */
 163 CFArrayRef SecCertificateCopyRFC822Names(SecCertificateRef certificate);
 164
 165 /* Return an array of CFStringRefs representing the common names in the
 166    certificates subject if any. */
 167 CFArrayRef SecCertificateCopyCommonNames(SecCertificateRef certificate);
 168
 169 /* Return an array of CFStringRefs representing the organization in the
 170    certificate's subject if any. */
 171 CFArrayRef SecCertificateCopyOrganization(SecCertificateRef certificate);
 172
 173 /* Return an array of CFStringRefs representing the organizational unit in the
 174    certificate's subject if any. */
 175 CFArrayRef SecCertificateCopyOrganizationalUnit(SecCertificateRef certificate);
 176
 177 /* Return an array of CFStringRefs representing the NTPrincipalNames in the
 178    certificate if any. */
 179 CFArrayRef SecCertificateCopyNTPrincipalNames(SecCertificateRef certificate);
 180
 181 /* Return a string formatted according to RFC 2253 representing the complete
 182    subject of certificate. */
 183 CFStringRef SecCertificateCopySubjectString(SecCertificateRef certificate);
 184
 185 /* Return a string with the company name of an ev leaf certificate. */
 186 CFStringRef SecCertificateCopyCompanyName(SecCertificateRef certificate);
 187
 188 /* X.509 Certificate Version: 1, 2 or 3. */
 189 CFIndex SecCertificateVersion(SecCertificateRef certificate);
 190 CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate);
 191 CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate);
 192
 193 /* Return true in isSelfSigned output parameter if certificate is self-signed.
 194    Function result is a non-zero status if the answer cannot be determined
 195    (e.g. certRef is invalid), otherwise errSecSuccess. */
 196 OSStatus SecCertificateIsSelfSigned(SecCertificateRef certRef, Boolean *isSelfSigned);
 197
 198 /* Return true iff certificate is self signed and has a basic constraints
 199    extension indicating that it's a certificate authority. */
 200 bool SecCertificateIsSelfSignedCA(SecCertificateRef certificate);
 201
 202 /* Return true if certificate has a basic constraints extension
 203    indicating that it's a certificate authority. */
 204 bool SecCertificateIsCA(SecCertificateRef certificate);
 205
 206 SecKeyUsage SecCertificateGetKeyUsage(SecCertificateRef certificate);
 207
 208 /* Returns an array of CFDataRefs for all extended key usage oids or NULL */
 209 CFArrayRef SecCertificateCopyExtendedKeyUsage(SecCertificateRef certificate);
 210
 211 /* Returns an array of CFDataRefs for all embedded SCTs */
 212 CFArrayRef SecCertificateCopySignedCertificateTimestamps(SecCertificateRef certificate);
 213
 214 /* Returns a certificate from a pem blob */
 215 SecCertificateRef SecCertificateCreateWithPEM(CFAllocatorRef allocator,
 216         CFDataRef pem_certificate);
 217
 218 /* Append certificate to xpc_certificates. */
 219 bool SecCertificateAppendToXPCArray(SecCertificateRef certificate, xpc_object_t xpc_certificates, CFErrorRef *error);
 220
 221 /* Decode certificate from xpc_certificates[index] as encoded by SecCertificateAppendToXPCArray(). */
 222 SecCertificateRef SecCertificateCreateWithXPCArrayAtIndex(xpc_object_t xpc_certificates, size_t index, CFErrorRef *error);
 223
 224 /* Retrieve the array of valid Escrow certificates for a given root type */
 225 CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType);
 226
 227 /* Return an xpc_array of data from an array of SecCertificateRefs. */
 228 xpc_object_t SecCertificateArrayCopyXPCArray(CFArrayRef certificates, CFErrorRef *error);
 229
 230 /* Return an array of SecCertificateRefs from a xpc_object array of datas. */
 231 CFArrayRef SecCertificateXPCArrayCopyArray(xpc_object_t xpc_certificates, CFErrorRef *error);
 232
 233 /* Return the precert TBSCertificate DER data - used for Certificate Transparency */
 234 CFDataRef SecCertificateCopyPrecertTBS(SecCertificateRef certificate);
 235
 236 /* Return an attribute dictionary used to store this item in a keychain. */
 237 CFDictionaryRef SecCertificateCopyAttributeDictionary(SecCertificateRef certificate);
 238
 239 /*
 240  * Enumerated constants for signature hash algorithms.
 241  */
 242 typedef CF_ENUM(uint32_t, SecSignatureHashAlgorithm){
 243     kSecSignatureHashAlgorithmUnknown = 0,
 244     kSecSignatureHashAlgorithmMD2 = 1,
 245     kSecSignatureHashAlgorithmMD4 = 2,
 246     kSecSignatureHashAlgorithmMD5 = 3,
 247     kSecSignatureHashAlgorithmSHA1 = 4,
 248     kSecSignatureHashAlgorithmSHA224 = 5,
 249     kSecSignatureHashAlgorithmSHA256 = 6,
 250     kSecSignatureHashAlgorithmSHA384 = 7,
 251     kSecSignatureHashAlgorithmSHA512 = 8
 252 };
 253
 254 /*!
 255         @function SecCertificateGetSignatureHashAlgorithm
 256         @abstract Determine the hash algorithm used in a certificate's signature.
 257         @param certificate A certificate reference.
 258         @result Returns an enumerated value indicating the signature hash algorithm
 259         used in a certificate. If the hash algorithm is unsupported or cannot be
 260         obtained (e.g. because the supplied certificate reference is invalid), a
 261         value of 0 (kSecSignatureHashAlgorithmUnknown) is returned.
 262 */
 263 SecSignatureHashAlgorithm SecCertificateGetSignatureHashAlgorithm(SecCertificateRef certificate)
 264     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 265
 266 /* Return the auth capabilities bitmask from the iAP marker extension */
 267 CF_RETURNS_RETAINED CFDataRef SecCertificateCopyiAPAuthCapabilities(SecCertificateRef certificate)
 268     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 269
 270 typedef CF_ENUM(uint32_t, SeciAuthVersion) {
 271     kSeciAuthInvalid = 0,
 272     kSeciAuthVersion1 = 1, /* unused */
 273     kSeciAuthVersion2 = 2,
 274     kSeciAuthVersion3 = 3,
 275 } __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 276
 277 /* Return the iAuth version indicated by the certificate. This function does
 278  * not guarantee that the certificate is valid, so the caller must still call
 279  * SecTrustEvaluate to guarantee that the certificate was properly issued */
 280 SeciAuthVersion SecCertificateGetiAuthVersion(SecCertificateRef certificate)
 281     __OSX_AVAILABLE_STARTING(__MAC_10_12, __IPHONE_10_0);
 282
 283 __END_DECLS
 284
 285 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */