 |
Index for
Section 3 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
gss_wrap(3)
NAME
gss_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
minor_status
Kerberos 5 error code.
context_handle
Security context that contains the session key used to encrypt the
message and generate its checksum.
conf_req_flag
Protection requested for wrapping, that is, encrypting to ensure
confidentiality.
· Non-zero -- encryption is requested.
· Zero -- encryption is not requested.
qop_req 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 algorithm 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
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_CONF_C_QOP_DES3 for DES3.
· GSS_KRB5_CONF_C_QOP_DES for DES.
input_message_buffer
Message to be protected.
conf_state
Protection 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_message_buffer
Output buffer that receives the protected 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 application 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
message 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
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 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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|