GSS-API Programming Guide

Mechanisms and QOPs

Although it is strongly recommended that you use the default QOP and mechanism provided by the GSS-API if at all possible (see OIDs), you might have your own reasons for specifying these OIDs. For that reason this chapter briefly discusses how to specify OIDs.

Files Containing OID Values

For convenience, the GSS-API does allow mechanisms and QOPs to be displayed in human-readable form. On Solaris systems, two files, /etc/gss/mech and /etc/gss/qop, contain information about available mechanisms and QOPs. If you don't have access to these files (perhaps because a remote machine won't let you in), then you must provide the string literals from some other source, such as the published internet standard for that mechanism or QOP.

The /etc/gss/mech File

You can look in the /etc/gss/mech file to see which mechanisms are available; /etc/gss/mech contains their names in both numerical and alphabetic form. /etc/gss/mech presents the information in this format: the mechanism name, in ASCII; the mechanism's OID; the shared library implementing the services provided by this mechanism; and, optionally, the kernel module implementing the service. A sample /etc/gss/mech might look like Example C–1.

Example C–1 The /etc/gss/mech File

# Copyright (c) 2000, by Sun Microsystems, Inc.
# All rights reserved.
#ident  "@(#)mech 1.6     00/12/04 SMI" 
# This file contains the GSS-API based security mechanism names,
# its object identifier (OID) and a shared library that implements 
# the services for that mechanism under GSS-API.
# Mechanism Name        Object Identifier       Shared Library  Kernel Module
kerberos_v5             1.2.840.113554.1.2.2    gl/ gl_kmech_krb5

The /etc/gss/qop File

The /etc/gss/qop file stores, for all mechanisms installed, all the QOPs supported by each mechanism, both as an ASCII string as its corresponding 32–bit integer. A sample /etc/gss/qop might look like Example C–2.

Example C–2 The /etc/gss/qop File

# Copyright (c) 2000, by Sun Microsystems, Inc.
# All rights reserved.
#ident  "@(#)qop 1.3     00/11/09 SMI" 
# This file contains information about the GSS-API based quality of
# protection (QOP), its string name and its value (32-bit integer).
# QOP string                    QOP Value       Mechanism Name
GSS_KRB5_INTEG_C_QOP_DES_MD5    0               kerberos_v5
GSS_KRB5_CONF_C_QOP_DES         0               kerberos_v5


For backward compatibility with earlier versions of the GSS-API, this implementation of the GSS-API supports the function gss_str_to_oid(). gss_str_to_oid() converts a string representing a mechanism or QOP (either as a number or a word) to an OID.

Caution – Caution –

gss_str_to_oid(), gss_oid_to_str(), and gss_release_oid() are not supported by some implementations of the GSS-API in order to discourage the use of explicit, non-default mechanisms and QOPs.

The string can be hard-coded in the application, or come from user input. However, not all implementations of the GSS-API support this function, so applications shouldn't rely on it.

Note that the number representing a mechanism can have two different formats. The first

{ 1 2 3 4 }

is officially mandated by the GSS-API specifications, while the second:

is more widely used but is not an official standard format. gss_str_to_oid() expects the mechanism number in the first format, so you must convert the string if it's in the second format before calling gss_str_to_oid(). An example of this is shown in parse_oid(). If the mechanism is not a valid one, gss_str_to_oid() returns GSS_S_BAD_MECH.

Because gss_str_to_oid() allocates GSS-API dataspace, the gss_release_oid() function exists, to remove the allocated OID when you've finished with it. Like gss_str_to_oid(), gss_release_oid() is not a generally supported function and should not be relied upon in programs that aspire to universal portability.

Constructing Mechanism OIDs

Since gss_str_to_oid() is not always available or desirable, there are preferable, if more complex, ways to find out which mechanisms are available, and to choose one. One way is to construct a mechanism OID “by hand” and then compare it to a set of available mechanisms; another way is to get the set of available mechanisms and choose one from it.

The gss_OID type has the following form:

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

where 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 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.

One way to construct a mechanism OID is to declare a gss_OID and then initialize its elements “by hand” to represent that of a given mechanism. (As above, the input for the elements values might be hard-coded, be looked up in a table, or come from user input.) This is somewhat more painstaking than using gss_str_to_oid() but achieves the same effect.

Such a gss_OID can then be compared against a set of available mechanisms returned by the functions gss_indicate_mechs() or gss_inquire_mechs_for_name(). The application can check to see if its constructed mechanism OID is in this set of available mechanisms by using the gss_test_oid_set_member() function. If gss_test_oid_set_member() does not return an error, then the constructed OID can be used as the mechanism for GSS-API transactions.

As an alternative to constructing a pre-set OID, the application can use gss_indicate_mechs() or gss_inquire_mechs_for_name() to get the gss_OID_set of available mechanisms. A gss_OID_set has the following form:

typedef struct gss_OID_set_desc_struct {
     OM_uint32 length;
     void           *elements;
} gss_OID_set_desc, *gss_OID_set;

where each of the elements is a gss_OID representing a mechanism. The application can then parse each mechanism and display the element values of each one, in effect displaying the numerical representation of each mechanism. A user can then choose which of the mechanisms to use, based on this display, and the application then sets its mechanism to be the appropriate member of the gss_OID_set. Or the application can compare these desired mechanisms with a list of preferred mechanisms.