8    GSS-API

The Generic Security Service Application Program Interface (GSS-API) functions enable applications in a distributed network environment to use the following security services on the network:

• Authentication — The application can verify the identity of a user or service.

• Integrity — The application can detect message tampering or corruption when it receives the message.

• Confidentiality — A message can be encrypted to render it unintelligible to eavesdroppers during transmission.

This chapter contains the following information:

• GSS-API overview

• Application security SDK

• Application security SDK functions

• Best practices

• Building a portable application

8.1    GSS-API Overview

The GSS-API is a standard programming interface that defines a set of generic C functions that can be used to secure distributed applications. The GSS-API has two primary design goals which are fundamental to its operation:

• Security mechanism independence

• Transport protocol independence

Because it is an open standard, the GSS-API has been designed to be generic so that as security and network technologies evolve, the API does not have to change.

The GSS-API supports a wide range of underlying security mechanisms and technologies using the following architecture.

A security mechanism is a method of providing security (such as Kerberos or public-key encryption). It is not only the cryptographic technology used, but also the syntax and semantics of the data that the technology employs. An application secured using the GSS-API standard may use one or more security mechanisms.

The GSS-API can be used in a broad range of network environments (for example, TCP/IP, SNA, and DECnet). The standard was not designed to provide a transport mechanism. Rather, the design provides security over an arbitrary network transport. The transport must be provided by the application. The communications protocol can be an interprocess communications path or a series of networks.

GSS-API functions return information to the application, which then sends the information across the communications protocol in use. The other side of the distributed application passes the information to the GSS-API library.

For a developer securing an application using the GSS-API standard, these design goals of mechanism and transport independence provide a consistent interface that is independent of the underlying hardware and software platform — a one-time programming investment. The investment in modifications to secure an application remains constant even as the technologies evolve.

8.1.1    GSS-API Assumptions

The GSS-API standard makes the following assumptions:

• The application is distributed.

  The GSS-API standard assumes that the application is a distributed network application or divided into two parts using a peer-to-peer or a initiator-acceptor relationship.

• The source code can be modified.

  The GSS-API standard assumes that you can incorporate GSS-API functions in the application source code.

• The application guarantees token delivery.

  A token is an opaque data object returned by the GSS-API that an application needs to communicate with its peer. The GSS-API standard assumes that your application can deliver tokens generated during context establishment and context termination in the order in which they are generated.

• The application deallocates its data objects.

  The GSS-API standard assumes that if an application allocated a data object, it is responsible for deallocating it. If a data object is returned by a GSS-API function, the application must use the corresponding GSS-API function to release the object, thereby deallocating it. Otherwise, there can be a memory leak or memory fault in the application. Failure to use the proper functions for deallocation may create a situation where the security network may be compromised.

8.1.2    Further Information

The GSS-API is an industry standard created as part of the ongoing Internet RFC (Request For Comments) process.

Application Security SDK is based on the following RFCs:

• RFC 2078 "Generic Security Service Application Program Interface, Version 2, Update 1" September 3, 1998

• "Generic Security Service API Version 2: C-bindings," August 7, 1998

• RFC 1964 "The Kerberos Version 5 GSS-API Mechanism," June 1996

• RFC 1510 "The Kerberos Network Authentication Service (V5)," September 1993

• Internet Draft "Public Key Cryptography for Initial Authentication in Kerberos" (updates RFC 1510)

  File name: draft-ietf-cat-kerberos-pk-init-07.txt

The GSS-API standard is monitored by the Common Authentication Technology Internet Engineering Task Force (CAT-IETF) working group. For more information on the GSS-API, see the IETF web site at www.ietf.org.

8.2    Application Security SDK

HP implements the GSS-API functions through the Application Security Service Developers Kit (SDK). The Application Security SDK is an implementation of the GSS-API version 2.0 that provides several unique contributions to the GSS-API standard.

• Application Security SDK supports the Kerberos 5 mechanism. The sample code and documentation provide clear instructions for securing distributed applications using Kerberos 5 with the GSS-API, complete with considerations that are specific to this security mechanism.

• Application Security SDK has many additional functions to enhance the capabilities of the GSS-API. These functions, termed extensions, permit additional Kerberos 5 security features, including:

  • complete support for Triple DES (DES3), including encryption of authentication tokens and user data. HP recommends that all data be encrypted using DES3, which provides significantly increased security in comparison to DES encryption.

  • programmatic support for acquiring the initial credentials needed before the initiator application can establish a security context. Using the HP extension function eliminates the need to use kinit, ActiveTRUST SignOn (available from CyberSafe Corporation), or HP Single SignOn to obtain these initial credentials.

  • recognition of hardware authentication devices, such as token cards. This adds an extra level of security at the client level during authentication requests.

  • ability to renew Kerberos 5 credentials. This prolongs the lifetime of an existing valid credential, and reduces the number of times the number of times the user is required to provide their username and password.

8.3    Application Security SDK Functions

Application Security SDK functions can be grouped into categories, of which only a subset is required to secure a distributed application. The functions can be divided according to these categories:

• Name Management Functions — Describes functions used to manipulate the internal and external names used by the GSS-API.

• Credential Management Functions — Describes functions used to acquire, query, and release credentials. This category also contains the HP extension functions included in Application Security SDK that are not part of the GSS-API standard. These functions are used to implement initial authentication, and include support for DES3 encryption, hardware authentication, and credential renewal.

• Security Context Management Functions — Describes functions used to initiate, accept, export, import, query and delete security contexts.

• Message Functions — Describes functions used to protect messages by ensuring data integrity, data origin, and, optionally, confidentiality.

• Miscellaneous Functions — Describes other support functions used to display status, release buffers, and manipulate object identifier (OID) sets.

