tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 2744

 
 
 

Generic Security Service API Version 2 : C-bindings

Part 3 of 4, p. 50 to 75
Prev RFC Part       Next RFC Part

 


prevText      Top       Page 50 
5.14. gss_export_sec_context

   OM_uint32 gss_export_sec_context (
     OM_uint32    *minor_status,
     gss_ctx_id_t *context_handle,
     gss_buffer_t interprocess_token)

   Purpose:

   Provided to support the sharing of work between multiple processes.
   This routine will typically be used by the context-acceptor, in an
   application where a single process receives incoming connection
   requests and accepts security contexts over them, then passes the
   established context to one or more other processes for message
   exchange. gss_export_sec_context() deactivates the security context
   for the calling process and creates an interprocess token which, when
   passed to gss_import_sec_context in another process, will re-activate
   the context in the second process. Only a single instantiation of a
   given context may be active at any one time; a subsequent attempt by
   a context exporter to access the exported security context will fail.

   The implementation may constrain the set of processes by which the
   interprocess token may be imported, either as a function of local
   security policy, or as a result of implementation decisions.  For
   example, some implementations may constrain contexts to be passed
   only between processes that run under the same account, or which are
   part of the same process group.

   The interprocess token may contain security-sensitive information
   (for example cryptographic keys).  While mechanisms are encouraged to
   either avoid placing such sensitive information within interprocess
   tokens, or to encrypt the token before returning it to the
   application, in a typical object-library GSS-API implementation this
   may not be possible. Thus the application must take care to protect
   the interprocess token, and ensure that any process to which the
   token is transferred is trustworthy.

   If creation of the interprocess token is successful, the
   implementation shall deallocate all process-wide resources associated
   with the security context, and set the context_handle to
   GSS_C_NO_CONTEXT.  In the event of an error that makes it impossible
   to complete the export of the security context, the implementation
   must not return an interprocess token, and should strive to leave the
   security context referenced by the context_handle parameter
   untouched.  If this is impossible, it is permissible for the
   implementation to delete the security context, providing it also sets
   the context_handle parameter to GSS_C_NO_CONTEXT.

Top       Page 51 
   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   context_handle    gss_ctx_id_t, modify
                     context handle identifying the context to
                     transfer.

   interprocess_token   buffer, opaque, modify
                        token to be transferred to target process.
                        Storage associated with this token must be
                        freed by the application after use with a
                        call to gss_release_buffer().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_CONTEXT_EXPIRED The context has expired

   GSS_S_NO_CONTEXT  The context was invalid

   GSS_S_UNAVAILABLE The operation is not supported.

5.15. gss_get_mic

   OM_uint32 gss_get_mic (
     OM_uint32          *minor_status,
     const gss_ctx_id_t context_handle,
     gss_qop_t             qop_req,
     const gss_buffer_t message_buffer,
     gss_buffer_t       msg_token)

   Purpose:

   Generates a cryptographic MIC for the supplied message, and places
   the MIC in a token for transfer to the peer application. The qop_req
   parameter allows a choice between several cryptographic algorithms,
   if supported by the chosen mechanism.

   Since some application-level protocols may wish to use tokens emitted
   by gss_wrap() to provide "secure framing", implementations must
   support derivation of MICs from zero-length messages.

Top       Page 52 
   Parameters:

   minor_status      Integer, modify
                     Implementation specific status code.

   context_handle    gss_ctx_id_t, read
                     identifies the context on which the message
                     will be sent

   qop_req           gss_qop_t, read, optional
                     Specifies requested quality of protection.
                     Callers are encouraged, on portability grounds,
                     to accept the default quality of protection
                     offered by the chosen mechanism, which may be
                     requested by specifying GSS_C_QOP_DEFAULT for
                     this parameter.  If an unsupported protection
                     strength is requested, gss_get_mic will return a
                     major_status of GSS_S_BAD_QOP.

   message_buffer    buffer, opaque, read
                     message to be protected

   msg_token         buffer, opaque, modify
                     buffer to receive token.  The application must
                     free storage associated with this buffer after
                     use with a call to gss_release_buffer().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_CONTEXT_EXPIRED The context has already expired

   GSS_S_NO_CONTEXT  The context_handle parameter did not identify
                     a valid context

   GSS_S_BAD_QOP     The specified QOP is not supported by the
                     mechanism.

5.16. gss_import_name

   OM_uint32 gss_import_name (
     OM_uint32          *minor_status,
     const gss_buffer_t input_name_buffer,
     const gss_OID      input_name_type,
     gss_name_t         *output_name)

