gssapi man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

gssapi(5)							     gssapi(5)

       gssapi - Generic Security Service Application Programming Interface

       This  introduction includes general information about the Generic Secu‐
       rity Service Application Programming Interface (GSSAPI) defined in  RFC
       2743, "Generic Security Service Application Programming Interface," and
       RFC 2744, "Generic Security Service API: C-bindings."  It also includes
       an  overview  of	 error	handling, data types, and calling conventions,
       including the following:

	      Integer types
	      String and other similar data types
	      Object identifiers (OIDs)
	      Object identifier sets (OID sets)
	      Authentication tokens
	      Major status values
	      Minor status values
	      Channel bindings
	      Optional parameters

   General Information
       The Generic Security Service Application Programming Interface (GSSAPI)
       provides	 security services to applications using peer-to-peer communi‐
       cations.	 Using GSSAPI routines, applications can perform the following

	      Enable  an  application  to  authenticate	 another application's

	      Enable an application  to	 delegate  access  rights  to  another

	      Apply  security services, such as confidentiality and integrity,
	      on a per-message basis.

       GSSAPI supports a secure connection between two communicating  applica‐
       tions.	The  application  that	establishes  the  secure connection is
       called the context initiator.  The application that accepts the	secure
       connection is the context acceptor

       There are four stages involved in using the GSSAPI:

	      The  context  initiator  acquires a credential with which it can
	      prove its identity to other processes.  Similarly,  the  context
	      acceptor acquires a credential to enable it to accept a security
	      context.	Either application may omit this  credential  acquisi‐
	      tion  and	 use  their  default credentials in subsequent stages.
	      See the "Credentials" section  in	 this  manual  page  for  more

       The  applications  use  credentials to establish their global identity.
       The global identity can be, but is  not	necessarily,  related  to  the
       local  user  name  under which the application is running.  Credentials
       can contain either of the following:

       Login Context	   The login context includes  a  principal's  network
			   credentials, as well as other account information.

       Security Context	   The	communicating  applications  establish a joint
			   security  context  by   exchanging	authentication

       The  is	a pair of GSSAPI data structures that contain information that
       is shared between  the  communicating  applications.   The  information
       describes  the  state  of  each	application.  This security context is
       required for per-message security services.

       To establish a security context, the context initiator calls  the  rou‐
       tine  to get a token.  The token is cryptographically protected, opaque
       data.  The context initiator transfers the token to the context	accep‐
       tor,  which  in	turn  passes  the  token  to the routine to decode and
       extract the shared information.

       As part of establishing the security context, the context initiator  is
       authenticated  to  the	context	 acceptor.   The context initiator can
       require the context acceptor to authenticate itself in return.

       The context initiator can delegate rights to allow the context acceptor
       to  act as its agent.  Delegation means the context initiator gives the
       context acceptor the ability  to initiate additional security  contexts
       as an agent of the context initiator.  To delegate, the context initia‐
       tor sets a flag on the routine indicating that it wants to delegate and
       sends  the  returned  token  in the normal way to the context acceptor.
       The acceptor passes this token to the routine, which generates a	 dele‐
       gated  credential.  The context acceptor can use the credential to ini‐
       tiate additional security contexts.  The applications can exchange pro‐
       tected messages and data using this context.

       The  applications can call GSSAPI routines to protect data exchanged in
       messages.  The application sends a protected  message  by  calling  the
       appropriate GSSAPI routine to do the following:

	      Apply protection.

	      Bind the message to the appropriate security context.

       The  application	 can  then  send the resulting information to the peer

       The application that receives the message passes the received data to a
       GSSAPI routine, which removes the protection and validates the data.

       GSSAPI  treats application data as arbitrary octet strings.  The GSSAPI
       per-message security services can provide either of the following:

	      Integrity and authentication of data origin.

	      Confidentiality, integrity, and authentication of data origin.

       When the applications  have  finished  communicating,  either  one  may
       instruct GSSAPI to delete the security context.

       The  Standard  GSSAPI  routines	are defined in the "Internet RFC 2743,
       Generic Security Service Application Programming Interface,"  and  "RFC
       2744,  Generic Security Service API : C-bindings."  These routines have
       the prefix

       The following sections provide an overview of the GSSAPI error handling
       and data types.

   Error Handling
       Each GSSAPI routine returns two status values, major and minor:

       major status values Major  status values are generic API routine errors
			   or calling errors defined in RFC 2744.

       minor status values Minor  status  values  indicate  mechanism-specific

       If  a  routine  has output parameters that contain pointers for storage
       allocated by the routine, the output parameters will always  contain  a
       valid  pointer even if the routine returns an error.  If no storage was
       allocated, the routine sets the pointer to NULL	and  sets  any	length
       fields  associated  with	 the  pointers (such as in the structure) to 0

       Minor status values usually contain more detailed information about the
       error.  They are not, however, portable between GSSAPI implementations.
       When designing portable applications, use major status values for  han‐
       dling  errors.	Use  minor  status values to debug applications and to
       display error and error-recovery information to users.

   GSSAPI Data Types
       This section provides an overview of the GSSAPI data  types  and	 their

       Integer Types	   The GSSAPI defines the following integer data type:

			   This integer data type is a portable data type that
			   the GSSAPI routine definitions use  for  guaranteed
			   minimum bit-counts.

       String and Similar Data types
			   Many	 of  the  GSSAPI  routines  take arguments and
			   return values that  describe	 contiguous  multiple-
			   byte	 data,	such  as  opaque  data	and  character
			   strings.  Use the data type, which is a pointer  to
			   the	buffer descriptor to pass the data between the
			   GSSAPI routines and applications.

			   The data type has the following structure:

			   The length field contains the total number of bytes
			   in  the data and the value field contains a pointer
			   to the actual data.

			   When using the data type, the GSSAPI routine	 allo‐
			   cates  storage for any data it passes to the appli‐
			   cation.  The calling application must allocate  the
			   object.   It can initialize unused objects with the
			   value To free the storage,  the  application	 calls
			   the routine.

       Object Identifier   Applications use the data type to choose a security
			   mechanism (for example Kerberos),  and  to  specify
			   name	 types.	  Select a security mechanism by using
			   the corresponding OIDs:

			   For Kerberos Version 5, specify

			   helps to ensure the portability of the application.

			   The	data  type  contains  tree-structured	values
			   defined by ISO and has the following structure:

			   The	elements  field of the structure points to the
			   first byte of an octet string containing the	 ASN.1
			   BER	encoding  of  the value of the data type.  The
			   length field contains the number of	bytes  in  the

			   The	values	returned from the GSSAPI are read-only
			   values.  The application should not try to  deallo‐
			   cate them.

       Object Identifier Sets
			   The data type represents one or more object identi‐
			   fiers.  The values of the data type are used to:

			   Report the available mechanisms supported  by  GSS‐

			   Request specific mechanisms.

			   Indicate which mechanisms a credential supports.

			   The data type has the following structure:

			   The	count field contains the number of OIDs in the
			   set.	 The elements field is a pointer to  an	 array
			   of  objects,	 each  describing  a  single OID.  The
			   application calls the routine to deallocate storage
			   associated with the values that the GSSAPI routines
			   return to the application.

       Credentials establish, or prove, the  identity  of  an  application  or
       other principal.

       The  data  type is an atomic data type that identifies a GSSAPI creden‐
       tial data structure.

       The security context is a pair of GSSAPI data structures	 that  contain
       information  shared between the communicating applications.  The infor‐
       mation describes the cryptographic state	 of  each  application.	  This
       security	 context  is required for per-message security services and is
       created by a successful authentication exchange.

       The data type contains an atomic value that identifies  one  end	 of  a
       GSSAPI security context.	 The data type is opaque to the caller.

   Authentication Tokens
       GSSAPI uses tokens to maintain the synchronization between the applica‐
       tions sharing a security context.  The  token  is  a  cryptographically
       protected  bit string generated by the security mechanism at one end of
       the GSSAPI security context for use by  the  peer  application  at  the
       other  end  of  the  security  context.	The data type is opaque to the

       The applications use the data type as tokens to GSSAPI routines.

   Major Status Values
       GSSAPI routines return GSS status codes as their function value.	 These
       codes indicate either generic API routine errors or calling errors.

       A  GSS  status code can indicate a single, fatal generic API error from
       the routine and a single calling error.	Additional status  information
       can  also  be contained in the GSS status code.	The errors are encoded
       into a 32-bit GSS status code, as follows:

       If a GSSAPI routine returns a GSS status code whose upper 16 bits  con‐
       tain  a	nonzero value,means the call has failed.  If the calling error
       field is nonzero, the context initiator's use of	 the  routine  was  in
       error.  In addition, the routine can indicate additional information by
       setting bits in the supplementary information field of the status code.
       The tables that follow describe the routine errors, calling errors, and
       supplementary information status bits and their meanings.

       The following table lists the GSSAPI routine errors and their meanings:

       GSSAPI Routine Errors

       Name			    Field   Meaning
       GSS_S_BAD_MECH		    1	    The required mecha‐
					    nism    is	 unsup‐
       GSS_S_NAME		    2	    The name passed  is
       GSS_S_NAMETYPE		    3	    The	 name passed is
       GSS_S_BAD_BINDINGS	    4	    The	 channel  bind‐
					    ings are incorrect.
       GSS_S_BAD_STATUS		    5	    A  status value was
       GSS_S_BAD_SIG		    6	    A  token   had   an
					    invalid signature.
       GSS_S_NO_CRED		    7	    No credentials were
       GSS_S_NO_CONTEXT		    8	    No context has been
       GSS_S_DEFECTIVE_TOKEN	    9	    A	  token	    was
       GSS_S_DEFECTIVE_CREDENTIAL   10	    A  credential   was
       GSS_S_CREDENTIALS_EXPIRED    11	    The referenced cre‐
					    dentials expired.
       GSS_S_CONTEXT_EXPIRED	    12	    The		context
       GSS_S_FAILURE		    13	    The routine failed.
					    Check minor	 status
       GSS_S_BAD_QOP		    14	    The quality of pro‐
					    tection   requested
					    could  not	be pro‐
       GSS_S_UNAUTHORIZED	    15	    The	 operation   is
					    forbidded  by local
					    security policy.

       The following table lists the calling error values and their meanings:

       Calling Errors

       Name			       Field   Meaning
       GSS_S_CALL_INACCESSIBLE_READ    1       Could  not  read	 a
					       required	     input
       GSS_S_CALL_INACCESSIBLE_WRITE   2       Could not  write	 a
					       required	    output
       GSS_S_BAD_STRUCTURE	       3       A   parameter   was
					       incorrectly  struc‐

       The following table lists the supplementary bits and their meanings.

       Supplementary Information Status Bits

       Name		       Bit	 Meaning

       GSS_S_CONTINUE_NEEDED   0 (LSB)	 Call  the   routine
					 again	to  complete
					 its function.
       GSS_S_DUPLICATE_TOKEN   1	 The  token  was   a
					 duplicate   of	  an
					 earlier token.
       GSS_S_OLD_TOKEN	       2	 The token's  valid‐
					 ity period expired;
					 the routine  cannot
					 verify	  that	 the
					 token	is   not   a
					 duplicate   of	  an
					 earlier token.
       GSS_S_UNSEQ_TOKEN       3	 A later  token	 has
					 been processed.

       All  symbols  equate  to complete status codes, rather than to bitfield
       values.	For example, the actual value of (value 3 in the routine error
       field) is

       The  major status code indicates that the underlying security mechanism
       has detected an error for which no  major  status  code	is  available.
       Check  the minor status code for details about the error.  See the sec‐
       tion on minor status values for more information.

       The GSSAPI provides three macros:

       Each macro takes a GSS status code  and	masks  all  but	 the  relevant
       field.	For  example,  when  you  use  the  macro on a status code, it
       returns a value.	 The value of the macro is arrived at  by  using  only
       the  routine  errors  field and zeroing the values of the calling error
       and the supplementary information fields.

       An additional macro, lets you determine whether the status  code	 indi‐
       cated a calling or routine error.  If the status code indicated a call‐
       ing or routine error, the macro returns a nonzero value.	 If no calling
       or routine error is indicated, the macro returns a 0 (zero).

       NOTE: At times, a GSSAPI routine that is unable to access data can gen‐
       erate a platform-specific signal, instead  of  returning	 a  or	status

   Minor Status Values
       The  GSSAPI routines return a minor_status parameter to indicate errors
       from the underlying security mechanism.	The parameter  can  contain  a
       single error, indicated by an datatype value.

       Names  identify	principals.  The GSSAPI authenticates the relationship
       between a name and the principal claiming the name.

       Names are represented in two forms:

	      A printable form, for presentation to an application.

	      An internal, canonical form that is used	by  the	 APIs  and  is
	      opaque to applications.

       The  and	 routines convert names between their printable form and their

       The routine compares internal form names.

   Channel Bindings
       You can define and use channel bindings to associate the security  con‐
       text with the communications channel that carries the context.  Channel
       bindings are communicated to the GSSAPI by using the  following	struc‐

       Use  the	 and fields to initiate the type of addresses contained in the
       and buffers.  The following table lists the  address  types  and	 their

       Address Type			     addrtype Value
       Unspecified			     GSS_C_AF_UNSPEC
       Host-local			     GSS_C_AF_LOCAL
       DARPA Internet			     GSS_C_AF_INET
       ARPAnet IMP			     GSS_C_AF_IMPLINK
       pup protocols (for example, BSP)	     GSS_C_AF_PUP
       MIT CHAOS protocol		     GSS_C_AF_CHAOS
       XEROX NS				     GSS_C_AF_NS
       nbs				     GSS_C_AF_NBS
       ECMA				     GSS_C_AF_ECMA
       datakit protocols		     GSS_C_AF_DATAKIT
       CCITT protocols (for example, X.25)   GSS_C_AF_CCITT
       IBM SNA				     GSS_C_AF_SNA
       Digital DECnet			     GSS_C_AF_DECnet
       Direct data link interface	     GSS_C_AF_DLI
       LAT				     GSS_C_AF_LAT
       NSC Hyperchannel			     GSS_C_AF_HYLINK
       AppleTalk			     GSS_C_AF_APPLETALK
       BISYNC 2780/3780			     GSS_C_AF_BSC
       Distributed system services	     GSS_C_AF_DSS
       OSI TP4				     GSS_C_AF_OSI
       X25				     GSS_C_AF_X25
       No address specified		     GSS_C_AF_NULLADDR

       The  tags specify address families rather than addressing formats.  For
       address families that contain several alternative  address  forms,  the
       and the fields should contain sufficient information to determine which
       address form is used.  Format the bytes that contain the	 addresses  in
       the order in which the bytes are transmitted across the network.

       The  GSSAPI creates an octet string by concatenating all the fields and
       The security mechanism signs the octet string and binds	the  signature
       to  the	token generated by the routine.	 The context acceptor presents
       the same bindings to the routine, which	evaluates  the	signature  and
       compares	 it  to the signature in the token.  If the signatures differ,
       the routine returns a error, and the context is not established.

       Some security mechanisms check that the field of the  channel  bindings
       presented  to  the  routine contains the correct network address of the
       host system.  Therefore portable applications  should  use  either  the
       correct	address	 type  and  value  or the for the address field.  Some
       security mechanisms include the	channel	 binding  data	in  the	 token
       instead	of a signature, so portable applications should not use confi‐
       dential data as channel-binding components.  The GSSAPI does not verify
       the  address  or	 include  the  plain  text bindings information in the

   Optional Parameters
       In routine descriptions, optional parameters allow the  application  to
       request default behaviors by passing a default value for the parameter.
       The following conventions are used for optional parameters:

       Convention		Value Default		    Explanation

       gss_buffer_t types	GSS_C_NO_BUFFER		    For an input param‐
							    eter,  indicates no
							    data  is  supplied.
							    For	   an	 output
							    parameter,	  indi‐
							    cates    that   the
							    returned   is   not
							    required   by   the
       Integer types (input)				    Refer to the refer‐
							    ence   pages    for
							    default values.
       Integer types (output)	NULL			    Indicates  that the
							    application	   does
							    not	  require   the
       Pointer types (output)	NULL			    Indicates that  the
							    application	   does
							    not	  require   the
       OIDs			GSS_C_NULL_OID		    Indicates	    the
							    default choice  for
							    name  type or secu‐
							    rity mechanism.
       OID sets			GSS_C_NULL_OID_SET	    Indicates	    the
							    default    set   of
							    security mechanisms
       Credentials		GSS_C_NO_CREDENTIAL	    Indicates that  the
							    application	 should
							    use	  the	default
							    credential handle.
       Channel bindings		GSS_C_NO_CHANNEL_BINDINGS   Indicates  that  no
							    channel    bindings
							    are used.

       gss_accept_sec_context(3),   gss_compare_name(3),  gss_display_name(3),
       gss_import_name(3),   gss_init_sec_context(3),	gss_release_buffer(3),
       gss_release_oid_set(3), libgss(4).

       RFC 2743, RFC 2744.

       The  manpages  for DCE-GSSAPI are included with the DCE-CoreTools prod‐
       uct.  To see those manpages add to


List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net