Separate clpreauth and kdcpreauth interfaces

Since there is no overlap between the clpreauth and kdcpreauth
interface declarations, there's no particular reason to combine them
into one header.  For backward compatibility and convenience, leave
behind a preauth_plugin.h which includes both.

1 files changed, 318 insertions, 0 deletions

diff --git a/src/include/krb5/kdcpreauth_plugin.h b/src/include/krb5/kdcpreauth_plugin.h
new file mode 100644
index 0000000000..e673d40035
--- /dev/null
+++ b/src/include/krb5/kdcpreauth_plugin.h
@@ -0,0 +1,318 @@
+/* -*- mode: c; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ * Copyright (c) 2006 Red Hat, Inc.
+ * Portions copyright (c) 2006, 2011 Massachusetts Institute of Technology
+ * All Rights Reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ *  * Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *  * Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *  * Neither the name of Red Hat, Inc., nor the names of its
+ *    contributors may be used to endorse or promote products derived
+ *    from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+ * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+ * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+ * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+ * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+ * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+ * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+ * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+ * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+ * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+/*
+ * Declarations for kdcpreauth plugin module implementors.
+ *
+ * The kdcpreauth interface has a single supported major version, which is 1.
+ * Major version 1 has a current minor version of 2.  kdcpreauth modules should
+ * define a function named kdcpreauth_<modulename>_initvt, matching the
+ * signature:
+ *
+ *   krb5_error_code
+ *   kdcpreauth_modname_initvt(krb5_context context, int maj_ver, int min_ver,
+ *                             krb5_plugin_vtable vtable);
+ *
+ * The initvt function should:
+ *
+ * - Check that the supplied maj_ver number is supported by the module, or
+ *   return KRB5_PLUGIN_VER_NOTSUPP if it is not.
+ *
+ * - Cast the vtable pointer as appropriate for the interface and maj_ver:
+ *     kdcpreauth, maj_ver == 1: Cast to krb5_kdcpreauth_vtable
+ *
+ * - Initialize the methods of the vtable, stopping as appropriate for the
+ *   supplied min_ver.  Optional methods may be left uninitialized.
+ *
+ * Memory for the vtable is allocated by the caller, not by the module.
+ */
+
+#ifndef KRB5_KDCPREAUTH_PLUGIN_H
+#define KRB5_KDCPREAUTH_PLUGIN_H
+
+#include <krb5/krb5.h>
+#include <krb5/plugin.h>
+
+/* kdcpreauth mechanism property flags */
+
+/*
+ * Causes the KDC to include this mechanism in a list of supported preauth
+ * types if the user's DB entry flags the user as requiring hardware-based
+ * preauthentication.
+ */
+#define PA_HARDWARE     0x00000004
+
+/*
+ * Causes the KDC to include this mechanism in a list of supported preauth
+ * types if the user's DB entry flags the user as requiring preauthentication,
+ * and to fail preauthentication if we can't verify the client data.  The
+ * flipside of PA_SUFFICIENT.
+ */
+#define PA_REQUIRED     0x00000008
+
+/*
+ * Causes the KDC to include this mechanism in a list of supported preauth
+ * types if the user's DB entry flags the user as requiring preauthentication,
+ * and to mark preauthentication as successful if we can verify the client
+ * data.  The flipside of PA_REQUIRED.
+ */
+#define PA_SUFFICIENT   0x00000010
+
+/*
+ * Marks this preauthentication mechanism as one which changes the key which is
+ * used for encrypting the response to the client.  Modules which have this
+ * flag have their server_return_fn called before modules which do not, and are
+ * passed over if a previously-called module has modified the encrypting key.
+ */
+#define PA_REPLACES_KEY 0x00000020
+
+/*
+ * Not really a padata type, so don't include it in any list of preauth types
+ * which gets sent over the wire.
+ */
+#define PA_PSEUDO       0x00000080
+
+/*
+ * Indicates that e_data in non-FAST errors should be encoded as typed data
+ * instead of padata.
+ */
+#define PA_TYPED_E_DATA 0x00000100
+
+/* Abstract type for a KDC callback data handle. */
+typedef struct krb5_kdcpreauth_rock_st *krb5_kdcpreauth_rock;
+
+/* Abstract type for module data and per-request module data. */
+typedef struct krb5_kdcpreauth_moddata_st *krb5_kdcpreauth_moddata;
+typedef struct krb5_kdcpreauth_modreq_st *krb5_kdcpreauth_modreq;
+
+/* The verto context structure type (typedef is in verto.h; we want to avoid a
+ * header dependency for the moment). */
+struct verto_ctx;
+
+/* Before using a callback after version 1, modules must check the vers
+ * field of the callback structure. */
+typedef struct krb5_kdcpreauth_callbacks_st {
+    int vers;
+
+    krb5_deltat (*max_time_skew)(krb5_context context,
+                                 krb5_kdcpreauth_rock rock);
+
+    /*
+     * Get an array of krb5_keyblock structures containing the client keys
+     * matching the request enctypes, terminated by an entry with key type = 0.
+     * Returns ENOENT if no keys are available for the request enctypes.  Free
+     * the resulting object with the free_keys callback.
+     */
+    krb5_error_code (*client_keys)(krb5_context context,
+                                   krb5_kdcpreauth_rock rock,
+                                   krb5_keyblock **keys_out);
+
+    /* Free the result of client_keys. */
+    void (*free_keys)(krb5_context context, krb5_kdcpreauth_rock rock,
+                      krb5_keyblock *keys);
+
+    /*
+     * Get the encoded request body, which is sometimes needed for checksums.
+     * For a FAST request this is the encoded inner request body.  The returned
+     * pointer is an alias and should not be freed.
+     */
+    krb5_data *(*request_body)(krb5_context context,
+                               krb5_kdcpreauth_rock rock);
+
+    /* Get a pointer to the FAST armor key, or NULL if the request did not use
+     * FAST.  The returned pointer is an alias and should not be freed. */
+    krb5_keyblock *(*fast_armor)(krb5_context context,
+                                 krb5_kdcpreauth_rock rock);
+
+    /* Retrieve a string attribute from the client DB entry, or NULL if no such
+     * attribute is set.  Free the result with the free_string callback. */
+    krb5_error_code (*get_string)(krb5_context context,
+                                  krb5_kdcpreauth_rock rock, const char *key,
+                                  char **value_out);
+
+    /* Free the result of get_string. */
+    void (*free_string)(krb5_context context, krb5_kdcpreauth_rock rock,
+                        char *string);
+
+    /* Get a pointer to the client DB entry (returned as a void pointer to
+     * avoid a dependency on a libkdb5 type). */
+    void *(*client_entry)(krb5_context context, krb5_kdcpreauth_rock rock);
+
+    /* Get a pointer to the verto context which should be used by an
+     * asynchronous edata or verify method. */
+    struct verto_ctx *(*event_context)(krb5_context context,
+                                       krb5_kdcpreauth_rock rock);
+
+    /* End of version 1 kdcpreauth callbacks. */
+} *krb5_kdcpreauth_callbacks;
+
+/* Optional: preauth plugin initialization function. */
+typedef krb5_error_code
+(*krb5_kdcpreauth_init_fn)(krb5_context context,
+                           krb5_kdcpreauth_moddata *moddata_out,
+                           const char **realmnames);
+
+/* Optional: preauth plugin cleanup function. */
+typedef void
+(*krb5_kdcpreauth_fini_fn)(krb5_context context,
+                           krb5_kdcpreauth_moddata moddata);
+
+/*
+ * Optional: return the flags which the KDC should use for this module.  This
+ * is a callback instead of a static value because the module may or may not
+ * wish to count itself as a hardware preauthentication module (in other words,
+ * the flags may be affected by the configuration, for example if a site
+ * administrator can force a particular preauthentication type to be supported
+ * using only hardware).  This function is called for each entry entry in the
+ * server_pa_type_list.
+ */
+typedef int
+(*krb5_kdcpreauth_flags_fn)(krb5_context context, krb5_preauthtype pa_type);
+
+/*
+ * Responder for krb5_kdcpreauth_edata_fn.  If invoked with a non-zero code, pa
+ * will be ignored and the padata type will not be included in the hint list.
+ * If invoked with a zero code and a null pa value, the padata type will be
+ * included in the list with an empty value.  If invoked with a zero code and a
+ * non-null pa value, pa will be included in the hint list and will later be
+ * freed by the KDC.
+ */
+typedef void
+(*krb5_kdcpreauth_edata_respond_fn)(void *arg, krb5_error_code code,
+                                    krb5_pa_data *pa);
+
+/*
+ * Optional: provide pa_data to send to the client as part of the "you need to
+ * use preauthentication" error.  The implementation must invoke the respond
+ * when complete, whether successful or not, either before returning or
+ * asynchronously using the verto context returned by cb->event_context().
+ *
+ * This function is not allowed to create a modreq object because we have no
+ * guarantee that the client will ever make a follow-up request, or that it
+ * will hit this KDC if it does.
+ */
+typedef void
+(*krb5_kdcpreauth_edata_fn)(krb5_context context, krb5_kdc_req *request,
+                            krb5_kdcpreauth_callbacks cb,
+                            krb5_kdcpreauth_rock rock,
+                            krb5_kdcpreauth_moddata moddata,
+                            krb5_preauthtype pa_type,
+                            krb5_kdcpreauth_edata_respond_fn respond,
+                            void *arg);
+
+/*
+ * Responder for krb5_kdcpreauth_verify_fn.  Invoke with the arg parameter
+ * supplied to verify, the error code (0 for success), an optional module
+ * request state object to be consumed by return_fn or free_modreq_fn, optional
+ * e_data to be passed to the caller if code is nonzero, and optional
+ * authorization data to be included in the ticket.  In non-FAST replies,
+ * e_data will be encoded as typed-data if the module sets the PA_TYPED_E_DATA
+ * flag, and as pa-data otherwise.  e_data and authz_data will be freed by the
+ * KDC.
+ */
+typedef void
+(*krb5_kdcpreauth_verify_respond_fn)(void *arg, krb5_error_code code,
+                                     krb5_kdcpreauth_modreq modreq,
+                                     krb5_pa_data **e_data,
+                                     krb5_authdata **authz_data);
+
+/*
+ * Optional: verify preauthentication data sent by the client, setting the
+ * TKT_FLG_PRE_AUTH or TKT_FLG_HW_AUTH flag in the enc_tkt_reply's "flags"
+ * field as appropriate.  The implementation must invoke the respond function
+ * when complete, whether successful or not, either before returning or
+ * asynchronously using the verto context returned by cb->event_context().
+ */
+typedef void
+(*krb5_kdcpreauth_verify_fn)(krb5_context context,
+                             krb5_data *req_pkt, krb5_kdc_req *request,
+                             krb5_enc_tkt_part *enc_tkt_reply,
+                             krb5_pa_data *data,
+                             krb5_kdcpreauth_callbacks cb,
+                             krb5_kdcpreauth_rock rock,
+                             krb5_kdcpreauth_moddata moddata,
+                             krb5_kdcpreauth_verify_respond_fn respond,
+                             void *arg);
+
+/*
+ * Optional: generate preauthentication response data to send to the client as
+ * part of the AS-REP.  If it needs to override the key which is used to
+ * encrypt the response, it can do so.
+ */
+typedef krb5_error_code
+(*krb5_kdcpreauth_return_fn)(krb5_context context,
+                             krb5_pa_data *padata,
+                             krb5_data *req_pkt,
+                             krb5_kdc_req *request,
+                             krb5_kdc_rep *reply,
+                             krb5_keyblock *encrypting_key,
+                             krb5_pa_data **send_pa_out,
+                             krb5_kdcpreauth_callbacks cb,
+                             krb5_kdcpreauth_rock rock,
+                             krb5_kdcpreauth_moddata moddata,
+                             krb5_kdcpreauth_modreq modreq);
+
+/* Optional: free a per-request context. */
+typedef void
+(*krb5_kdcpreauth_free_modreq_fn)(krb5_context,
+                                  krb5_kdcpreauth_moddata moddata,
+                                  krb5_kdcpreauth_modreq modreq);
+
+/* Optional: invoked after init_fn to provide the module with a pointer to the
+ * verto main loop. */
+typedef krb5_error_code
+(*krb5_kdcpreauth_loop_fn)(krb5_context context,
+                           krb5_kdcpreauth_moddata moddata,
+                           struct verto_ctx *ctx);
+
+typedef struct krb5_kdcpreauth_vtable_st {
+    /* Mandatory: name of module. */
+    char *name;
+
+    /* Mandatory: pointer to zero-terminated list of pa_types which this module
+     * can provide services for. */
+    krb5_preauthtype *pa_type_list;
+
+    krb5_kdcpreauth_init_fn init;
+    krb5_kdcpreauth_fini_fn fini;
+    krb5_kdcpreauth_flags_fn flags;
+    krb5_kdcpreauth_edata_fn edata;
+    krb5_kdcpreauth_verify_fn verify;
+    krb5_kdcpreauth_return_fn return_padata;
+    krb5_kdcpreauth_free_modreq_fn free_modreq;
+    /* Minor 1 ends here. */
+
+    krb5_kdcpreauth_loop_fn loop;
+    /* Minor 2 ends here. */
+} *krb5_kdcpreauth_vtable;
+
+#endif /* KRB5_KDCPREAUTH_PLUGIN_H */