gss_get_mic(3)gss_get_mic(3)NAMEgss_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
Kerberos 5 error code. Security context that contains the session key
used to generate the message checksum. Requested quality of protection
(QOP): CSF_GSS_KRB5_INTEG_C_QOP_DES3_MD5 -- This algorithm first calcu‐
lates 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 mes‐
sage. 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 to be protected.
Output buffer that receives the token containing a checksum. The
message passed via the message_buffer parameter is not encapsu‐
lated in the token.
Storage associated with this buffer must be freed by the appli‐
cation 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 sup‐
ported. 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 secu‐
rity 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
GSS_S_BAD_QOP xx0Exxxx
GSS_S_CALL_INACCESSIBLE_READ 01xxxxxx
GSS_S_CALL_INACCESSIBLE_WRITE 02xxxxxx
GSS_S_COMPLETE 00000000
GSS_S_FAILURE xx0Dxxxx
GSS_S_NO_CONTEXT xx08xxxx
GSS_S_UNAVAILABLE xx10xxxx
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)gss_get_mic(3)