-

Developing with GSSAPI

+

Developing with GSSAPI

The GSSAPI (Generic Security Services API) allows applications to communicate securely using Kerberos 5 or other security mechanisms. We recommend using the GSSAPI (or a higher-level framework which encompasses GSSAPI, such as SASL) for secure network communication over using the libkrb5 API directly.

-

GSSAPIv2 is specified in RFC 2743 and RFC 2744. Also see -RFC 7546 for a description of how to use the GSSAPI in a client or +

GSSAPIv2 is specified in RFC 2743 and RFC 2744. Also see +RFC 7546 for a description of how to use the GSSAPI in a client or server program.

This documentation will describe how various ways of using the GSSAPI will behave with the krb5 mechanism as implemented in MIT krb5, as well as krb5-specific extensions to the GSSAPI.

-

Name types

+

Name types

A GSSAPI application can name a local or remote entity by calling gss_import_name, specifying a name type and a value. The following name types are supported by the krb5 mechanism:

@@ -97,19 +95,19 @@ string representation of the uid.

  • GSS_C_NT_EXPORT_NAME: The value must be the result of a gss_export_name call.

  • GSS_KRB5_NT_ENTERPRISE_NAME: The value should be a krb5 -enterprise name string (see RFC 6806 section 5), in the form +enterprise name string (see RFC 6806 section 5), in the form user@suffix. This name type is used to convey alias names, and is defined in the <gssapi/gssapi_krb5.h> header. (New in release 1.17.)

  • GSS_KRB5_NT_X509_CERT: The value should be an X.509 certificate -encoded according to RFC 5280. This name form can be used for +encoded according to RFC 5280. This name form can be used for the desired_name parameter of gss_acquire_cred_impersonate_name(), to identify the S4U2Self user by certificate. (New in release 1.19.)

    • -

    Initiator credentials

    +

    Initiator credentials

    A GSSAPI client application uses gss_init_sec_context to establish a security context. The initiator_cred_handle parameter determines what tickets are used to establish the connection. An application can @@ -160,7 +158,7 @@ cache or collection, and will be refreshed by future calls to gss_acquire_cred as they approach their expire time.

    -

    Acceptor names

    +

    Acceptor names

    A GSSAPI server application uses gss_accept_sec_context to establish a security context based on tokens provided by the client. The acceptor_cred_handle parameter determines what @@ -212,9 +210,9 @@ type which is mapped to a krb5 principal name, clients will only be allowed to authenticate to that principal in the default keytab.

    -

    Name Attributes

    +

    Name Attributes

    In release 1.8 or later, the gss_inquire_name and -gss_get_name_attribute functions, specified in RFC 6680, can be +gss_get_name_attribute functions, specified in RFC 6680, can be used to retrieve name attributes from the src_name returned by gss_accept_sec_context. The following attributes are defined when the krb5 mechanism is used:

    @@ -228,7 +226,7 @@ so multiple invocations may be necessary to retrieve all of the indicators from the ticket. (New in release 1.15.)

    -

    Credential store extensions

    +

    Credential store extensions

    Beginning with release 1.11, the following GSSAPI extensions declared in <gssapi/gssapi_ext.h> can be used to specify how credentials are acquired or stored:

    @@ -308,7 +306,7 @@ is true, the primary cache of the collection will be switched to the selected cache.

    -

    Importing and exporting credentials

    +

    Importing and exporting credentials

    The following GSSAPI extensions can be used to import and export credentials (declared in <gssapi/gssapi_ext.h>):

    OM_uint32 gss_export_cred(OM_uint32 *minor_status,
@@ -351,7 +349,7 @@ resulting token may be imported even if the original memory credential
 cache no longer exists.
    -

    Constrained delegation (S4U)

    +

    Constrained delegation (S4U)

    The Microsoft S4U2Self and S4U2Proxy Kerberos protocol extensions allow an intermediate service to acquire credentials from a client to a target service without requiring the client to delegate a @@ -426,8 +424,39 @@ is not a proxy credential, data_set will be set to an empty buffer set. If the library does not support the query, gss_inquire_cred_by_oid will return GSS_S_UNAVAILABLE.

    +
    +

    Channel binding behavior and GSS_C_CHANNEL_BOUND_FLAG

    +

    GSSAPI channel bindings can be used to limit the scope of a context +establishment token to a particular protected channel or endpoint, +such as a TLS channel or server certificate. Channel bindings can be +supplied via the input_chan_bindings parameter to either +gss_init_sec_context() or gss_accept_sec_context().

    +

    If both the initiator and acceptor of a GSSAPI exchange supply +matching channel bindings, GSS_C_CHANNEL_BOUND_FLAG will be +included in the gss_accept_sec_context() ret_flags result. If +either the initiator or acceptor (or both) do not supply channel +bindings, the exchange will succeed, but GSS_C_CHANNEL_BOUND_FLAG +will not be included in the return flags. If the acceptor and +initiator both inlude channel bindings but they do not match, the +exchange will fail.

    +

    If GSS_C_CHANNEL_BOUND_FLAG is included in the req_flags +parameter of gss_init_sec_context(), the initiator will add the +Microsoft KERB_AP_OPTIONS_CBT extension to the Kerberos authenticator. +This extension requests that the acceptor strictly enforce channel +bindings, causing the exchange to fail if the acceptor supplies +channel bindings and the initiator does not. The KERB_AP_OPTIONS_CBT +extension will also be included if the +client_aware_channel_bindings variable is set to true in +[libdefaults].

    +

    Prior to release 1.19, GSS_C_CHANNEL_BOUND_FLAG is not +implemented, and the exchange will fail if the acceptor supply channel +bindings and the initiator does not (but not vice versa). Between +releases 1.19 and 1.21, GSS_C_CHANNEL_BOUND_FLAG is not recognized +as an initiator flag, so client_aware_channel_bindings is the only +way to cause KERB_AP_OPTIONS_CBT to be included.

    +
    -

    AEAD message wrapping

    +

    AEAD message wrapping

    The following GSSAPI extensions (declared in <gssapi/gssapi_ext.h>) can be used to wrap and unwrap messages with additional “associated data” which is integrity-checked but is @@ -454,7 +483,7 @@ if the same input_assoc_buffer contents are presented to gss_unwrap_aead.

    -

    IOV message wrapping

    +

    IOV message wrapping

    The following extensions (declared in <gssapi/gssapi_ext.h>) can be used for in-place encryption, fine-grained control over wrap token layout, and for constructing wrap tokens compatible with Microsoft DCE @@ -582,7 +611,7 @@ Here is an example of using gss_wrap_iov_length and gss_wrap_iov: