'\" te

.\" Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights reserved.

.SH NAME

gss_wrap \- attach a cryptographic message

.SH SYNOPSIS

.LP

.nf

\fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ] 

#include <gssapi/gssapi.h>

\fBOM_uint32\fR \fBgss_wrap\fR(\fBOM_uint32 *\fR\fIminor_status\fR,

     \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR, \fBint\fR \fIconf_req_flag\fR,

     \fBgss_qop_t\fR \fIqop_req\fR, \fBconst gss_buffer_t\fR \fIinput_message_buffer\fR,

     \fBint *\fR\fIconf_state\fR, \fBgss_buffer_t\fR \fIoutput_message_buffer\fR);

.fi

.SH DESCRIPTION

.sp

.LP

The \fBgss_wrap()\fR function attaches a cryptographic \fBMIC\fR and optionally encrypts the specified \fIinput_message\fR. The \fIoutput_message\fR contains both the \fBMIC\fR and the message. The \fIqop_req\fR parameter allows a choice between several cryptographic algorithms, if supported by the chosen mechanism.

.sp

.LP

Since some application-level protocols may wish to use tokens emitted by \fBgss_wrap()\fR to provide secure framing, the \fBGSS-API\fR supports the wrapping of zero-length messages.

.SH PARAMETERS

.sp

.LP

The parameter descriptions for \fBgss_wrap()\fR follow:

.sp

.ne 2

.mk

.na

\fB\fIminor_status\fR\fR

.ad

.RS 25n

.rt  

The status code returned by the underlying mechanism.

.RE

.sp

.ne 2

.mk

.na

\fB\fIcontext_handle\fR\fR

.ad

.RS 25n

.rt  

Identifies the context on which the message will be sent.

.RE

.sp

.ne 2

.mk

.na

\fB\fIconf_req_flag\fR\fR

.ad

.RS 25n

.rt  

If the value of \fIconf_req_flag\fR is non-zero, both confidentiality and integrity services are requested. If the value is zero, then only integrity service is requested.

.RE

.sp

.ne 2

.mk

.na

\fB\fIqop_req\fR\fR

.ad

.RS 25n

.rt  

Specifies the required quality of protection. A mechanism-specific default may be requested by setting \fIqop_req\fR to \fBGSS_C_QOP_DEFAULT\fR. If an unsupported protection strength is requested, \fBgss_wrap()\fR will return a \fImajor_status\fR of \fBGSS_S_BAD_QOP\fR.

.RE

.sp

.ne 2

.mk

.na

\fB\fIinput_message_buffer\fR\fR

.ad

.RS 25n

.rt  

The message to be protected.

.RE

.sp

.ne 2

.mk

.na

\fB\fIconf_state\fR\fR

.ad

.RS 25n

.rt  

If the value of \fIconf_state\fR is non-zero, confidentiality, data origin authentication, and integrity services have been applied. If the value is zero, then integrity services have been applied. Specify \fBNULL\fR if this parameter is not required.

.RE

.sp

.ne 2

.mk

.na

\fB\fIoutput_message_buffer\fR\fR

.ad

.RS 25n

.rt  

The buffer to receive the protected message. Storage associated with this message must be freed by the application after use with a call to \fBgss_release_buffer\fR(3GSS).

.RE

.SH ERRORS

.sp

.LP

\fBgss_wrap()\fR may return the following status codes:

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_COMPLETE\fR\fR

.ad

.RS 25n

.rt  

Successful completion.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR

.ad

.RS 25n

.rt  

The context has already expired.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_NO_CONTEXT\fR\fR

.ad

.RS 25n

.rt  

The \fIcontext_handle\fR parameter did not identify a valid context.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_BAD_QOP\fR\fR

.ad

.RS 25n

.rt  

The specified \fBQOP\fR is not supported by the mechanism.

.RE

.sp

.ne 2

.mk

.na

\fB\fBGSS_S_FAILURE\fR\fR

.ad

.RS 25n

.rt  

The underlying mechanism detected an error for which no specific \fBGSS\fR status code is defined.  The mechanism-specific status code reported by means of the \fIminor_status\fR parameter details the error condition.

.RE

.SH ATTRIBUTES

.sp

.LP

See \fBattributes\fR(5)  for descriptions of the following attributes:

.sp

.sp

.TS

tab() box;

cw(2.75i) |cw(2.75i) 

lw(2.75i) |lw(2.75i) 

.

ATTRIBUTE TYPEATTRIBUTE VALUE

_

MT-LevelSafe

.TE

.SH SEE ALSO

.sp

.LP

\fBgss_release_buffer\fR(3GSS), \fBattributes\fR(5)

.sp

.LP