1 '\" te

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

     3 .TH gss_wrap 3GSS "22 Aug 2011" "SunOS 5.12" "Generic Security Services API Library Functions"

     4 .SH NAME

     5 gss_wrap \- attach a cryptographic message

     6 .SH SYNOPSIS

     7 .LP

     8 .nf

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

    10 #include <gssapi/gssapi.h>

    11 

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

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

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

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

    16 .fi

    17 

    18 .SH DESCRIPTION

    19 .sp

    20 .LP

    21 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.

    22 .sp

    23 .LP

    24 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.

    25 .SH PARAMETERS

    26 .sp

    27 .LP

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

    29 .sp

    30 .ne 2

    31 .mk

    32 .na

    33 \fB\fIminor_status\fR\fR

    34 .ad

    35 .RS 25n

    36 .rt  

    37 The status code returned by the underlying mechanism.

    38 .RE

    39 

    40 .sp

    41 .ne 2

    42 .mk

    43 .na

    44 \fB\fIcontext_handle\fR\fR

    45 .ad

    46 .RS 25n

    47 .rt  

    48 Identifies the context on which the message will be sent.

    49 .RE

    50 

    51 .sp

    52 .ne 2

    53 .mk

    54 .na

    55 \fB\fIconf_req_flag\fR\fR

    56 .ad

    57 .RS 25n

    58 .rt  

    59 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.

    60 .RE

    61 

    62 .sp

    63 .ne 2

    64 .mk

    65 .na

    66 \fB\fIqop_req\fR\fR

    67 .ad

    68 .RS 25n

    69 .rt  

    70 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.

    71 .RE

    72 

    73 .sp

    74 .ne 2

    75 .mk

    76 .na

    77 \fB\fIinput_message_buffer\fR\fR

    78 .ad

    79 .RS 25n

    80 .rt  

    81 The message to be protected.

    82 .RE

    83 

    84 .sp

    85 .ne 2

    86 .mk

    87 .na

    88 \fB\fIconf_state\fR\fR

    89 .ad

    90 .RS 25n

    91 .rt  

    92 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.

    93 .RE

    94 

    95 .sp

    96 .ne 2

    97 .mk

    98 .na

    99 \fB\fIoutput_message_buffer\fR\fR

   100 .ad

   101 .RS 25n

   102 .rt  

   103 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).

   104 .RE

   105 

   106 .SH ERRORS

   107 .sp

   108 .LP

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

   110 .sp

   111 .ne 2

   112 .mk

   113 .na

   114 \fB\fBGSS_S_COMPLETE\fR\fR

   115 .ad

   116 .RS 25n

   117 .rt  

   118 Successful completion.

   119 .RE

   120 

   121 .sp

   122 .ne 2

   123 .mk

   124 .na

   125 \fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR

   126 .ad

   127 .RS 25n

   128 .rt  

   129 The context has already expired.

   130 .RE

   131 

   132 .sp

   133 .ne 2

   134 .mk

   135 .na

   136 \fB\fBGSS_S_NO_CONTEXT\fR\fR

   137 .ad

   138 .RS 25n

   139 .rt  

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

   141 .RE

   142 

   143 .sp

   144 .ne 2

   145 .mk

   146 .na

   147 \fB\fBGSS_S_BAD_QOP\fR\fR

   148 .ad

   149 .RS 25n

   150 .rt  

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

   152 .RE

   153 

   154 .sp

   155 .ne 2

   156 .mk

   157 .na

   158 \fB\fBGSS_S_FAILURE\fR\fR

   159 .ad

   160 .RS 25n

   161 .rt  

   162 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.

   163 .RE

   164 

   165 .SH ATTRIBUTES

   166 .sp

   167 .LP

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

   169 .sp

   170 

   171 .sp

   172 .TS

   173 tab() box;

   174 cw(2.75i) |cw(2.75i) 

   175 lw(2.75i) |lw(2.75i) 

   176 .

   177 ATTRIBUTE TYPEATTRIBUTE VALUE

   178 _

   179 MT-LevelSafe

   180 .TE

   181 

   182 .SH SEE ALSO

   183 .sp

   184 .LP

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

   186 .sp

   187 .LP

   188