• V1 Compliance Functions — Describes the functions that are supported for GSS-API Version 1 interoperability. These functions have been replaced for GSS-API Version 2.

8.3.1    Name Management Functions

The GSS-API uses names to identify entities in a network, just as a person uses a username to log in to a system on the network. The username identifies the person according to the system's naming structure. In the GSS-API standard, names identify an application or person using the application.

In the Kerberos 5 mechanism, names translate to principals. A principal is any user, client, network service, application, or system that has shared a secret with Kerberos (usually a password). Principals must have unique names within a realm, as well as an associated key.

The GSS-API utilizes four forms of names: external, exported, internal, and mechanism names. Functions are provided to convert between the various name forms.

• External names are text strings that are used as input to the GSS-API standard.

• Exported names are octet strings in a standard format, which are produced by a GSS-API function for use in name comparisons outside the standard.

• Internal names are opaque. This means the name cannot be displayed in an error message, for example. This type of name is used for all purposes internal to the GSS-API. An example of the usage with the Kerberos 5 mechanism is locating a credential belong to a specific username.

• Mechanism names are a special case of internal names that are mechanism-specific; meaning they are specific to a single mechanism. For single mechanism support, as in the case of Application Security SDK, the internal name and mechanism name are identical.

In the GSS-API, names are used to:

• Acquire credentials — Each side of an application imports its name into the GSS-API internal format for acquiring credentials.

• Establish a security context — The initiator identifies by name the acceptor with which it wants to establish a security context.

• Compare names — After the security context is established, name comparison may be required. This can be inside or outside the GSS-API standard, provided the proper name format is used.

  • Inside the GSS-API standard, the internal name can be used for comparisons (using gss_compare_name()).

  • Outside the GSS-API standard, the exported name should be used for comparisons. The acceptor, for example, may want to compare the initiator's name against an access control list (ACL). There is no function call provided in the API to perform this comparison.

The name of the application or person using the application does not follow a syntax, structure, or convention defined by the GSS-API. The application's name is dependent on the application itself. Because the GSS-API is generic, it is possible to provide names in different formats. These different methods to represent names are called name types, and are passed as object identifiers (OIDs).

The application can also use the GSS-API default for its name. This eliminates the requirement to provide the particular name, and avoids the need to pass the OID. In this case, the name is dependent on the GSS-API implementation.

8.3.1.1    Default Names and Syntax

Kerberos principal names are of the following form: name/instance@REALM, where the /instance and @REALM parts are optional. If the /instance is omitted, an empty instance is assumed. If the @REALM is omitted, the default realm is assumed. Multiple instances are allowed, each separated by a /.

If the application uses the GSS-API default for its name when acquiring credentials using the Kerberos 5 mechanism, the name used is the default principal from the default credential in the default credentials cache, if the cache exists. If it does not exist, the default name is determined according to the following rules:

• The default principal for a user (that is, a person) is the user's login name

• The default principal for a service is host/fqdn@REALM, where fqdn is the fully qualified domain name of the system on which the service is running and REALM is the system's default realm.

  HP recommends that for additional security, a service have its own principal name rather than share the use of the system's default host/ principal name. For example, a secure FTP service might use the principal name ftp/fqdn@REALM or ftp@REALM, (skipping the fqdn instance); a secure telnet service might use the principal name telnet/fqdn@REALM or telnet@REALM.

When an application calls gss_import_name() and does not use the default input format, it passes in an object identifier (OID) that specifies how to parse the application's name. For example, the GSS_KRB5_NT_HOSTBASED_SERVICE_NAME OID specifies the parsing syntax for a name of the format service@host. The NT in this parameter stands for name type.

8.3.2    Credential Management Functions

Credentials are used by an application to prove its identity. Each side of a distributed application needs to obtain credentials, which are used to initiate and accept a security context.

In Kerberos 5, there are three types of credentials:

• initial tickets — This type of credential is received from the Kerberos security server after initial authentication of a user principal. An initial ticket is properly termed a ticket-granting-ticket or TGT, and is required by the initiator application.

• service tickets — This ticket permits a user principal to gain access to a protected application. A TGT must be acquired before a service ticket can be received.

• service key table entry — This is a copy of the secret key associated with the principal in the principal database. This key must be extracted from the principal database to the service key table file using a database administration program. The key in the service key table file is used by an acceptor application instead of acquiring initial tickets.

For more information on Kerberos 5 security terms and infrastructure, see Security Primer.

When using the Kerberos 5 mechanism with the GSS-API standard, initial tickets are held and presented by a Kerberos principal as proof that it is what or who it claims to be. These credentials are used by the principal to prove that the trusted KDC has been contacted for initial authentication. Typically, initial tickets provided by the security server are placed in a central storage location called the credential cache.

In the GSS-API, initial tickets are retrieved from storage and used to establish a security context. In the standard GSS-API with the Kerberos 5 mechanism, the initiator application must already have obtained an initial ticket (TGT) prior to calling gss_acquire_cred(). A user can obtain an initial ticket by running kinit or an equivalent application (for example, Single SignOn). The acceptor application will use the key stored in the service key table file to verify its identity.

The Application Security SDK provides additional functions called the HP extension functions that are used to perform a variety of tasks, including:

• Obtaining initial credentials before initiating a context. This can be done either through a program prompt to obtain secret information from the user, or by allowing the initiator application to also use a secret key stored in a service key table file on the initiator's host.

• Retrieving public-key credentials from a smart card device to obtain a TGT.

• Requesting initial credentials with specific options such as forwardable or renewable credentials.

• Renewing credentials before expiration to prolong the usable lifetime.

• Releasing buffers associated with credentials after they are no longer needed.

