1GSSAPI mechanism interface 2========================== 3 4The GSSAPI library in MIT krb5 can load mechanism modules to augment 5the set of built-in mechanisms. 6 7.. note: The GSSAPI loadable mechanism interface does not follow the 8 normal conventions for MIT krb5 pluggable interfaces. 9 10A mechanism module is a Unix shared object or Windows DLL, built 11separately from the krb5 tree. Modules are loaded according to the 12GSS mechanism config files described in :ref:`gssapi_plugin_config`. 13 14For the most part, a GSSAPI mechanism module exports the same 15functions as would a GSSAPI implementation itself, with the same 16function signatures. The mechanism selection layer within the GSSAPI 17library (called the "mechglue") will dispatch calls from the 18application to the module if the module's mechanism is requested. If 19a module does not wish to implement a GSSAPI extension, it can simply 20refrain from exporting it, and the mechglue will fail gracefully if 21the application calls that function. 22 23The mechglue does not invoke a module's **gss_add_cred**, 24**gss_add_cred_from**, **gss_add_cred_impersonate_name**, or 25**gss_add_cred_with_password** function. A mechanism only needs to 26implement the "acquire" variants of those functions. 27 28A module does not need to coordinate its minor status codes with those 29of other mechanisms. If the mechglue detects conflicts, it will map 30the mechanism's status codes onto unique values, and then map them 31back again when **gss_display_status** is called. 32 33 34NegoEx modules 35-------------- 36 37Some Windows GSSAPI mechanisms can only be negotiated via a Microsoft 38extension to SPNEGO called NegoEx. Beginning with release 1.18, 39mechanism modules can support NegoEx as follows: 40 41* Implement the gssspi_query_meta_data(), gssspi_exchange_meta_data(), 42 and gssspi_query_mechanism_info() SPIs declared in 43 ``<gssapi/gssapi_ext.h>``. 44 45* Implement gss_inquire_sec_context_by_oid() and answer the 46 **GSS_C_INQ_NEGOEX_KEY** and **GSS_C_INQ_NEGOEX_VERIFY_KEY** OIDs 47 to provide the checksum keys for outgoing and incoming checksums, 48 respectively. The answer must be in two buffers: the first buffer 49 contains the key contents, and the second buffer contains the key 50 encryption type as a four-byte little-endian integer. 51 52By default, NegoEx mechanisms will not be directly negotiated via 53SPNEGO. If direct SPNEGO negotiation is required for 54interoperability, implement gss_inquire_attrs_for_mech() and assert 55the GSS_C_MA_NEGOEX_AND_SPNEGO attribute (along with any applicable 56RFC 5587 attributes). 57 58 59Interposer modules 60------------------ 61 62The mechglue also supports a kind of loadable module, called an 63interposer module, which intercepts calls to existing mechanisms 64rather than implementing a new mechanism. 65 66An interposer module must export the symbol **gss_mech_interposer** 67with the following signature:: 68 69 gss_OID_set gss_mech_interposer(gss_OID mech_type); 70 71This function is invoked with the OID of the interposer mechanism as 72specified in the mechanism config file, and returns a set of mechanism 73OIDs to be interposed. The returned OID set must have been created 74using the mechglue's gss_create_empty_oid_set and 75gss_add_oid_set_member functions. 76 77An interposer module must use the prefix ``gssi_`` for the GSSAPI 78functions it exports, instead of the prefix ``gss_``. In most cases, 79unexported ``gssi_`` functions will result in failure from their 80corresponding ``gss_`` calls. 81 82An interposer module can link against the GSSAPI library in order to 83make calls to the original mechanism. To do so, it must specify a 84special mechanism OID which is the concatention of the interposer's 85own OID byte string and the original mechanism's OID byte string. 86 87Functions that do not accept a mechanism argument directly require no 88special handling, with the following exceptions: 89 90Since **gss_accept_sec_context** does not accept a mechanism argument, 91an interposer mechanism must, in order to invoke the original 92mechanism's function, acquire a credential for the concatenated OID 93and pass that as the *verifier_cred_handle* parameter. 94 95Since **gss_import_name**, **gss_import_cred**, and 96**gss_import_sec_context** do not accept mechanism parameters, the SPI 97has been extended to include variants which do. This allows the 98interposer module to know which mechanism should be used to interpret 99the token. These functions have the following signatures:: 100 101 OM_uint32 gssi_import_sec_context_by_mech(OM_uint32 *minor_status, 102 gss_OID desired_mech, gss_buffer_t interprocess_token, 103 gss_ctx_id_t *context_handle); 104 105 OM_uint32 gssi_import_name_by_mech(OM_uint32 *minor_status, 106 gss_OID mech_type, gss_buffer_t input_name_buffer, 107 gss_OID input_name_type, gss_name_t output_name); 108 109 OM_uint32 gssi_import_cred_by_mech(OM_uint32 *minor_status, 110 gss_OID mech_type, gss_buffer_t token, 111 gss_cred_id_t *cred_handle); 112 113To re-enter the original mechanism when importing tokens for the above 114functions, the interposer module must wrap the mechanism token in the 115mechglue's format, using the concatenated OID (except in 116**gss_import_name**). The mechglue token formats are: 117 118* For **gss_import_sec_context**, a four-byte OID length in big-endian 119 order, followed by the concatenated OID, followed by the mechanism 120 token. 121 122* For **gss_import_name**, the bytes 04 01, followed by a two-byte OID 123 length in big-endian order, followed by the mechanism OID, followed 124 by a four-byte token length in big-endian order, followed by the 125 mechanism token. Unlike most uses of OIDs in the API, the mechanism 126 OID encoding must include the DER tag and length for an object 127 identifier (06 followed by the DER length of the OID byte string), 128 and this prefix must be included in the two-byte OID length. 129 input_name_type must also be set to GSS_C_NT_EXPORT_NAME. 130 131* For **gss_import_cred**, a four-byte OID length in big-endian order, 132 followed by the concatenated OID, followed by a four-byte token 133 length in big-endian order, followed by the mechanism token. This 134 sequence may be repeated multiple times. 135