Top       Page 53 
   Purpose:

   Convert a contiguous string name to internal form.  In general, the
   internal name returned (via the <output_name> parameter) will not be
   an MN; the exception to this is if the <input_name_type> indicates
   that the contiguous string provided via the <input_name_buffer>
   parameter is of type GSS_C_NT_EXPORT_NAME, in which case the returned
   internal name will be an MN for the mechanism that exported the name.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   input_name_buffer  buffer, octet-string, read
                     buffer containing contiguous string name to convert

   input_name_type   Object ID, read, optional
                     Object ID specifying type of printable
                     name.  Applications may specify either
                     GSS_C_NO_OID to use a mechanism-specific
                     default printable syntax, or an OID recognized
                     by the GSS-API implementation to name a
                     specific namespace.

   output_name       gss_name_t, modify
                     returned name in internal form.  Storage
                     associated with this name must be freed
                     by the application after use with a call
                     to gss_release_name().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_BAD_NAMETYPE The input_name_type was unrecognized

   GSS_S_BAD_NAME    The input_name parameter could not be interpreted
                     as a name of the specified type

   GSS_S_BAD_MECH    The input name-type was GSS_C_NT_EXPORT_NAME,
                     but the mechanism contained within the
                     input-name is not supported

Top       Page 54 
5.17. gss_import_sec_context

   OM_uint32 gss_import_sec_context (
     OM_uint32          *minor_status,
     const gss_buffer_t interprocess_token,
     gss_ctx_id_t       *context_handle)

   Purpose:

   Allows a process to import a security context established by another
   process.  A given interprocess token may be imported only once.  See
   gss_export_sec_context.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   interprocess_token  buffer, opaque, modify
                       token received from exporting process

   context_handle    gss_ctx_id_t, modify
                     context handle of newly reactivated context.
                     Resources associated with this context handle
                     must be released by the application after use
                     with a call to gss_delete_sec_context().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion.

   GSS_S_NO_CONTEXT  The token did not contain a valid context
   reference.

   GSS_S_DEFECTIVE_TOKEN The token was invalid.

   GSS_S_UNAVAILABLE The operation is unavailable.

   GSS_S_UNAUTHORIZED Local policy prevents the import of this context
                      by the current process.

5.18. gss_indicate_mechs

   OM_uint32 gss_indicate_mechs (
     OM_uint32   *minor_status,
     gss_OID_set *mech_set)

Top       Page 55 
   Purpose:

   Allows an application to determine which underlying security
   mechanisms are available.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code.

   mech_set          set of Object IDs, modify
                     set of implementation-supported mechanisms.
                     The returned gss_OID_set value will be a
                     dynamically-allocated OID set, that should
                     be released by the caller after use with a
                     call to gss_release_oid_set().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

5.19. gss_init_sec_context

   OM_uint32 gss_init_sec_context (
     OM_uint32                    *minor_status,
     const gss_cred_id_t          initiator_cred_handle,
     gss_ctx_id_t                 *context_handle,\
     const gss_name_t             target_name,
     const gss_OID                mech_type,
     OM_uint32                    req_flags,
     OM_uint32                    time_req,
     const gss_channel_bindings_t input_chan_bindings,
     const gss_buffer_t           input_token
     gss_OID                      *actual_mech_type,
     gss_buffer_t                 output_token,
     OM_uint32                    *ret_flags,
     OM_uint32                    *time_rec )

   Purpose:

   Initiates the establishment of a security context between the
   application and a remote peer.  Initially, the input_token parameter
   should be specified either as GSS_C_NO_BUFFER, or as a pointer to a
   gss_buffer_desc object whose length field contains the value zero.
   The routine may return a output_token which should be transferred to
   the peer application, where the peer application will present it to
   gss_accept_sec_context.  If no token need be sent,
   gss_init_sec_context will indicate this by setting the length field

