Digital DCE for OpenVMS VAX and OpenVMS Alpha
Reference Guide
Previous Contents Index

UAF_NOTDELETED, error deleting entry <USERNAME>

UAF_NOTMODED, error modifying entry <USERNAME>

UAF_NOVERIFY, unable to verify account

UAF_NOVREC, no version record found in file

UAF_NYI, this feature is not yet implemented

UAF_RECEXISTS, record already exists

UAF_SYSCHKBEG, starting scan of SYSUAF file

UAF_SYSCHKEND, completed scan of SYSUAF file

UAF_VERSIONSKEW, version skew between library and UAF file

UAF_VERUSERERR, error accessing registry

UAF_VRECFAIL, write of version record failed

Part 2
GSSAPI Reference

Chapter 5
GSSAPI Reference Pages

The following reference pages describe the Generic Security Services API (GSSAPI). For more information on GSSAPI, see the Digital DCE for OpenVMS VAX and OpenVMS Alpha Product Guide.

intro(3gss)

Generic Security Service Application Programming Interface

Description

This introduction includes general information about the Generic Security Service Application Programming Interface (GSSAPI) defined in the Internet RFC 1508, Generic Security Service Application Programming Interface, and RFC 1509 Generic Security Service API: C-bindings, and an overview of error handling, data types, and calling conventions, including the following:

General Information

The Generic Security Service Application Programming Interface (GSSAPI) provides security services to applications using peer-to-peer communications. Using OSF DCE GSSAPI routines, applications can perform the following operations:

In peer-to-peer communications, the application that establishes the secure connection is the context initiator or simply initiator. The context initiator is like a DCE RPC client. The application that accepts the secure connection is the context acceptor or simply acceptor. The context acceptor is like a DCE RPC server. There are four stages to using the GSSAPI:

  1. The context initiator acquires a credential with which it can prove its identity to other processes.
    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
    • Principal name and a key
      The key corresponding to the principal name must be registered with the DCE Security Registration in a key table. A set of DCE GSSAPI routines enable applications to register and use principal names.
  2. The communicating applications establish a joint security context by exchanging authentication tokens.
    The security context 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 gss_init_sec_context() routine to get a token. The token is cryptographically protected, opaque data. The context initiator transfers the token to the context acceptor, which in turn passes the token to the gss_accept_sec_context() routine to decode and extract the shared information.
    As part of the establishment of 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 initiator sets a flag on the gss_init_sec_context() routine indicating that it wants to delegate. The acceptor accepts the call and then calls the gss_accept_sec_context() routine, which generates a delegated credential. The context acceptor can use the credential to initiate additional security contexts.
  3. The applications exchange protected messages and data.
    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:
    1. Apply protection.
    2. Bind the message to the appropriate security context
    The application can then send the resulting information to the peer application.
    The application that receives the message passes the received data to a GSSAPI routine, which removes the protection and validates the data.
    The 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
  4. When the applications finish their communication, either one of the applications deletes the security context.
    The context initiator calls GSSAPI routines to delete any security contexts that were established in a single communications session.

There are two sets of GSSAPI routines:

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

Error Handling

Each GSSAPI routine returns two status values:

The GSSAPI routines return a minor_status parameter to indicate errors from DCE.

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 and no storage was allocated. If no storage was allocated, the routine sets the pointer to NULL and sets any length fields associated with the pointers (such as the gss_buffer_desc structure) to zero. 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 handling 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 definitions.

Integer Types

The GSSAPI defines the following integer data type: 


 OM_uint32 32-bit unsigned integer

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

Strings and Similar Data

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 gss_buffer_t data type, which is a pointer to the buffer descriptor gss_buff_desc, to pass the data between the GSSAPI routines and applications.

The gss_buffer_t data type has the following structure: 


 typedef struct gss_buffer_desc_struct { 
  size_t length; 
  void *value; 
 } gss_buffer_desc, *gss_buffer_t;

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

The GSSAPI routine allocates storage for any data it passes to the application using the gss_buffer_t data type. The calling application must allocate the gss_buffer_desc object. It can initialize unused gss_buffer_desc objects with the value GSS_C_EMPTY_BUFFER. To free the storage, the application calls the gss_release_buffer() routine.

Object Identifier

Applications use the gss_OID data type to choose a security mechanism, either DCE Security or Kerberos, and to specify name types. Choose the security mechanism using the following two OIDs:

Use the default security mechanisms to help ensure the portability of the application.

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


 typedef struct gss_OID_desc_struct { 
  OM_uint32 length; 
  void * elements; 
 }  gss_OID_desc, *gss_OID;

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 gss_OID data type. The length field contains the number of bytes in the value.

The gss_OID_descr values returned from the GSSAPI are read-only values. The application should not try to deallocate them.

Object Identifier Sets

The gss_OID_set data type represents one or more object identifiers. The values of the gss_OID_set data type are used to:

The gss_OID_set data type has the following structure: 


 typedef struct gss_OID_set_desc_struct { 
  int count 
  gss_OID elements 
 } gss_OID_set_desc, *gss_OID_set;

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

