Wrap Size

Wrapping a message with gss_wrap() increases its size. Because the protected message packet must not be too big to “fit through” a given transportation protocol, the GSS-API provides a function, gss_wrap_size_limit(), that calculates the maximum size of a message that can be wrapped without becoming too large. The application can break up messages that exceed this size before calling gss_wrap(). It's a good idea to check the wrap-size limit before actually wrapping the message.

The amount of the size increase depends on two things:

• Which QOP (Quality of Protection) algorithm is used for making the transformation. Since the default QOP can vary from one implementation of the GSS-API to another, a wrapped message can vary in size even if you do not specify a non-default QOP. This is shown in the following figure.

  Figure 1–12 Wrap Size (Different QOPs)

  
  

• Whether confidentiality is invoked. Whether or not confidentiality is applied, gss_wrap() still increases the size of a message, because it embeds a MIC into the transmitted message. However, encrypting the message can further increase the size. The following figure shows how this works.

  Figure 1–13 Wrap Size (Confidentiality/No Confidentiality)

  
  

gss_wrap_size_limit() looks like this:

OM_uint32 gss_wrap_size_limit (
OM_uint32          *minor_status,
const gss_ctx_id_t context_handle,
int                conf_req_flag,
gss_qop_t          qop_req,
OM_uint32          req_output_size,
OM_uint32          *max_input_size)

minor_status

The status code returned by the underlying mechanism.

context_handle

The context under which the data is transmitted.

conf_req_flag

A flag for requesting the confidentiality service (encryption). If non-zero, both confidentiality and integrity are requested; if zero, only the integrity service is requested.

qop_req

A requested QOP (Quality of Protection). This is the cryptographic algorithm used in generating the MIC and doing the encryption. For portability's sake, applications should specify the default QOP by setting this argument to GSS_C_QOP_DEFAULT whenever possible. (See Appendix C, Specifying an OID on specifying a non-default QOP.)

req_output_size

The maximum size (as an int) of a data chunk that a given transport protocol can handle. You must provide this information yourself; since the GSS-API is protocol-independent, it has no way of knowing which protocol is being used.

max_input_size

Returned by the function, this is the maximum size of an unwrapped message that, when wrapped, will not exceed req_output_size.

gss_wrap_size_limit() returns GSS_S_COMPLETE if it completes successfully. If the specified QOP was not valid, it returns GSS_S_BAD_QOP. call_server() includes an example of gss_wrap_size_limit() being used to return the maximum original message size, both if confidentiality is used and if it is not used.

Successful completion of this call does not necessarily guarantee that gss_wrap() will be able to protect a message of length max_input_size bytes, since this ability can depend on the availability of system resources at the time that gss_wrap() is called. For more information, see the gss_wrap_size_limit(3GSS) man page.