Using these special HP extension functions, the initial credential is received by the calling application, and placed in a credentials cache. The initial credential then can be retrieved using GSS-API functions, and be used to obtain the service tickets required for establishing the security context.

These functions may block pending exchanges between network entities such as authentication servers or network file systems. Blocking depends on the characteristics of the operating system and the security mechanism being used. In the Kerberos 5 mechanism, the credential management functions may block pending exchanges between other network entities such as directories or authentication servers.

8.3.2.1    Acquiring Initial Credentials

In the GSS-API standard before attempting to establish a context, the initiator application is required to have obtained initial credentials, and placed them in a central storage location called the credentials cache. The credentials are then retrieved from the cache using the function gss_acquire_cred().

8.3.2.1.1    Initiator Applications

Application Security SDK provides a special function to perform initial authentication for initiator applications, and places credentials into the cache for retrieval using the GSS-API standard. The function csf_gss_acq_user() can be used as a replacement for the authentication process controlled by Single Sign-On, Credentials Manager, or kinit.

Parameters specified for this function indicate the type of secret that is being retrieved from the principal in order to prove their identity. In the case of a user principal, the secret is typically in the form of a principal name and password that are provided at a prompt, though it can be a service key table entry.

The initial tickets or TGTs can be obtained with selected Kerberos ticket flags, indicating such attributes as forwardable, or proxiable tickets, and designating the ticket lifetime and renew time.

8.3.2.1.2    Acceptor Applications

An acceptor service principal requires the use of a service key table file. This file is used to store the service principal's secret, which is in the form of a random key that was initially generated and provided by a Kerberos database administration program. This type of initial authentication is performed using the GSS-API function gss_acquire_cred().

8.3.2.1.3    DES3

Application Security SDK provides support for DES3 encryption. Using DES3 provides greatly enhanced security protection over DES encryption.

The following conditions must be met before DES3 encryption can used to encrypt messages:

• ActiveTRUST Security Server must be configured for DES3.

• The principals for the initiating and accepting applications must have a DES3 key stored in the principal database.

• The initiator principal must obtain a TGT using DES3.

• The initiating application must indicate the use of DES3 when initiating the security context.

Note

Multiple encryption systems for a single security context are not allowed. You must use one or the other.

8.3.2.2    Credential Attributes

The function gss_inquire_cred() is used to determine the properties or attributes associated with a particular credential. Some of the Kerberos information returned by this function includes the credential lifetime, the mechanisms supported, and the credential usage. The attributes assigned to an initial credential depend upon the attributes requested when acquiring the TGT. Service tickets obtained with a particular TGT inherit the attributes assigned to the TGT.

Credentials may have a defined lifetime, after which they expire. The gss_inquire_cred() function can be used to determine if the credential has expired.

In some mechanism implementations, an application can no longer use credentials after they have expired. The application must release the credentials and acquire credentials again before it can continue. In the Kerberos 5 mechanism, the lifetime of the credentials is defined as the Kerberos ticket lifetime. After the credentials have expired, an application can no longer use them to establish a new security context. The application must release the credentials and acquire new ones using csf_gss_acq_user() and then gss_acquire_cred().

Note

The GSS-API standard does not provide a function for renewing credentials beyond their initially established lifetime. However, you can use the HP extension function csf_gss_renew_cred() to renew credentials if they have not already expired. Note that in order to renew a credential, the initial ticket must be requested from the security server with the renewable attribute flag.

8.3.2.3    Credentials Storage Location

For Kerberos 5, credentials are assumed to be stored on disk or other persistent storage medium on the local host.

For user principals, the credentials cache default location is assumed (unless the location is overridden by environment variables). The location is platform-dependent.

The default UNIX user's credentials cache file is located in krb5/tmp/cc/krb5cc_uid (where uid is the user identification number retrieved from the password file) unless the CSFC5CCNAME environment variable is set to an alternate path name.

For service principals, the default service key table file is contained in the platform-dependent locations; for UNIX systems, the default file is /krb5/v5srvtab, unless the CSFC5KTNAME environment variable is set to an alternate path name.

For more information on these credentials cache and service key table file settings, see the SSO Installation and Administration Guide.

8.3.2.4    Managing Credential Resources

Any credentials acquired with gss_acquire_cred() must be released by calling gss_release_cred(). The exact behavior that occurs when the credentials are released is dependent on the security mechanism used. In some cases, the internal buffers may be the only aspects of the credentials which are released. In other cases, the credentials stored on disk may be released as well. In the Kerberos 5 mechanism, only the internal buffers are released with this function.

Before deciding when to release credentials, the application must determine if it is going to be initiating or accepting security contexts more than once during the application's execution. If so, the application needs to acquire credentials and reuse them later with the initiate or accept security context functions, rather than releasing them immediately after this first use. In Kerberos 5 implementations, this provides improved performance.

8.3.3    Security Context Management Functions

A security context, once established, defines a unique conversation between each side of an application in a distributed environment. A security context is initiated by one side of the application, and then is accepted by the other side. A security context must be established prior to exchanging secured messages.

For Kerberos 5 implementations of the GSS-API standard, when a context is established, the Kerberos processes required for managing service tickets are performed. This includes obtaining, transferring and verification of these tickets. Once a context is established, it contains keys and other security parameters. The contents of a security context are used directly to apply protection to messages.

These functions may block pending exchanges between applications and security servers.

8.3.3.1    Identifying a Mechanism

The GSS-API standard is designed to be used in an environment where there are multiple security mechanisms available. This means that the targeted security mechanism must be identified programmatically.

