contrib/bind-9.5.2/lib/dns/include/dst/gssapi.h

   1 /*
   2  * Copyright (C) 2004-2007, 2009  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.9.128.2 2009/01/19 23:47:03 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 #else
  38 #include ISC_PLATFORM_GSSAPIHEADER
  39 #endif
  40 #ifndef GSS_SPNEGO_MECHANISM
  41 #define GSS_SPNEGO_MECHANISM ((void*)0)
  42 #endif
  43 #endif
  44
  45 ISC_LANG_BEGINDECLS
  46
  47 /***
  48  *** Types
  49  ***/
  50
  51 /***
  52  *** Functions
  53  ***/
  54
  55 isc_result_t
  56 dst_gssapi_acquirecred(dns_name_t *name, isc_boolean_t initiate,
  57                        gss_cred_id_t *cred);
  58 /*
  59  *      Acquires GSS credentials.
  60  *
  61  *      Requires:
  62  *      'name'      is a valid name, preferably one known by the GSS provider
  63  *      'initiate'  indicates whether the credentials are for initiating or
  64  *                  accepting contexts
  65  *      'cred'      is a pointer to NULL, which will be allocated with the
  66  *                  credential handle.  Call dst_gssapi_releasecred to free
  67  *                  the memory.
  68  *
  69  *      Returns:
  70  *              ISC_R_SUCCESS msg was successfully updated to include the
  71  *                                    query to be sent
  72  *              other             an error occurred while building the message
  73  */
  74
  75 isc_result_t
  76 dst_gssapi_releasecred(gss_cred_id_t *cred);
  77 /*
  78  *      Releases GSS credentials.  Calling this function does release the
  79  *  memory allocated for the credential in dst_gssapi_acquirecred()
  80  *
  81  *      Requires:
  82  *      'mctx'  is a valid memory context
  83  *      'cred'  is a pointer to the credential to be released
  84  *
  85  *      Returns:
  86  *              ISC_R_SUCCESS   credential was released successfully
  87  *              other           an error occurred while releaseing
  88  *                              the credential
  89  */
  90
  91 isc_result_t
  92 dst_gssapi_initctx(dns_name_t *name, isc_buffer_t *intoken,
  93                    isc_buffer_t *outtoken, gss_ctx_id_t *gssctx);
  94 /*
  95  *      Initiates a GSS context.
  96  *
  97  *      Requires:
  98  *      'name'     is a valid name, preferably one known by the GSS
  99  *      provider
 100  *      'intoken'  is a token received from the acceptor, or NULL if
 101  *                 there isn't one
 102  *      'outtoken' is a buffer to receive the token generated by
 103  *                 gss_init_sec_context() to be sent to the acceptor
 104  *      'context'  is a pointer to a valid gss_ctx_id_t
 105  *                 (which may have the value GSS_C_NO_CONTEXT)
 106  *
 107  *      Returns:
 108  *              ISC_R_SUCCESS   msg was successfully updated to include the
 109  *                              query to be sent
 110  *              other           an error occurred while building the message
 111  */
 112
 113 isc_result_t
 114 dst_gssapi_acceptctx(gss_cred_id_t cred,
 115                      isc_region_t *intoken, isc_buffer_t **outtoken,
 116                      gss_ctx_id_t *context, dns_name_t *principal,
 117                      isc_mem_t *mctx);
 118 /*
 119  *      Accepts a GSS context.
 120  *
 121  *      Requires:
 122  *      'mctx'     is a valid memory context
 123  *      'cred'     is the acceptor's valid GSS credential handle
 124  *      'intoken'  is a token received from the initiator
 125  *      'outtoken' is a pointer a buffer pointer used to return the token
 126  *                 generated by gss_accept_sec_context() to be sent to the
 127  *                 initiator
 128  *      'context'  is a valid pointer to receive the generated context handle.
 129  *                 On the initial call, it should be a pointer to NULL, which
 130  *                 will be allocated as a gss_ctx_id_t.  Subsequent calls
 131  *                 should pass in the handle generated on the first call.
 132  *                 Call dst_gssapi_releasecred to delete the context and free
 133  *                 the memory.
 134  *
 135  *      Requires:
 136  *              'outtoken' to != NULL && *outtoken == NULL.
 137  *
 138  *      Returns:
 139  *              ISC_R_SUCCESS   msg was successfully updated to include the
 140  *                              query to be sent
 141  *              other           an error occurred while building the message
 142  */
 143
 144 isc_result_t
 145 dst_gssapi_deletectx(isc_mem_t *mctx, gss_ctx_id_t *gssctx);
 146 /*
 147  *      Destroys a GSS context.  This function deletes the context from the GSS
 148  *      provider and then frees the memory used by the context pointer.
 149  *
 150  *      Requires:
 151  *      'mctx'    is a valid memory context
 152  *      'context' is a valid GSS context
 153  *
 154  *      Returns:
 155  *              ISC_R_SUCCESS
 156  */
 157
 158
 159 void
 160 gss_log(int level, const char *fmt, ...)
 161 ISC_FORMAT_PRINTF(2, 3);
 162 /*
 163  * Logging function for GSS.
 164  *
 165  *  Requires
 166  *      'level' is the log level to be used, as an integer
 167  *      'fmt'   is a printf format specifier
 168  */
 169
 170 char *
 171 gss_error_tostring(isc_uint32_t major, isc_uint32_t minor,
 172                    char *buf, size_t buflen);
 173 /*
 174  *      Render a GSS major status/minor status pair into a string
 175  *
 176  *      Requires:
 177  *      'major' is a GSS major status code
 178  *      'minor' is a GSS minor status code
 179  *
 180  *      Returns:
 181  *              A string containing the text representation of the error codes.
 182  *              Users should copy the string if they wish to keep it.
 183  */
 184
 185 isc_boolean_t
 186 dst_gssapi_identitymatchesrealmkrb5(dns_name_t *signer, dns_name_t *name,
 187                               dns_name_t *realm);
 188 /*
 189  *      Compare a "signer" (in the format of a Kerberos-format Kerberos5
 190  *      principal: host/example.com@EXAMPLE.COM) to the realm name stored
 191  *      in "name" (which represents the realm name).
 192  *
 193  */
 194
 195 isc_boolean_t
 196 dst_gssapi_identitymatchesrealmms(dns_name_t *signer, dns_name_t *name,
 197                             dns_name_t *realm);
 198 /*
 199  *      Compare a "signer" (in the format of a Kerberos-format Kerberos5
 200  *      principal: host/example.com@EXAMPLE.COM) to the realm name stored
 201  *      in "name" (which represents the realm name).
 202  *
 203  */
 204
 205 ISC_LANG_ENDDECLS
 206
 207 #endif /* DST_GSSAPI_H */