1/*
2 * Copyright (c) 2004-2008 Apple Inc.  All Rights Reserved.
3 *
4 * Export of this software from the United States of America may require
5 * a specific license from the United States Government.  It is the
6 * responsibility of any person or organization contemplating export to
7 * obtain such a license before exporting.
8 *
9 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
10 * distribute this software and its documentation for any purpose and
11 * without fee is hereby granted, provided that the above copyright
12 * notice appear in all copies and that both that copyright notice and
13 * this permission notice appear in supporting documentation, and that
14 * the name of Apple Inc. not be used in advertising or publicity pertaining
15 * to distribution of the software without specific, written prior
16 * permission.  Apple Inc. makes no representations about the suitability of
17 * this software for any purpose.  It is provided "as is" without express
18 * or implied warranty.
19 *
20 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
21 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
22 * WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
23 *
24 */
25
26/*
27 * pkinit_cert_store.h - PKINIT certificate storage/retrieval utilities
28 *
29 * Created 26 May 2004 by Doug Mitchell at Apple.
30 */
31
32#ifndef	_PKINIT_CERT_STORE_H_
33#define _PKINIT_CERT_STORE_H_
34
35#ifdef  __cplusplus
36extern "C" {
37#endif
38
39#include <krb5/krb5.h>
40
41/*
42 * Opaque reference to a machine-dependent representation of a certificate
43 * which is capable of signing. On Mac OS X this is actually a SecIdentityRef.
44 */
45typedef void *krb5_pkinit_signing_cert_t;
46
47/*
48 * Opaque reference to a machine-dependent representation of a certificate.
49 * On Mac OS X this is actually a SecCertificateRef.
50 */
51typedef void *krb5_pkinit_cert_t;
52
53/*
54 * Opaque reference to a database in which PKINIT-related certificates are stored.
55 */
56typedef void *krb5_pkinit_cert_db_t;
57
58/*
59 * Obtain signing cert for specified principal. On successful return,
60 * caller must eventually release the cert with krb5_pkinit_release_cert().
61 *
62 * Returns KRB5_PRINC_NOMATCH if client cert not found.
63 */
64krb5_error_code krb5_pkinit_get_client_cert(
65    const char			*principal,     /* full principal string */
66    krb5_pkinit_signing_cert_t	*client_cert);  /* RETURNED */
67
68/*
69 * Determine if the specified client has a signing cert. Returns TRUE
70 * if so, else returns FALSE.
71 */
72krb5_boolean krb5_pkinit_have_client_cert(
73    const char			*principal);    /* full principal string */
74
75/*
76 * Store the specified certificate (or, more likely, some platform-dependent
77 * reference to it) as the specified principal's signing cert. Passing
78 * in NULL for the client_cert has the effect of deleting the relevant entry
79 * in the cert storage.
80 */
81krb5_error_code krb5_pkinit_set_client_cert_from_signing_cert(
82    const char			*principal,     /* full principal string */
83    krb5_pkinit_signing_cert_t	client_cert);
84krb5_error_code krb5_pkinit_set_client_cert(
85    const char			*principal,     /* full principal string */
86    krb5_pkinit_cert_t	client_cert);
87
88/*
89 * Obtain a reference to the client's cert database. Specify either principal
90 * name or client_cert as obtained from krb5_pkinit_get_client_cert().
91 */
92krb5_error_code krb5_pkinit_get_client_cert_db(
93    const char			*principal,	    /* optional, full principal string */
94    krb5_pkinit_signing_cert_t	client_cert,	    /* optional, from krb5_pkinit_get_client_cert() */
95    krb5_pkinit_cert_db_t	*client_cert_db);   /* RETURNED */
96
97/*
98 * Obtain the KDC signing cert, with optional CA and specific cert specifiers.
99 * CAs and cert specifiers are in the form of DER-encoded issuerAndSerialNumbers.
100 *
101 * The client_spec argument is typically provided by the client as kdcPkId.
102 *
103 * If trusted_CAs and client_spec are NULL, a platform-dependent preferred
104 * KDC signing cert is returned, if one exists.
105 *
106 * On successful return, caller must eventually release the cert with
107 * krb5_pkinit_release_cert(). Outside of an unusual test configuration this =
108 *
109 * Returns KRB5_PRINC_NOMATCH if KDC cert not found.
110 *
111 */
112krb5_error_code krb5_pkinit_get_kdc_cert(
113    krb5_ui_4			num_trusted_CAs,    /* sizeof *trusted_CAs */
114    krb5_data			*trusted_CAs,	    /* optional */
115    krb5_data			*client_spec,	    /* optional */
116    krb5_pkinit_signing_cert_t	*kdc_cert);	    /* RETURNED */
117
118/*
119 * Obtain a reference to the KDC's cert database.
120 */
121krb5_error_code krb5_pkinit_get_kdc_cert_db(
122    krb5_pkinit_cert_db_t	*kdc_cert_db);	/* RETURNED */
123
124/*
125 * Release certificate references obtained via krb5_pkinit_get_client_cert() and
126 * krb5_pkinit_get_kdc_cert().
127 */
128extern void krb5_pkinit_release_cert(
129    krb5_pkinit_signing_cert_t   cert);
130
131/*
132 * Release database references obtained via krb5_pkinit_get_client_cert_db() and
133 * krb5_pkinit_get_kdc_cert_db().
134 */
135extern void krb5_pkinit_release_cert_db(
136    krb5_pkinit_cert_db_t	cert_db);
137
138/*
139 * Obtain a mallocd C-string representation of a certificate's SHA1 digest.
140 * Only error is a NULL return indicating memory failure.
141 * Caller must free the returned string.
142 */
143char *krb5_pkinit_cert_hash_str(
144    const krb5_data *cert);
145
146/*
147 * Obtain a client's optional list of trusted KDC CA certs (trustedCertifiers)
148 * and/or trusted KDC cert (kdcPkId) for a given client and server.
149 * All returned values are mallocd and must be freed by caller; the contents
150 * of the krb5_datas are DER-encoded certificates.
151 */
152krb5_error_code krb5_pkinit_get_server_certs(
153    const char *client_principal,
154    const char *server_principal,
155    krb5_data **trusted_CAs,	    /* RETURNED, though return value may be NULL */
156    krb5_ui_4 *num_trusted_CAs,	    /* RETURNED */
157    krb5_data *kdc_cert);	    /* RETURNED, though may be 0/NULL */
158
159#ifdef  __cplusplus
160}
161#endif
162
163#endif  /* _PKINIT_CERT_STORE_H_ */
164