One parameter passed to gss_init_sec_context() is the security mechanism identifier (or mech_type) that the initiator desires to use. The mechanism identifier is passed as an object identifier (OID). Alternatively, the initiator can use the default mechanism identifier. The default that would be selected is dependent on the GSS-API implementation. For Application Security SDK, the default mechanism is Kerberos 5.

8.3.3.2    Token Exchange

During the gss_init_sec_context() call, Application Security SDK searches the user's credentials cache for a service ticket. If the service ticket is not in the cache, Application Security SDK fetches a service ticket from the KDC. The returned service ticket is stored in the user's credentials cache. The GSS-API encodes the service ticket, along with other information, and returns it in a token to be sent to the other side of the application.

During the gss_accept_sec_context() call, the GSS-API decodes the token and extracts and verifies the service ticket, using its secret key from the service key table file. If verification was successful and mutual authentication was requested, the GSS-API generates a token in response. If mutual authentication was not requested, no return token is generated. If an error occurred, the GSS-API may generate an error token.

8.3.3.3    Optional Security Measures

When initiating a context, the application can identify a number of optional security measures. The GSS-API implementation of these optional security measures is dependent on the security mechanism in use.

The following sections introduce the optional security measures:

• Channel Bindings

• Confidentiality and Integrity

• Replay Detection

• Out-of-Sequence Message Detection

• Mutual Authentication

• Encryption Type: DES vs. DES3

• Credentials Delegation

8.3.3.3.1    Channel Bindings

Channel bindings are used to strengthen the quality of the authentication between two sides of a distributed application during context establishment, by limiting the scope within which an intercepted context establishment token can be reused by an imposter. Channel bindings accomplish this by adding additional items of data (specified by the distributed application) into the security context.

Channel bindings are composed of two main parts:

• Address information

• Optional application data

The address information consists of an address type and an address value for both the initiator and the acceptor. The address type specifies the protocol type contained in the address value buffer. The address value is the actual address of the initiator or the acceptor (in a format that corresponds to the address type).

In Kerberos 5, when the KDC builds a service ticket, it encodes the client address into the ticket. When the initiator presents that ticket to the acceptor and channel bindings are passed to gss_accept_sec_context(), the GSS-API verifies that the client address in the ticket is identical to the initiator address in the channel bindings. However, this check is not performed when using a TCP connection.

Note

The only address format supported is GSS_C_AF_INET.

The other component of the channel bindings data structure is application data, which the initiator can send to the other side of the application to be compared by the acceptor. Application data, if used, is determined by the application. The data supplied when the context is initiated must exactly match on the acceptor side. For example, the application may insert its "version number" in the application data, thereby prohibiting establishment of a security context with another application that is not a compatible version.

Channel bindings are encoded into the token generated by gss_init_sec_context(), which is then sent to the acceptor. The channel bindings are verified by gss_accept_sec_context(). The application initiating the security context must determine the channel binding values before calling gss_init_sec_context(), and both applications must provide consistent values to the security context functions. The GSS-API checks the channel bindings on the accepting side of the application.

When channel bindings are passed to gss_init_sec_context(), a hash value is computed using the channel bindings. The hash value is encoded into the token. During the call to gss_accept_sec_context(), the GSS-API computes a hash value using the channel bindings passed to it and compares the computed hash value against the hash value in the token passed to it.

8.3.3.3.2    Confidentiality and Integrity

The initiator can specify that it wants message confidentiality or integrity, or both, to be available when sending and receiving messages. The acceptor can query to see if message confidentiality or integrity, or both, is required for this context. This information is then passed back to the initiator.

Note

The initiator can request confidentiality, but if the acceptor cannot supply it, confidentiality is not used.

Use the GSS_C_CONF_FLAG and the GSS_C_INTEG_FLAG of the gss_init_sec_context() function to specify the confidentiality and integrity requirements.

8.3.3.3.3    Replay Detection

Replay detection means one side of the application checks to see if the token or message has been sent to it previously.

The initiator can specify that it wants messages to be checked against a message replay cache. This is used to determine if the message is a replay of a previous message.

The replay cache expands as required, allocating more resources for the cache as more messages are cached. Note that there is an upper limit on the cache size. Once a replay cache reaches a certain size, adding a new entry will be accompanied by freeing an older entry. The resources associated with the entire cache are freed when the security context is deleted.

Note

There are two different replay caches supported in Kerberos 5. The message replay cache is a memory-based cache that is controlled by parameters set during context establishment. The authentication replay cache is a file-based cache with settings controlled by UNIX environment variables.

8.3.3.3.4    Out-of-Sequence Message Detection

The initiator can specify that it wants messages to be sequenced (or numbered) to verify that all messages are received and that they are received in the order sent. Message sequencing also provides replay detection.

8.3.3.3.5    Mutual Authentication

The initiator can specify that it wants the acceptor to also perform authentication to the initiator. This way, both sides of the application can be assured that they are talking to the genuine other side of the application.

8.3.3.3.6    Encryption Type: DES vs. DES3

The initiator can specify the DES3 encryption standard during initial authentication. The initiator can also request DES3 encryption when initiating a security context. DES3 encryption offers significantly enhanced security over DES encryption.

8.3.3.3.7    Credentials Delegation

For Kerberos 5 implementations, the initiator can set the GSS_C_DELEG_FLAG delegation flag to specify that it wants initial tickets (TGTs) to be forwarded from one network host to another. Note that a TGT can be forwarded only if it has the Kerberos forwardable TGT attribute.

8.3.3.4    Identifying the Targeted Security Measures

The initiator calls gss_init_sec_context() and identifies the security measures that it wants the security mechanism to use. Flags are returned to the application, indicating which security measures are provided by the security mechanism. Not all security measures defined by the GSS-API standard may be provided by a security mechanism.

