usr/src/man/man3gss/gss_wrap.3gss

   1 '\" te
   2 .\" Copyright (C) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH GSS_WRAP 3GSS "Jan 15, 2003"
   7 .SH NAME
   8 gss_wrap \- attach a cryptographic message
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  13 #include <gssapi/gssapi.h>
  14
  15 \fBOM_uint32\fR \fBgss_wrap\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  16      \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR, \fBint\fR \fIconf_req_flag\fR,
  17      \fBgss_qop_t\fR \fIqop_req\fR, \fBconst gss_buffer_t\fR \fIinput_message_buffer\fR,
  18      \fBint *\fR\fIconf_state\fR, \fBgss_buffer_t\fR \fIoutput_message_buffer\fR);
  19 .fi
  20
  21 .SH DESCRIPTION
  22 .sp
  23 .LP
  24 The \fBgss_wrap()\fR function attaches a cryptographic \fBMIC\fR and optionally
  25 encrypts the specified \fIinput_message\fR. The \fIoutput_message\fR contains
  26 both the \fBMIC\fR and the message. The \fIqop_req\fR parameter allows a choice
  27 between several cryptographic algorithms, if supported by the chosen mechanism.
  28 .sp
  29 .LP
  30 Since some application-level protocols may wish to use tokens emitted by
  31 \fBgss_wrap()\fR to provide secure framing, the \fBGSS-API\fR supports the
  32 wrapping of zero-length messages.
  33 .SH PARAMETERS
  34 .sp
  35 .LP
  36 The parameter descriptions for \fBgss_wrap()\fR follow:
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIminor_status\fR\fR
  41 .ad
  42 .RS 25n
  43 The status code returned by the underlying mechanism.
  44 .RE
  45
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fIcontext_handle\fR\fR
  50 .ad
  51 .RS 25n
  52 Identifies the context on which the message will be sent.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fIconf_req_flag\fR\fR
  59 .ad
  60 .RS 25n
  61 If the value of \fIconf_req_flag\fR is non-zero, both confidentiality and
  62 integrity services are requested. If the value is zero, then only integrity
  63 service is requested.
  64 .RE
  65
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fIqop_req\fR\fR
  70 .ad
  71 .RS 25n
  72 Specifies the required quality of protection. A mechanism-specific default may
  73 be requested by setting \fIqop_req\fR to \fBGSS_C_QOP_DEFAULT\fR. If an
  74 unsupported protection strength is requested, \fBgss_wrap()\fR will return a
  75 \fImajor_status\fR of \fBGSS_S_BAD_QOP\fR.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIinput_message_buffer\fR\fR
  82 .ad
  83 .RS 25n
  84 The message to be protected.
  85 .RE
  86
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fIconf_state\fR\fR
  91 .ad
  92 .RS 25n
  93 If the value of \fIconf_state\fR is non-zero, confidentiality, data origin
  94 authentication, and integrity services have been applied. If the value is zero,
  95 then integrity services have been applied. Specify \fBNULL\fR if this parameter
  96 is not required.
  97 .RE
  98
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fIoutput_message_buffer\fR\fR
 103 .ad
 104 .RS 25n
 105 The buffer to receive the protected message. Storage associated with this
 106 message must be freed by the application after use with a call to
 107 \fBgss_release_buffer\fR(3GSS).
 108 .RE
 109
 110 .SH ERRORS
 111 .sp
 112 .LP
 113 \fBgss_wrap()\fR may return the following status codes:
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBGSS_S_COMPLETE\fR\fR
 118 .ad
 119 .RS 25n
 120 Successful completion.
 121 .RE
 122
 123 .sp
 124 .ne 2
 125 .na
 126 \fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR
 127 .ad
 128 .RS 25n
 129 The context has already expired.
 130 .RE
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fB\fBGSS_S_NO_CONTEXT\fR\fR
 136 .ad
 137 .RS 25n
 138 The \fIcontext_handle\fR parameter did not identify a valid context.
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBGSS_S_BAD_QOP\fR\fR
 145 .ad
 146 .RS 25n
 147 The specified \fBQOP\fR is not supported by the mechanism.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBGSS_S_FAILURE\fR\fR
 154 .ad
 155 .RS 25n
 156 The underlying mechanism detected an error for which no specific \fBGSS\fR
 157 status code is defined.  The mechanism-specific status code reported by means
 158 of the \fIminor_status\fR parameter details the error condition.
 159 .RE
 160
 161 .SH ATTRIBUTES
 162 .sp
 163 .LP
 164 See \fBattributes\fR(5)  for descriptions of the following attributes:
 165 .sp
 166
 167 .sp
 168 .TS
 169 box;
 170 c | c
 171 l | l .
 172 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 173 _
 174 MT-Level        Safe
 175 .TE
 176
 177 .SH SEE ALSO
 178 .sp
 179 .LP
 180 \fBgss_release_buffer\fR(3GSS), \fBattributes\fR(5)
 181 .sp
 182 .LP
 183 \fISolaris Security for Developers Guide\fR