Next: , Up: Standard GSS API


3.1 Simple Data Types

The following conventions are used by the GSS-API C-language bindings:

3.1.1 Integer types

GSS-API uses the following integer data type:

   OM_uint32    32-bit unsigned integer

3.1.2 String and similar data

Many of the GSS-API routines take arguments and return values that describe contiguous octet-strings. All such data is passed between the GSS-API and the caller using the gss_buffer_t data type. This data type is a pointer to a buffer descriptor, which consists of a length field that contains the total number of bytes in the datum, and a value field which contains a pointer to the actual datum:

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

Storage for data returned to the application by a GSS-API routine using the gss_buffer_t conventions is allocated by the GSS-API routine. The application may free this storage by invoking the gss_release_buffer routine. Allocation of the gss_buffer_desc object is always the responsibility of the application; unused gss_buffer_desc objects may be initialized to the value GSS_C_EMPTY_BUFFER.

3.1.2.1 Opaque data types

Certain multiple-word data items are considered opaque data types at the GSS-API, because their internal structure has no significance either to the GSS-API or to the caller. Examples of such opaque data types are the input_token parameter to gss_init_sec_context (which is opaque to the caller), and the input_message parameter to gss_wrap (which is opaque to the GSS-API). Opaque data is passed between the GSS-API and the application using the gss_buffer_t datatype.

3.1.2.2 Character strings

Certain multiple-word data items may be regarded as simple ISO Latin-1 character strings. Examples are the printable strings passed to gss_import_name via the input_name_buffer parameter. Some GSS-API routines also return character strings. All such character strings are passed between the application and the GSS-API implementation using the gss_buffer_t datatype, which is a pointer to a gss_buffer_desc object.

When a gss_buffer_desc object describes a printable string, the length field of the gss_buffer_desc should only count printable characters within the string. In particular, a trailing NUL character should NOT be included in the length count, nor should either the GSS-API implementation or the application assume the presence of an uncounted trailing NUL.

3.1.3 Object Identifiers

Certain GSS-API procedures take parameters of the type gss_OID, or Object identifier. This is a type containing ISO-defined tree- structured values, and is used by the GSS-API caller to select an underlying security mechanism and to specify namespaces. A value of type gss_OID has the following structure:

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

The elements field of this structure points to the first byte of an octet string containing the ASN.1 BER encoding of the value portion of the normal BER TLV encoding of the gss_OID. The length field contains the number of bytes in this value. For example, the gss_OID value corresponding to iso(1) identified-organization(3) icd-ecma(12) member-company(2) dec(1011) cryptoAlgorithms(7) DASS(5), meaning the DASS X.509 authentication mechanism, has a length field of 7 and an elements field pointing to seven octets containing the following octal values: 53,14,2,207,163,7,5. GSS-API implementations should provide constant gss_OID values to allow applications to request any supported mechanism, although applications are encouraged on portability grounds to accept the default mechanism. gss_OID values should also be provided to allow applications to specify particular name types (see section 3.10). Applications should treat gss_OID_desc values returned by GSS-API routines as read-only. In particular, the application should not attempt to deallocate them with free().

3.1.4 Object Identifier Sets

Certain GSS-API procedures take parameters of the type gss_OID_set. This type represents one or more object identifiers (see Object Identifiers). A gss_OID_set object has the following structure:

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

The count field contains the number of OIDs within the set. The elements field is a pointer to an array of gss_OID_desc objects, each of which describes a single OID. gss_OID_set values are used to name the available mechanisms supported by the GSS-API, to request the use of specific mechanisms, and to indicate which mechanisms a given credential supports.

All OID sets returned to the application by GSS-API are dynamic objects (the gss_OID_set_desc, the "elements" array of the set, and the "elements" array of each member OID are all dynamically allocated), and this storage must be deallocated by the application using the gss_release_oid_set routine.