When the initiator specifies the security measures to use when establishing a security context, the acceptor must accept them. There is no room for negotiation at this time. For example, if the initiator specifies sequencing or replay detection when it calls gss_init_sec_context(), the acceptor must provide it.

If channel bindings are specified when the initiator calls gss_init_sec_context(), the acceptor must supply the exact same channel bindings in its call to gss_accept_sec_context().

8.3.4    Message Functions

The GSS-API message functions perform protection on a per-message basis. They can be invoked by either side of the application. When the application calls these functions, it specifies the quality of protection (QOP), which identifies the cryptographic algorithm that will be used to process the message. The values of the QOP are mechanism-dependent. The key used to apply the cryptographic algorithm is taken from the security context.

These four functions are related to each other as pairs:

• gss_get_mic() and gss_verify_mic()

• gss_wrap() and gss_unwrap()

An application may use gss_get_mic() and gss_verify_mic() if it wants to send the signature separately from the data. For example, in PGP mail (Pretty Good Privacy), the message is sent first, followed by the signature. The signature is verified and the results are displayed, indicating the message was not modified in transit.

Note

These functions are new in GSS-API V2. The previous release used the functions gss_sign(), gss_verify(), gss_seal(), and gss_unseal().

8.3.4.1    Quality of Protection

When the application calls these functions, it specifies the QOP, which identifies the integrity or confidentiality algorithm that will be applied to the message. Six algorithms are defined for the quality of protection in Kerberos 5:

• DES-MAC-MD5

• DES3-MAC-MD5

• MD2.5

• DES-MAC

• DES-CBC

• DES3-CBC

Note

Given the same quality of protection, gss_get_mic() and gss_wrap() calculate the signature the same way.

8.3.5    Miscellaneous Support Functions

This section lists miscellaneous support functions that may be used when securing applications.

In addition, there are some HP extension functions.

8.3.5.1    OID and OID sets

In order to understand OIDs (Object Identifiers) and OID sets, it is useful to review some background information.

8.3.5.1.1    OSI

OSI, described in CCITT X.200, is an internationally standardized architecture that governs the interconnection of computers from the physical layer up to the user application layer. Objects at higher layers are defined abstractly and intended to be implemented with objects at lower layers.

8.3.5.1.2    ASN.1

OSI's method of specifying abstract objects is called ASN.1 (Abstract Syntax Notation One, defined in CCITT X.208), which defines a set of rules for representing such objects as strings of ones and zeros. ASN.1 is a flexible notation that allows the definition of a variety of data types, including simple types such as integers and bit strings, structured types such as sets and sequences, and complex types defined in terms of other types.

8.3.5.1.3    Object Identifiers

An OID (Object Identifier) is one such data type, being a simple data type used to identify objects such as algorithms and attribute types. OIDs are composed of a sequence of integer components, values that are given meanings by registration authorities.

In the GSS-API, OIDs are used to identify parameters such as name types and mechanisms. The following examples shows how they work.

Example 8-1:  Constant Pointing to a Structure Containing a String

The constant GSS_C_NT_USER_NAME is a gss_OID type initialized to point to a gss_OID_desc structure containing the following OID string:

{10, (void *)"\x2a\x86\x48\x86\xf7\x12\x01\x02\x01\x01"}

This can be converted to the decimal object identifier values:

{ 1 2 840 113554 1 2 1 1 }

which in turn represent the following hierarchy of objects:

{iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) generic(1) user_name(1)}

Example 8-2:  Constant Pointing to a String

The constant rfc_krb5_c_OID is a gss_OID type which points to the OID string for:

{iso(1) member-body(2) United States(840) mit(113554) infosys(1) gssapi(2) krb5v2(3)}

8.3.5.1.4    OID Sets

An OID set is a GSS-API data structure that contains a set of OIDs, and a integer representing the number of OIDs in the set. Some GSS-API functions use sets to input and output a large number and/or a large variety of mechanism and attribute objects. For example, when you call gss_acquire_cred(), an OID set is returned that contains object identifiers for all supported mechanisms. You can use gss_test_oid_set_member() to see if a certain OID is in the set.

OID sets can also be created using the functions gss_create_empty_oid_set() and gss_add_oid_set_member().

8.3.6    V1 Compliance Functions

There are several functions included in Application Security SDK that are not supported in the GSS-API Version 2. HP continues to support these functions in this release for v1 interoperability. New applications being written using GSS-API Version 2 should not use the following v1 functions; instead use the v2 replacement.

8.4    Best Practices

The following sections provide information regarding security considerations and recommendations that should be followed when you are using Application Security SDK to create a custom application.

8.4.1    Multi-threading

The following functions are not thread-safe:

• gss_acquire_cred()

• gss_add_cred()

• csf_gss_acq_user()

• csf_gss_inq_user()

• csf_gss_release_user()

• csf_gss_renew_cred()

All of these functions pertain to the acquisition of initial tickets, and should therefore not be used in the multi-thread portion of your application.

Special care has been taken to ensure that gss_init_sec_context() and gss_accept_sec_context() are both multi-thread safe. All other function calls are thread-safe, provided that each thread uses a unique security context.

8.4.2    Cache Management

Cache sharing between principals is a security risk. One principal that shares the cache may impersonate another principal that also uses the cache. This can result in exploitation of the principals or the servers that trust the principals, or the passing of replayed messages.

HP recommends that you use a unique credentials cache for each initiator, and a unique key table entry for each acceptor. Ideally, each acceptor application should have a separate key table file.

8.4.3    Encryption Types

Application Security SDK supports both DES and DES3 encryption types. HP recommends using DES3 encryption as it provides significantly enhanced protection over DES.

Note that using DES3 restricts portability. Applications that use DES3 encryption can only be used with Application Security SDK implementations.