Top       Page 56 
   of the output_token argument to zero. To complete the context
   establishment, one or more reply tokens may be required from the peer
   application; if so, gss_init_sec_context will return a status
   containing the supplementary information bit GSS_S_CONTINUE_NEEDED.
   In this case, gss_init_sec_context should be called again when the
   reply token is received from the peer application, passing the reply
   token to gss_init_sec_context via the input_token parameters.

   Portable applications should be constructed to use the token length
   and return status to determine whether a token needs to be sent or
   waited for.  Thus a typical portable caller should always invoke
   gss_init_sec_context within a loop:

   int context_established = 0;
   gss_ctx_id_t context_hdl = GSS_C_NO_CONTEXT;
          ...
   input_token->length = 0;

   while (!context_established) {
     maj_stat = gss_init_sec_context(&min_stat,
                                     cred_hdl,
                                     &context_hdl,
                                     target_name,
                                     desired_mech,
                                     desired_services,
                                     desired_time,
                                     input_bindings,
                                     input_token,
                                     &actual_mech,
                                     output_token,
                                     &actual_services,
                                     &actual_time);
     if (GSS_ERROR(maj_stat)) {
       report_error(maj_stat, min_stat);
     };

     if (output_token->length != 0) {
       send_token_to_peer(output_token);
       gss_release_buffer(&min_stat, output_token)
     };
     if (GSS_ERROR(maj_stat)) {

       if (context_hdl != GSS_C_NO_CONTEXT)
         gss_delete_sec_context(&min_stat,
                                &context_hdl,
                                GSS_C_NO_BUFFER);
       break;
     };

Top       Page 57 
     if (maj_stat & GSS_S_CONTINUE_NEEDED) {
       receive_token_from_peer(input_token);
     } else {
       context_established = 1;
     };
   };

   Whenever the routine returns a major status that includes the value
   GSS_S_CONTINUE_NEEDED, the context is not fully established and the
   following restrictions apply to the output parameters:

      The value returned via the time_rec parameter is undefined Unless
      the accompanying ret_flags parameter contains the bit
      GSS_C_PROT_READY_FLAG, indicating that per-message services may be
      applied in advance of a successful completion status, the value
      returned via the actual_mech_type parameter is undefined until the
      routine returns a major status value of GSS_S_COMPLETE.

      The values of the GSS_C_DELEG_FLAG, GSS_C_MUTUAL_FLAG,
      GSS_C_REPLAY_FLAG, GSS_C_SEQUENCE_FLAG, GSS_C_CONF_FLAG,
      GSS_C_INTEG_FLAG and GSS_C_ANON_FLAG bits returned via the
      ret_flags parameter should contain the values that the
      implementation expects would be valid if context establishment
      were to succeed.  In particular, if the application has requested
      a service such as delegation or anonymous authentication via the
      req_flags argument, and such a service is unavailable from the
      underlying mechanism, gss_init_sec_context should generate a token
      that will not provide the service, and indicate via the ret_flags
      argument that the service will not be supported.  The application
      may choose to abort the context establishment by calling
      gss_delete_sec_context (if it cannot continue in the absence of
      the service), or it may choose to transmit the token and continue
      context establishment (if the service was merely desired but not
      mandatory).

      The values of the GSS_C_PROT_READY_FLAG and GSS_C_TRANS_FLAG bits
      within ret_flags should indicate the actual state at the time
      gss_init_sec_context returns, whether or not the context is fully
      established.

      GSS-API implementations that support per-message protection are
      encouraged to set the GSS_C_PROT_READY_FLAG in the final ret_flags
      returned to a caller (i.e. when accompanied by a GSS_S_COMPLETE
      status code).  However, applications should not rely on this
      behavior as the flag was not defined in Version 1 of the GSS-API.
      Instead, applications should determine what per-message services
      are available after a successful context establishment according
      to the GSS_C_INTEG_FLAG and GSS_C_CONF_FLAG values.

Top       Page 58 
      All other bits within the ret_flags argument should be set to
      zero.

   If the initial call of gss_init_sec_context() fails, the
   implementation should not create a context object, and should leave
   the value of the context_handle parameter set to GSS_C_NO_CONTEXT to
   indicate this.  In the event of a failure on a subsequent call, the
   implementation is permitted to delete the "half-built" security
   context (in which case it should set the context_handle parameter to
   GSS_C_NO_CONTEXT), but the preferred behavior is to leave the
   security context untouched for the application to delete (using
   gss_delete_sec_context).

   During context establishment, the informational status bits
   GSS_S_OLD_TOKEN and GSS_S_DUPLICATE_TOKEN indicate fatal errors, and
   GSS-API mechanisms should always return them in association with a
   routine error of GSS_S_FAILURE.  This requirement for pairing did not
   exist in version 1 of the GSS-API specification, so applications that
   wish to run over version 1 implementations must special-case these
   codes.

   Parameters:

   minor_status      Integer,  modify
                     Mechanism specific status code.

   initiator_cred_handle  gss_cred_id_t, read, optional
                          handle for credentials claimed.  Supply
                          GSS_C_NO_CREDENTIAL to act as a default
                          initiator principal.  If no default
                          initiator is defined, the function will
                          return GSS_S_NO_CRED.

   context_handle    gss_ctx_id_t, read/modify
                     context handle for new context.  Supply
                     GSS_C_NO_CONTEXT for first call; use value
                     returned by first call in continuation calls.
                     Resources associated with this context-handle
                     must be released by the application after use
                     with a call to gss_delete_sec_context().

   target_name       gss_name_t, read
                     Name of target

   mech_type         OID, read, optional
                     Object ID of desired mechanism. Supply
                     GSS_C_NO_OID to obtain an implementation
                     specific default

