Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GSS_ACQUIRE_CRED(3)	      Programmer's Manual	   GSS_ACQUIRE_CRED(3)

NAME
     gss_acquire_cred -- Obtain	a GSS-API credential handle for	pre-existing
     credentials

SYNOPSIS
     #include <gssapi/gssapi.h>

     OM_uint32
     gss_acquire_cred(OM_uint32	*minor_status, const gss_name_t	desired_name,
	 OM_uint32 time_req, const gss_OID_set desired_mechs,
	 gss_cred_usage_t cred_usage, gss_cred_id_t *output_cred_handle,
	 gss_OID_set *actual_mechs, OM_uint32 *time_rec);

DESCRIPTION
     Allows an application to acquire a	handle for a pre-existing credential
     by	name.  GSS-API implementations must impose a local access-control pol-
     icy on callers of this routine to prevent unauthorized callers from ac-
     quiring credentials to which they are not entitled.  This routine is not
     intended to provide a "login to the network" function, as such a function
     would involve the creation	of new credentials rather than merely acquir-
     ing a handle to existing credentials.  Such functions, if required,
     should be defined in implementation-specific extensions to	the API.

     If	desired_name is	GSS_C_NO_NAME, the call	is interpreted as a request
     for a credential handle that will invoke default behavior when passed to
     gss_init_sec_context() (if	cred_usage is GSS_C_INITIATE or	GSS_C_BOTH) or
     gss_accept_sec_context() (if cred_usage is	GSS_C_ACCEPT or	GSS_C_BOTH ).

     Mechanisms	should honor the desired_mechs parameter, and return a creden-
     tial that is suitable to use only with the	requested mechanisms.  An ex-
     ception to	this is	the case where one underlying credential element can
     be	shared by multiple mechanisms; in this case it is permissible for an
     implementation to indicate	all mechanisms with which the credential ele-
     ment may be used.	If desired_mechs is an empty set, behavior is unde-
     fined.

     This routine is expected to be used primarily by context acceptors, since
     implementations are likely	to provide mechanism-specific ways of obtain-
     ing GSS-API initiator credentials from the	system login process.  Some
     implementations may therefore not support the acquisition of
     GSS_C_INITIATE or GSS_C_BOTH credentials via gss_acquire_cred() for any
     name other	than GSS_C_NO_NAME, or a name produced by applying either
     gss_inquire_cred()	to a valid credential, or gss_inquire_context()	to an
     active context.

     If	credential acquisition is time-consuming for a mechanism, the mecha-
     nism may choose to	delay the actual acquisition until the credential is
     required (e.g. by gss_init_sec_context() or gss_accept_sec_context().)
     Such mechanism-specific implementation decisions should be	invisible to
     the calling application; thus a call of gss_inquire_cred()	immediately
     following the call	of gss_acquire_cred() must return valid	credential
     data, and may therefore incur the overhead	of a deferred credential ac-
     quisition.

PARAMETERS
     desired_name	 Name of principal whose credential should be ac-
			 quired.

     time_req		 Number	of seconds that	credentials should remain
			 valid.	 Specify GSS_C_INDEFINITE to request that the
			 credentials have the maximum permitted	lifetime.

     desired_mechs	 Set of	underlying security mechanisms that may	be
			 used.	GSS_C_NO_OID_SET may be	used to	obtain an im-
			 plementation-specific default.

     cred_usage

			 GSS_C_BOTH	 Credentials may be used either	to
					 initiate or accept security contexts.

			 GSS_C_INITIATE	 Credentials will only be used to ini-
					 tiate security	contexts.

			 GSS_C_ACCEPT	 Credentials will only be used to ac-
					 cept security contexts.

     output_cred_handle	 The returned credential handle.  Resources associated
			 with this credential handle must be released by the
			 application after use with a call to
			 gss_release_cred().

     actual_mechs	 The set of mechanisms for which the credential	is
			 valid.	 Storage associated with the returned OID-set
			 must be released by the application after use with a
			 call to gss_release_oid_set().	 Specify NULL if not
			 required.

     time_rec		 Actual	number of seconds for which the	returned cre-
			 dentials will remain valid.  If the implementation
			 does not support expiration of	credentials, the value
			 GSS_C_INDEFINITE will be returned.  Specify NULL if
			 not required.

     minor_status	 Mechanism specific status code.

RETURN VALUES
     GSS_S_COMPLETE		Successful completion.

     GSS_S_BAD_MECH		Unavailable mechanism requested.

     GSS_S_BAD_NAMETYPE		Type contained within desired_name parameter
				is not supported.

     GSS_S_BAD_NAME		Value supplied for desired_name	parameter is
				ill formed.

     GSS_S_CREDENTIALS_EXPIRED	The credentials	could not be acquired because
				they have expired.

     GSS_S_NO_CRED		No credentials were found for the specified
				name.

SEE ALSO
     gss_accept_sec_context(3),	gss_init_sec_context(3),
     gss_inquire_context(3), gss_inquire_cred(3), gss_release_cred(3),
     gss_release_oid_set(3)

STANDARDS
     RFC 2743  Generic Security	Service	Application Program Interface Version
	       2, Update 1

     RFC 2744  Generic Security	Service	API Version 2 :	C-bindings

HISTORY
     The gss_acquire_cred function first appeared in FreeBSD 7.0.

AUTHORS
     John Wray,	Iris Associates

COPYRIGHT
     Copyright (C) The Internet	Society	(2000).	 All Rights Reserved.

     This document and translations of it may be copied	and furnished to oth-
     ers, and derivative works that comment on or otherwise explain it or as-
     sist in its implementation	may be prepared, copied, published and dis-
     tributed, in whole	or in part, without restriction	of any kind, provided
     that the above copyright notice and this paragraph	are included on	all
     such copies and derivative	works.	However, this document itself may not
     be	modified in any	way, such as by	removing the copyright notice or ref-
     erences to	the Internet Society or	other Internet organizations, except
     as	needed for the purpose of developing Internet standards	in which case
     the procedures for	copyrights defined in the Internet Standards process
     must be followed, or as required to translate it into languages other
     than English.

     The limited permissions granted above are perpetual and will not be re-
     voked by the Internet Society or its successors or	assigns.

     This document and the information contained herein	is provided on an "AS
     IS" basis and THE INTERNET	SOCIETY	AND THE	INTERNET ENGINEERING TASK
     FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR	IMPLIED, INCLUDING BUT NOT
     LIMITED TO	ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
     INFRINGE ANY RIGHTS OR ANY	IMPLIED	WARRANTIES OF MERCHANTABILITY OR FIT-
     NESS FOR A	PARTICULAR PURPOSE.

BSD			       January 26, 2010				   BSD

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | RETURN VALUES | SEE ALSO | STANDARDS | HISTORY | AUTHORS | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gss_acquire_cred&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help