lib/libgssapi/gss_add_cred.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_ADD_CRED 3 PRM
  32 .Os
  33 .Sh NAME
  34 .Nm gss_add_cred
  35 .Nd Construct credentials incrementally
  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_add_cred
  42 .Fa "OM_uint32 *minor_status"
  43 .Fa "const gss_cred_id_t input_cred_handle"
  44 .Fa "const gss_name_t desired_name"
  45 .Fa "const gss_OID desired_mech"
  46 .Fa "gss_cred_usage_t cred_usage"
  47 .Fa "OM_uint32 initiator_time_req"
  48 .Fa "OM_uint32 acceptor_time_req"
  49 .Fa "gss_cred_id_t *output_cred_handle"
  50 .Fa "gss_OID_set *actual_mechs"
  51 .Fa "OM_uint32 *initiator_time_rec"
  52 .Fa "OM_uint32 *acceptor_time_rec"
  53 .Fc
  54 .Sh DESCRIPTION
  55 Adds a credential-element to a credential.
  56 The credential-element is identified by the name of the principal to
  57 which it refers.
  58 GSS-API implementations must impose a local access-control policy on
  59 callers of this routine to prevent unauthorized callers from acquiring
  60 credential-elements to which they are not entitled.
  61 This routine is not intended to provide a "login to the network"
  62 function,
  63 as such a function would involve the creation of new
  64 mechanism-specific authentication data,
  65 rather than merely acquiring a GSS-API handle to existing data.
  66 Such functions,
  67 if required,
  68 should be defined in implementation-specific extensions to the API.
  69 .Pp
  70 If
  71 .Fa desired_name
  72 is
  73 .Dv GSS_C_NO_NAME ,
  74 the call is interpreted as a request to add a credential element that
  75 will invoke default behavior when passed to
  76 .Fn gss_init_sec_context
  77 (if cred_usage is
  78 .Dv GSS_C_INITIATE
  79 or
  80 .Dv GSS_C_BOTH )
  81 or
  82 .Fn gss_accept_sec_context
  83 (if
  84 .Fa cred_usage
  85 is
  86 .Dv GSS_C_ACCEPT
  87 or
  88 .Dv GSS_C_BOTH ).
  89 .Pp
  90 This routine is expected to be used primarily by context acceptors,
  91 since implementations are likely to provide mechanism-specific ways of
  92 obtaining GSS-API initiator credentials from the system login process.
  93 Some implementations may therefore not support the acquisition of
  94 .Dv GSS_C_INITIATE
  95 or
  96 .Dv GSS_C_BOTH
  97 credentials via
  98 .Fn gss_acquire_cred
  99 for any name other than
 100 .Dv GSS_C_NO_NAME ,
 101 or a name produced by applying either
 102 .Fn gss_inquire_cred
 103 to a valid credential,
 104 or
 105 .Fn gss_inquire_context
 106 to an active context.
 107 .Pp
 108 If credential acquisition is time-consuming for a mechanism,
 109 the mechanism may choose to delay the actual acquisition until the
 110 credential is required (e.g. by
 111 .Fn gss_init_sec_context
 112 or
 113 .Fn gss_accept_sec_context ).
 114 Such mechanism-specific implementation decisions should be invisible
 115 to the calling application;
 116 thus a call of
 117 .Fn gss_inquire_cred
 118 immediately following the call of
 119 .Fn gss_add_cred
 120 must return valid credential data,
 121 and may therefore incur the overhead of a deferred credential acquisition.
 122 .Pp
 123 This routine can be used to either compose a new credential containing
 124 all credential-elements of the original in addition to the
 125 newly-acquire credential-element,
 126 or to add the new credential-element to an existing credential.
 127 If
 128 .Dv NULL
 129 is specified for the
 130 .Fa output_cred_handle
 131 parameter argument,
 132 the new credential-element will be added to the credential identified
 133 by
 134 .Fa input_cred_handle ;
 135 if a valid pointer is specified for the
 136 .Fa output_cred_handle
 137 parameter,
 138 a new credential handle will be created.
 139 .Pp
 140 If
 141 .Dv GSS_C_NO_CREDENTIAL
 142 is specified as the
 143 .Fa input_cred_handle ,
 144 .Fn gss_add_cred
 145 will compose a credential (and set the
 146 .Fa output_cred_handle
 147 parameter accordingly) based on default behavior.
 148 That is, the call will have the same effect as if the application had
 149 first made a call to
 150 .Fn gss_acquire_cred ,
 151 specifying the same usage and passing
 152 .Dv GSS_C_NO_NAME
 153 as the
 154 .Fa desired_name
 155 parameter to obtain an explicit credential handle embodying default
 156 behavior,
 157 passed this credential handle to
 158 .Fn gss_add_cred ,
 159 and finally called
 160 .Fn gss_release_cred
 161 on the first credential handle.
 162 .Pp
 163 If
 164 .Dv GSS_C_NO_CREDENTIAL
 165 is specified as the
 166 .Fa input_cred_handle
 167 parameter,
 168 a non-
 169 .Dv NULL
 170 .Fa output_cred_handle
 171 must be supplied.
 172 .Sh PARAMETERS
 173 .Bl -tag
 174 .It minor_status
 175 Mechanism specific status code.
 176 .It input_cred_handle
 177 The credential to which a credential-element will be added.
 178 If
 179 .Dv GSS_C_NO_CREDENTIAL
 180 is specified, the routine will compose the new credential based on
 181 default behavior (see description above).
 182 Note that, while the credential-handle is not modified by
 183 .Fn gss_add_cred ,
 184 the underlying credential will be modified if
 185 .Fa output_credential_handle
 186 is
 187 .Dv NULL .
 188 .It desired_name
 189 Name of principal whose credential should be acquired.
 190 .It desired_mech
 191 Underlying security mechanism with which the credential may be used.
 192 .It cred_usage
 193 .Bl -tag -width "GSS_C_INITIATE"
 194 .It GSS_C_BOTH
 195 Credential may be used either to initiate or accept security
 196 contexts.
 197 .It GSS_C_INITIATE
 198 Credential will only be used to initiate security contexts.
 199 .It GSS_C_ACCEPT
 200 Credential will only be used to accept security contexts.
 201 .El
 202 .It initiator_time_req
 203 Number of seconds that the credential should remain valid for
 204 initiating security contexts.
 205 This argument is ignored if the composed credentials are of type
 206 .Dv GSS_C_ACCEPT .
 207 Specify
 208 .Dv GSS_C_INDEFINITE
 209 to request that the credentials have the maximum permitted initiator lifetime.
 210 .It acceptor_time_req
 211 Number of seconds that the credential should remain valid for
 212 accepting security contexts.
 213 This argument is ignored if the composed credentials are of type
 214 .Dv GSS_C_INITIATE .
 215 Specify
 216 .Dv GSS_C_INDEFINITE
 217 to request that the credentials have the maximum permitted initiator lifetime.
 218 .It output_cred_handle
 219 The returned credential handle,
 220 containing
 221 the new credential-element and all the credential-elements from
 222 .Fa input_cred_handle .
 223 If a valid pointer to a
 224 .Fa gss_cred_id_t
 225 is supplied for this parameter,
 226 .Fn gss_add_cred
 227 creates a new credential handle containing all credential-elements
 228 from the
 229 .Fa input_cred_handle
 230 and the newly acquired credential-element;
 231 if
 232 .Dv NULL
 233 is specified for this parameter,
 234 the newly acquired credential-element will be added to the credential
 235 identified by
 236 .Fa input_cred_handle .
 237 .Pp
 238 The resources associated with any credential handle returned via this
 239 parameter must be released by the application after use with a call to
 240 .Fn gss_release_cred .
 241 .It actual_mechs
 242 The complete set of mechanisms for which the new credential is valid.
 243 Storage for the returned OID-set must be freed by the application
 244 after use with a call to
 245 .Fn gss_release_oid_set .
 246 Specify
 247 .Dv NULL if not required.
 248 .It initiator_time_rec
 249 Actual number of seconds for which the returned credentials will
 250 remain valid for initiating contexts using the specified mechanism.
 251 If the implementation or mechanism does not support expiration of
 252 credentials,
 253 the value
 254 .Dv GSS_C_INDEFINITE
 255 will be returned.
 256 Specify
 257 .Dv NULL
 258 if not required.
 259 .It acceptor_time_rec
 260 Actual number of seconds for which the returned credentials will
 261 remain valid for accepting security contexts using the specified
 262 mechanism.
 263 If the implementation or mechanism does not support expiration of
 264 credentials,
 265 the value
 266 .Dv GSS_C_INDEFINITE
 267 will be returned.
 268 Specify
 269 .Dv NULL
 270 if not required.
 271 .El
 272 .Sh RETURN VALUES
 273 .Bl -tag
 274 .It GSS_S_COMPLETE
 275 Successful completion.
 276 .It GSS_S_BAD_MECH
 277 Unavailable mechanism requested.
 278 .It GSS_S_BAD_NAMETYPE
 279 Type contained within desired_name parameter is not supported
 280 .It GSS_S_BAD_NAME
 281 Value supplied for desired_name parameter is ill-formed.
 282 .It GSS_S_DUPLICATE_ELEMENT
 283 The credential already contains an element for the requested mechanism
 284 with overlapping usage and validity period.
 285 .It GSS_S_CREDENTIALS_EXPIRED
 286 The required credentials could not be added because they have expired.
 287 .It GSS_S_NO_CRED
 288 No credentials were found for the specified name.
 289 .El
 290 .Sh SEE ALSO
 291 .Xr gss_init_sec_context 3 ,
 292 .Xr gss_accept_sec_context 3 ,
 293 .Xr gss_acquire_cred 3 ,
 294 .Xr gss_inquire_cred 3 ,
 295 .Xr gss_inquire_context 3 ,
 296 .Xr gss_release_cred 3 ,
 297 .Xr gss_release_oid_set 3
 298 .Sh STANDARDS
 299 .Bl -tag
 300 .It RFC 2743
 301 Generic Security Service Application Program Interface Version 2, Update 1
 302 .It RFC 2744
 303 Generic Security Service API Version 2 : C-bindings
 304 .El
 305 .Sh HISTORY
 306 The
 307 .Nm
 308 function first appeared in
 309 .Fx 7.0 .
 310 .Sh AUTHORS
 311 John Wray, Iris Associates
 312 .Sh COPYRIGHT
 313 Copyright (C) The Internet Society (2000).  All Rights Reserved.
 314 .Pp
 315 This document and translations of it may be copied and furnished to
 316 others, and derivative works that comment on or otherwise explain it
 317 or assist in its implementation may be prepared, copied, published
 318 and distributed, in whole or in part, without restriction of any
 319 kind, provided that the above copyright notice and this paragraph are
 320 included on all such copies and derivative works.  However, this
 321 document itself may not be modified in any way, such as by removing
 322 the copyright notice or references to the Internet Society or other
 323 Internet organizations, except as needed for the purpose of
 324 developing Internet standards in which case the procedures for
 325 copyrights defined in the Internet Standards process must be
 326 followed, or as required to translate it into languages other than
 327 English.
 328 .Pp
 329 The limited permissions granted above are perpetual and will not be
 330 revoked by the Internet Society or its successors or assigns.
 331 .Pp
 332 This document and the information contained herein is provided on an
 333 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 334 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 335 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 336 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 337 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.