Top       Page 59 
   req_flags         bit-mask, read
                     Contains various independent flags, each of
                     which requests that the context support a
                     specific service option.  Symbolic
                     names are provided for each flag, and the
                     symbolic names corresponding to the required
                     flags should be logically-ORed
                     together to form the bit-mask value.  The
                     flags are:

                     GSS_C_DELEG_FLAG
                       True - Delegate credentials to remote peer
                       False - Don't delegate

                     GSS_C_MUTUAL_FLAG
                       True - Request that remote peer
                              authenticate itself
                       False - Authenticate self to remote peer
                               only

                     GSS_C_REPLAY_FLAG
                       True - Enable replay detection for
                              messages protected with gss_wrap
                              or gss_get_mic
                       False - Don't attempt to detect
                               replayed messages

                     GSS_C_SEQUENCE_FLAG
                       True - Enable detection of out-of-sequence
                              protected messages
                       False - Don't attempt to detect
                               out-of-sequence messages

                     GSS_C_CONF_FLAG
                       True - Request that confidentiality service
                              be made available (via gss_wrap)
                       False - No per-message confidentiality service
                               is required.

                     GSS_C_INTEG_FLAG
                       True - Request that integrity service be
                              made available (via gss_wrap or
                              gss_get_mic)
                       False - No per-message integrity service
                               is required.

Top       Page 60 
                     GSS_C_ANON_FLAG
                       True - Do not reveal the initiator's
                              identity to the acceptor.
                       False - Authenticate normally.

   time_req          Integer, read, optional
                     Desired number of seconds for which context
                     should remain valid.  Supply 0 to request a
                     default validity period.

   input_chan_bindings  channel bindings, read, optional
                        Application-specified bindings.  Allows
                        application to securely bind channel
                        identification information to the security
                        context.  Specify GSS_C_NO_CHANNEL_BINDINGS
                        if channel bindings are not used.

   input_token       buffer, opaque, read, optional (see text)
                     Token received from peer application.
                     Supply GSS_C_NO_BUFFER, or a pointer to
                     a buffer containing the value GSS_C_EMPTY_BUFFER
                     on initial call.

   actual_mech_type  OID, modify, optional
                     Actual mechanism used.  The OID returned via
                     this parameter will be a pointer to static
                     storage that should be treated as read-only;
                     In particular the application should not attempt
                     to free it.  Specify NULL if not required.

   output_token      buffer, opaque, modify
                     token to be sent to peer application.  If
                     the length field of the returned buffer is
                     zero, no token need be sent to the peer
                     application.  Storage associated with this
                     buffer must be freed by the application
                     after use with a call to gss_release_buffer().

   ret_flags         bit-mask, modify, optional
                     Contains various independent flags, each of which
                     indicates that the context supports a specific
                     service option.  Specify NULL if not
                     required.  Symbolic names are provided
                     for each flag, and the symbolic names
                     corresponding to the required flags should be
                     logically-ANDed with the ret_flags value to test
                     whether a given option is supported by the
                     context.  The flags are:

Top       Page 61 
                     GSS_C_DELEG_FLAG
                       True - Credentials were delegated to
                              the remote peer
                       False - No credentials were delegated

                     GSS_C_MUTUAL_FLAG
                       True - The remote peer has authenticated
                              itself.
                       False - Remote peer has not authenticated
                               itself.

                     GSS_C_REPLAY_FLAG
                       True - replay of protected messages
                              will be detected
                       False - replayed messages will not be
                               detected

                     GSS_C_SEQUENCE_FLAG
                       True - out-of-sequence protected
                              messages will be detected
                       False - out-of-sequence messages will
                               not be detected

                     GSS_C_CONF_FLAG
                       True - Confidentiality service may be
                              invoked by calling gss_wrap routine
                       False - No confidentiality service (via
                               gss_wrap) available. gss_wrap will
                               provide message encapsulation,
                               data-origin authentication and
                               integrity services only.

                     GSS_C_INTEG_FLAG
                       True - Integrity service may be invoked by
                              calling either gss_get_mic or gss_wrap
                              routines.
                       False - Per-message integrity service
                               unavailable.

                     GSS_C_ANON_FLAG
                       True - The initiator's identity has not been
                              revealed, and will not be revealed if
                              any emitted token is passed to the
                              acceptor.
                       False - The initiator's identity has been or
                               will be authenticated normally.

                     GSS_C_PROT_READY_FLAG

