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