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