Top       Page 62 
                       True - Protection services (as specified
                              by the states of the GSS_C_CONF_FLAG
                              and GSS_C_INTEG_FLAG) are available for
                              use if the accompanying major status
                              return value is either GSS_S_COMPLETE or
                              GSS_S_CONTINUE_NEEDED.
                       False - Protection services (as specified
                               by the states of the GSS_C_CONF_FLAG
                               and GSS_C_INTEG_FLAG) are available
                               only if the accompanying major status
                               return value is GSS_S_COMPLETE.

                     GSS_C_TRANS_FLAG
                       True - The resultant security context may
                              be transferred to other processes via
                              a call to gss_export_sec_context().
                       False - The security context is not
                               transferable.

                     All other bits should be set to zero.

   time_rec          Integer, modify, optional
                     number of seconds for which the context
                     will remain valid. If the implementation does
                     not support context expiration, the value
                     GSS_C_INDEFINITE will be returned.  Specify
                     NULL if not required.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_CONTINUE_NEEDED Indicates that a token from the peer
                         application is required to complete the
                         context, and that gss_init_sec_context
                         must be called again with that token.

   GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed
                         on the input_token failed

   GSS_S_DEFECTIVE_CREDENTIAL Indicates that consistency checks
                              performed on the credential failed.

   GSS_S_NO_CRED     The supplied credentials were not valid for
                     context initiation, or the credential handle
                     did not reference any credentials.

   GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired

Top       Page 63 
   GSS_S_BAD_BINDINGS The input_token contains different channel
                      bindings to those specified via the
                      input_chan_bindings parameter

   GSS_S_BAD_SIG     The input_token contains an invalid MIC, or a MIC
                     that could not be verified

   GSS_S_OLD_TOKEN   The input_token was too old.  This is a fatal
                     error during context establishment

   GSS_S_DUPLICATE_TOKEN The input_token is valid, but is a duplicate
                         of a token already processed.  This is a
                         fatal error during context establishment.

   GSS_S_NO_CONTEXT  Indicates that the supplied context handle did
                     not refer to a valid context

   GSS_S_BAD_NAMETYPE The provided target_name parameter contained an
                      invalid or unsupported type of name

   GSS_S_BAD_NAME    The provided target_name parameter was ill-formed.

   GSS_S_BAD_MECH    The specified mechanism is not supported by the
                     provided credential, or is unrecognized by the
                     implementation.

5.20. gss_inquire_context

   OM_uint32 gss_inquire_context (
     OM_uint32          *minor_status,
     const gss_ctx_id_t context_handle,
     gss_name_t         *src_name,
     gss_name_t         *targ_name,
     OM_uint32          *lifetime_rec,
     gss_OID            *mech_type,
     OM_uint32          *ctx_flags,
     int                *locally_initiated,
     int                *open )

   Purpose:

   Obtains information about a security context.  The caller must
   already have obtained a handle that refers to the context, although
   the context need not be fully established.

Top       Page 64 
   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   context_handle    gss_ctx_id_t, read
                     A handle that refers to the security context.

   src_name          gss_name_t, modify, optional
                     The name of the context initiator.
                     If the context was established using anonymous
                     authentication, and if the application invoking
                     gss_inquire_context is the context acceptor,
                     an anonymous name will be returned.  Storage
                     associated with this name must be freed by the
                     application after use with a call to
                     gss_release_name().  Specify NULL if not
                     required.

   targ_name         gss_name_t, modify, optional
                     The name of the context acceptor.
                     Storage associated with this name must be
                     freed by the application after use with a call
                     to gss_release_name().  If the context acceptor
                     did not authenticate itself, and if the initiator
                     did not specify a target name in its call to
                     gss_init_sec_context(), the value GSS_C_NO_NAME
                     will be returned.  Specify NULL if not required.

   lifetime_rec      Integer, modify, optional
                     The number of seconds for which the context
                     will remain valid.  If the context has
                     expired, this parameter will be set to zero.
                     If the implementation does not support
                     context expiration, the value
                     GSS_C_INDEFINITE will be returned.  Specify
                     NULL if not required.

   mech_type         gss_OID, modify, optional
                     The security mechanism providing the
                     context.  The returned OID will be a
                     pointer to static storage that should
                     be treated as read-only by the application;
                     in particular the application should not
                     attempt to free it.  Specify NULL if not
                     required.

