1 /* $NetBSD: gssapi.h,v 1.4 2020/05/24 19:46:23 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 #ifndef DST_GSSAPI_H 15 #define DST_GSSAPI_H 1 16 17 /*! \file dst/gssapi.h */ 18 19 #include <inttypes.h> 20 #include <stdbool.h> 21 22 #include <isc/formatcheck.h> 23 #include <isc/lang.h> 24 #include <isc/platform.h> 25 #include <isc/types.h> 26 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 /* ifdef WIN32 */ 37 #include ISC_PLATFORM_GSSAPIHEADER 38 #ifdef ISC_PLATFORM_GSSAPI_KRB5_HEADER 39 #include ISC_PLATFORM_GSSAPI_KRB5_HEADER 40 #endif /* ifdef ISC_PLATFORM_GSSAPI_KRB5_HEADER */ 41 #endif /* ifdef WIN32 */ 42 #ifndef GSS_SPNEGO_MECHANISM 43 #define GSS_SPNEGO_MECHANISM ((void *)0) 44 #endif /* ifndef GSS_SPNEGO_MECHANISM */ 45 #endif /* ifdef GSSAPI */ 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, const char *gssapi_keytab, 119 isc_region_t *intoken, isc_buffer_t **outtoken, 120 gss_ctx_id_t *context, dns_name_t *principal, 121 isc_mem_t *mctx); 122 /* 123 * Accepts a GSS context. 124 * 125 * Requires: 126 * 'mctx' is a valid memory context 127 * 'cred' is the acceptor's valid GSS credential handle 128 * 'intoken' is a token received from the initiator 129 * 'outtoken' is a pointer a buffer pointer used to return the token 130 * generated by gss_accept_sec_context() to be sent to the 131 * initiator 132 * 'context' is a valid pointer to receive the generated context handle. 133 * On the initial call, it should be a pointer to NULL, which 134 * will be allocated as a gss_ctx_id_t. Subsequent calls 135 * should pass in the handle generated on the first call. 136 * Call dst_gssapi_releasecred to delete the context and free 137 * the memory. 138 * 139 * Requires: 140 * 'outtoken' to != NULL && *outtoken == NULL. 141 * 142 * Returns: 143 * ISC_R_SUCCESS msg was successfully updated to include the 144 * query to be sent 145 * DNS_R_CONTINUE transaction still in progress 146 * other an error occurred while building the message 147 */ 148 149 isc_result_t 150 dst_gssapi_deletectx(isc_mem_t *mctx, gss_ctx_id_t *gssctx); 151 /* 152 * Destroys a GSS context. This function deletes the context from the GSS 153 * provider and then frees the memory used by the context pointer. 154 * 155 * Requires: 156 * 'mctx' is a valid memory context 157 * 'context' is a valid GSS context 158 * 159 * Returns: 160 * ISC_R_SUCCESS 161 */ 162 163 void 164 gss_log(int level, const char *fmt, ...) ISC_FORMAT_PRINTF(2, 3); 165 /* 166 * Logging function for GSS. 167 * 168 * Requires 169 * 'level' is the log level to be used, as an integer 170 * 'fmt' is a printf format specifier 171 */ 172 173 char * 174 gss_error_tostring(uint32_t major, uint32_t minor, char *buf, size_t buflen); 175 /* 176 * Render a GSS major status/minor status pair into a string 177 * 178 * Requires: 179 * 'major' is a GSS major status code 180 * 'minor' is a GSS minor status code 181 * 182 * Returns: 183 * A string containing the text representation of the error codes. 184 * Users should copy the string if they wish to keep it. 185 */ 186 187 bool 188 dst_gssapi_identitymatchesrealmkrb5(const dns_name_t *signer, 189 const dns_name_t *name, 190 const dns_name_t *realm, bool subdomain); 191 /* 192 * Compare a "signer" (in the format of a Kerberos-format Kerberos5 193 * principal: host/example.com@EXAMPLE.COM) to the realm name stored 194 * in "name" (which represents the realm name). 195 * 196 */ 197 198 bool 199 dst_gssapi_identitymatchesrealmms(const dns_name_t *signer, 200 const dns_name_t *name, 201 const dns_name_t *realm, bool subdomain); 202 /* 203 * Compare a "signer" (in the format of a Kerberos-format Kerberos5 204 * principal: host/example.com@EXAMPLE.COM) to the realm name stored 205 * in "name" (which represents the realm name). 206 * 207 */ 208 209 ISC_LANG_ENDDECLS 210 211 #endif /* DST_GSSAPI_H */ 212