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