Top       Page 65 
   ctx_flags         bit-mask, modify, optional
                     Contains various independent flags, each of
                     which indicates that the context supports
                     (or is expected to support, if ctx_open is
                     false) a specific service option.  If not
                     needed, specify NULL.  Symbolic names are
                     provided for each flag, and the symbolic names
                     corresponding to the required flags
                     should be logically-ANDed with the ret_flags
                     value to test whether a given option is
                     supported by the context.  The flags are:

                     GSS_C_DELEG_FLAG
                       True - Credentials were delegated from
                              the initiator to the acceptor.
                       False - No credentials were delegated

                     GSS_C_MUTUAL_FLAG
                       True - The acceptor was authenticated
                              to the initiator
                       False - The acceptor did not authenticate
                               itself.

                     GSS_C_REPLAY_FLAG
                       True - replay of protected messages
                              will be detected
                       False - replayed messages will not be
                               detected

                     GSS_C_SEQUENCE_FLAG
                       True - out-of-sequence protected
                              messages will be detected
                       False - out-of-sequence messages will not
                               be detected

                     GSS_C_CONF_FLAG
                       True - Confidentiality service may be invoked
                              by calling gss_wrap routine
                       False - No confidentiality service (via
                               gss_wrap) available. gss_wrap will
                               provide message encapsulation,
                               data-origin authentication and
                               integrity services only.

                     GSS_C_INTEG_FLAG
                       True - Integrity service may be invoked by
                              calling either gss_get_mic or gss_wrap
                              routines.

Top       Page 66 
                       False - Per-message integrity service
                               unavailable.

                     GSS_C_ANON_FLAG
                       True - The initiator's identity will not
                              be revealed to the acceptor.
                              The src_name parameter (if
                              requested) contains an anonymous
                              internal name.
                       False - The initiator has been
                               authenticated normally.

                     GSS_C_PROT_READY_FLAG
                       True - Protection services (as specified
                              by the states of the GSS_C_CONF_FLAG
                              and GSS_C_INTEG_FLAG) are available
                              for use.
                       False - Protection services (as specified
                               by the states of the GSS_C_CONF_FLAG
                               and GSS_C_INTEG_FLAG) are available
                               only if the context is fully
                               established (i.e. if the open parameter
                               is non-zero).

                     GSS_C_TRANS_FLAG
                       True - The resultant security context may
                              be transferred to other processes via
                              a call to gss_export_sec_context().
                       False - The security context is not
                               transferable.

   locally_initiated Boolean, modify
                     Non-zero if the invoking application is the
                     context initiator.
                     Specify NULL if not required.

   open              Boolean, modify
                     Non-zero if the context is fully established;
                     Zero if a context-establishment token
                     is expected from the peer application.
                     Specify NULL if not required.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_NO_CONTEXT  The referenced context could not be accessed.

Top       Page 67 
5.21. gss_inquire_cred

   OM_uint32 gss_inquire_cred (
     OM_uint32           *minor_status,
     const gss_cred_id_t cred_handle,
     gss_name_t          *name,
     OM_uint32           *lifetime,
     gss_cred_usage_t    *cred_usage,
     gss_OID_set         *mechanisms )

   Purpose:

   Obtains information about a credential.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   cred_handle       gss_cred_id_t, read
                     A handle that refers to the target credential.
                     Specify GSS_C_NO_CREDENTIAL to inquire about
                     the default initiator principal.

   name              gss_name_t, modify, optional
                     The name whose identity the credential asserts.
                     Storage associated with this name should be freed
                     by the application after use with a call to
                     gss_release_name().  Specify NULL if not required.

   lifetime          Integer, modify, optional
                     The number of seconds for which the credential
                     will remain valid.  If the credential has
                     expired, this parameter will be set to zero.
                     If the implementation does not support
                     credential expiration, the value
                     GSS_C_INDEFINITE will be returned.  Specify
                     NULL if not required.

   cred_usage        gss_cred_usage_t, modify, optional
                     How the credential may be used.  One of the
                     following:
                     GSS_C_INITIATE
                     GSS_C_ACCEPT
                     GSS_C_BOTH
                     Specify NULL if not required.

Top       Page 68 
   mechanisms        gss_OID_set, modify, optional
                     Set of mechanisms supported by the credential.
                     Storage associated with this OID set must be
                     freed by the application after use with a call
                     to gss_release_oid_set().  Specify NULL if not
                     required.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_NO_CRED     The referenced credentials could not be accessed.

   GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.

   GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
                     If the lifetime parameter was not passed as NULL,
                     it will be set to 0.

