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