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