1/*
2 * Copyright (c) 2006-2012 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
49typedef uint32_t SecKeyUsage;
50enum {
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
66typedef uint32_t SecCertificateEscrowRootType;
67enum {
68    kSecCertificateBaselineEscrowRoot = 0,
69    kSecCertificateProductionEscrowRoot = 1,
70};
71
72/* The names of the files that contain the escrow certificates */
73extern CFTypeRef kSecCertificateProductionEscrowKey;
74extern CFTypeRef kSecCertificateEscrowFileName;
75
76
77/* Return a certificate for the DER representation of this certificate.
78   Return NULL if the passed-in data is not a valid DER-encoded X.509
79   certificate. */
80SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
81	const UInt8 *bytes, CFIndex length);
82
83/* Return the length of the DER representation of this certificate. */
84CFIndex SecCertificateGetLength(SecCertificateRef certificate);
85
86/* Return the bytes of the DER representation of this certificate. */
87const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
88
89// MARK: -
90// MARK: Certificate Accessors
91
92CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate);
93
94CFDataRef SecCertificateCopyIssuerSHA1Digest(SecCertificateRef certificate);
95
96CFDataRef SecCertificateCopyPublicKeySHA1Digest(SecCertificateRef certificate);
97
98/*!
99	@function SecCertificateCopyIssuerSummary
100	@abstract Return a simple string which hopefully represents a human understandable issuer.
101    @param certificate SecCertificate object created with SecCertificateCreateWithData().
102    @discussion All the data in this string comes from the certificate itself
103    and thus it's in whatever language the certificate itself is in.
104	@result A CFStringRef which the caller should CFRelease() once it's no longer needed.
105*/
106CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
107
108/*!
109	@function SecCertificateCopyProperties
110	@abstract Return a property array for this trust certificate.
111	@param certificate A reference to the certificate to evaluate.
112    @result A property array. It is the caller's responsability to CFRelease
113    the returned array when it is no longer needed.
114    See SecTrustCopySummaryPropertiesAtIndex on how to intepret this array.
115	Unlike that function call this function returns a detailed description
116    of the certificate in question.
117*/
118CFArrayRef SecCertificateCopyProperties(SecCertificateRef certificate);
119
120CFMutableArrayRef SecCertificateCopySummaryProperties(
121    SecCertificateRef certificate, CFAbsoluteTime verifyTime);
122
123/* Return the content of a DER-encoded integer (without the tag and length
124   fields) for this certificate's serial number.   The caller must CFRelease
125   the value returned.  */
126CFDataRef SecCertificateCopySerialNumber(SecCertificateRef certificate);
127
128/* Return an array of CFStringRefs representing the ip addresses in the
129   certificate if any. */
130CFArrayRef SecCertificateCopyIPAddresses(SecCertificateRef certificate);
131
132/* Return an array of CFStringRefs representing the dns addresses in the
133   certificate if any. */
134CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate);
135
136/* Return an array of CFStringRefs representing the email addresses in the
137   certificate if any. */
138CFArrayRef SecCertificateCopyRFC822Names(SecCertificateRef certificate);
139
140/* Return an array of CFStringRefs representing the common names in the
141   certificates subject if any. */
142CFArrayRef SecCertificateCopyCommonNames(SecCertificateRef certificate);
143
144/* Return an array of CFStringRefs representing the organization in the
145   certificate's subject if any. */
146CFArrayRef SecCertificateCopyOrganization(SecCertificateRef certificate);
147
148/* Return an array of CFStringRefs representing the organizational unit in the
149   certificate's subject if any. */
150CFArrayRef SecCertificateCopyOrganizationalUnit(SecCertificateRef certificate);
151
152/* Return an array of CFStringRefs representing the NTPrincipalNames in the
153   certificate if any. */
154CFArrayRef SecCertificateCopyNTPrincipalNames(SecCertificateRef certificate);
155
156/* Return a string formatted according to RFC 2253 representing the complete
157   subject of certificate. */
158CFStringRef SecCertificateCopySubjectString(SecCertificateRef certificate);
159
160/* Return a string with the company name of an ev leaf certificate. */
161CFStringRef SecCertificateCopyCompanyName(SecCertificateRef certificate);
162
163/* X.509 Certificate Version: 1, 2 or 3. */
164CFIndex SecCertificateVersion(SecCertificateRef certificate);
165CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate);
166CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate);
167
168/* Return true iff certificate is self signed and has a basic constraints
169   extension indicating that it's a certificate authority. */
170bool SecCertificateIsSelfSignedCA(SecCertificateRef certificate);
171
172SecKeyUsage SecCertificateGetKeyUsage(SecCertificateRef certificate);
173
174/* Returns an array of CFDataRefs for all extended key usage oids or NULL */
175CFArrayRef SecCertificateCopyExtendedKeyUsage(SecCertificateRef certificate);
176
177/* Returns a certificate from a pem blob */
178SecCertificateRef SecCertificateCreateWithPEM(CFAllocatorRef allocator,
179	CFDataRef pem_certificate);
180
181/* Append certificate to xpc_certificates. */
182bool SecCertificateAppendToXPCArray(SecCertificateRef certificate, xpc_object_t xpc_certificates, CFErrorRef *error);
183
184/* Decode certificate from xpc_certificates[index] as encoded by SecCertificateAppendToXPCArray(). */
185SecCertificateRef SecCertificateCreateWithXPCArrayAtIndex(xpc_object_t xpc_certificates, size_t index, CFErrorRef *error);
186
187/* Retrieve the array of valid Escrow certificates for a given root type */
188CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType);
189
190/* Return an xpc_array of data from an array of SecCertificateRefs. */
191xpc_object_t SecCertificateArrayCopyXPCArray(CFArrayRef certificates, CFErrorRef *error);
192
193/* Return an array of SecCertificateRefs from a xpc_object array of datas. */
194CFArrayRef SecCertificateXPCArrayCopyArray(xpc_object_t xpc_certificates, CFErrorRef *error);
195
196__END_DECLS
197
198#endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */
199