1/*
2 * Copyright (c) 2002-2004,2012-2013 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#ifndef _SECURITY_SECCERTIFICATEPRIV_H_
25#define _SECURITY_SECCERTIFICATEPRIV_H_
26
27#include <Security/SecBase.h>
28#include <Security/cssmtype.h>
29#include <Security/x509defs.h>
30#include <CoreFoundation/CFBase.h>
31#include <CoreFoundation/CFArray.h>
32#include <CoreFoundation/CFData.h>
33#include <CoreFoundation/CFDate.h>
34
35#if defined(__cplusplus)
36extern "C" {
37#endif
38
39typedef uint32_t SecCertificateEscrowRootType;
40enum {
41    kSecCertificateBaselineEscrowRoot = 0,
42    kSecCertificateProductionEscrowRoot = 1,
43};
44
45extern CFTypeRef kSecCertificateProductionEscrowKey;
46extern CFTypeRef kSecCertificateEscrowFileName;
47
48
49/* Return a certificate for the DER representation of this certificate.
50   Return NULL if the passed-in data is not a valid DER-encoded X.509
51   certificate. */
52SecCertificateRef SecCertificateCreateWithBytes(CFAllocatorRef allocator,
53    const UInt8 *bytes, CFIndex length);
54
55/* Return the length of the DER representation of this certificate. */
56CFIndex SecCertificateGetLength(SecCertificateRef certificate);
57
58/* Return the bytes of the DER representation of this certificate. */
59const UInt8 *SecCertificateGetBytePtr(SecCertificateRef certificate);
60
61/* Return the SHA-1 hash of this certificate. */
62CFDataRef SecCertificateGetSHA1Digest(SecCertificateRef certificate);
63
64/* Deprecated; use SecCertificateCopyCommonName() instead. */
65OSStatus SecCertificateGetCommonName(SecCertificateRef certificate, CFStringRef *commonName);
66
67/* Deprecated; use SecCertificateCopyEmailAddresses() instead. */
68/* This should have been Copy instead of Get since the returned address is not autoreleased. */
69OSStatus SecCertificateGetEmailAddress(SecCertificateRef certificate, CFStringRef *emailAddress);
70
71/* Return an array of CFStringRefs representing the dns addresses in the
72   certificate if any. */
73CFArrayRef SecCertificateCopyDNSNames(SecCertificateRef certificate);
74
75/*!
76	@function SecCertificateCopyIssuerSummary
77	@abstract Return a simple string which hopefully represents a human understandable issuer.
78	@param certificate SecCertificate object created with SecCertificateCreateWithData().
79	@discussion All the data in this string comes from the certificate itself
80	and thus it's in whatever language the certificate itself is in.
81	@result A CFStringRef which the caller should CFRelease() once it's no longer needed.
82*/
83CFStringRef SecCertificateCopyIssuerSummary(SecCertificateRef certificate);
84
85/*
86 * Private API to infer a display name for a SecCertificateRef which
87 * may or may not be in a keychain.
88 */
89OSStatus SecCertificateInferLabel(SecCertificateRef certificate, CFStringRef *label);
90
91/*
92 * Subset of the above, useful for both certs and CRLs.
93 * Infer printable label for a given an CSSM_X509_NAME. Returns NULL
94 * if no appropriate printable name found.
95 */
96const CSSM_DATA *SecInferLabelFromX509Name(
97	const CSSM_X509_NAME *x509Name);
98
99/* Accessors for fields in the cached certificate */
100
101/*!
102	@function SecCertificateCopyFieldValues
103	@abstract Retrieves the values for a particular field in a given certificate.
104    @param certificate A valid SecCertificateRef to the certificate.
105    @param field Pointer to the OID whose values should be returned.
106    @param fieldValues On return, a zero terminated list of CSSM_DATA_PTR's.
107	@result A result code.  See "Security Error Codes" (SecBase.h).
108	@discussion Return a zero terminated list of CSSM_DATA_PTR's with the
109	values of the field specified by field.  Caller must call
110	SecCertificateReleaseFieldValues to free the storage allocated by this call.
111*/
112OSStatus SecCertificateCopyFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR **fieldValues);
113
114/*!
115	@function SecCertificateReleaseFieldValues
116	@abstract Release the storage associated with the values returned by SecCertificateCopyFieldValues.
117    @param certificate A valid SecCertificateRef to the certificate.
118    @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValues.
119    @param fieldValues Pointer to a zero terminated list of CSSM_DATA_PTR's.
120	@result A result code.  See "Security Error Codes" (SecBase.h).
121	@discussion Release the storage associated with the values returned by SecCertificateCopyFieldValues.
122*/
123OSStatus SecCertificateReleaseFieldValues(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValues);
124
125/*!
126	@function SecCertificateCopyFirstFieldValue
127	@abstract Return a CSSM_DATA_PTR with the value of the first field specified by field.
128    @param certificate A valid SecCertificateRef to the certificate.
129    @param field Pointer to the OID whose value should be returned.
130    @param fieldValue On return, a CSSM_DATA_PTR to the field data.
131	@result A result code.  See "Security Error Codes" (SecBase.h).
132	@discussion Return a CSSM_DATA_PTR with the value of the first field specified by field.  Caller must call
133	SecCertificateReleaseFieldValue to free the storage allocated by this call.
134*/
135OSStatus SecCertificateCopyFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR *fieldValue);
136
137/*!
138	@function SecCertificateReleaseFirstFieldValue
139	@abstract Release the storage associated with the values returned by SecCertificateCopyFirstFieldValue.
140    @param certificate A valid SecCertificateRef to the certificate.
141    @param field Pointer to the OID whose values were returned by SecCertificateCopyFieldValue.
142    @param fieldValue The field data to release.
143	@result A result code.  See "Security Error Codes" (SecBase.h).
144	@discussion Release the storage associated with the values returned by SecCertificateCopyFieldValue.
145*/
146OSStatus SecCertificateReleaseFirstFieldValue(SecCertificateRef certificate, const CSSM_OID *field, CSSM_DATA_PTR fieldValue);
147
148/*!
149    @function SecCertificateCopySubjectComponent
150    @abstract Retrieves a component of the subject distinguished name of a given certificate.
151    @param certificate A reference to the certificate from which to retrieve the common name.
152	@param component A component oid naming the component desired. See <Security/oidsattr.h>.
153    @param result On return, a reference to the string form of the component, if present in the subject.
154		Your code must release this reference by calling the CFRelease function.
155    @result A result code. See "Security Error Codes" (SecBase.h).
156 */
157OSStatus SecCertificateCopySubjectComponent(SecCertificateRef certificate, const CSSM_OID *component,
158	CFStringRef *result);
159
160/* Return the DER encoded issuer sequence for the certificate's issuer. */
161CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate);
162
163/* Return the DER encoded subject sequence for the certificate's subject. */
164CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate);
165
166
167/*	Convenience functions for searching.
168*/
169
170OSStatus SecCertificateFindByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
171	const CSSM_DATA *serialNumber, 	SecCertificateRef *certificate);
172
173OSStatus SecCertificateFindBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
174	SecCertificateRef *certificate);
175
176OSStatus SecCertificateFindByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
177	SecCertificateRef *certificate);
178
179
180/* These should go to SecKeychainSearchPriv.h. */
181OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN(CFTypeRef keychainOrArray, const CSSM_DATA *issuer,
182	const CSSM_DATA *serialNumber, SecKeychainSearchRef *searchRef);
183
184OSStatus SecKeychainSearchCreateForCertificateByIssuerAndSN_CF(CFTypeRef keychainOrArray, CFDataRef issuer,
185	CFDataRef serialNumber, SecKeychainSearchRef *searchRef);
186
187OSStatus SecKeychainSearchCreateForCertificateBySubjectKeyID(CFTypeRef keychainOrArray, const CSSM_DATA *subjectKeyID,
188	SecKeychainSearchRef *searchRef);
189
190OSStatus SecKeychainSearchCreateForCertificateByEmail(CFTypeRef keychainOrArray, const char *emailAddress,
191	SecKeychainSearchRef *searchRef);
192
193/* Convenience function for generating digests; should be moved elsewhere. */
194CSSM_RETURN SecDigestGetData(CSSM_ALGORITHMS alg, CSSM_DATA* digest, const CSSM_DATA* data);
195
196/* Return true iff certificate is valid as of verifyTime. */
197/* DEPRECATED: Use SecCertificateIsValid instead. */
198bool SecCertificateIsValidX(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
199    __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_7, __MAC_10_9, __IPHONE_NA, __IPHONE_NA);
200
201/*!
202	@function SecCertificateIsValid
203	@abstract Check certificate validity on a given date.
204	@param certificate A certificate reference.
205	@result Returns true if the specified date falls within the certificate's validity period, false otherwise.
206*/
207bool SecCertificateIsValid(SecCertificateRef certificate, CFAbsoluteTime verifyTime)
208	__OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
209
210/*!
211	@function SecCertificateNotValidBefore
212	@abstract Obtain the starting date of the given certificate.
213	@param certificate A certificate reference.
214	@result Returns the absolute time at which the given certificate becomes valid,
215	or 0 if this value could not be obtained.
216*/
217CFAbsoluteTime SecCertificateNotValidBefore(SecCertificateRef certificate)
218    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
219
220/*!
221	@function SecCertificateNotValidAfter
222	@abstract Obtain the expiration date of the given certificate.
223	@param certificate A certificate reference.
224	@result Returns the absolute time at which the given certificate expires,
225	or 0 if this value could not be obtained.
226*/
227CFAbsoluteTime SecCertificateNotValidAfter(SecCertificateRef certificate)
228    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_2_0);
229
230/*!
231	@function SecCertificateIsSelfSigned
232	@abstract Determine if the given certificate is self-signed.
233	@param certRef A certificate reference.
234	@param isSelfSigned Will be set to true on return if the certificate is self-signed, false otherwise.
235	@result A result code. Returns errSecSuccess if the certificate's status can be determined.
236*/
237OSStatus SecCertificateIsSelfSigned(SecCertificateRef certRef, Boolean *isSelfSigned)
238    __OSX_AVAILABLE_STARTING(__MAC_10_5, __IPHONE_NA);
239
240/*!
241	@function SecCertificateCopyEscrowRoots
242	@abstract Retrieve the array of valid escrow certificates for a given root type.
243	@param escrowRootType An enumerated type indicating which root type to return.
244	@result An array of zero or more escrow certificates matching the provided type.
245*/
246CFArrayRef SecCertificateCopyEscrowRoots(SecCertificateEscrowRootType escrowRootType)
247    __OSX_AVAILABLE_STARTING(__MAC_10_9, __IPHONE_7_0);
248
249
250#if defined(__cplusplus)
251}
252#endif
253
254#endif /* !_SECURITY_SECCERTIFICATEPRIV_H_ */
255