gss_wrap(3)gss_wrap(3)NAMEgss_wrap - generate a checksum for the supplied message. Can also
include the message
SYNOPSIS
#include <gssapi/gssapi.h>
OM_uint32 gss_wrap(
OM_uint32 * minor_status,
const gss_ctx_id_t context_handle,
int conf_req_flag,
gss_qop_t qop_req,
const gss_buffer_t input_message_buffer,
int * conf_state,
gss_buffer_t output_message_buffer );
PARAMETERS
Kerberos 5 error code. Security context that contains the session key
used to encrypt the message and generate its checksum. Protection
requested for wrapping, that is, encrypting to ensure confidentiality.
Non-zero -- encryption is requested. Zero -- encryption is not
requested. Requested quality of protection (QOP):
CSF_GSS_KRB5_CONF_C_QOP_DES3 -- Confidentiality QOP that provides DES3
encryption.
This QOP is unique to the HP implementation of DES3 for the GSS-
API standard. CSF_GSS_KRB5_INTEG_C_QOP_DES3_MD5 -- This algo‐
rithm first calculates a 16-byte MD5 checksum of the message.
Then it performs a DES3-CBC MAC on the MD5 checksum using an
initial vector of zero.
This QOP is unique to the HP implementation of DES3 for the GSS-
API standard. GSS_KRB5_CONF_C_QOP_DES -- Confidentiality QOP
that provides DES encryption. 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 per‐
forms 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_CONF_C_QOP_DES3 for DES3.
GSS_KRB5_CONF_C_QOP_DES for DES. Message to be protected. Pro‐
tection available when the message is wrapped, that is,
encrypted to ensure confidentiality. Specify NULL if this
information is not needed. Non-zero -- encryption used. Zero
-- encryption not used. Output buffer that receives the pro‐
tected message.
Storage associated with the message buffer must be freed by the
application after use with a call to gss_release_buffer().
DESCRIPTION
The gss_wrap() function generates a checksum, called a message
integrity code (MIC), for the supplied message. The checksum and the
message are placed in a token that is transferred to the peer applica‐
tion when the local application sends the message. If requested, this
function also encrypts the message before it encapsulates it in the
token.
Message confidentiality is provided using the DES-CBC algorithm for DES
encryption and the DES3-CBC-EDE algorithm for DES3 encryption.
Note
This function is a direct replacement for the gss_seal() function used
in GSS-API version 1 compliant products, including the HP Application
Security Toolkit.
The HP Application Security SDK supports the following confidentiality
QOPs: CSF_GSS_KRB5_CONF_C_QOP_DES3 GSS_KRB5_CONF_C_QOP_DES
Supported integrity QOPs are: 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 QOP passed to gss_wrap() specifies the protection algorithm to use:
If an integrity QOP is passed, the specified integrity algorithm is
used to compute a checksum for the message. If confidentiality is
requested, the default confidentiality algorithm is used:
CSF_GSS_KRB5_CONF_C_QOP_DES3 for DES3. GSS_KRB5_CONF_C_QOP_DES for
DES. If a confidentiality QOP is passed, the specified confidentiality
algorithm is used, if confidentiality was requested. The default mes‐
sage integrity algorithm is used for the message checksum:
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 gss_inquire_context() to determine whether DES or DES3 is
available.
Storage associated with the output message buffer 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
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_inquire_context(3), gss_release_buffer(3),
gss_unwrap(3)gss_wrap(3)
