From 4918001d76f26cbf663fbc362f7deb0365d99767 Mon Sep 17 00:00:00 2001 From: Greg Hudson Date: Wed, 29 Feb 2012 18:49:04 +0000 Subject: [PATCH] Add GSSAPI acceptor names documentation In the application developer documentation, create a little bit of framing for documentation about krb5 GSS mechanism behavior and extensions, and create an initial section about how host-based service names affect keytab principal selection. git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@25722 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/rst_source/krb_appldev/gssapi.rst | 75 +++++++++++++++++++++++++++ doc/rst_source/krb_appldev/index.rst | 1 + 2 files changed, 76 insertions(+) create mode 100644 doc/rst_source/krb_appldev/gssapi.rst diff --git a/doc/rst_source/krb_appldev/gssapi.rst b/doc/rst_source/krb_appldev/gssapi.rst new file mode 100644 index 000000000..cb21f6873 --- /dev/null +++ b/doc/rst_source/krb_appldev/gssapi.rst @@ -0,0 +1,75 @@ +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`. This +documentation will describe how various ways of using GSSAPI will +behave with the krb5 mechanism as implemented in MIT krb5, as well as +krb5-specific extensions to the GSSAPI. + + +Acceptor names +-------------- + +A GSSAPI server uses gss_accept_sec_context_ to establish a security +context based on tokens provided by the client. The +*acceptor_cred_handle* parameter determines what keytab entries may be +authenticated to by the client, if the krb5 mechanism is used. + +The simplest choice is to pass **GSS_C_NO_CREDENTIAL** as the acceptor +credential. In this case, clients may authenticate to any service +principal in the default keytab (typically ``/etc/krb5.keytab``, or +the value of the **KRB5_KTNAME** environment variable). This is the +recommended approach if the server application has no specific +requirements to the contrary. + +A server may acquire an acceptor credential with gss_acquire_cred_ and +a *cred_usage* of **GSS_C_ACCEPT** or **GSS_C_BOTH**. If the +*desired_name* parameter is **GSS_C_NO_NAME**, clients, as above, be +allowed to authenticate to any service principal in the default +keytab. + +If a server wishes to specify a *desired_name* to gss_acquire_cred_, +the most common method is to call gss_import_name_ with an +*input_name_type* of **GSS_C_NT_HOSTBASED_SERVCE** and an +*input_name_buffer* containing a string of the form ``service`` or +``service@hostname``. If the input name contains just a *service*, +then clients will be allowed to authenticate to any host-based service +principal (that is, a principal of the form +``service/hostname@REALM``) for the named service, regardless of +hostname or realm, as long as it is present in the default keytab. If +the input name contains both a *service* and a *hostname*, clients +will be allowed to authenticate to any host-based principal for the +named service and hostname, regardless of realm. + +.. note:: If a *hostname* is specified, it will be canonicalized + using forward name resolution, and possibly also using + reverse name resolution depending on the value of the + **rdns** variable in :ref:`libdefaults`. + +.. note:: If the **ignore_acceptor_hostname** variable in + :ref:`libdefaults` is enabled, then *hostname* will be + ignored even if one is specified in the input name. + +.. note:: In MIT krb5 versions prior to 1.10, and in Heimdal's + implementation of the krb5 mechanism, an input name with + just a *service* is treated like an input name of + ``service@localhostname``, where *localhostname* is the + string returned by gethostname(). + +It is also possible to directly specify a service principal name using +the *input_name_type* value **GSS_KRB5_NT_PRINCIPAL_NAME** (defined in +````), and an *input_name_buffer* containing an +unparsed principal name. Doing so will prevent the server application +from working with mechanisms other than krb5. If the a service +principal name is specified, clients will only be allowed to +authenticate to that principal in the default keytab. + +.. _gss_accept_sec_context: http://tools.ietf.org/html/rfc2744.html#section-5.1 +.. _gss_acquire_cred: http://tools.ietf.org/html/rfc2744.html#section-5.2 +.. _gss_import_name: http://tools.ietf.org/html/rfc2744.html#section-5.16 diff --git a/doc/rst_source/krb_appldev/index.rst b/doc/rst_source/krb_appldev/index.rst index 0966fba64..f2e1986ef 100644 --- a/doc/rst_source/krb_appldev/index.rst +++ b/doc/rst_source/krb_appldev/index.rst @@ -7,6 +7,7 @@ Contents .. toctree:: :maxdepth: 1 + gssapi.rst h5l_mit_apidiff.rst princ_handle.rst -- 2.26.2