Adding upstream version 2:4.17.12+dfsg.upstream/2%4.17.12+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 110 insertions, 0 deletions

diff --git a/third_party/heimdal/lib/gss_preauth/README.md b/third_party/heimdal/lib/gss_preauth/README.md
new file mode 100644
index 0000000..2a3b142
--- /dev/null
+++ b/third_party/heimdal/lib/gss_preauth/README.md
@@ -0,0 +1,110 @@
+# GSS-API Pre-authentication in Heimdal
+
+GSS-API pre-authentication in Heimdal is based on
+[draft-perez-krb-wg-gss-preauth](https://datatracker.ietf.org/doc/html/draft-perez-krb-wg-gss-preauth)
+but with some simplifications to the protocol.
+
+The following text assumes the reader is familiar with the draft.
+
+## Client side
+
+Because libkrb5 cannot have a recursive dependency on libgssapi, it instead
+exports the function `_krb5_init_creds_init_gss()` which allows libgssapi to
+register a set of function pointers for:
+
+  - Generating context tokens
+  - Finalizing a context (inquiring the initiator name and reply key)
+  - Releasing context and credential handles
+
+This is a private API.
+
+This architecture also means that the libkrb5 implementation could be used with
+an alternative GSS-API implementation such as SSPI, without too much work. The
+bulk of the pre-authentication logic remains in libkrb5, however, in
+[`init_creds_pw.c`](../../krb5/init_creds_pw.c).
+
+libgssapi itself exports `krb5_gss_set_init_creds()`, which is the public
+interface for GSS-API pre-authentication.
+
+`krb5_gss_set_init_creds()` enables GSS-API pre-authentication on an initial
+credentials context, taking a GSS-API credential handle and mechanism. Both are
+optional; defaults will be used if absent. These two parameters are exposed as
+the `--gss-name` and `--gss-mech` options to `kinit` (see
+[kinit(1)](../../../kuser/kinit.1) for further details). `kinit` supports
+acquiring anonymous, keytab- and password-based GSS-API credentials using the
+same arguments as regular Kerberos.
+
+The selected GSS-API mechanism must support mutual authentication (ie.
+authenticating the KDC) as it replaces the AS-REP reply key, However, if FAST
+was used, and we know that the KDC was verified, then this requirement is
+removed.
+
+If the client does not know its initiator name, it can specify the last
+arugment to `kinit` as `@REALM`, and the initiator name will be filled in when
+the authentication is complete. (The realm is required to select a KDC.)
+
+## KDC side
+
+The KDC implements the acceptor side of the GSS-API authentication exchange.
+The selected GSS-API mechanism must allow `gss_export_sec_context()` to be
+called by the acceptor before the context is established, if it needs more than
+a single round trip of token exchanges.
+
+### Configuration
+
+Configuration directives live in the [kdc] section of
+[krb5.conf(5)](../../krb5/krb5.conf.5).
+
+The `enable_gss_preauth` krb5.conf option must be set in order to enable
+GSS-API pre-authentication in the KDC. When authenticating federated principals
+which may not exist in the KDC, the `synthetic_clients` option should also be
+set.
+
+The `gss_mechanisms_allowed` option can be used to limit the set of GSS-API
+mechanisms which are allowed to perform pre-authentication. Mechanisms are
+specified as dot-separated OIDs or by a short name, such as `sanon-x25519`.
+
+The `enable_gss_auth_data` option will include a composite GSS name in the
+authorization data of returned tickets.
+
+### Authorization
+
+The default is that the initiator is permitted to authenticate to the Kerberos
+principal that directly corresponds to it. The correspondence is governed as
+follows: if the authenticating mechanism is in the list of mechanisms in the
+`gss_cross_realm_mechanisms_allowed` configuration option, then the principal
+is mapped identically: an initiator named `lukeh@AAA.PADL.COM` will be mapped
+to the Kerberos principal `lukeh@AAA.PADL.COM`.
+
+If the authenticating mechanism is not in this list, then the initiator will be
+mapped to an enterprise principal in the service realm. For example,
+`lukeh@AAA.PADL.COM` might be mapped to `lukeh\@AAA.PADL.COM@PADL.COM`
+(enterprise principal name type);
+
+This mapping has no effect for principals that exist in the HDB, because
+enterprise principal names are always looked up by their first component (as if
+they were an ordinary principal name). This logic is instead useful when
+synthetic principals are enabled as we wish to avoid issuing tickets with a
+client name in a foreign Kerberos realm, as that would conflate GSS-API
+"realms" with Kerberos realms.
+
+A custom authorization plugin installed in `$prefix/lib/plugin/kdc` will
+replace this mapping and authorization logic. The plugin interface is defined in
+[`gss_preauth_authorizer_plugin.h`](../../../kdc/gss_preauth_authorizer_plugin.h)).
+
+### Anonymous authentication
+
+A further note on the interaction of anonymous GSS-API authentication and
+pre-authentication. Initiator contexts that set `GSS_C_ANON_FLAG` and a
+`GSS_C_NT_ANONYMOUS` name are mapped to the unauthenticated anonymous Kerberos
+principal, `WELLKNOWN/ANONYMOUS@WELLKNOWN:ANONYMOUS`. However, the local
+`WELLKNOWN/ANONYMOUS` HDB entry is used to perform any authorization decisions
+(as it would be for anonymous PKINIT). The AP-REP will contain the well-known
+anonymous realm.
+
+If `GSS_C_NT_ANONYMOUS` was set but a different name type was returned, then
+the initiator is treated as authenticated anonymous, and the client realm will
+be present in the AP-REP.
+
+The `request-anonymous` AP-REQ flag must also be set for GSS-API anonymous
+authentication to succeed.