← Back to branch summary

~ubuntu-branches/ubuntu/utopic/krb5/utopic

« back to all changes in this revision

Viewing changes to doc/html/_sources/plugindev/gssapi.txt

  • Committer: Package Import Robot
  • Author(s): Dmitrijs Ledkovs
  • Date: 2013-11-10 02:20:12 UTC
  • mfrom: (53.1.3 trusty-proposed)
  • Revision ID: package-import@ubuntu.com-20131110022012-b8ojkqhcxos55kln
Add alternate dependency on libverto-libevent1 as that's the package
ABI name in ubuntu.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/html/_sources/plugindev/gssapi.txt
 
1
GSSAPI mechanism interface
 
2
==========================
 
3
 
 
4
The GSSAPI library in MIT krb5 can load mechanism modules to augment
 
5
the set of built-in mechanisms.
 
6
 
 
7
.. note: The GSSAPI loadable mechanism interface does not follow the
 
8
         normal conventions for MIT krb5 pluggable interfaces.
 
9
 
 
10
A mechanism module is a Unix shared object or Windows DLL, built
 
11
separately from the krb5 tree.  Modules are loaded according to the
 
12
``/etc/gss/mech`` config file, as described in
 
13
:ref:`gssapi_plugin_config`.
 
14
 
 
15
For the most part, a GSSAPI mechanism module exports the same
 
16
functions as would a GSSAPI implementation itself, with the same
 
17
function signatures.  The mechanism selection layer within the GSSAPI
 
18
library (called the "mechglue") will dispatch calls from the
 
19
application to the module if the module's mechanism is requested.  If
 
20
a module does not wish to implement a GSSAPI extension, it can simply
 
21
refrain from exporting it, and the mechglue will fail gracefully if
 
22
the application calls that function.
 
23
 
 
24
The mechglue does not invoke a module's **gss_add_cred**,
 
25
**gss_add_cred_from**, **gss_add_cred_impersonate_name**, or
 
26
**gss_add_cred_with_password** function.  A mechanism only needs to
 
27
implement the "acquire" variants of those functions.
 
28
 
 
29
A module does not need to coordinate its minor status codes with those
 
30
of other mechanisms.  If the mechglue detects conflicts, it will map
 
31
the mechanism's status codes onto unique values, and then map them
 
32
back again when **gss_display_status** is called.
 
33
 
 
34
 
 
35
Interposer modules
 
36
------------------
 
37
 
 
38
The mechglue also supports a kind of loadable module, called an
 
39
interposer module, which intercepts calls to existing mechanisms
 
40
rather than implementing a new mechanism.
 
41
 
 
42
An interposer module must export the symbol **gss_mech_interposer**
 
43
with the following signature::
 
44
 
 
45
    gss_OID_set gss_mech_interposer(gss_OID mech_type);
 
46
 
 
47
This function is invoked with the OID of the interposer mechanism as
 
48
specified in ``/etc/gss/mech``, and returns a set of mechanism OIDs to
 
49
be interposed.  The returned OID set must have been created using the
 
50
mechglue's gss_create_empty_oid_set and gss_add_oid_set_member
 
51
functions.
 
52
 
 
53
An interposer module must use the prefix ``gssi_`` for the GSSAPI
 
54
functions it exports, instead of the prefix ``gss_``.
 
55
 
 
56
An interposer module can link against the GSSAPI library in order to
 
57
make calls to the original mechanism.  To do so, it must specify a
 
58
special mechanism OID which is the concatention of the interposer's
 
59
own OID byte string and the original mechanism's OID byte string.
 
60
 
 
61
Since **gss_accept_sec_context** does not accept a mechanism argument,
 
62
an interposer mechanism must, in order to invoke the original
 
63
mechanism's function, acquire a credential for the concatenated OID
 
64
and pass that as the *verifier_cred_handle* parameter.
 
65
 
 
66
Since **gss_import_name**, **gss_import_cred**, and
 
67
**gss_import_sec_context** do not accept mechanism parameters, the SPI
 
68
has been extended to include variants which do.  This allows the
 
69
interposer module to know which mechanism should be used to interpret
 
70
the token.  These functions have the following signatures::
 
71
 
 
72
    OM_uint32 gssi_import_sec_context_by_mech(OM_uint32 *minor_status,
 
73
        gss_OID desired_mech, gss_buffer_t interprocess_token,
 
74
        gss_ctx_id_t *context_handle);
 
75
 
 
76
    OM_uint32 gssi_import_name_by_mech(OM_uint32 *minor_status,
 
77
        gss_OID mech_type, gss_buffer_t input_name_buffer,
 
78
        gss_OID input_name_type, gss_name_t output_name);
 
79
 
 
80
    OM_uint32 gssi_import_cred_by_mech(OM_uint32 *minor_status,
 
81
        gss_OID mech_type, gss_buffer_t token,
 
82
        gss_cred_id_t *cred_handle);
 
83
 
 
84
To re-enter the original mechanism when importing tokens for the above
 
85
functions, the interposer module must wrap the mechanism token in the
 
86
mechglue's format, using the concatenated OID.  The mechglue token
 
87
formats are:
 
88
 
 
89
* For **gss_import_sec_context**, a four-byte OID length in big-endian
 
90
  order, followed by the mechanism OID, followed by the mechanism
 
91
  token.
 
92
 
 
93
* For **gss_import_name**, the bytes 04 01, followed by a two-byte OID
 
94
  length in big-endian order, followed by the mechanism OID, followed
 
95
  by the bytes 06, followed by the OID length as a single byte,
 
96
  followed by the mechanism OID, followed by the mechanism token.
 
97
 
 
98
* For **gss_import_cred**, a four-byte OID length in big-endian order,
 
99
  followed by the mechanism OID, followed by a four-byte token length
 
100
  in big-endian order, followed by the mechanism token.  This sequence
 
101
  may be repeated multiple times.