src/WINNT/netidmgr_plugin/afspext.h

   1 /*
   2  * Copyright (c) 2005,2006 Secure Endpoints Inc.
   3  *
   4  * Permission is hereby granted, free of charge, to any person
   5  * obtaining a copy of this software and associated documentation
   6  * files (the "Software"), to deal in the Software without
   7  * restriction, including without limitation the rights to use, copy,
   8  * modify, merge, publish, distribute, sublicense, and/or sell copies
   9  * of the Software, and to permit persons to whom the Software is
  10  * furnished to do so, subject to the following conditions:
  11  *
  12  * The above copyright notice and this permission notice shall be
  13  * included in all copies or substantial portions of the Software.
  14  *
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  18  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  19  * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  20  * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  21  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 /* $Id$ */
  26
  27 #ifndef __AFSPLUGIN_EXT_H
  28 #define __AFSPLUGIN_EXT_H
  29
  30 /*! \defgroup afs_ext OpenAFS Plugin extensions
  31
  32     This section documents messages and data structures used by AFS
  33     extension plugins.  These are plugins which augment the behavior
  34     of the AFS plugin.
  35
  36     When performing specific tasks for NetIDMgr, the AFS plugin will
  37     send out messages to the extension plugins either via broadcast or
  38     unicast.  The extension plugins provide functionality by
  39     responding to these messages.
  40
  41   @{*/
  42
  43 #define MAXCELLCHARS   256
  44 #define MAXHOSTCHARS   256
  45 #define MAXHOSTSPERCELL 8
  46
  47 #define TRANSARCAFSDAEMON "TransarcAFSDaemon"
  48
  49 #define AFS_TOKENNAME_AUTO L"Auto"
  50 #define AFS_TOKENNAME_KRB5 L"Kerberos5"
  51 #define AFS_TOKENNAME_KRB524 L"Kerberos524"
  52 #define AFS_TOKENNAME_KRB4 L"Kerberos4"
  53
  54 /*! \brief An AFS token acquisition method identifier
  55
  56     This takes on a value from ::afs_token_method or a token
  57     acquisition method identifier assigned to an extension plugin.
  58 */
  59 typedef khm_int32 afs_tk_method;
  60
  61 /*! \brief Predefined token acquisition methods */
  62 enum afs_token_method {
  63     AFS_TOKEN_AUTO = 0,         /*!< Automatic.  This method iterates
  64                                   through Krb5, Krb524, Krb4 and then
  65                                   any extensions which provide token
  66                                   acquisition methods until one of
  67                                   them succeeds. */
  68     AFS_TOKEN_KRB5,             /*!< Kerberos 5 */
  69     AFS_TOKEN_KRB524,           /*!< Kerberos 5 with krb524 translation */
  70     AFS_TOKEN_KRB4,             /*!< Kerberos 4 */
  71 };
  72
  73 /*! \brief Version of the OpenAFS Plugin
  74
  75     This is an internal number that identifies the version of the
  76     OpenAFS plugin API that this extension was built against.  This
  77     number is specified when sending the ::AFS_MSG_ANNOUNCE message.
  78  */
  79 #define AFS_PLUGIN_VERSION 0x0000001
  80
  81 /*! \name Messages
  82
  83     The AFS plugin registers the message type named ::AFS_MSG_TYPENAME
  84     and sends messages of this type to notify any AFS extension
  85     plugins to notify them of various events.
  86
  87  @{*/
  88
  89 /*! \brief Name of the AFS plugin message
  90
  91     This message type is registered when the AFS plugin starts and is
  92     unregistered when the plugin stops.
  93
  94     Use kmq_find_type() to find the type ID of this message type.
  95  */
  96 #define AFS_MSG_TYPENAME L"AfsExtMessage"
  97
  98 /*! \brief Announce an extension plugin
  99
 100     Sent by an extension plugin to announce its existence to the AFS
 101     plugin.  This message should be sent by the extension plugin when
 102     it has finished loading, and is the only message permitted to be
 103     sent by an extension. All other messages are sent by the AFS
 104     plugin.
 105
 106     Since this message contains pointer parameters and there is no
 107     cleanup performed on this, the message should be sent using
 108     kmq_send_message().
 109
 110     <table>
 111     <tr><td>Type</td><td>type ID of ::AFS_MSG_TYPENAME</td></tr>
 112     <tr><td>Subtype</td><td>::AFS_MSG_ANNOUNCE</td></tr>
 113     <tr><td>uparam</td><td>0</td></tr>
 114     <tr><td>vparam</td><td>Pointer to a ::afs_msg_announce structure</td></tr>
 115     </table>
 116
 117     \note This message is only sent from extension plugins to the AFS plugin.
 118  */
 119 #define AFS_MSG_ANNOUNCE 1
 120
 121 /*! \brief Parameter structure for announcing an extension plugin
 122
 123     \see ::AFS_MSG_ANNOUNCE
 124  */
 125 typedef struct tag_afs_msg_announce_v1 {
 126     khm_size  cbsize;           /*!< Size of the strucutre.  Set to \a
 127                                   sizeof(::afs_msg_announce).  If
 128                                   there is a version skew between the
 129                                   AFS plugin and the extension, then
 130                                   this parameter will ensure that the
 131                                   AFS plugin understands the correct
 132                                   version of the structure. */
 133
 134     khm_ui_4  version;          /*!< Version of the AFS plugin that
 135                                   the extension is compiled for.  Set
 136                                   this to ::AFS_PLUGIN_VERSION.
 137                                   Depending on this value, the AFS
 138                                   plugin will either reject the
 139                                   extension or determine which set of
 140                                   messages and structures should be
 141                                   used to communicate with the
 142                                   extension. */
 143
 144     const wchar_t * name;       /*!< Name of the extension.  Should be
 145                                   unique among all AFS extension
 146                                   plugins. Size constrained by
 147                                   ::KHUI_MAXCCH_NAME*/
 148
 149     khm_handle sub;             /*!< A valid subscription for unicast
 150                                   messages.  This must have been
 151                                   created through
 152                                   kmq_create_subscription().  The
 153                                   supplied handle will be
 154                                   automatically released when the
 155                                   plugin exits.  However, if the
 156                                   announcement message fails, then the
 157                                   extension has to release the handle
 158                                   itself. */
 159
 160     khm_boolean provide_token_acq; /*!< non-zero if the extension
 161                                      provides a token acquisition
 162                                      method. The \a token_acq
 163                                      substructure should be filled if
 164                                      this member is set to
 165                                      non-zero. */
 166
 167     struct {
 168         const wchar_t * short_desc; /*!< Short description of token
 169                                   acquisition method. (localized,
 170                                   required).  Size is constrained by
 171                                   ::KHUI_MAXCCH_SHORT_DESC */
 172
 173         const wchar_t * long_desc; /*!< Long description.  (localized,
 174                                   optional).  Size is constrained by
 175                                   ::KHUI_MAXCCH_LONG_DESC */
 176
 177         afs_tk_method method_id; /*!< Once the message is processed,
 178                                   this will receive a new method
 179                                   identifier.  The value of this field
 180                                   on entry is ignored. */
 181
 182     } token_acq;                /*!< Registration information for
 183                                   token acquisition method.  Only
 184                                   assumed to be valid if \a
 185                                   provide_token_acq is TRUE. */
 186
 187 } afs_msg_announce;
 188
 189 /*! \brief Sent to all extensions to resolve the identity of a token
 190
 191     If the identity and credentials acquisition method of an AFS token
 192     cannot be determined by the AFS plugin, this message is sent out
 193     to extension plugins to allow them a chance to resolve it.
 194
 195     If the extension plugin successfully resolves the identity and
 196     token acquisition method of the specified token, it should return
 197     ::KHM_ERROR_SUCCESS.  Otherwise it should return a failure code.
 198     The actual return code is not interpreted other than whether or
 199     not it passes the ::KHM_SUCCEEDED() test.
 200
 201     <table>
 202     <tr><td>Type</td><td>type ID of ::AFS_MSG_TYPENAME</td></tr>
 203     <tr><td>Subtype</td><td>::AFS_MSG_RESOLVE_TOKEN</td></tr>
 204     <tr><td>uparam</td><td>0</td></tr>
 205     <tr><td>vparam</td><td>Pointer to a ::afs_msg_resolve_token structure</td></tr>
 206     </table>
 207
 208     \note This message is only sent from the AFS plugin to extension plugins
 209
 210     \note Only sent if the extension plugin has ::provide_token_acq set.
 211  */
 212 #define AFS_MSG_RESOLVE_TOKEN 2
 213
 214 /*! \brief Message structure for AFS_MSG_RESOLVE_TOKEN
 215
 216     Other than the fields marked as \a [OUT], all other fields should
 217     be considered read-only and should not be modified.
 218
 219     \see ::AFS_MSG_RESOLVE_TOKEN
 220  */
 221 typedef struct tag_afs_msg_resolve_token_v1 {
 222     khm_size cbsize;            /*!< Size of the structure.  This will
 223                                   be set to \a
 224                                   sizeof(::afs_msg_resolve_token). */
 225
 226     const wchar_t * cell;       /*!< Specifies the cell that the token
 227                                   belongs to. */
 228
 229     const struct ktc_token * token; /*!< The token */
 230     const struct ktc_principal * serverp; /*!< Server principal */
 231     const struct ktc_principal * clientp; /*!< Client principal */
 232
 233     khm_handle ident;           /*!< [OUT] If the extension
 234                                   successfully resolves the identity,
 235                                   then it should assign a handle to
 236                                   the identity to this field and
 237                                   return ::KHM_ERROR_SUCCESS.  The
 238                                   handle will be automatically freed
 239                                   by the AFS plugin. */
 240
 241     afs_tk_method method;       /*!< [OUT] If the extension
 242                                   successfully resolves the identity,
 243                                   it should also assign the token
 244                                   acquisition method identifier to
 245                                   this field.  The default method is
 246                                   ::AFS_TOKEN_AUTO.  This field
 247                                   indicates the token acquisition
 248                                   method that was used to obtain the
 249                                   token and is used when the token
 250                                   needs to be renewed. */
 251 } afs_msg_resolve_token;
 252
 253 /*! \brief Sent to an extension plugin to obtain AFS tokens
 254
 255     <table>
 256     <tr><td>Type</td><td>type ID of ::AFS_MSG_TYPENAME</td></tr>
 257     <tr><td>Subtype</td><td>::AFS_MSG_KLOG</td></tr>
 258     <tr><td>uparam</td><td>0</td></tr>
 259     <tr><td>vparam</td><td>Pointer to a ::afs_msg_klog</td></tr>
 260     </table>
 261
 262     \note Only sent from the AFS plugin to extension plugins
 263     \note Only sent to extension plugins which have ::provide_token_acq set.
 264 */
 265 #define AFS_MSG_KLOG 3
 266
 267 /*! \brief Cell configuration information
 268
 269     \see ::afs_msg_klog
 270
 271     \note This structure uses ANSI char fields instead of unicode fields.
 272  */
 273 typedef struct tag_afs_conf_cellA_v1 {
 274     khm_size cbsize;            /*!< set to \a sizeof(afs_conf_cell) */
 275
 276     char     name[MAXCELLCHARS]; /*!< Name of the cell */
 277     short    numServers;        /*!< Number of servers for cell.
 278                                   Upper bound of MAXHOSTSPERCELL */
 279     short    flags;             /*!< Not used. Set to zero. */
 280     struct sockaddr_in hostAddr[MAXHOSTSPERCELL];
 281                                 /*!< addresses for each server.  There
 282                                   are \a numServers entries.*/
 283     char     hostName[MAXHOSTSPERCELL][MAXHOSTCHARS];
 284                                 /*!< names of the servers. There are
 285                                   \a numServers entries. */
 286     char *   linkedCell;        /*!< Not used.  Set to zero. */
 287 } afs_conf_cell;
 288
 289 /*! \brief Message parameters for AFS_MSG_KLOG message
 290
 291     \see ::AFS_MSG_KLOG
 292
 293     \note This structure uses ANSI char fields instead of unicode fields.
 294  */
 295 typedef struct tag_afs_msg_klogA_v1 {
 296     khm_size        cbsize;     /*!< Set to \a sizeof(afs_msg_klog) */
 297
 298     khm_handle      identity;   /*!< Handle to identity for which we
 299                                   are obtaining tokens. */
 300
 301     const char *    service;    /*!< Service name to use when
 302                                   obtaining token.  This can be NULL
 303                                   if the service name has not be
 304                                   determined. */
 305
 306     const char *    cell;       /*!< Name of cell to obtain tokens
 307                                   for.  Can be NULL if the local cell
 308                                   is to be used. */
 309
 310     const char *    realm;      /*!< Realm to use when obtaining
 311                                   tokens.  Can be NULL if the realm
 312                                   has not been determined. */
 313
 314     const afs_conf_cell * cell_config; /*!< Cell configuration for the
 315                                    cell specified in \a cell. */
 316
 317     khm_int32       lifetime;   /*!< Advisory lifetime specifier, in
 318                                   seconds.  If set to zero, means
 319                                   there is no specification for
 320                                   lifetime.  Extensions should feel
 321                                   free to ignore this parameter. */
 322 } afs_msg_klog;
 323
 324 /*!@}*/
 325
 326 /*!@}*/
 327
 328 #endif