1/*
2 * Copyright (c) 2001-2010 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 _EAP8021X_EAPCERTIFICATE_UTIL_H
25#define _EAP8021X_EAPCERTIFICATE_UTIL_H
26
27
28/*
29 * EAPCertificateUtil.h
30 * - certificate utility functions
31 */
32
33/*
34 * Modification History
35 *
36 * April 2, 2004	Dieter Siegmund (dieter@apple.com)
37 * - created
38 */
39
40#include <Security/SecCertificate.h>
41#include <Security/SecIdentity.h>
42#include <CoreFoundation/CFBase.h>
43#include <CoreFoundation/CFData.h>
44#include <CoreFoundation/CFArray.h>
45#include <CoreFoundation/CFString.h>
46#include <CoreFoundation/CFPropertyList.h>
47#include <TargetConditionals.h>
48
49/*
50 * Type: EAPSecIdentityHandleRef
51 * Purpose:
52 *   Type used to store a handle for a SecIdentityRef.  This is just
53 *   an alias for a CFPropertyListRef, thus it can be serialized and stored
54 *   in persistent storage.
55 */
56typedef CFPropertyListRef	EAPSecIdentityHandleRef;
57
58/*
59 * Function: EAPSecIdentityHandleCreate
60 * Purpose:
61 *   Creates an CFPropertyListRef type to represent a SecIdentity.
62 */
63EAPSecIdentityHandleRef
64EAPSecIdentityHandleCreate(SecIdentityRef identity);
65
66/*
67 * Function: EAPSecIdentityHandleCreateSecIdentityTrustChain
68 * Purpose:
69 *   Find the identity that matches the given id_handle, and
70 *   return it along with the certificate trust chain (see
71 *   EAPSecIdentityHandleCreateSecIdentity() below).
72 *
73 * Returns:
74 *   If return value is noErr, returns an array (*ret_array) containing the
75 *   identity plus certificate trust chain for use with SSLSetCertificate().
76 *
77 *   If return code is not noErr, *ret_array is NULL.
78 */
79OSStatus
80EAPSecIdentityHandleCreateSecIdentityTrustChain(EAPSecIdentityHandleRef handle,
81						CFArrayRef * ret_array);
82
83/*
84 * Function: EAPSecIdentityCreateTrustChain
85 *
86 * Purpose:
87 *   Turns an SecIdentityRef into the array required by
88 *   SSLSetCertificates().  See the <Security/SecureTransport.h> for more
89 *   information.
90 *
91 * Returns:
92 *   noErr and *ret_array != NULL on success, non-noErr otherwise.
93 */
94OSStatus
95EAPSecIdentityCreateTrustChain(SecIdentityRef identity,
96			       CFArrayRef * ret_array);
97
98/*
99 * Function: EAPSecIdentityHandleCreateSecIdentity
100 * Purpose:
101 *   Retrieve a SecIdentityRef corresponding to the given id_handle.
102 *   If id_handle is NULL, finds the first SecIdentityRef capable of
103 *   signing.
104 *
105 *   To create the id_handle, use EAPSecIdentityHandleCreateFromSecIdentity().
106 */
107OSStatus
108EAPSecIdentityHandleCreateSecIdentity(EAPSecIdentityHandleRef id_handle,
109				      SecIdentityRef * ret_identity);
110
111/*
112 * Function: EAPSecIdentityListCreate
113 * Purpose:
114 *   Return a list of SecIdentityRef's suitable for use with EAP/TLS.
115 * Returns:
116 *   If the return value is noErr, a CFArrayRef of SecIdentityRef's.
117 */
118OSStatus
119EAPSecIdentityListCreate(CFArrayRef * ret_array);
120
121/*
122 * Function: EAPSecCertificateArrayCreateCFDataArray
123 * Purpose:
124 *   Creates a CFArray[CFData] from a CFArray[SecCertificate].
125 */
126CFArrayRef
127EAPSecCertificateArrayCreateCFDataArray(CFArrayRef certs);
128
129/*
130 * Function: EAPCFDataArrayCreateSecCertificateArray
131 * Purpose:
132 *   Creates a CFArray[SecCertificate] from a CFArray[CFData].
133 */
134CFArrayRef
135EAPCFDataArrayCreateSecCertificateArray(CFArrayRef certs);
136
137CFTypeRef
138isA_SecCertificate(CFTypeRef obj);
139
140/*
141 * EAPSecCertificateAttribute dictionary keys:
142 */
143/* CFBoolean's */
144#define kEAPSecCertificateAttributeIsRoot		CFSTR("IsRoot")
145
146/* CFString's */
147#define kEAPSecCertificateAttributeCommonName		CFSTR("CommonName")
148#define kEAPSecCertificateAttributeNTPrincipalName	CFSTR("NTPrincipalName")
149#define kEAPSecCertificateAttributeRFC822Name		CFSTR("RFC822Name")
150#define kEAPSecCertificateAttributeEmailAddress		CFSTR("EmailAddress")
151
152/*
153 * Function: EAPSecCertificateCopyAttributesDictionary
154 * Purpose:
155 *   Returns a CFDictionary containing certificate attributes.
156 * Notes:
157 *   A certificate can contain multiple value for a given attribute i.e. a
158 *   cert can contain multiple Subject Alt Name's with multiple RFC 822 fields.
159 *   This API stores just the first one that is encountered.
160 */
161CFDictionaryRef
162EAPSecCertificateCopyAttributesDictionary(SecCertificateRef cert);
163
164/*
165 * Function: EAPSecCertificateCopyUserNameString
166 * Purpose:
167 *   Parse the given certificate, and return the best name to use as a
168 *   username.
169 * Returns:
170 *   Non-NULL username, if one was found, NULL otherwise.
171 */
172CFStringRef
173EAPSecCertificateCopyUserNameString(SecCertificateRef cert);
174
175#if TARGET_OS_EMBEDDED
176/*
177 * Function EAPSecCertificateCopySHA1DigestString
178 * Purpose:
179 *   Return the SHA1 digest for the given cert as a CFString.
180 */
181CFStringRef
182EAPSecCertificateCopySHA1DigestString(SecCertificateRef cert);
183
184#endif /* TARGET_OS_EMBEDDED */
185
186#endif /* _EAP8021X_EAPCERTIFICATE_UTIL_H */
187