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 uint32_t SecKeyUsage;
  50 enum {
  51     kSecKeyUsageUnspecified      = 0,
  52     kSecKeyUsageDigitalSignature = 1 << 0,
  53     kSecKeyUsageNonRepudiation   = 1 << 1,
  54     kSecKeyUsageContentCommitment= 1 << 1,
  55     kSecKeyUsageKeyEncipherment  = 1 << 2,
  56     kSecKeyUsageDataEncipherment = 1 << 3,
  57     kSecKeyUsageKeyAgreement     = 1 << 4,
  58     kSecKeyUsageKeyCertSign      = 1 << 5,
  59     kSecKeyUsageCRLSign          = 1 << 6,
  60     kSecKeyUsageEncipherOnly     = 1 << 7,
  61     kSecKeyUsageDecipherOnly     = 1 << 8,
  62     kSecKeyUsageCritical         = 1 << 31,
  63     kSecKeyUsageAll              = 0x7FFFFFFF
  64 };
  65
  66 typedef uint32_t SecCertificateEscrowRootType;
  67 enum {
  68     kSecCertificateBaselineEscrowRoot = 0,
  69     kSecCertificateProductionEscrowRoot = 1,
  70     kSecCertificateBaselinePCSEscrowRoot = 2,
  71     kSecCertificateProductionPCSEscrowRoot = 3,
  72 };
  73
  74 /* The names of the files that contain the escrow certificates */
  75 extern const CFStringRef kSecCertificateProductionEscrowKey;
  76 extern const CFStringRef kSecCertificateProductionPCSEscrowKey;
  77 extern const CFStringRef kSecCertificateEscrowFileName;
  78
  79
  80 /* Return a certificate for the DER representation of this certificate.
  81    Return NULL if the passed-in data is not a valid DER-encoded X.509
  82    certificate. */
  83 SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
  84         const UInt8 *bytes, CFIndex length);
  85
  86 /* Return the length of the DER representation of this certificate. */
  87 CFIndex SecCertificateGetLength(SecCertificateRef certificate);
  88
  89 /* Return the bytes of the DER representation of this certificate. */
  90 const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
  91
  92 // MARK: -
  93 // MARK: Certificate Accessors
  94
  95 CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate);
  96
  97 CFDataRef SecCertificateCopyIssuerSHA1Digest(SecCertificateRef certificate);
  98
  99 CFDataRef SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate);
 100
 101 CFDataRef SecCertificateCopySubjectPublicKeyInfoSHA256Digest(SecCertificateRef certificate);
 102
 103 CFDataRef SecCertificateCopySHA256Digest(SecCertificateRef certificate);
 104
 105 SecCertificateRef SecCertificateCreateWithKeychainItem(CFAllocatorRef allocator,
 106         CFDataRef der_certificate, CFTypeRef keychainItem);
 107
 108 CFTypeRef SecCertificateCopyKeychainItem(SecCertificateRef certificate);
 109
 110 /*!
 111         @function SecCertificateCopyIssuerSummary
 112         @abstract Return a simple string which hopefully represents a human understandable issuer.
 113     @param certificate SecCertificate object created with SecCertificateCreateWithData().
 114     @discussion All the data in this string comes from the certificate itself
 115     and thus it's in whatever language the certificate itself is in.
 116         @result A CFStringRef which the caller should CFRelease() once it's no longer needed.
 117 */
 118 CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
 119
 120 /*!
 121         @function SecCertificateCopyProperties
 122         @abstract Return a property array for this trust certificate.
 123         @param certificate A reference to the certificate to evaluate.
 124     @result A property array. It is the caller's responsability to CFRelease
 125     the returned array when it is no longer needed.
 126     See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
 127         Unlike that function call this function returns a detailed description
 128     of the certificate in question.
 129 */
 130 CFArrayRef SecCertificateCopyProperties(SecCertificateRef certificate);
 131
 132 CFMutableArrayRef SecCertificateCopySummaryProperties(
 133     SecCertificateRef certificate, CFAbsoluteTime verifyTime);
 134
 135 /* Return the content of a DER-encoded integer (without the tag and length
 136    fields) for this certificate's serial number.   The caller must CFRelease
 137    the value returned.  */
 138 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE))
 139 CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate, CFErrorRef *error);
 140 #else
 141 CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate);
 142 #endif
 143
 144 /* Return an array of CFStringRefs representing the ip addresses in the
 145    certificate if any. */
 146 CFArrayRef SecCertificateCopyIPAddresses(SecCertificateRef certificate);
 147
 148 /* Return an array of CFStringRefs representing the dns addresses in the
 149    certificate if any. */
 150 CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate);
 151
 152 /* Return an array of CFStringRefs representing the email addresses in the
 153    certificate if any. */
 154 CFArrayRef SecCertificateCopyRFC822Names(SecCertificateRef certificate);
 155
 156 /* Return an array of CFStringRefs representing the common names in the
 157    certificates subject if any. */
 158 CFArrayRef SecCertificateCopyCommonNames(SecCertificateRef certificate);
 159
 160 /* Return an array of CFStringRefs representing the organization in the
 161    certificate's subject if any. */
 162 CFArrayRef SecCertificateCopyOrganization(SecCertificateRef certificate);
 163
 164 /* Return an array of CFStringRefs representing the organizational unit in the
 165    certificate's subject if any. */
 166 CFArrayRef SecCertificateCopyOrganizationalUnit(SecCertificateRef certificate);
 167
 168 /* Return an array of CFStringRefs representing the NTPrincipalNames in the
 169    certificate if any. */
 170 CFArrayRef SecCertificateCopyNTPrincipalNames(SecCertificateRef certificate);
 171
 172 /* Return a string formatted according to RFC 2253 representing the complete
 173    subject of certificate. */
 174 CFStringRef SecCertificateCopySubjectString(SecCertificateRef certificate);
 175
 176 /* Return a string with the company name of an ev leaf certificate. */
 177 CFStringRef SecCertificateCopyCompanyName(SecCertificateRef certificate);
 178
 179 /* X.509 Certificate Version: 1, 2 or 3. */
 180 CFIndex SecCertificateVersion(SecCertificateRef certificate);
 181 CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate);
 182 CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate);
 183
 184 /* Return true in isSelfSigned output parameter if certificate is self-signed.
 185    Function result is a non-zero status if the answer cannot be determined
 186    (e.g. certRef is invalid), otherwise errSecSuccess. */
 187 OSStatus SecCertificateIsSelfSigned(SecCertificateRef certRef, Boolean *isSelfSigned);
 188
 189 /* Return true iff certificate is self signed and has a basic constraints
 190    extension indicating that it's a certificate authority. */
 191 bool SecCertificateIsSelfSignedCA(SecCertificateRef certificate);
 192
 193 SecKeyUsage SecCertificateGetKeyUsage(SecCertificateRef certificate);
 194
 195 /* Returns an array of CFDataRefs for all extended key usage oids or NULL */
 196 CFArrayRef SecCertificateCopyExtendedKeyUsage(SecCertificateRef certificate);
 197
 198 /* Returns an array of CFDataRefs for all embedded SCTs */
 199 CFArrayRef SecCertificateCopySignedCertificateTimestamps(SecCertificateRef certificate);
 200
 201 /* Returns a certificate from a pem blob */
 202 SecCertificateRef SecCertificateCreateWithPEM(CFAllocatorRef allocator,
 203         CFDataRef pem_certificate);
 204
 205 /* Append certificate to xpc_certificates. */
 206 bool SecCertificateAppendToXPCArray(SecCertificateRef certificate, xpc_object_t xpc_certificates, CFErrorRef *error);
 207
 208 /* Decode certificate from xpc_certificates[index] as encoded by SecCertificateAppendToXPCArray(). */
 209 SecCertificateRef SecCertificateCreateWithXPCArrayAtIndex(xpc_object_t xpc_certificates, size_t index, CFErrorRef *error);
 210
 211 /* Retrieve the array of valid Escrow certificates for a given root type */
 212 CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType);
 213
 214 /* Return an xpc_array of data from an array of SecCertificateRefs. */
 215 xpc_object_t SecCertificateArrayCopyXPCArray(CFArrayRef certificates, CFErrorRef *error);
 216
 217 /* Return an array of SecCertificateRefs from a xpc_object array of datas. */
 218 CFArrayRef SecCertificateXPCArrayCopyArray(xpc_object_t xpc_certificates, CFErrorRef *error);
 219
 220 /* Return the precert TBSCertificate DER data - used for Certificate Transparency */
 221 CFDataRef SecCertificateCopyPrecertTBS(SecCertificateRef certificate);
 222
 223 /*
 224  * Enumerated constants for signature hash algorithms.
 225  */
 226 typedef uint32_t SecSignatureHashAlgorithm;
 227 enum {
 228     kSecSignatureHashAlgorithmUnknown = 0,
 229     kSecSignatureHashAlgorithmMD2 = 1,
 230     kSecSignatureHashAlgorithmMD4 = 2,
 231     kSecSignatureHashAlgorithmMD5 = 3,
 232     kSecSignatureHashAlgorithmSHA1 = 4,
 233     kSecSignatureHashAlgorithmSHA224 = 5,
 234     kSecSignatureHashAlgorithmSHA256 = 6,
 235     kSecSignatureHashAlgorithmSHA384 = 7,
 236     kSecSignatureHashAlgorithmSHA512 = 8
 237 };
 238
 239 /*!
 240         @function SecCertificateGetSignatureHashAlgorithm
 241         @abstract Determine the hash algorithm used in a certificate's signature.
 242         @param certificate A certificate reference.
 243         @result Returns an enumerated value indicating the signature hash algorithm
 244         used in a certificate. If the hash algorithm is unsupported or cannot be
 245         obtained (e.g. because the supplied certificate reference is invalid), a
 246         value of 0 (kSecSignatureHashAlgorithmUnknown) is returned.
 247 */
 248 SecSignatureHashAlgorithm SecCertificateGetSignatureHashAlgorithm(SecCertificateRef certificate)
 249     __OSX_AVAILABLE_STARTING(__MAC_10_11, __IPHONE_9_0);
 250
 251
 252 __END_DECLS
 253
 254 #endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */