usr/src/man/man3gss/gss_wrap_size_limit.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_SIZE_LIMIT 3GSS "Jan 15, 2003"
   7 .SH NAME
   8 gss_wrap_size_limit \- allow application to determine maximum message size with
   9 resulting output token of a specified maximum size
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lgss\fR  [ \fIlibrary\fR... ]
  14 #include <gssapi/gssapi.h>
  15
  16 \fBOM_uint32\fR \fBgss_process_context_token\fR(\fBOM_uint32 *\fR\fIminor_status\fR,
  17      \fBconst gss_ctx_id_t\fR \fIcontext_handle\fR, \fBint\fR  \fIconf_req_flag\fR,
  18      \fBgss_qop_t\fR \fIqop_req\fR, \fBOM_uint32\fR \fIreq_output_size\fR,
  19      \fBOM_uint32 *\fR\fImax_input_size\fR);
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBgss_wrap_size_limit()\fR function allows an application to determine the
  26 maximum message size that, if presented to \fBgss_wrap()\fR with the same
  27 \fIconf_req_flag\fR and \fIqop_req\fR parameters, results in an output token
  28 containing no more than \fIreq_output_size\fR bytes. This call is intended for
  29 use by applications that communicate over protocols that impose a maximum
  30 message size. It enables the application to fragment messages prior to applying
  31 protection. The \fBGSS-API\fR detects invalid \fBQOP\fR values when
  32 \fBgss_wrap_size_limit()\fR is called. This routine guarantees only a maximum
  33 message size, not the availability of specific \fBQOP\fR values for message
  34 protection.
  35 .sp
  36 .LP
  37 Successful completion of \fBgss_wrap_size_limit()\fR does not guarantee that
  38 \fBgss_wrap()\fR will be able to protect a message of length
  39 \fImax_input_size\fR bytes, since this ability might depend on the availability
  40 of system resources at the time that \fBgss_wrap()\fR is called.
  41 .SH PARAMETERS
  42 .sp
  43 .LP
  44 The parameter descriptions for \fBgss_wrap_size_limit()\fR are as follows:
  45 .sp
  46 .ne 2
  47 .na
  48 \fB\fIminor_status\fR\fR
  49 .ad
  50 .RS 19n
  51 A mechanism-specific status code.
  52 .RE
  53
  54 .sp
  55 .ne 2
  56 .na
  57 \fB\fIcontext_handle\fR\fR
  58 .ad
  59 .RS 19n
  60 A handle that refers to the security over which the messages will be sent.
  61 .RE
  62
  63 .sp
  64 .ne 2
  65 .na
  66 \fB\fIconf_req_flag\fR\fR
  67 .ad
  68 .RS 19n
  69 Indicates whether \fBgss_wrap()\fR will be asked to apply confidential
  70 protection in addition to integrity protection. See \fBgss_wrap\fR(3GSS) for
  71 more details.
  72 .RE
  73
  74 .sp
  75 .ne 2
  76 .na
  77 \fB\fIqop_req\fR\fR
  78 .ad
  79 .RS 19n
  80 Indicates the level of protection that \fBgss_wrap()\fR will be asked to
  81 provide.  See \fBgss_wrap\fR(3GSS) for more details.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fIreq_output_size\fR\fR
  88 .ad
  89 .RS 19n
  90 The desired maximum size for tokens emitted by \fBgss_wrap()\fR.
  91 .RE
  92
  93 .sp
  94 .ne 2
  95 .na
  96 \fB\fImax_input_size\fR\fR
  97 .ad
  98 .RS 19n
  99 The maximum input message size that can be presented to \fBgss_wrap()\fR to
 100 guarantee that the emitted token will be no larger than \fIreq_output_size\fR
 101 bytes.
 102 .RE
 103
 104 .SH ERRORS
 105 .sp
 106 .LP
 107 \fBgss_wrap_size_limit()\fR returns one of the following status codes:
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBGSS_S_COMPLETE\fR\fR
 112 .ad
 113 .RS 25n
 114 Successful completion.
 115 .RE
 116
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBGSS_S_NO_CONTEXT\fR\fR
 121 .ad
 122 .RS 25n
 123 The referenced context could not be accessed.
 124 .RE
 125
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBGSS_S_CONTEXT_EXPIRED\fR\fR
 130 .ad
 131 .RS 25n
 132 The context has expired.
 133 .RE
 134
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBGSS_S_BAD_QOP\fR\fR
 139 .ad
 140 .RS 25n
 141 The specified \fBQOP\fR is not supported by the mechanism.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBGSS_S_FAILURE\fR\fR
 148 .ad
 149 .RS 25n
 150 The underlying mechanism detected an error for which no specific \fBGSS\fR
 151 status code is defined.  The mechanism-specific status code reported by means
 152 of the \fIminor_status\fR parameter details the error condition.
 153 .RE
 154
 155 .SH ATTRIBUTES
 156 .sp
 157 .LP
 158 See \fBattributes\fR(5) for descriptions of the following attributes:
 159 .sp
 160
 161 .sp
 162 .TS
 163 box;
 164 c | c
 165 l | l .
 166 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 167 _
 168 MT Level        Safe
 169 .TE
 170
 171 .SH SEE ALSO
 172 .sp
 173 .LP
 174 \fBgss_wrap\fR(3GSS), \fBattributes\fR(5)
 175 .sp
 176 .LP
 177 \fISolaris Security for Developers Guide\fR