Next: Complex Data Types, Up: Standard GSS API
The following conventions are used by the GSS-API C-language bindings:
GSS-API uses the following integer data type:
OM_uint32 32-bit unsigned integer
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.
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.
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.
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().
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.