1/* 2 * Copyright (C) 2004-2007, 2009-2011 Internet Systems Consortium, Inc. ("ISC") 3 * Copyright (C) 2000, 2001 Internet Software Consortium. 4 * 5 * Permission to use, copy, modify, and/or distribute this software for any 6 * purpose with or without fee is hereby granted, provided that the above 7 * copyright notice and this permission notice appear in all copies. 8 * 9 * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH 10 * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 11 * AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, 12 * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 13 * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 14 * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 15 * PERFORMANCE OF THIS SOFTWARE. 16 */ 17 18/* $Id: gssapi.h,v 1.16 2011/01/08 23:47:01 tbox Exp $ */ 19 20#ifndef DST_GSSAPI_H 21#define DST_GSSAPI_H 1 22 23/*! \file dst/gssapi.h */ 24 25#include <isc/formatcheck.h> 26#include <isc/lang.h> 27#include <isc/platform.h> 28#include <isc/types.h> 29#include <dns/types.h> 30 31#ifdef GSSAPI 32#ifdef _WINDOWS 33/* 34 * MSVC does not like macros in #include lines. 35 */ 36#include <gssapi/gssapi.h> 37#include <gssapi/gssapi_krb5.h> 38#else 39#include ISC_PLATFORM_GSSAPIHEADER 40#ifdef ISC_PLATFORM_GSSAPI_KRB5_HEADER 41#include ISC_PLATFORM_GSSAPI_KRB5_HEADER 42#endif 43#endif 44#ifndef GSS_SPNEGO_MECHANISM 45#define GSS_SPNEGO_MECHANISM ((void*)0) 46#endif 47#endif 48 49ISC_LANG_BEGINDECLS 50 51/*** 52 *** Types 53 ***/ 54 55/*** 56 *** Functions 57 ***/ 58 59isc_result_t 60dst_gssapi_acquirecred(dns_name_t *name, isc_boolean_t initiate, 61 gss_cred_id_t *cred); 62/* 63 * Acquires GSS credentials. 64 * 65 * Requires: 66 * 'name' is a valid name, preferably one known by the GSS provider 67 * 'initiate' indicates whether the credentials are for initiating or 68 * accepting contexts 69 * 'cred' is a pointer to NULL, which will be allocated with the 70 * credential handle. Call dst_gssapi_releasecred to free 71 * the memory. 72 * 73 * Returns: 74 * ISC_R_SUCCESS msg was successfully updated to include the 75 * query to be sent 76 * other an error occurred while building the message 77 */ 78 79isc_result_t 80dst_gssapi_releasecred(gss_cred_id_t *cred); 81/* 82 * Releases GSS credentials. Calling this function does release the 83 * memory allocated for the credential in dst_gssapi_acquirecred() 84 * 85 * Requires: 86 * 'mctx' is a valid memory context 87 * 'cred' is a pointer to the credential to be released 88 * 89 * Returns: 90 * ISC_R_SUCCESS credential was released successfully 91 * other an error occurred while releaseing 92 * the credential 93 */ 94 95isc_result_t 96dst_gssapi_initctx(dns_name_t *name, isc_buffer_t *intoken, 97 isc_buffer_t *outtoken, gss_ctx_id_t *gssctx, 98 isc_mem_t *mctx, char **err_message); 99/* 100 * Initiates a GSS context. 101 * 102 * Requires: 103 * 'name' is a valid name, preferably one known by the GSS 104 * provider 105 * 'intoken' is a token received from the acceptor, or NULL if 106 * there isn't one 107 * 'outtoken' is a buffer to receive the token generated by 108 * gss_init_sec_context() to be sent to the acceptor 109 * 'context' is a pointer to a valid gss_ctx_id_t 110 * (which may have the value GSS_C_NO_CONTEXT) 111 * 112 * Returns: 113 * ISC_R_SUCCESS msg was successfully updated to include the 114 * query to be sent 115 * other an error occurred while building the message 116 * *err_message optional error message 117 */ 118 119isc_result_t 120dst_gssapi_acceptctx(gss_cred_id_t cred, 121 const char *gssapi_keytab, 122 isc_region_t *intoken, isc_buffer_t **outtoken, 123 gss_ctx_id_t *context, dns_name_t *principal, 124 isc_mem_t *mctx); 125/* 126 * Accepts a GSS context. 127 * 128 * Requires: 129 * 'mctx' is a valid memory context 130 * 'cred' is the acceptor's valid GSS credential handle 131 * 'intoken' is a token received from the initiator 132 * 'outtoken' is a pointer a buffer pointer used to return the token 133 * generated by gss_accept_sec_context() to be sent to the 134 * initiator 135 * 'context' is a valid pointer to receive the generated context handle. 136 * On the initial call, it should be a pointer to NULL, which 137 * will be allocated as a gss_ctx_id_t. Subsequent calls 138 * should pass in the handle generated on the first call. 139 * Call dst_gssapi_releasecred to delete the context and free 140 * the memory. 141 * 142 * Requires: 143 * 'outtoken' to != NULL && *outtoken == NULL. 144 * 145 * Returns: 146 * ISC_R_SUCCESS msg was successfully updated to include the 147 * query to be sent 148 * other an error occurred while building the message 149 */ 150 151isc_result_t 152dst_gssapi_deletectx(isc_mem_t *mctx, gss_ctx_id_t *gssctx); 153/* 154 * Destroys a GSS context. This function deletes the context from the GSS 155 * provider and then frees the memory used by the context pointer. 156 * 157 * Requires: 158 * 'mctx' is a valid memory context 159 * 'context' is a valid GSS context 160 * 161 * Returns: 162 * ISC_R_SUCCESS 163 */ 164 165 166void 167gss_log(int level, const char *fmt, ...) 168ISC_FORMAT_PRINTF(2, 3); 169/* 170 * Logging function for GSS. 171 * 172 * Requires 173 * 'level' is the log level to be used, as an integer 174 * 'fmt' is a printf format specifier 175 */ 176 177char * 178gss_error_tostring(isc_uint32_t major, isc_uint32_t minor, 179 char *buf, size_t buflen); 180/* 181 * Render a GSS major status/minor status pair into a string 182 * 183 * Requires: 184 * 'major' is a GSS major status code 185 * 'minor' is a GSS minor status code 186 * 187 * Returns: 188 * A string containing the text representation of the error codes. 189 * Users should copy the string if they wish to keep it. 190 */ 191 192isc_boolean_t 193dst_gssapi_identitymatchesrealmkrb5(dns_name_t *signer, dns_name_t *name, 194 dns_name_t *realm); 195/* 196 * Compare a "signer" (in the format of a Kerberos-format Kerberos5 197 * principal: host/example.com@EXAMPLE.COM) to the realm name stored 198 * in "name" (which represents the realm name). 199 * 200 */ 201 202isc_boolean_t 203dst_gssapi_identitymatchesrealmms(dns_name_t *signer, dns_name_t *name, 204 dns_name_t *realm); 205/* 206 * Compare a "signer" (in the format of a Kerberos-format Kerberos5 207 * principal: host/example.com@EXAMPLE.COM) to the realm name stored 208 * in "name" (which represents the realm name). 209 * 210 */ 211 212ISC_LANG_ENDDECLS 213 214#endif /* DST_GSSAPI_H */ 215