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