8.4.4    Exported Security Contexts

The gss_export_sec_context() function creates a token that can be used to pass a security context between processes. This token contains the context's secret key, and therefore is extremely sensitive data. These exported security contexts cannot be secured by the GSS-API, and must be protected by the application.

Applications that use this GSS-API feature must be sure to pass an exported security context between processes in a secure manner. Exported security contexts should be kept within the boundaries of the host that created the security context.

8.4.5    Key Management with GSS and Kerberos 5

Secret keys are used with encryption algorithms and keyed checksum algorithms, and should be changed periodically. How often depends on the algorithms used and the amount of data that is protected by them. One way to decrease the frequency is by using a stronger encryption algorithm, such as DES3 instead of DES.

There are five different types of keys that are used:

• A user principal has a secret key (password) stored in the principal database. This key is used to acquire ticket-granting-tickets (TGTs). If a user principal acquires many TGTs with the same password, the password may need to be changed in advance of its expiration time.

• Each TGT contains a session key. This key is used to acquire service tickets and to renew tickets. If a user principal, or a service principal acting as a client to other services, acquires many service tickets with the same TGT, you may need to acquire a new TGT in advance of its expiration time.

  You can also shorten the lifetime of the TGT. When specifying the lifetime with csf_gss_acq_user(), the function treats it as the minimum lifetime. To ensure that you don't use a TGT with a greater lifetime, use the CSF_GSS_C_ACQ_USER_OPT_ALWAYS_FETCH option which will force csf_gss_acq_user() to obtain a new TGT with the desired lifetime from the KDC.

• Each service ticket contains a session key. This key is used when establishing a security context. If a user principal, or a service principal acting as a client to another service, establishes many security contexts using the same service ticket, you may need to replace the service ticket before it expires. Service tickets generally expire at the same time as the TGT used to obtain them. The only way to replace a service ticket before it expires is to acquire a new TGT, which will re-initialize the credentials cache in which the tickets are stored.

• A service principal has a secret key stored in the principal database and also in a service key table file. When accepting a security context, this key is used to encrypt data. Each service ticket that a user principal acquires for the service principal contains the encrypted data.

  Also, a service principal that acts as a client to other services uses its secret key to acquire TGTs. A service principal's secret key is typically used often and therefore needs to be changed often. This is one reason why HP recommends against sharing of a service principal amongst server applications.

• Each security context contains a session key. This key is used when protecting messages. Security contexts do not expire. If you use one security context to exchange a lot of data or if you have a long-lived conversation, you may need to delete the security context and establish a new one periodically.

Since all but the security context session keys are stored in either a credentials cache or a service key table file, credentials caches and service key table files need to be protected.

8.4.6    Multi-threaded Functions

The following Application Security SDK functions are not thread-safe:

• gss_acquire_cred()

• gss_add_cred()

• csf_gss_acq_user()

• csf_gss_inq_user()

• csf_gss_release_user()

• csf_gss_renew_cred()

All of these functions pertain to the acquisition of initial tickets, and should therefore not be used in a multi-thread environment. If credentials are fetched before a program creates threads, the credential may be passed into the threads for a multi-threaded acceptor or initiator.

Special care has been taken to ensure that gss_init_sec_context() and gss_accept_sec_context() are both multi-thread safe. All other Application Security SDK calls are thread-safe, provided that each thread uses a unique security context.

8.4.7    Mutual Authentication

Mutual authentication means that both the initiator and acceptor principals are required to verify their identities before the security context can be established. The GSS_C_MUTUAL_FLAG option in the req_flags parameter of the function gss_init_sec_context() indicates whether mutual authentication is required.

If principals are not required to perform mutual authentication, there is a risk of getting a replayed message. If mutual authentication is not performed, message replay detection should be enabled using the GSS_C_REPLAY_FLAG of the req_flags parameter.

8.4.8    Protecting Passwords

HP recommends that all dialog boxes or forms used to obtain password information from principals should have the keyboard echo turned-off. This prevents other persons in the room from reading the user's password on the computer display.

Buffers used to store passwords should be set to zero immediately after use.

8.4.9    Replay Protection

The gss_init_sec_context() function contains a flag (GSS_C_REPLAY_FLAG of the req_flags parameter) that indicates if message replay detection should be enabled. Enabling message replay detection is important if applications are not performing mutual authentication during context establishment, as indicated by the GSS_C_MUTUAL_FLAG in the req_flags parameter being set to FALSE.

Message replay detection requires that a replay cache be used to store message received from the other application. There is a cache located on both the initiator and acceptor hosts. These caches are memory-based, and can expand in size to an upper limit. Consequently, replay detection will have an impact on the size of the process. New replay cache entries are allocated during gss_unwrap() and gss_verify_mic(), giving the appearance of a memory leak in the application. This is normal behavior. When a security context that uses message replay detection is deleted, the entire message replay cache is also deleted.

There is a different type of replay cache that is used for authentication replay detection. This is by default a file-based cache, as controlled by the UNIX CSFC5RCNAME environment variables or the Windows RepCache registry entries. This cache should never be configured to be a memory-based cache as that would introduce a security vulnerability. This cache type is always active, and is not controlled by the initiating application.

8.4.10    Refreshing Credentials

There are two security parameters containing cryptographic keys that do not expire. One is the service key table entry. The other is the security context. HP advises that these parameters should be refreshed periodically to minimize the potential for cryptographic exploitation of these keys.

8.4.11    Resource Management

Many functions create strings, buffers or other resources that are used to store security information for use by the application. It is very important that these resources are properly freed or released after use by calling the appropriate function included in the SDK. Failure to do so may compromise your security. A mismanaged resource may be able to be retrieved and read in a security attack.