5.22. gss_inquire_cred_by_mech

   OM_uint32 gss_inquire_cred_by_mech (
     OM_uint32           *minor_status,
     const gss_cred_id_t cred_handle,
     const gss_OID       mech_type,
     gss_name_t          *name,
     OM_uint32           *initiator_lifetime,
     OM_uint32           *acceptor_lifetime,
     gss_cred_usage_t    *cred_usage )

   Purpose:

   Obtains per-mechanism information about a credential.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   cred_handle       gss_cred_id_t, read
                     A handle that refers to the target credential.
                     Specify GSS_C_NO_CREDENTIAL to inquire about
                     the default initiator principal.

   mech_type         gss_OID, read
                     The mechanism for which information should be
                     returned.

Top       Page 69 
   name              gss_name_t, modify, optional
                     The name whose identity the credential asserts.
                     Storage associated with this name must be
                     freed by the application after use with a call
                     to gss_release_name().  Specify NULL if not
                     required.

   initiator_lifetime  Integer, modify, optional
                     The number of seconds for which the credential
                     will remain capable of initiating security contexts
                     under the specified mechanism.  If the credential
                     can no longer be used to initiate contexts, or if
                     the credential usage for this mechanism is
                     GSS_C_ACCEPT, this parameter will be set to zero.
                     If the implementation does not support expiration
                     of initiator credentials, the value
                     GSS_C_INDEFINITE will be returned.  Specify NULL
                     if not required.

   acceptor_lifetime Integer, modify, optional
                     The number of seconds for which the credential
                     will remain capable of accepting security contexts
                     under the specified mechanism.  If the credential
                     can no longer be used to accept contexts, or if
                     the credential usage for this mechanism is
                     GSS_C_INITIATE, this parameter will be set to zero.

                     If the implementation does not support expiration
                     of acceptor credentials, the value GSS_C_INDEFINITE
                     will be returned.  Specify NULL if not required.

   cred_usage        gss_cred_usage_t, modify, optional
                     How the credential may be used with the specified
                     mechanism.  One of the following:
                       GSS_C_INITIATE
                       GSS_C_ACCEPT
                       GSS_C_BOTH
                     Specify NULL if not required.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_NO_CRED     The referenced credentials could not be accessed.

   GSS_S_DEFECTIVE_CREDENTIAL The referenced credentials were invalid.

Top       Page 70 
   GSS_S_CREDENTIALS_EXPIRED The referenced credentials have expired.
                    If the lifetime parameter was not passed as NULL,
                    it will be set to 0.

5.23. gss_inquire_mechs_for_name

   OM_uint32 gss_inquire_mechs_for_name (
     OM_uint32        *minor_status,
     const gss_name_t input_name,
     gss_OID_set      *mech_types )

   Purpose:

   Returns the set of mechanisms supported by the GSS-API implementation
   that may be able to process the specified name.

   Each mechanism returned will recognize at least one element within
   the name.  It is permissible for this routine to be implemented
   within a mechanism-independent GSS-API layer, using the type
   information contained within the presented name, and based on
   registration information provided by individual mechanism
   implementations.  This means that the returned mech_types set may
   indicate that a particular mechanism will understand the name when in
   fact it would refuse to accept the name as input to
   gss_canonicalize_name, gss_init_sec_context, gss_acquire_cred or
   gss_add_cred (due to some property of the specific name, as opposed
   to the name type).  Thus this routine should be used only as a pre-
   filter for a call to a subsequent mechanism-specific routine.

   Parameters:

   minor_status      Integer, modify
                     Implementation specific status code.

   input_name        gss_name_t, read
                     The name to which the inquiry relates.

   mech_types        gss_OID_set, modify
                     Set of mechanisms that may support the
                     specified name.  The returned OID set
                     must be freed by the caller after use
                     with a call to gss_release_oid_set().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_BAD_NAME    The input_name parameter was ill-formed.

Top       Page 71 
   GSS_S_BAD_NAMETYPE The input_name parameter contained an invalid or
                      unsupported type of name

5.24. gss_inquire_names_for_mech

   OM_uint32 gss_inquire_names_for_mech (
     OM_uint32     *minor_status,
     const gss_OID mechanism,
     gss_OID_set   *name_types)

   Purpose:

   Returns the set of nametypes supported by the specified mechanism.

   Parameters:

   minor_status      Integer, modify
                     Implementation specific status code.

   mechanism         gss_OID, read
                     The mechanism to be interrogated.

   name_types        gss_OID_set, modify
                     Set of name-types supported by the specified
                     mechanism.  The returned OID set must be
                     freed by the application after use with a
                     call to gss_release_oid_set().

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

