1/*
2 * Copyright (c) 2007-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   SecCertificateInternal
26*/
27
28#ifndef _SECURITY_SECCERTIFICATEINTERNAL_H_
29#define _SECURITY_SECCERTIFICATEINTERNAL_H_
30
31#include <Security/SecCertificatePriv.h>
32#include <Security/certextensions.h>
33#include <libDER/DER_Keys.h>
34
35__BEGIN_DECLS
36
37CFDataRef SecCertificateGetAuthorityKeyID(SecCertificateRef certificate);
38CFDataRef SecCertificateGetSubjectKeyID(SecCertificateRef certificate);
39
40/* Return an array of CFURLRefs each of which is an crl distribution point for
41   this certificate. */
42CFArrayRef SecCertificateGetCRLDistributionPoints(SecCertificateRef certificate);
43
44/* Return an array of CFURLRefs each of which is an ocspResponder for this
45   certificate. */
46CFArrayRef SecCertificateGetOCSPResponders(SecCertificateRef certificate);
47
48/* Return an array of CFURLRefs each of which is an caIssuer for this
49   certificate. */
50CFArrayRef SecCertificateGetCAIssuers(SecCertificateRef certificate);
51
52/* Dump certificate for debugging. */
53void SecCertificateShow(SecCertificateRef certificate);
54
55/* Return the DER encoded issuer sequence for the receiving certificates issuer. */
56CFDataRef SecCertificateCopyIssuerSequence(SecCertificateRef certificate);
57
58/* Return the DER encoded subject sequence for the receiving certificates subject. */
59CFDataRef SecCertificateCopySubjectSequence(SecCertificateRef certificate);
60
61/* Return the content of a DER encoded X.501 name (without the tag and length
62   fields) for the receiving certificates issuer. */
63CFDataRef SecCertificateGetNormalizedIssuerContent(SecCertificateRef certificate);
64
65/* Return the content of a DER encoded X.501 name (without the tag and length
66   fields) for the receiving certificates subject. */
67CFDataRef SecCertificateGetNormalizedSubjectContent(SecCertificateRef certificate);
68
69/* Return the normalized name or NULL if it fails to parse */
70CFDataRef SecDistinguishedNameCopyNormalizedContent(CFDataRef distinguished_name);
71
72/* Return true iff the certificate has a subject. */
73bool SecCertificateHasSubject(SecCertificateRef certificate);
74/* Return true iff the certificate has a critical subject alt name. */
75bool SecCertificateHasCriticalSubjectAltName(SecCertificateRef certificate);
76
77/* Return true if certificate contains one or more critical extensions we
78   are unable to parse. */
79bool SecCertificateHasUnknownCriticalExtension(SecCertificateRef certificate);
80
81/* Return true iff certificate is valid as of verifyTime. */
82bool SecCertificateIsValid(SecCertificateRef certificate,
83	CFAbsoluteTime verifyTime);
84
85/* Return an attribute dictionary used to store this item in a keychain. */
86CFDictionaryRef SecCertificateCopyAttributeDictionary(
87	SecCertificateRef certificate);
88
89/* Return a certificate from the attribute dictionary that was used to store
90   this item in a keychain. */
91SecCertificateRef SecCertificateCreateFromAttributeDictionary(
92	CFDictionaryRef refAttributes);
93
94/* Return a SecKeyRef for the public key embedded in the cert. */
95SecKeyRef SecCertificateCopyPublicKey(SecCertificateRef certificate);
96
97/* Return the SecCEBasicConstraints extension for this certificate if it
98   has one. */
99const SecCEBasicConstraints *
100SecCertificateGetBasicConstraints(SecCertificateRef certificate);
101
102/* Return the SecCEPolicyConstraints extension for this certificate if it
103   has one. */
104const SecCEPolicyConstraints *
105SecCertificateGetPolicyConstraints(SecCertificateRef certificate);
106
107/* Return a dictionary from CFDataRef to CFArrayRef of CFDataRef
108   representing the policyMapping extension of this certificate. */
109CFDictionaryRef
110SecCertificateGetPolicyMappings(SecCertificateRef certificate);
111
112/* Return the SecCECertificatePolicies extension for this certificate if it
113   has one. */
114const SecCECertificatePolicies *
115SecCertificateGetCertificatePolicies(SecCertificateRef certificate);
116
117/* Returns UINT32_MAX if InhibitAnyPolicy extension is not present or invalid,
118   returns the value of the SkipCerts field of the InhibitAnyPolicy extension
119   otherwise. */
120uint32_t
121SecCertificateGetInhibitAnyPolicySkipCerts(SecCertificateRef certificate);
122
123/* Return the public key algorithm and parameters for certificate.  */
124const DERAlgorithmId *SecCertificateGetPublicKeyAlgorithm(
125	SecCertificateRef certificate);
126
127/* Return the raw public key data for certificate.  */
128const DERItem *SecCertificateGetPublicKeyData(SecCertificateRef certificate);
129
130// MARK: -
131// MARK: Certificate Operations
132
133OSStatus SecCertificateIsSignedBy(SecCertificateRef certificate,
134    SecKeyRef issuerKey);
135
136// MARK: -
137// MARK: Certificate Creation
138
139#ifdef OPTIONAL_METHODS
140/* Return a certificate for the PEM representation of this certificate.
141   Return NULL the passed in der_certificate is not a valid DER encoded X.509
142   certificate, and return a CFError by reference.  It is the
143   responsibility of the caller to release the CFError. */
144SecCertificateRef SecCertificateCreateWithPEM(CFAllocatorRef allocator,
145	CFStringRef pem_certificate);
146
147/* Return a CFStringRef containing the the pem representation of this
148   certificate. */
149CFStringRef SecCertificateGetPEM(SecCertificateRef der_certificate);
150
151#endif /* OPTIONAL_METHODS */
152
153#if 0
154/* Complete the certificate chain of this certificate, setting the parent
155   certificate for each certificate along they way.  Return 0 if the
156   system is able to find all the certificates to complete the certificate
157   chain either in the passed in other_certificates array or in the user or
158   the systems keychain(s).
159   If the certifcates issuer chain can not be completed, this function
160   will return an error status code.
161   NOTE: This function does not verify whether the certificate is trusted it's
162   main use is just to ensure that anyone using this certificate upstream will
163   have access to a complete (or as complete as possible in the case of
164   something going wrong) certificate chain.  */
165OSStatus SecCertificateCompleteChain(SecCertificateRef certificate,
166	CFArrayRef other_certificates);
167#endif
168
169#if 0
170
171/*!
172	@function SecCertificateGetVersionNumber
173	@abstract Retrieves the version of a given certificate as a CFNumberRef.
174    @param certificate A reference to the certificate from which to obtain the certificate version.
175	@result A CFNumberRef representing the certificate version.  The following values are currently known to be returned, but more may be added in the future:
176        1: X509v1
177        2: X509v2
178        3: X509v3
179*/
180CFNumberRef SecCertificateGetVersionNumber(SecCertificateRef certificate);
181
182/*!
183	@function SecCertificateGetSerialDER
184	@abstract Retrieves the serial number of a given certificate in DER encoding.
185    @param certificate A reference to the certificate from which to obtain the serial number.
186	@result A CFDataRef containing the DER encoded serial number of the certificate, minus the tag and length fields.
187*/
188CFDataRef SecCertificateGetSerialDER(SecCertificateRef certificate);
189
190
191/*!
192	@function SecCertificateGetSerialString
193	@abstract Retrieves the serial number of a given certificate in human readable form.
194    @param certificate A reference to the certificate from which to obtain the serial number.
195	@result A CFStringRef containing the human readable serial number of the certificate in decimal form.
196*/
197CFStringRef SecCertificateGetSerialString(SecCertificateRef certificate);
198
199
200
201CFDataRef SecCertificateGetPublicKeyDER(SecCertificateRef certificate);
202CFDataRef SecCertificateGetPublicKeySHA1FingerPrint(SecCertificateRef certificate);
203CFDataRef SecCertificateGetPublicKeyMD5FingerPrint(SecCertificateRef certificate);
204CFDataRef SecCertificateGetSignatureAlgorithmDER(SecCertificateRef certificate);
205CFDataRef SecCertificateGetSignatureAlgorithmName(SecCertificateRef certificate);
206CFStringRef SecCertificateGetSignatureAlgorithmOID(SecCertificateRef certificate);
207CFDataRef SecCertificateGetSignatureDER(SecCertificateRef certificate);
208CFDataRef SecCertificateGetSignatureAlgorithmParametersDER(SecCertificateRef certificate);
209
210/* plist top level array is orderd list of key/value pairs */
211CFArrayRef SecCertificateGetSignatureAlgorithmParametersArray(SecCertificateRef certificate);
212
213#if 0
214/* This cert is signed by it's parent? */
215bool SecCertificateIsSignatureValid(SecCertificateRef certificate);
216
217/* This cert is signed by it's parent and so on until no parent certificate can be found? */
218bool SecCertificateIsIssuerChainValid(SecCertificateRef certificate, CFArrayRef additionalCertificatesToSearch);
219
220/* This cert is signed by it's parent and so on until no parent certificate can be found? */
221bool SecCertificateIsSignatureChainValid(SecCertificateRef certificate);
222
223/* This cert is signed by it's parent and so on until a certiicate in anchors can be found. */
224bool SecCertificateIssuerChainHasAnchorIn(SecCertificateRef certificate, CFArrayRef anchors);
225
226/* This cert is signed by it's parent and so on until a certiicate in anchors can be found. */
227bool SecCertificateSignatureChainHasAnchorIn(SecCertificateRef certificate, CFArrayRef anchors);
228
229bool SecCertificateIsSelfSigned(SecCertificateRef certificate);
230#endif
231
232
233/* The entire certificate in DER encoding including the outer tag and length fields. */
234CFDataRef SecCertificateGetDER(SecCertificateRef certificate);
235
236/* Returns the status code of the last failed call for this certificate on this thread. */
237OSStatus SecCertificateGetStatus(SecCertificateRef certificate);
238
239CFDataRef SecCertificateGetIssuerDER(SecCertificateRef certificate);
240CFDataRef SecCertificateGetNormalizedIssuerDER(SecCertificateRef certificate);
241
242/* Return the issuer as an X509 name encoded in an array.  Each element in this array is an array.  Each inner array has en even number of elements.  Each pair of elements in the inner array represents a key and a value.  The key is a string and the value is also a string.  Elements in the outer array should be considered ordered while pairs in the inner array should not. */
243CFArrayRef SecCertificateGetIssuerArray(SecCertificateRef certificate);
244
245
246CFDataRef SecCertificateGetSubjectDER(SecCertificateRef certificate);
247CFDataRef SecCertificateGetNormalizedSubjectDER(SecCertificateRef certificate);
248/* See SecCertificateGetIssuerArray for a description of the returned array. */
249CFArrayRef SecCertificateGetSubjectArray(SecCertificateRef certificate);
250
251CFDateRef SecCertificateGetNotValidBeforeDate(SecCertificateRef certificate);
252CFDateRef SecCertificateGetNotValidDateDate(SecCertificateRef certificate);
253
254
255#if 0
256
257CFIndex SecCertificateGetExtensionCount(SecCertificateRef certificate,  index);
258CFDataRef SecCertificateGetExtensionAtIndexDER(SecCertificateRef certificate, CFIndex index);
259bool SecCertificateIsExtensionAtIndexCritical(SecCertificateRef certificate, CFIndex index);
260
261/* array see email example. */
262CFArrayRef SecCertificateGetExtensionAtIndexParamsArray(SecCertificateRef certificate, CFIndex index);
263
264CFStringRef SecCertificateGetExtensionAtIndexName(SecCertificateRef certificate, CFIndex index);
265CFStringRef SecCertificateGetExtensionAtIndexOID(SecCertificateRef certificate, CFIndex index);
266
267#else
268
269/* Return an array with all of this certificates SecCertificateExtensionRefs. */
270CFArrayRef SecCertificateGetExtensions(SecCertificateRef certificate);
271
272/* Return the SecCertificateExtensionRef for the extension with the given oid.  Return NULL if it does not exist or if an error occours call SecCertificateGetStatus() to see if an error occured or not. */
273SecCertificateExtensionRef SecCertificateGetExtensionWithOID(SecCertificateRef certificate, CFDataRef oid);
274
275CFDataRef SecCertificateExtensionGetDER(SecCertificateExtensionRef extension, CFDataRef oid);
276CFStringRef SecCertificateExtensionName(SecCertificateExtensionRef extension);
277CFDataRef SecCertificateExtensionGetOIDDER(SecCertificateExtensionRef extension, CFDataRef oid);
278CFStringRef SecCertificateExtensionGetOIDString(SecCertificateExtensionRef extension, CFDataRef oid);
279bool SecCertificateExtensionIsCritical(SecCertificateExtensionRef extension);
280CFArrayRef SecCertificateExtensionGetContentDER(SecCertificateExtensionRef extension);
281
282/* Return the content of extension as an array.  The array has en even number of elements.  Each pair of elements in the array represents a key and a value.  The key is a string and the value is either a string, or dictionary or an array of key value pairs like the outer array.  */
283CFArrayRef SecCertificateExtensionGetContentArray(SecCertificateExtensionRef extension);
284
285#endif /* 0 */
286
287#endif /* 0 */
288
289
290void appendProperty(CFMutableArrayRef properties, CFStringRef propertyType,
291    CFStringRef label, CFStringRef localizedLabel, CFTypeRef value);
292
293/* Utility functions. */
294CFStringRef SecDERItemCopyOIDDecimalRepresentation(CFAllocatorRef allocator,
295    const DERItem *oid);
296CFDataRef createNormalizedX501Name(CFAllocatorRef allocator,
297	const DERItem *x501name);
298
299/* Decode a choice of UTCTime or GeneralizedTime to a CFAbsoluteTime. Return
300   an absoluteTime if the date was valid and properly decoded.  Return
301   NULL_TIME otherwise. */
302CFAbsoluteTime SecAbsoluteTimeFromDateContent(DERTag tag, const uint8_t *bytes,
303    size_t length);
304
305bool SecCertificateHasMarkerExtension(SecCertificateRef certificate, CFTypeRef oid);
306
307__END_DECLS
308
309#endif /* !_SECURITY_SECCERTIFICATEINTERNAL_H_ */
310