Projects/GSS IOV MIC API

This project was completed in release 1.12.

Description

This project adds support for constructing GSSAPI MIC tokens using IOV lists.

Background

The GSSAPI defines several types of per-message tokens, including wrap tokens (normally created by gss_wrap) and MIC tokens (normally created by gss_get_mic). Wrap tokens allow data to be encrypted or integrity-protected, while MIC tokens allow keyed checksums of data to be created without including the data itself in the token.

Release 1.7 added the gss_wrap_iov, gss_wrap_iov_length, and gss_unwrap_iov functions which allow wrap tokens to be created using lists of gss_iov_buffer_desc structures, and also allow "sign-only" data to be included in the authentication checksum without being encrypted. Although this work included some untested internal support for constructing MIC tokens in the same fashion, that work was not completed and no interfaces were exposed. Today there is interest in the ability to construct and verify MIC tokens over several data buffers without having to concatenate them.

Public API

The following public functions are added, with prototypes in <gssapi/gssapi_ext.h>:

   OM_uint32 gss_get_mic_iov(OM_uint32 *minor_status, gss_ctx_id_t context_handle,
                             gss_qop_t qop_req, gss_iov_buffer_desc *iov,
                             int iov_count);

   OM_uint32 gss_get_mic_iov_length(OM_uint32 *minor_status,
                                    gss_ctx_id_t context_handle,
                                    gss_qop_t qop_req, gss_iov_buffer_desc *iov,
                                    int iov_count);

   OM_uint32 gss_verify_mic_iov(OM_uint32 *minor_status,
                                gss_ctx_id_t context_handle, gss_qop_t *qop_state,
                                gss_iov_buffer_desc *iov, int iov_count);

As with all GSSAPI entry points, the KRB5_CALLCONV macro will be used to use the __stdcall calling convention on Windows.

A new buffer type is added, GSS_IOV_BUFFER_TYPE_MIC_TOKEN. This buffer type is used as the destination for gss_get_mic_iov, and the token to be verified for gss_verify_mic_iov. gss_get_mic_iov_length can be used to query its length. As with the wrap interfaces, the GSS_IOV_BUFFER_FLAG_ALLOCATE flag can be used to request that gss_get_mic_iov allocate the buffer, in which case gss_release_iov_buffer can be used to free the allocated buffer from the IOV list after it is no longer needed.

Testing

A new program t_iov.c is added to test the gss_wrap interfaces with several different token configurations. MIC tests are added to this program. The program is run by t_gssapi.py using all of the different enctype configurations defined by the Python test suite, to make sure that we exercise both v1 and v3 token types.

Documentation

The existing IOV functions are currently documented via comments in gssapi_ext.h, and the new ones will be documented this way as well. Time permitting, gssapi.rst will be extended to add a section about IOV functions.

Mailing list discussions

http://mailman.mit.edu/pipermail/krbdev/2013-September/011757.html

Commits

   95f6a640573076b8e68051ed4f2447be767cd2ec Factor out context establishment in GSS tests
   ecd91cd350b2c3880b3f967acfcb00ac1bdac154 Add tests for GSS IOV and AEAD interfaces
   da10b66df1f1411ad54cba177454a7634619bb08 Use gss_release_iov_buffer in t_iov.c
   daf42938a262c3a88164b07972f2a2e6e8552620 Get rid of G_VFY_TOKEN_HDR_IGNORE_SEQ_SIZE

Completed in [krbdev.mit.edu #7705].

Release notes

Developer experience:

• Add GSSAPI extensions for constructing MIC tokens using IOV lists.