NAME

gss_get_mic − generate a checksum for a supplied message. Does not include the message

SYNOPSIS

#include <gssapi/gssapi.h>
OM_uint32 gss_get_mic(
        OM_uint32 ∗ minor_status,
        const gss_ctx_id_t context_handle,
        gss_qop_t qop_req,
        const gss_buffer_t message_buffer,
        gss_buffer_t message_token );

PARAMETERS

minor_status
Kerberos 5 error code.

context_handle
Security context that contains the session key used to generate the message checksum.

qop_req
Requested quality of protection (QOP):

       •CSF_GSS_KRB5_INTEG_C_QOP_DES3_MD5 −− This algorithm first calculates a 16-byte MD5 checksum of the message. Then it performs a DES3-CBC MAC on the MD5 checksum using the key as the initial vector. 

This QOP is unique to the HP implementation of DES3 for the GSS-API standard. 

       •GSS_KRB5_INTEG_C_QOP_DES_MAC −− This algorithm computes the checksum as a standard 64-bit DES-CBC MAC. 

       •GSS_KRB5_INTEG_C_QOP_DES_MD5 −− This algorithm first calculates a 16-byte MD5 checksum of the message. Then it performs a DES-CBC MAC on the MD5 checksum using an initial vector of zero. 

       •GSS_KRB5_INTEG_C_QOP_MD5 −− This algorithm first DES-CBC encrypts a 16-byte zero-block using a initial vector of zero and a DES key formed by reversing the security context key. Then it logically prepends the resulting 16-byte checksum to the message. Finally a standard MD2.5 checksum is calculated over the combined length. The first 8 bytes of the 16-byte MD5 checksum are encoded into the returned token. 

To obtain the default QOP, specify GSS_C_QOP_DEFAULT.  The default QOP is determined by the encryption method stored in the context:

       •CSF_GSS_KRB5_INTEG_C_QOP_DES3_MD5 for DES3. 

       •GSS_KRB5_INTEG_C_QOP_DES_MD5 for DES. 

message_buffer
Message to be protected.

message_token
Output buffer that receives the token containing a checksum. The message passed via the message_buffer parameter is not encapsulated in the token. 

Storage associated with this buffer must be freed by the application after use with a call to gss_release_buffer(). 

DESCRIPTION

The gss_get_mic() function generates a checksum, called a message integrity code (MIC), for the supplied message. The checksum is placed in a token that is transferred to the peer application when the local application sends the message. 

The message itself is not encrypted or encapsulated in the token with this function. To encrypt the message or encapsulate it in the token, use gss_wrap(). 

Note

This function is a direct replacement for the gss_sign() function used in GSS-API version 1 compliant products, including the HP Application Security Toolkit. 

The HP Application Security SDK supports the following QOPs:

       •CSF_GSS_KRB5_INTEG_C_QOP_DES3_MD5

       •GSS_KRB5_INTEG_C_QOP_DES_MAC

       •GSS_KRB5_INTEG_C_QOP_DES_MD5

       •GSS_KRB5_INTEG_C_QOP_MD5

If an unsupported protection strength is requested, the error code GSS_S_BAD_QOP is returned. 

The default QOP is determined by the encryption method stored in the context:

       •CSF_GSS_KRB5_INTEG_C_QOP_DES3_MD5 for DES3. 

       •GSS_KRB5_INTEG_C_QOP_DES_MD5 for DES. 

Note

Multiple encryption systems for a single security context are not supported.  The QOP value requested must be consistent with the encryption method used.  For example, if an application obtains a DES3 security context but requests GSS_KRB5_CONF_C_QOP_DES, the encryption algorithm is automatically upgraded to GSS_KRB5_CONF_C_QOP_DES3. Or, if a DES3 QOP was specified when the application previously obtained a DES security context, a GSS_S_BAD_QOP error would result. Check the flags returned with csf_gss_get_context_options() to determine whether DES or DES3 is available. 

Storage associated with the message token being sent must be freed by the application after use with a call to gss_release_buffer(). 

RETURN VALUES

PORTABILITY CONSIDERATIONS

Since the HP implementation of DES3 is an extension of the GSS-API, it will not interoperate with other GSS-API vendors offering DES3. 

SEE ALSO

Functions:  csf_gss_get_context_options(3), gss_accept_sec_context(3), gss_init_sec_context(3), gss_release_buffer(3), gss_verify_mic(3), gss_wrap(3)