lib/libgssapi/gss_wrap_size_limit.3

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2005 Doug Rabson
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\"     $FreeBSD$
  28 .\"
  29 .\" The following commands are required for all man pages.
  30 .Dd January 26, 2010
  31 .Dt GSS_WRAP_SIZE_LIMIT 3 PRM
  32 .Os
  33 .Sh NAME
  34 .Nm gss_wrap_size_limit
  35 .Nd Determine maximum message sizes
  36 .\" This next command is for sections 2 and 3 only.
  37 .\" .Sh LIBRARY
  38 .Sh SYNOPSIS
  39 .In "gssapi/gssapi.h"
  40 .Ft OM_uint32
  41 .Fo gss_wrap_size_limit
  42 .Fa "OM_uint32 *minor_status"
  43 .Fa "const gss_ctx_id_t context_handle"
  44 .Fa "int conf_req_flag"
  45 .Fa "gss_qop_t qop_req"
  46 .Fa "OM_uint32 req_output_size"
  47 .Fa "OM_uint32 *max_input_size"
  48 .Fc
  49 .Sh DESCRIPTION
  50 Allows an application to determine the maximum message size that,
  51 if presented to
  52 .Xr gss_wrap 3
  53 with the same
  54 .Dv conf_req_flag
  55 and
  56 .Dv qop_req
  57 parameters,
  58 will result in an output token containing no more than
  59 .Dv req_output_size
  60 bytes.
  61 .Pp
  62 This call is intended for use by applications that
  63 communicate over protocols that impose a maximum message size.
  64 It enables the application to fragment messages prior to applying protection.
  65 .Pp
  66 GSS-API implementations are recommended but not required to detect
  67 invalid QOP values when
  68 .Fn gss_wrap_size_limit
  69 is called.
  70 This routine guarantees only a maximum message size,
  71 not the availability of specific QOP values for message protection.
  72 .Pp
  73 Successful completion of this call does not guarantee that
  74 .Xr gss_wrap 3
  75 will be able to protect a message of length max_input_size bytes,
  76 since this ability may depend on the availability of system resources
  77 at the time that
  78 .Xr gss_wrap 3
  79 is called.
  80 However, if the implementation itself imposes an upper limit on
  81 the length of messages that may be processed by gss_wrap,
  82 the implementation should not return a value via
  83 .Dv max_input_bytes
  84 that is greater than this length.
  85 .Sh PARAMETERS
  86 .Bl -tag -width ".It req_output_size"
  87 .It minor_status
  88 Mechanism specific status code.
  89 .It context_handle
  90 A handle that refers to the security over which the messages will be sent.
  91 .It conf_req_flag
  92 Indicates whether
  93 .Xr gss_wrap 3
  94 will be asked to apply confidentiality protection
  95 in addition to integrity protection.
  96 .It qop_req
  97 Indicates the level of protection that
  98 .Xr gss_wrap 3
  99 will be asked to provide.
 100 .It req_output_size
 101 The desired maximum size for tokens emitted by
 102 .Xr gss_wrap 3 .
 103 .It max_input_size
 104 The maximum input message size that may be presented to
 105 .Xr gss_wrap 3
 106 in order to guarantee that the emitted token shall
 107 be no larger than
 108 .Dv req_output_size
 109 bytes.
 110 .El
 111 .Sh RETURN VALUES
 112 .Bl -tag -width ".It GSS_S_CONTEXT_EXPIRED"
 113 .It GSS_S_COMPLETE
 114 Successful completion.
 115 .It GSS_S_NO_CONTEXT
 116 The referenced context could not be accessed.
 117 .It GSS_S_CONTEXT_EXPIRED
 118 The context has expired.
 119 .It GSS_S_BAD_QOP
 120 The specified QOP is not supported by the mechanism.
 121 .El
 122 .Sh SEE ALSO
 123 .Xr gss_wrap 3
 124 .Sh STANDARDS
 125 .Bl -tag -width ".It RFC 2743"
 126 .It RFC 2743
 127 Generic Security Service Application Program Interface Version 2, Update 1
 128 .It RFC 2744
 129 Generic Security Service API Version 2 : C-bindings
 130 .El
 131 .Sh HISTORY
 132 The
 133 .Nm
 134 function first appeared in
 135 .Fx 7.0 .
 136 .Sh AUTHORS
 137 John Wray, Iris Associates
 138 .Sh COPYRIGHT
 139 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 140 .Pp
 141 This document and translations of it may be copied and furnished to
 142 others, and derivative works that comment on or otherwise explain it
 143 or assist in its implementation may be prepared, copied, published
 144 and distributed, in whole or in part, without restriction of any
 145 kind, provided that the above copyright notice and this paragraph are
 146 included on all such copies and derivative works.  However, this
 147 document itself may not be modified in any way, such as by removing
 148 the copyright notice or references to the Internet Society or other
 149 Internet organizations, except as needed for the purpose of
 150 developing Internet standards in which case the procedures for
 151 copyrights defined in the Internet Standards process must be
 152 followed, or as required to translate it into languages other than
 153 English.
 154 .Pp
 155 The limited permissions granted above are perpetual and will not be
 156 revoked by the Internet Society or its successors or assigns.
 157 .Pp
 158 This document and the information contained herein is provided on an
 159 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 160 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 161 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 162 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 163 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.