5.25. gss_process_context_token

   OM_uint32 gss_process_context_token (
     OM_uint32          *minor_status,
     const gss_ctx_id_t context_handle,
     const gss_buffer_t token_buffer)

        Purpose:

   Provides a way to pass an asynchronous token to the security service.
   Most context-level tokens are emitted and processed synchronously by
   gss_init_sec_context and gss_accept_sec_context, and the application
   is informed as to whether further tokens are expected by the
   GSS_C_CONTINUE_NEEDED major status bit.  Occasionally, a mechanism
   may need to emit a context-level token at a point when the peer
   entity is not expecting a token.  For example, the initiator's final

Top       Page 72 
   call to gss_init_sec_context may emit a token and return a status of
   GSS_S_COMPLETE, but the acceptor's call to gss_accept_sec_context may
   fail.  The acceptor's mechanism may wish to send a token containing
   an error indication to the initiator, but the initiator is not
   expecting a token at this point, believing that the context is fully
   established.  Gss_process_context_token provides a way to pass such a
   token to the mechanism at any time.

   Parameters:

   minor_status      Integer, modify
                     Implementation specific status code.

   context_handle    gss_ctx_id_t, read
                     context handle of context on which token is to
                     be processed

   token_buffer      buffer, opaque, read
                     token to process

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_DEFECTIVE_TOKEN Indicates that consistency checks performed
                     on the token failed

   GSS_S_NO_CONTEXT  The context_handle did not refer to a valid context

5.26. gss_release_buffer

   OM_uint32 gss_release_buffer (
     OM_uint32    *minor_status,
     gss_buffer_t buffer)

   Purpose:

   Free storage associated with a buffer.  The storage must have been
   allocated by a GSS-API routine.  In addition to freeing the
   associated storage, the routine will zero the length field in the
   descriptor to which the buffer parameter refers, and implementations
   are encouraged to additionally set the pointer field in the
   descriptor to NULL.  Any buffer object returned by a GSS-API routine
   may be passed to gss_release_buffer (even if there is no storage
   associated with the buffer).

Top       Page 73 
   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   buffer            buffer, modify
                     The storage associated with the buffer will be
                     deleted.  The gss_buffer_desc object will not
                     be freed, but its length field will be zeroed.


   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

5.27. gss_release_cred

   OM_uint32 gss_release_cred (
     OM_uint32     *minor_status,
     gss_cred_id_t *cred_handle)

   Purpose:

   Informs GSS-API that the specified credential handle is no longer
   required by the application, and frees associated resources.
   Implementations are encouraged to set the cred_handle to
   GSS_C_NO_CREDENTIAL on successful completion of this call.

   Parameters:

   cred_handle       gss_cred_id_t, modify, optional
                     Opaque handle identifying credential
                     to be released.  If GSS_C_NO_CREDENTIAL
                     is supplied, the routine will complete
                     successfully, but will do nothing.

   minor_status      Integer, modify
                     Mechanism specific status code.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_NO_CRED     Credentials could not be accessed.

Top       Page 74 
5.28. gss_release_name

   OM_uint32 gss_release_name (
     OM_uint32  *minor_status,
     gss_name_t *name)

   Purpose:

   Free GSSAPI-allocated storage associated with an internal-form name.
   Implementations are encouraged to set the name to GSS_C_NO_NAME on
   successful completion of this call.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

   name              gss_name_t, modify
                     The name to be deleted

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion

   GSS_S_BAD_NAME    The name parameter did not contain a valid name

5.29. gss_release_oid_set

   OM_uint32 gss_release_oid_set (
     OM_uint32   *minor_status,
     gss_OID_set *set)

   Purpose:

   Free storage associated with a GSSAPI-generated gss_OID_set object.
   The set parameter must refer to an OID-set that was returned from a
   GSS-API routine.  gss_release_oid_set() will free the storage
   associated with each individual member OID, the OID set's elements
   array, and the gss_OID_set_desc.

   Implementations are encouraged to set the gss_OID_set parameter to
   GSS_C_NO_OID_SET on successful completion of this routine.

   Parameters:

   minor_status      Integer, modify
                     Mechanism specific status code

Top       Page 75 
   set               Set of Object IDs, modify
                     The storage associated with the gss_OID_set
                     will be deleted.

   Function value:   GSS status code

   GSS_S_COMPLETE    Successful completion



(page 75 continued on part 4)

Next RFC Part