1 /* $NetBSD: gssapi.h,v 1.3 2019/01/09 16:55:12 christos Exp $ */ 2 3 /* 4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC") 5 * 6 * This Source Code Form is subject to the terms of the Mozilla Public 7 * License, v. 2.0. If a copy of the MPL was not distributed with this 8 * file, You can obtain one at http://mozilla.org/MPL/2.0/. 9 * 10 * See the COPYRIGHT file distributed with this work for additional 11 * information regarding copyright ownership. 12 */ 13 14 15 #ifndef DST_GSSAPI_H 16 #define DST_GSSAPI_H 1 17 18 /*! \file dst/gssapi.h */ 19 20 #include <inttypes.h> 21 #include <stdbool.h> 22 23 #include <isc/formatcheck.h> 24 #include <isc/lang.h> 25 #include <isc/platform.h> 26 #include <isc/types.h> 27 #include <dns/types.h> 28 29 #ifdef GSSAPI 30 #ifdef WIN32 31 /* 32 * MSVC does not like macros in #include lines. 33 */ 34 #include <gssapi/gssapi.h> 35 #include <gssapi/gssapi_krb5.h> 36 #else 37 #include ISC_PLATFORM_GSSAPIHEADER 38 #ifdef ISC_PLATFORM_GSSAPI_KRB5_HEADER 39 #include ISC_PLATFORM_GSSAPI_KRB5_HEADER 40 #endif 41 #endif 42 #ifndef GSS_SPNEGO_MECHANISM 43 #define GSS_SPNEGO_MECHANISM ((void*)0) 44 #endif 45 #endif 46 47 ISC_LANG_BEGINDECLS 48 49 /*** 50 *** Types 51 ***/ 52 53 /*** 54 *** Functions 55 ***/ 56 57 isc_result_t 58 dst_gssapi_acquirecred(const dns_name_t *name, bool initiate, 59 gss_cred_id_t *cred); 60 /* 61 * Acquires GSS credentials. 62 * 63 * Requires: 64 * 'name' is a valid name, preferably one known by the GSS provider 65 * 'initiate' indicates whether the credentials are for initiating or 66 * accepting contexts 67 * 'cred' is a pointer to NULL, which will be allocated with the 68 * credential handle. Call dst_gssapi_releasecred to free 69 * the memory. 70 * 71 * Returns: 72 * ISC_R_SUCCESS msg was successfully updated to include the 73 * query to be sent 74 * other an error occurred while building the message 75 */ 76 77 isc_result_t 78 dst_gssapi_releasecred(gss_cred_id_t *cred); 79 /* 80 * Releases GSS credentials. Calling this function does release the 81 * memory allocated for the credential in dst_gssapi_acquirecred() 82 * 83 * Requires: 84 * 'mctx' is a valid memory context 85 * 'cred' is a pointer to the credential to be released 86 * 87 * Returns: 88 * ISC_R_SUCCESS credential was released successfully 89 * other an error occurred while releaseing 90 * the credential 91 */ 92 93 isc_result_t 94 dst_gssapi_initctx(const dns_name_t *name, isc_buffer_t *intoken, 95 isc_buffer_t *outtoken, gss_ctx_id_t *gssctx, 96 isc_mem_t *mctx, char **err_message); 97 /* 98 * Initiates a GSS context. 99 * 100 * Requires: 101 * 'name' is a valid name, preferably one known by the GSS 102 * provider 103 * 'intoken' is a token received from the acceptor, or NULL if 104 * there isn't one 105 * 'outtoken' is a buffer to receive the token generated by 106 * gss_init_sec_context() to be sent to the acceptor 107 * 'context' is a pointer to a valid gss_ctx_id_t 108 * (which may have the value GSS_C_NO_CONTEXT) 109 * 110 * Returns: 111 * ISC_R_SUCCESS msg was successfully updated to include the 112 * query to be sent 113 * other an error occurred while building the message 114 * *err_message optional error message 115 */ 116 117 isc_result_t 118 dst_gssapi_acceptctx(gss_cred_id_t cred, 119 const char *gssapi_keytab, 120 isc_region_t *intoken, isc_buffer_t **outtoken, 121 gss_ctx_id_t *context, dns_name_t *principal, 122 isc_mem_t *mctx); 123 /* 124 * Accepts a GSS context. 125 * 126 * Requires: 127 * 'mctx' is a valid memory context 128 * 'cred' is the acceptor's valid GSS credential handle 129 * 'intoken' is a token received from the initiator 130 * 'outtoken' is a pointer a buffer pointer used to return the token 131 * generated by gss_accept_sec_context() to be sent to the 132 * initiator 133 * 'context' is a valid pointer to receive the generated context handle. 134 * On the initial call, it should be a pointer to NULL, which 135 * will be allocated as a gss_ctx_id_t. Subsequent calls 136 * should pass in the handle generated on the first call. 137 * Call dst_gssapi_releasecred to delete the context and free 138 * the memory. 139 * 140 * Requires: 141 * 'outtoken' to != NULL && *outtoken == NULL. 142 * 143 * Returns: 144 * ISC_R_SUCCESS msg was successfully updated to include the 145 * query to be sent 146 * DNS_R_CONTINUE transaction still in progress 147 * other an error occurred while building the message 148 */ 149 150 isc_result_t 151 dst_gssapi_deletectx(isc_mem_t *mctx, gss_ctx_id_t *gssctx); 152 /* 153 * Destroys a GSS context. This function deletes the context from the GSS 154 * provider and then frees the memory used by the context pointer. 155 * 156 * Requires: 157 * 'mctx' is a valid memory context 158 * 'context' is a valid GSS context 159 * 160 * Returns: 161 * ISC_R_SUCCESS 162 */ 163 164 165 void 166 gss_log(int level, const char *fmt, ...) 167 ISC_FORMAT_PRINTF(2, 3); 168 /* 169 * Logging function for GSS. 170 * 171 * Requires 172 * 'level' is the log level to be used, as an integer 173 * 'fmt' is a printf format specifier 174 */ 175 176 char * 177 gss_error_tostring(uint32_t major, uint32_t minor, 178 char *buf, size_t buflen); 179 /* 180 * Render a GSS major status/minor status pair into a string 181 * 182 * Requires: 183 * 'major' is a GSS major status code 184 * 'minor' is a GSS minor status code 185 * 186 * Returns: 187 * A string containing the text representation of the error codes. 188 * Users should copy the string if they wish to keep it. 189 */ 190 191 bool 192 dst_gssapi_identitymatchesrealmkrb5(const dns_name_t *signer, 193 const dns_name_t *name, 194 const dns_name_t *realm, 195 bool subdomain); 196 /* 197 * Compare a "signer" (in the format of a Kerberos-format Kerberos5 198 * principal: host/example.com@EXAMPLE.COM) to the realm name stored 199 * in "name" (which represents the realm name). 200 * 201 */ 202 203 bool 204 dst_gssapi_identitymatchesrealmms(const dns_name_t *signer, 205 const dns_name_t *name, 206 const dns_name_t *realm, 207 bool subdomain); 208 /* 209 * Compare a "signer" (in the format of a Kerberos-format Kerberos5 210 * principal: host/example.com@EXAMPLE.COM) to the realm name stored 211 * in "name" (which represents the realm name). 212 * 213 */ 214 215 ISC_LANG_ENDDECLS 216 217 #endif /* DST_GSSAPI_H */ 218