Credentials

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

The gss_cred_id_t data type is an atomic data type that identifies a GSSAPI credential data structure.

Contexts

The security context is a pair of GSSAPI data structures that contain information shared between the communicating applications. The information 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 gss_ctx_id_t 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 applications sharing a security context. The token is a cryptographically protected bit string generated by DCE Security 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 caller.

The applications use the gss_buffer_t data type to pass tokens to GSSAPI routines.

Major Status Values

GSSAPI routines return GSS status codes as their OM_uint32 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: 


 MSB         LSB 
 +---------------------------------------------------+ 
 | Calling Error | Routine Error | Supplementary Info| 
 +---------------------------------------------------+ 
    Bit 31       24 23           16 15                 0

If a GSSAPI routine returns a GSS status code whose upper 16 bits contain a nonzero value, the call 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 error, and supplementary information status bits and their meanings.

Table 5-1 lists the GSSAPI routine errors and their meanings.

Table 5-1 GSSAPI Routine Errors
Name Field Value Meaning
GSS_S_BAD_MECH 1 The required mechanism is unsupported.
GSS_S_NAME 2 The name passed is invalid.
GSS_S_NAMETYPE 3 The name passed is unsupported.
GSS_S_BAD_BINDINGS 4 The channel bindings are incorrect.
GSS_S_BAD_STATUS 5 A status value was invalid.
GSS_S_BAD_SIG 6 A token had an invalid signature.
GSS_S_NO_CRED 7 No credentials were supplied.
GSS_S_NO_CONTEXT 8 No context has been established.
GSS_S_DEFECTIVE_TOKEN 9 A token was invalid.
GSS_S_DEFECTIVE_CREDENTIAL 10 A credential was invalid.
GSS_S_CREDENTIALS_EXPIRED 11 The referenced credentials expired.
GSS_S_CONTEXT_EXPIRED 12 The context expired.
GSS_S_FAILURE 13 The routine failed. Check minor status codes.

Table 5-2 lists the calling error values and their meanings.

Table 5-2 Calling Error
Name Field Value Meaning
GSS_S_CALL_INACCESSIBLE_READ 1 Could not read a required input parameter.
GSS_S_CALL_INACCESSIBLE_WRITE 2 Could not write a required output parameter.
GSS_S_BAD_STRUCTURE 3 A parameter was incorrectly structured.

Table 5-3 lists the supplementary bits and their meanings.

Table 5-3 Suplementary Information Status Bits
Name Field Value 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 validity 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 GSS_S_ symbols equate to complete OM_uint32 status codes, rather than to bitfield values. For example, the actual value of GSS_S_BAD_NAMETYPE (value 3 in the routine error field) is 3 << 16.

The major status code GSS_S_FAILURE indicates that DCE Security detected an error for which no major status code is available. Check the minor status code for details about the error. See the section 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 GSS_ROUTINE_ERROR() 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 info fields.

An additional macro, GSS_ERROR(), lets you determine whether the status code indicated a calling or routine error. If the status code indicated a calling or routine error, the macro returns a nonzero value. If no calling or routine error is indicated, the routine returns a zero.

At times, a GSSAPI routine that is unable to access data can generate a platform-specific signal, instead of returning a GSS_S_CALL_INACCESSIBLE_READ or GSS_S_CALL_INACCESSIBLE_WRITE\*O status value.

Minor Status Values

The GSSAPI routines return a minor_status parameter to indicate errors from either DCE Security or Kerberos. The parameter can contain a single error, indicated by an OM_uint32 value. The OM_uint32 data type is equivalent to the DCE data type error_status_t and can contain any DCE-defined error.

Names

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

Names are represented in two forms:

The gss_import_name() and gss_display_name() routines convert names between their printable form and their gss_name_t data type. DCE GSSAPI supports only DCE principal names, which are identified by the constant OID, GSSCDE_C_OID_DCENAME.

The gss_compare_names() routine compares internal form names.

Channel Bindings

You can define and use channel bindings to associate the security context with the communications channel that carries the context. Channel bindings are communicated to the GSSAPI using the following structure: 


 
 typedef struct gss_channel_binding_struct { 
  OM_uint32 initiator_addrtype; 
  gss_buffer_desc initiator_address; 
  OM_uint32 acceptor_addrtype; 
  gss_buffer_desc aceptor_address; 
  gss_buffer_desc application_data; 
 } *gss_channel_bindings_t;

Use the initiator_addrtype and acceptor_addrtype fields to initiate the type of addresses contained in the initiator_address and acceptor_address buffers. The following table lists the address types and their addrtype values:
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 initiator_address and the acceptor_address 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 (initiator_addrtype, initiator_address, acceptor_addrtype, acceptor_address, and application_data). The security mechanism signs the octet string and binds the signature to the token generated by the gss_init_sec_context() routine. The context acceptor presents the same bindings to the gss_accept_sec_context() routine, which evaluates the signature and compares it to the signature in the token. If the signatures differ, the gss_accept_sec_context() routine returns a GSS_S_BAD_BINDINGS error, and the context is not established.

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

Previous Next Contents Index