In the Reference section of the SDK Manuals, information is provided on the appropriate resource management call that is used to free or release the contents of each function that creates a sensitive resource. Be sure to read the Reference sections of the individual SDK manuals thoroughly to determine the correct procedures to avoid this security exposure.

8.4.12    Service Key Table Files

The service key table file contains the credentials used by the acceptor application to verify its identity. Access to this file should be very restricted, allowing no user permission to read the contents of the file. Only trusted services should have the permissions to access the file.

The credentials in the service key table file do not expire. HP recommends that these credentials be refreshed periodically. To refresh an entry in the service key table file, a new random key should be generated by the security server, and extracted to the service host using a principal database administration program.

8.4.13    Ticket Attributes

Kerberos 5 initial tickets can be requested with a variety of attributes, as specified by flags in the csf_gss_acq_user() function. The following sections describe the attributes that can be requested.

8.4.13.1    Forwardable Tickets

Forwarding is a mechanism that sends a TGT from one host to another. The forwarded TGT can be used to generate a new service ticket on the second host on behalf of the initial principal named in the TGT. Tickets should only be forwarded to trusted principals.

8.4.13.2    Preauthentication

Preauthentication means that additional encrypted data is sent with a TGT request. The additional encrypted data is in the form of the Encrypted Timestamp. This added information provides extra security during the authentication process. If the CSF_GSS_C_ACQ_USER_OPT_NOPREAUTH is indicated, preauthentication is not required.

HP does not recommend skipping preauthentication, unless there is some need to do so unrelated to security, and therefore recommends that you avoid using this option unless absolutely necessary. Specifically for the Kerberos 5 security mechanism, preauthentication during acquisition of initial tickets prevents an impostor from getting tickets written in your name. In normal circumstances these tickets are only usable by the principal that is named in the ticket, as only they possess the secret key to decrypt it. However in the event there is some cryptographic exploitation capability held by an adversary, preauthentication prevents them from getting information from the security server that they can exploit. It also guarantees freshness of the ticket request.

8.4.13.3    Ticket Lifetime

The requested ticket lifetime is designated by the CSF_GSS_ACQ_USER_OPT_LIFETIME flag. The security server may return an initial ticket with a shorter lifetime than requested. This is because the maximum lifetime for a ticket issued to a principal in a given realm is controlled by the settings for the special principal krbtgt/REALM@REALM.

There are also ticket lifetime limits imposed by the Kerberos version. The maximum ticket lifetime for a Kerberos 4 ticket is 21 hours and 15 minutes. If you permit a maximum lifetime of 1 day, a Kerberos 5 ticket will last a full 24 hours, but a Kerberos 4 ticket expires after 21 hours and 15 minutes.

8.4.13.4    Ticket Renew Time

A ticket can be requested with a renewable attribute using the CSF_GSS_C_ACQ_USER_OPT_RENEWABLE flag. Note that the security server may return an initial ticket with a shorter renew time than requested. This is because the maximum renew time for a ticket issued to a principal in a given realm is controlled by the settings for the special principal krbtgt/REALM@REALM.

Once a renewable ticket is received, the renew time is controlled by a set of rules. When a principal initially requests a TGT, lifetime and renew time are not related. The granted renewable time has no relationship to the lifetime when the original ticket is issued. However, the two times do interact when a ticket is renewed.

8.4.13.4.1    General Rules for Lifetime and Renew Settings

When you renew a ticket, the resulting lifetime is determined according to the following rules:

• A ticket can only be renewed if it has a renewable ticket attribute.

• Renewable tickets may be renewed at any point during the ticket's lifetime.

• An expired ticket cannot be renewed.

• A renewable ticket can be renewed multiple times, until the renew time limit has expired.

• A renewed ticket will have the same lifetime as the original lifetime of the renewable ticket. As an example, assume a ticket has a lifetime of 30 minutes but is renewable for 50 minutes. After 15 minutes, the ticket is renewed. The renewed ticket lifetime is also 30 minutes.

• The rule is modified when a ticket is renewed if the remaining renew time is shorter than the original ticket lifetime. The renewed ticket expiration time cannot be later than the renew expiration time when the original ticket was issued. Referring to the example above, suppose the ticket is renewed before the ticket expires, say at 25 minutes after it is originally obtained as a renewable ticket. The renewed ticket will be valid for 25 minutes---not 30 minutes (25 + 25 = 50 minutes). The total time that the renewable and renewed ticket are valid must be less than or equal to the renew time limit set on the original ticket.

• Any proxy (service) tickets obtained with a renewable TGT inherit the renewable option and the renew time, and are renewed along with the TGT. This follows the general idea that service tickets inherit the attributes (when possible) of the TGT used to obtain them.

• Renewing tickets does not require a password.

8.5    Building a Portable Application

The GSS-API standard is designed to be generic, and to allow applications that incorporate the GSS-API to be source-level compatible. However, if you use GSS-API implementations from different vendors, you may encounter some portability problems between these vendors.

The following sections provide recommendations to help minimize this impact and make your GSS-API applications created using Application Security SDK more portable across platforms.

8.5.1    Using Printable Names and Comparing Names

The gss_display_name() function converts an internal name (i.e., a name returned by gss_import_name()) to a text form suitable for printing. Since the GSS-API standard does not require that the printable name and name-type OID returned from gss_display_name() be suitable for input to gss_import_name(), the printable name format is implementation-specific and operating system-dependent. The format of printable names may differ across GSS-API implementations, whether the implementations are cross-vendor, cross-platform, or incremental vendor releases. Consequently, printable names are not reliable as input to name comparison functions outside the GSS-API standard. You should use the export name format created with the gss_export_name() function for this purpose. Examples where the export name may be used include ACL (access control list) functions, accounting functions, or diagnostic aids.

8.5.2    Specifying Mechanisms

Passing an OID set to gss_acquire_cred() or csf_gss_acq_user() and passing an OID to gss_init_sec_context() and gss_import_name() reduce the portability of an application as technology changes. For example, your enterprise may start out using the Kerberos security mechanism, but may later change to a public-key security mechanism. If application developers hard-coded OID sets specifying Kerberos, those applications would have to be modified. Also, mechanism OIDs can change.

To increase portability, an application should pass default OID and OID set values to functions, thus permitting the GSS-API implementation to choose whatever mechanisms are available and appropriate.

8.5.3    Specifying a Quality of Protection (QOP)

The gss_wrap() and gss_get_mic() functions accept a QOP parameter that specifies the algorithm to be applied to the message. The QOP parameter value is mechanism-specific. Specifying anything other than the default value (in which case the GSS-API implementation chooses a value) hard-codes the application to a mechanism.

Consequently, should you change the mechanism used, or the mechanism you currently use changes functionally, application source code modifications may be required.

The gss_unwrap() and gss_verify_mic() functions and their inverse functions of gss_wrap() and gss_get_mic() are supposed to return the actual QOP used to protect the message. If an application specifies the default QOP when it encodes a message, the QOP returned by the inverse function is mechanism-dependent.

To increase portability, an application should specify the default QOP value when calling gss_wrap() and gss_get_mic() and should not rely on the value returned by their inverse functions (gss_unwrap() and gss_verify_mic(), respectively).

The default integrity QOPs are as follows:

• CSF_GSS_KRB5_INTEG_C_QOP_DES3_MD5 for DES3.

• GSS_KRB5_INTEG_C_QOP_DES_MD5 for DES

The confidentiality QOPs are as follows:

• CSF_GSS_KRB5_CONF_C_QOP_DES3 for DES3

• GSS_KRB5_CONF_C_QOP_DES for DES

The default QOP used depends on the encryption type selected when the security context was established.

Note

The DES3 QOP is not portable; designating this QOP renders the application to be Kerberos 5 mechanism-specific.

8.5.4    Default Names

Some GSS-API functions accept a parameter that selects a default name. However, the GSS-API standard does not define how default names are formed; it is mechanism-dependent and operating system-dependent. For example, one GSS-API implementation may form a default name by interrogating an environment variable, whereas another may form it from the user's ID (for example, a UNIX UID). There are also GSS-API implementations that form a default name based on indirect selection criteria and mechanism common sense. For example, Application Security SDK Kerberos mechanism implementation forms the default name user@REALM for credentials of usage GSS_C_INITIATE and the default host/hostname@REALM for credentials of usage GSS_C_ACCEPT.

HP recommends that to increase portability, you do not use mechanism-dependent default names.

8.6    Quick Reference

Application Security SDK consists of standard and proprietary functions described in that are used to secure applications:

• Function calls beginning with the letters gss correspond to the GSS-API standard.

• Function calls beginning with the letters cs or csf are HP-specific extensions.

8.6.1    Reference Page Conventions

Each function is described in a reference page using the following categories:

Purpose

A brief description of the function purpose.

Syntax

A complete listing of permitted parameters and command line arguments.

Input parameters are those parameters passed from the application to Application Security SDK.

Output parameters are those parameters, passed from Application Security SDK to the application.

If an input parameter is optional, the application can supply a default value for that parameter.

If an output parameter is optional, Application Security SDK does not need to return a value to the application because the application does not need it. Use NULL in the output parameter to indicate this.

Note

To avoid memory leaks, the application must always release the storage associated with returned values after use.

Parameters

A list of variables passed to and returned from the function. For binary values:

• Logical 1 represents true.

• Logical 0 represents false.

Parameters initialized to NULL may also be zero.

Description

The definition, purpose, and usage tips for a function.

Portability Considerations

Concerns for porting an HP secured application to another environment.

Return Values

A list of major status values returned by the function.

See Also

A list of related function calls.

8.7    Constants

The header files included with Application Security SDK include many constants. The constant definitions from the header files are included here for reference.

8.8    Data Structures

Application Security SDK uses the following data structures to pass data to and from function calls:

• gss_channel_bindings_t — identifies the communications channel for a security context

• gss_buffer_t — specifies input or output data for a function call

• csf_gss_opts_t — specifies options for a user context

8.8.1    gss_channel_bindings_t

gss_channel_bindings_t is a pointer to the data structure containing information that identifies the communications channel for a security context. Channel bindings explains how channel bindings work.

The structure is defined in the gssapi.h header file as follows:

typedef struct _gss_channel_bindings_struct {
OM_uint32					initiator_addrtype;
gss_buffer_desc		initiator_address;
OM_uint32					acceptor_addrtype;
gss_buffer_desc		acceptor_address;
gss_buffer_desc		application_data;
} gss_channel_bindings_desc, *gss_channel_bindings_t;

The initiator_addrtype and acceptor_addrtype fields denote the type of addresses contained in the initiator_address and acceptor_address buffers. Application Security SDK supports the address format GSS_C_AF_INET.

The following function calls use channel_bindings_t structures:

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

typedef struct csf_gss_mech_opt_desc_struct {
gss_OID					mechOID;			/* Mech to specify option for */ 
OM_uint32				id;					/* Identifier of option */
void *					val;					/* Value associated with option if appropriate */  
} csf_gss_mech_opt_desc, *csf_gss_opts_t;

GSS_ERROR(major_status)

GSS_CALLING_ERROR(major_status)

GSS_ROUTINE_ERROR(major_status)

GSS_SUPPLEMENTARY_ERROR(major_status)